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

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