dojo data 接口详解
本文摘自http://www.dojochina.com/?q=node/653。
dojo/data
- 主要定义了dojo/data的接口结构，以及最基本的几个util
1. dojo/data/api
- 定义接口结构
1.1. Read.js
1.1.1. 依赖
dojo.require("dojo.data.api.Request");
1.1.2. 成员函数
getValue: function( /* item */ item, /* attribute-name-string */ attribute, /* value? */ defaultValue)
- 摘要：
- 返回一个单独的属性值
- 当且仅当item中不存在attribute属性时，返回defaultValue设置的值
- 当且仅当item中的attirebute值为空时，返回null
- 如果item中没有attribute属性，且没有指定defaultValue，则返回undefined
- 描述：如果 store.hasAttribute(item, attribute) 返回 false，则 store.getValue(item, attribute) 将返回undefined
- 异常：当item并不是item类型，或attribute不是字符串时，抛出异常。
- 举例：
var darthVader = store.getValue(lukeSkywalker, "father");
getValues: function(/* item */ item, /* attribute-name-string */ attribute)
- 摘要：
- 与getValue函数类似，只是返回的为数组
- 如果item并不含有那个属性的值，则返回为 ［］，也就是说，如果如果 store.hasAttribute(item, attribute) 返回 false，则 store.getValues(item, attribute) 将返回 ［］
- 举例：
var friendsOfLuke = store.getValues(lukeSkywalker, "friends");
getAttributes: function(/* item */ item)
- 摘要：
- 返回那个item所包含的所有属性的数组
- 如果item没有任何属性，也会返回一个数组：［］
- 举例：
var array = store.getAttributes(kermit);
hasAttribute: function( /* item */ item, /* attribute-name-string */ attribute)
- 摘要：如果item中包含指定的attribute属性，则返回true，否则返回false
- 举例：
var trueOrFalse = store.hasAttribute(kermit, "color");
containsValue: function(/* item */ item, /* attribute-name-string */ attribute, /* anything */ value)
- 摘要：如果value的值是那个item使用getValues()所返回的值数组中的一个，则这个函数返回true
- 举例：
var trueOrFalse = store.containsValue(kermit, "color", "green");
isItem: function(/* anything */ something)
- 摘要： 如果somethind是一个item并且是从指定的store对象实例化而来的，就返回true，否则返回false
- 举例：
var yes = store.isItem(store.newItem());
var no = store.isItem("green");
isItemLoaded: function(/* anything */ something)
- 摘要：
- 如果isItem(something)返回false的话，本函数就返回false
- 如果isItem(something)返回true，但这个item还没有被完全载入内存（比如没有完全从服务器去回来），本函数就返回false
- 举例：
var yes = store.isItemLoaded(store.newItem());
var no = store.isItemLoaded("green");
loadItem: function(/* object */ keywordArgs)
- 摘要：
- 用于载入item，之后的isItemLoaded()函数才能返回true
- 如果在loadItem()调用之前，先调用isItemLoaded()并且该函数返回true，则loadItem()不需要做任何事情，而且也不会再调用载入数据的回调函数。所以调用loadItem()之前，要先检查是否已经载入过那个item了。
- keywordArgs：
- item: Object, 必要
- onItem: Function(item), item载入完成之后要执行的回调函数
- onError: Function(error), 发生错误时调用的函数
- scope: Object, 如果指定了这个参数，则上面的回调函数中的this将指向这个对象，否则，指向dojo.global()
fetch: function(/* Object */ keywordArgs)
- 摘要： 给定查询query，以及一些预定义的选项，比如返回item的start和count，这个函数就会自动执行查询，并把返回结果作为数据items返回。
- 描述：
- 每次都会返回（并立即返回）一个Request对象
- 最简单的Request，就是传入给fetch的keywordargs参数，以及一个附加的函数 abort()。
- 返回的这个Request对象，可以在后面用来取消fetch()
- 所有返回的数据项以及在回调函数中传递的数据，都在fetch的参数中定义，而且并不会出现在Request对象里。
- 更多信息参见 dojo.data.api.Request
- keywordsArgs：
- query: query-string or query-object,
- queryOptions: object,
- onBegin: Function,
- onItem: Function,
- onComplete: Function,
- onError: Function,
- scope: object,
- start: int
- count: int
- sort: array
getFeatures: function()
- 摘要：
- 返回这个接口实现的特性
- 可能是如下'dojo.data.api.Read', 'dojo.data.api.Write', 'dojo.data.api.Identity', and 'dojo.data.api.Attribution'
close: function(/*dojo.data.api.Request || keywordArgs || null */ request)
- 举例：
var request = store.fetch({onComplete: doSomething});
...
store.close(request);
getLabel: function(/* item */ item)
- 摘要：返回item所含有的标签的人类可读形式信息，比如一个person条目的getLabel结果会是："firstname lastname"
getLabelAttributes: function(/* item */ item)
- 摘要：返回item属性标签的数组
1.2. Write.js
1.2.1. 依赖
dojo.require("dojo.data.api.Read");
1.2.2 成员函数
getFeatures: function()
- 同data.Read.getFeatuers()
newItem: function(/* Object? */ keywordArgs, /*Object?*/ parentInfo)
- 摘要：
- 返回一个新创建的item
- 通过keywordsArgs参数来设置新对象的属性
- parentInfo: 可选的，定义当前创建的item的父节点
- parent: someItem
- attribute: "attribute-name-string"
- 举例：
var kermit = store.newItem({name: "Kermit", color:[blue, green]});
deleteItem: function(/* item */ item)
- 举例：
var success = store.deleteItem(kermit)
setValue: function( /* item */ item, /* string */ attribute, /* almost anything */ value)
- 摘要：
- 设置item中指定属性的值
- 替换原有的值
- 举例：
var success = store.set(kermit, "color", "green");
setValues: function(/* item */ item, /* string */ attribute, /* array */ values)
- 摘要：
- 给指定的item的指定属性添加values数组中的每一个值
- 替换原先的value或者values
- 调用 store.setValues(x, y, [])，与调用 store.unsetAttribute(x, y) 的效果相同
- 举例：
var success = store.setValues(kermit, "color", ["green", "aqua"]);
success = store.setValues(kermit, "color", []);
if (success) {assert(!store.hasAttribute(kermit, "color"));}
unsetAttribute: function( /* item */ item, /* string */ attribute)
- 摘要： 删除指定item的指定属性上的全部值
- 举例：
var success = store.unsetAttribute(kermit, "color");
if (success) {assert(!store.hasAttribute(kermit, "color"));}
save: function(/* object */ keywordArgs)
- 摘要：
- 将所有修改保存到服务器上
- 运行结果会被传入save所支持的一系列回调函数中
- keywordsArgs
- onComplete: function()
- onError: function(errorData)
- scope: object
- 举例：
store.save({onComplete: onSave});
store.save({scope: fooObj, onComplete: onSave, onError: saveFailed});
revert: function()
- 摘要：丢弃所有没有保存的修改
- 举例：
var success = store.revert()
isDirty: function(/* item? */ item)
- 摘要：
- 如果该item在最后一次save()之后被修改过，则返回true
- 如果没有传入item，则返回整个store对象，若其中任何一个item在最后一次save()之后被修改过，就返回ture
- 举例：
var trueOrFalse = store.isDirty(kermit); // true if kermit is dirty
var trueOrFalse = store.isDirty(); // true if any item is dirty
1.3. Identity.js (ToBeContinued)
1.4. Notification.js (ToBeContinued)
1.5. Request.js (ToBeContinued)
2. dojo/data/util
2.1. filter.js
dojo.data.util.filter.patternToRegExp = function(/*String*/pattern, /*boolean?*/ ignoreCase)
- 摘要：这是一个帮助函数，它负责进行简单的正则匹配
2.2. simpleFetch.js (ToBeContinued)
