Backbone学习之读Backbone.LocalStorage

上次写Todo时忽略了Backbone.LocalStorage插件，这次写第二个栗子Document Cloud用上了这个插件，决定一探究竟。

发现没想象中难，正如作者所说，重写了Backbone.sync，给Model设置了GUID，存为Json对象。Simple as that

(function(root, factory) {
  if (typeof define === "function" && define.amd) {
    // AMD. Register as an anonymous module.
    define(["underscore", "backbone"], function(_, Backbone) {
      // Use global variables if the locals are undefined.
      return factory(_ || root._, Backbone || root.Backbone);
    });
  } else {
    // RequireJS isn't being used. Assume underscore and backbone are loaded in script tags
    factory(_, Backbone);
  }
}(this, function(_, Backbone) {
  // 用16进制数来表示随机数，先生成一个5位16进制数，取整，去掉第一位，得到一个4位随机数
  // （Todo）用位或运算 |0 取整，不太明白 >>> 位运算的操作数必须是整数，或0也不会改变值的大小
  function S4() {
    return (((1 + Math.random()) * 0x10000) | 0).toString(16).substring(1);
  }

  // 把S4()返回的4位16进制数拼成GUID字符串
  function guid() {
    return (S4() + S4() + "-" + S4() + "-" + S4() + "-" + S4() + "-" + S4() + S4() + S4());
  }

  // 定义Store类，实例化时传入一个名字，比如在我的document cloud栗子里给个名字'books'
  // 'books'会被当作window.localStorage里的一个key，其value是一个由若干'books-GUID'组成的数组
  // 每个model在window.localStorage里都有一条对应的键值对, key是'books-GUID'，value是model的attribute hash
  Backbone.LocalStorage = window.Store = function(name) {
    this.name = name;
    // this.localStorage()就是返回window.localStorage
    var store = this.localStorage().getItem(this.name);
    // this.records存储所有model的GUID
    this.records = (store && store.split(",")) || [];
  };

  // 定义Store类的原型方法
  _.extend(Backbone.LocalStorage.prototype, {


    save: function() {
      this.localStorage().setItem(this.name, this.records.join(","));
    },

    // 添加模型时，如果model没有id，则给一个GUID
    create: function(model) {
      if (!model.id) {
        model.id = guid();
        model.set(model.idAttribute, model.id);
      }
      this.localStorage().setItem(this.name + "-" + model.id, JSON.stringify(model));
      this.records.push(model.id.toString());
      this.save();
      // 这里的返回值相当于server返回的resp，返回的是model的attribute hash
      // 为什么不返回model呢，我认为是由于success、error回调函数的使用，需要指定好统一的resp
      // 看了backbone的源码，在执行回调前会默认执行model.parse(resp, options)，这个parse函数的目的
      // 就是把原始的resp数据转换为model的attribue hash，fetch时也方便让collection来set/reset
      // 所以这里返回attribute hash
      return this.find(model);
    },

    // 更新localStorage里的对应记录
    update: function(model) {
      this.localStorage().setItem(this.name + "-" + model.id, JSON.stringify(model));
      if (!_.include(this.records, model.id.toString()))
        this.records.push(model.id.toString());
      this.save();
      return this.find(model);
    },

    // 通过model.id返回model的attribute hash
    find: function(model) {
      return this.jsonData(this.localStorage().getItem(this.name + "-" + model.id));
    },

    // 返回存储在this.records里的所有models的attribute hash array
    // 这里还用了underscore的链式操作
    findAll: function() {
      return _(this.records).chain()
        .map(function(id) {
          return this.jsonData(this.localStorage().getItem(this.name + "-" + id));
        }, this)
        // compact()剔除falsy(0, '', null, false, undefined, NaN)
        .compact()
        .value();
    },

    // 删除localStorage里的对应记录
    destroy: function(model) {
      if (model.isNew())
        return false;
      this.localStorage().removeItem(this.name + "-" + model.id);
      this.records = _.reject(this.records, function(id) {
        return id === model.id.toString();
      });
      this.save();
      // 这里我认为应该是 return model.toJSON()
      return model;
    },

    localStorage: function() {
      return localStorage;
    },


    jsonData: function(data) {
      return data && JSON.parse(data);
    }

  });

  // 这里method的几种case
  // model/collection.fetch - 'read'
  // model.save - 'create' 或 'patch' 或 'update'，视情况
  // model.destroy - 'delete'
  Backbone.LocalStorage.sync = window.Store.sync = Backbone.localSync = function(method, model, options) {
    // 使用时Store实例必须放在model或collection的localStorage里
    var store = model.localStorage || model.collection.localStorage;
    // $.Deffered是jQuery里用来管理回调的东西, $.resolve(resp)可以看成是success，$.reject(resp)对应fail
    var resp, errorMessage, syncDfd = $.Deferred && $.Deferred();

    try {
      // 发现没有"patch"，那么model.save({patch:true})的时候就拿不到resp了，可能版本问题，简单加上
      switch (method) {
        case "read":
          // model.id是否存在判断调用fetch的是model还是collection，后者的话则加载所有models
          resp = model.id != undefined ? store.find(model) : store.findAll();
          break;
        case "create":
          resp = store.create(model);
          break;
        case "patch":
        case "update":
          resp = store.update(model);
          break;
        case "delete":
          resp = store.destroy(model);
          break;
      }

    } catch (error) {
      if (error.code === DOMException.QUOTA_EXCEEDED_ERR && window.localStorage.length === 0)
        errorMessage = "Private browsing is unsupported";
      else
        errorMessage = error.message;
    }
    // sync成功
    if (resp) {
      model.trigger("sync", model, resp, options);
      if (options && options.success)
    // 这里的options.success已经不是我们调用方法时在末尾加上的{success: function(model,resp,options){...}}回调函数了
    // 我们的回调函数包括在这个options.success里面，error也是一样
        options.success(resp);
      if (syncDfd)
        syncDfd.resolve(resp);
      // sync失败
    } else {
      errorMessage = errorMessage ? errorMessage : "Record Not Found";

      if (options && options.error)
        options.error(errorMessage);
      if (syncDfd)
        syncDfd.reject(errorMessage);
    }


    if (options && options.complete) options.complete(resp);

    return syncDfd && syncDfd.promise();
  };

  // 保留原Backbone.sync
  Backbone.ajaxSync = Backbone.sync;

  // 如果使用了该插件，则用重写后的sync，否则用原始的sync
  Backbone.getSyncMethod = function(model) {
    if (model.localStorage || (model.collection && model.collection.localStorage)) {
      return Backbone.localSync;
    }

    return Backbone.ajaxSync;
  };


  Backbone.sync = function(method, model, options) {
    return Backbone.getSyncMethod(model).apply(this, [method, model, options]);
  };

  return Backbone.LocalStorage;
}));

使用起来还是挺方便的，记得把以前的set, add, remove换成save, create, destroy这些会调用Backbone.sync的方法。

不过这个插件有个明显的问题，就是当它擅自给model添加GUID时，会触发model的’change'事件，在之前的todo栗子里每次创建一个todo都会render两次，所以在render里我们还要加上一句

if (this.model.changed.id !== undefined) return;