lib/dojo/data/api/Notification.js.uncompressed.js

   1 define("dojo/data/api/Notification", ["../../_base/declare", "./Read"], function(declare, Read){
   2
   3 // module:
   4 //              dojo/data/api/Notification
   5
   6 return declare("dojo.data.api.Notification", Read, {
   7         // summary:
   8         //              This is an abstract API that data provider implementations conform to.
   9         //              This file defines functions signatures and intentionally leaves all the
  10         //              functions unimplemented.
  11         // description:
  12         //              This API defines a set of APIs that all datastores that conform to the
  13         //              Notifications API must implement.  In general, most stores will implement
  14         //              these APIs as no-op functions for users who wish to monitor them to be able
  15         //              to connect to then via dojo.connect().  For non-users of dojo.connect,
  16         //              they should be able to just replace the function on the store to obtain
  17         //               notifications.  Both read-only and read-write stores may implement
  18         //              this feature.  In the case of a read-only store, this feature makes sense if
  19         //              the store itself does internal polling to a back-end server and periodically updates
  20         //              its cache of items (deletes, adds, and updates).
  21         // example:
  22         //      |       function onSet(item, attribute, oldValue, newValue){
  23         //      |               //Do something with the information...
  24         //      |       };
  25         //      |       var store = new some.newStore();
  26         //      |       dojo.connect(store, "onSet", onSet);
  27
  28         getFeatures: function(){
  29                 // summary:
  30                 //              See dojo/data/api/Read.getFeatures()
  31                 return {
  32                         'dojo.data.api.Read': true,
  33                         'dojo.data.api.Notification': true
  34                 };
  35         },
  36
  37         onSet: function(/* dojo/data/api/Item */ item,
  38                                         /* attribute-name-string */ attribute,
  39                                         /* object|array */ oldValue,
  40                                         /* object|array */ newValue){
  41                 // summary:
  42                 //              This function is called any time an item is modified via setValue, setValues, unsetAttribute, etc.
  43                 // description:
  44                 //              This function is called any time an item is modified via setValue, setValues, unsetAttribute, etc.
  45                 //              Its purpose is to provide a hook point for those who wish to monitor actions on items in the store
  46                 //              in a simple manner.  The general expected usage is to dojo.connect() to the store's
  47                 //              implementation and be called after the store function is called.
  48                 // item:
  49                 //              The item being modified.
  50                 // attribute:
  51                 //              The attribute being changed represented as a string name.
  52                 // oldValue:
  53                 //              The old value of the attribute.  In the case of single value calls, such as setValue, unsetAttribute, etc,
  54                 //              this value will be generally be an atomic value of some sort (string, int, etc, object).  In the case of
  55                 //              multi-valued attributes, it will be an array.
  56                 // newValue:
  57                 //              The new value of the attribute.  In the case of single value calls, such as setValue, this value will be
  58                 //              generally be an atomic value of some sort (string, int, etc, object).  In the case of multi-valued attributes,
  59                 //              it will be an array.  In the case of unsetAttribute, the new value will be 'undefined'.
  60                 // returns:
  61                 //              Nothing.
  62                 throw new Error('Unimplemented API: dojo.data.api.Notification.onSet');
  63         },
  64
  65         onNew: function(/* dojo/data/api/Item */ newItem, /*object?*/ parentInfo){
  66                 // summary:
  67                 //              This function is called any time a new item is created in the store.
  68                 //              It is called immediately after the store newItem processing has completed.
  69                 // description:
  70                 //              This function is called any time a new item is created in the store.
  71                 //              It is called immediately after the store newItem processing has completed.
  72                 // newItem:
  73                 //              The item created.
  74                 // parentInfo:
  75                 //              An optional javascript object that is passed when the item created was placed in the store
  76                 //              hierarchy as a value f another item's attribute, instead of a root level item.  Note that if this
  77                 //              function is invoked with a value for parentInfo, then onSet is not invoked stating the attribute of
  78                 //              the parent item was modified.  This is to avoid getting two notification  events occurring when a new item
  79                 //              with a parent is created.  The structure passed in is as follows:
  80                 // |    {
  81                 // |            item: someItem,                                                 //The parent item
  82                 // |            attribute:      "attribute-name-string",        //The attribute the new item was assigned to.
  83                 // |            oldValue: something     //Whatever was the previous value for the attribute.
  84                 // |                                    //If it is a single-value attribute only, then this value will be a single value.
  85                 // |                                    //If it was a multi-valued attribute, then this will be an array of all the values minus the new one.
  86                 // |            newValue: something     //The new value of the attribute.  In the case of single value calls, such as setValue, this value will be
  87                 // |                                    //generally be an atomic value of some sort (string, int, etc, object).  In the case of multi-valued attributes,
  88                 // |                                    //it will be an array.
  89                 // |    }
  90                 // returns:
  91                 //              Nothing.
  92                 throw new Error('Unimplemented API: dojo.data.api.Notification.onNew');
  93         },
  94
  95         onDelete: function(/* dojo/data/api/Item */ deletedItem){
  96                 // summary:
  97                 //              This function is called any time an item is deleted from the store.
  98                 //              It is called immediately after the store deleteItem processing has completed.
  99                 // description:
 100                 //              This function is called any time an item is deleted from the store.
 101                 //              It is called immediately after the store deleteItem processing has completed.
 102                 // deletedItem:
 103                 //              The item deleted.
 104                 // returns:
 105                 //              Nothing.
 106                 throw new Error('Unimplemented API: dojo.data.api.Notification.onDelete');
 107         }
 108 });
 109
 110 });