Notification API--dojo学习

当使用data和items时，在dojo.data datastore中创建、删除、修改items的时候，

能够得到通知是非常有用的，即我们所说事件，stores即数据存储提供了

dojo.data.api.Notification来实现这项功能。这个函数集合定义了在一个Item上的

一些监视事件，比如：create,modify,delete等。

 

API Requirements

对于所有dataStores，不是所有的stores都实施了这些API,对于实施了这些API的stores，都遵循下列假定：
1、Items上的所有改变的事件(create,set attribute and delete)将触发对相关store通知函数的调用
2、Notifications发生在store级别并且对所有items都会发生。

Examples

这些函数对于change事件通常有两种listening模式. 第一种模式是使用 dojo.connect() event model来绑定你自定义的一个函数到store上，当无论何时store调用onSet, onNew, and onDelete时，将调用你的这个函数. 第二种模式是在store上使用自定义的逻辑来替换notification functions的实现方案. Example usage of such functions are provided in the following examples.

Basic dojo.connect

这个例子演示了如何使用dojo.connect to connect the datastores onNew function with one of your own functions:

var store = some.NotifyWriteStore();
var alertOnNew = function(item) {
  var label = store.getLabel(item);
  alert("New item was created: [" + label + "]");
};
dojo.connect(store, "onNew", alertOnNew);
//An alert should be thrown when this completes

var newItem = store.newItem({foo:"bar"});

Replacing the onNew function

本例演示了如何使用自定义函数覆盖dataStore的onNew函数:

var store = some.NotifyWriteStore();
store.onNew = function(item) {
  var label = this.getLabel(item);
  alert("New item was created: [" + label + "]");
};
//An alert should be thrown when this completes
var newItem = store.newItem({foo:"bar"});

The Complete Feature

For convenience, the complete feature from dojo/data/api/Notification.js is defined below:

onSet

onSet: function(item, attribute, oldValue, newValue)

summary:

任何时候一个Item被setValue,setValues,unsetAttribute等函数修改的时候，onSet将会被调用.

description:

它的用途是提供一个 hook point 以供希望在store里监视items上的行为. The general expected usage is to dojo.connect() to the store's implementation and be called after the store function is called.

parameters:

parameter	type	description
item	object	被修改的item.
attribute	string	被修改的属性，以 string name表示.
oldValue	object or array	属性的原值. In the case of single value calls, such as setValue, unsetAttribute, etc, this value will be generally be an atomic value of some sort (string, int, etc, object). In the case of multi-valued attributes, it will be an array.
newValue	object or array	属性的新值. In the case of single value calls, such as setValue, this value will be generally be an atomic value of some sort (string, int, etc, object). In the case of multi-valued attributes, it will be an array. In the case of unsetAttribute, the new value will be 'undefined'.

returns:

Nothing.

onNew

onNew: function(newItem, parentInfo)

summary:

任何时候在store里一个新的item被创建时，这个函数被调用.在store的newItem进程完成后将后立即被调用.

description:

This function is called any time a new item is created in the store. It is called immediately after the store newItem processing has completed.

parameters:

parameter	type	description
newItem	object	创建的The item.
parentInfo	object	一个可选的javascript object，当item被创建并放到store中的层次结构中后会从另一个item的属性传递一个值, instead of a root level item. Note that if this function is invoked with a value for parentInfo, then onSet is not invoked stating the attribute of the parent item was modified. This is to avoid getting two notification events occurring when a new item with a parent is created.

The structure of the parameter parentInfo is as follows:

{
  // The parent item:
  item: someItem,
  // The attribute the new item was assigned to:
  attribute: "attribute-name-string",
  // Whatever was the previous value for the attribute:
  // In the case of single value calls, such as setValue, unsetAttribute, etc,
  // this value will be generally be an atomic value of some sort (string, int, etc, object).
  // In the case of multi-valued attributes, it will be an array of all the values minues the new one.
  oldValue: something,
  // The new value of the attribute:
  // In the case of single value calls, such as setValue, this value will be
  // generally be an atomic value of some sort (string, int, etc, object).
  // In the case of multi-valued attributes, it will be an array.
  newValue: something
}

returns:

Nothing.

onDelete

onDelete: function(deletedItem)

summary:

This function is called any time an item is deleted from the store. It is called immediately after the store deleteItem processing has completed.

description:

This function is called any time an item is deleted from the store. It is called immediately after the store deleteItem processing has completed.

parameters:

parameter	type	description
deletedItem	object	The item deleted.

returns:

Nothing.