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

   1 define("dojo/data/api/Write", ["../..", "./Read"], function(dojo) {
   2         // module:
   3         //              dojo/data/api/Write
   4         // summary:
   5         //              TODOC
   6
   7
   8 dojo.declare("dojo.data.api.Write", dojo.data.api.Read, {
   9         // summary:
  10         //              This is an abstract API that data provider implementations conform to.
  11         //              This file defines function signatures and intentionally leaves all the
  12         //              functionss unimplemented.
  13
  14         getFeatures: function(){
  15                 // summary:
  16                 //              See dojo.data.api.Read.getFeatures()
  17                 return {
  18                         'dojo.data.api.Read': true,
  19                         'dojo.data.api.Write': true
  20                 };
  21         },
  22
  23         newItem: function(/* Object? */ keywordArgs, /*Object?*/ parentInfo){
  24                 // summary:
  25                 //              Returns a newly created item.  Sets the attributes of the new
  26                 //              item based on the *keywordArgs* provided.  In general, the attribute
  27                 //              names in the keywords become the attributes in the new item and as for
  28                 //              the attribute values in keywordArgs, they become the values of the attributes
  29                 //              in the new item.  In addition, for stores that support hierarchical item
  30                 //              creation, an optional second parameter is accepted that defines what item is the parent
  31                 //              of the new item and what attribute of that item should the new item be assigned to.
  32                 //              In general, this will assume that the attribute targetted is multi-valued and a new item
  33                 //              is appended onto the list of values for that attribute.
  34                 //
  35                 // keywordArgs:
  36                 //              A javascript object defining the initial content of the item as a set of JavaScript 'property name: value' pairs.
  37                 // parentInfo:
  38                 //              An optional javascript object defining what item is the parent of this item (in a hierarchical store.  Not all stores do hierarchical items),
  39                 //              and what attribute of that parent to assign the new item to.  If this is present, and the attribute specified
  40                 //              is a multi-valued attribute, it will append this item into the array of values for that attribute.  The structure
  41                 //              of the object is as follows:
  42                 //              {
  43                 //                      parent: someItem,
  44                 //                      attribute: "attribute-name-string"
  45                 //              }
  46                 //
  47                 // exceptions:
  48                 //              Throws an exception if *keywordArgs* is a string or a number or
  49                 //              anything other than a simple anonymous object.
  50                 //              Throws an exception if the item in parentInfo is not an item from the store
  51                 //              or if the attribute isn't an attribute name string.
  52                 // example:
  53                 //      |       var kermit = store.newItem({name: "Kermit", color:[blue, green]});
  54
  55                 throw new Error('Unimplemented API: dojo.data.api.Write.newItem');
  56         },
  57
  58         deleteItem: function(/* item */ item){
  59                 // summary:
  60                 //              Deletes an item from the store.
  61                 //
  62                 // item:
  63                 //              The item to delete.
  64                 //
  65                 // exceptions:
  66                 //              Throws an exception if the argument *item* is not an item
  67                 //              (if store.isItem(item) returns false).
  68                 // example:
  69                 //      |       var success = store.deleteItem(kermit);
  70                 throw new Error('Unimplemented API: dojo.data.api.Write.deleteItem');
  71         },
  72
  73         setValue: function(     /* item */ item,
  74                                                 /* string */ attribute,
  75                                                 /* almost anything */ value){
  76                 // summary:
  77                 //              Sets the value of an attribute on an item.
  78                 //              Replaces any previous value or values.
  79                 //
  80                 // item:
  81                 //              The item to modify.
  82                 // attribute:
  83                 //              The attribute of the item to change represented as a string name.
  84                 // value:
  85                 //              The value to assign to the item.
  86                 //
  87                 // exceptions:
  88                 //              Throws an exception if *item* is not an item, or if *attribute*
  89                 //              is neither an attribute object or a string.
  90                 //              Throws an exception if *value* is undefined.
  91                 // example:
  92                 //      |       var success = store.set(kermit, "color", "green");
  93                 throw new Error('Unimplemented API: dojo.data.api.Write.setValue');
  94         },
  95
  96         setValues: function(/* item */ item,
  97                                                 /* string */ attribute,
  98                                                 /* array */ values){
  99                 // summary:
 100                 //              Adds each value in the *values* array as a value of the given
 101                 //              attribute on the given item.
 102                 //              Replaces any previous value or values.
 103                 //              Calling store.setValues(x, y, []) (with *values* as an empty array) has
 104                 //              the same effect as calling store.unsetAttribute(x, y).
 105                 //
 106                 // item:
 107                 //              The item to modify.
 108                 // attribute:
 109                 //              The attribute of the item to change represented as a string name.
 110                 // values:
 111                 //              An array of values to assign to the attribute..
 112                 //
 113                 // exceptions:
 114                 //              Throws an exception if *values* is not an array, if *item* is not an
 115                 //              item, or if *attribute* is neither an attribute object or a string.
 116                 // example:
 117                 //      |       var success = store.setValues(kermit, "color", ["green", "aqua"]);
 118                 //      |       success = store.setValues(kermit, "color", []);
 119                 //      |       if (success) {assert(!store.hasAttribute(kermit, "color"));}
 120                 throw new Error('Unimplemented API: dojo.data.api.Write.setValues');
 121         },
 122
 123         unsetAttribute: function(       /* item */ item,
 124                                                                 /* string */ attribute){
 125                 // summary:
 126                 //              Deletes all the values of an attribute on an item.
 127                 //
 128                 // item:
 129                 //              The item to modify.
 130                 // attribute:
 131                 //              The attribute of the item to unset represented as a string.
 132                 //
 133                 // exceptions:
 134                 //              Throws an exception if *item* is not an item, or if *attribute*
 135                 //              is neither an attribute object or a string.
 136                 // example:
 137                 //      |       var success = store.unsetAttribute(kermit, "color");
 138                 //      |       if (success) {assert(!store.hasAttribute(kermit, "color"));}
 139                 throw new Error('Unimplemented API: dojo.data.api.Write.clear');
 140         },
 141
 142         save: function(/* object */ keywordArgs){
 143                 // summary:
 144                 //              Saves to the server all the changes that have been made locally.
 145                 //              The save operation may take some time and is generally performed
 146                 //              in an asynchronous fashion.  The outcome of the save action is
 147                 //              is passed into the set of supported callbacks for the save.
 148                 //
 149                 // keywordArgs:
 150                 //              {
 151                 //                      onComplete: function
 152                 //                      onError: function
 153                 //                      scope: object
 154                 //              }
 155                 //
 156                 //      The *onComplete* parameter.
 157                 //              function();
 158                 //
 159                 //              If an onComplete callback function is provided, the callback function
 160                 //              will be called just once, after the save has completed.  No parameters
 161                 //              are generally passed to the onComplete.
 162                 //
 163                 //      The *onError* parameter.
 164                 //              function(errorData);
 165                 //
 166                 //              If an onError callback function is provided, the callback function
 167                 //              will be called if there is any sort of error while attempting to
 168                 //              execute the save.  The onError function will be based one parameter, the
 169                 //              error.
 170                 //
 171                 //      The *scope* parameter.
 172                 //              If a scope object is provided, all of the callback function (
 173                 //              onComplete, onError, etc) will be invoked in the context of the scope
 174                 //              object.  In the body of the callback function, the value of the "this"
 175                 //              keyword will be the scope object.   If no scope object is provided,
 176                 //              the callback functions will be called in the context of dojo.global.
 177                 //              For example, onComplete.call(scope) vs.
 178                 //              onComplete.call(dojo.global)
 179                 //
 180                 // returns:
 181                 //              Nothing.  Since the saves are generally asynchronous, there is
 182                 //              no need to return anything.  All results are passed via callbacks.
 183                 // example:
 184                 //      |       store.save({onComplete: onSave});
 185                 //      |       store.save({scope: fooObj, onComplete: onSave, onError: saveFailed});
 186                 throw new Error('Unimplemented API: dojo.data.api.Write.save');
 187         },
 188
 189         revert: function(){
 190                 // summary:
 191                 //              Discards any unsaved changes.
 192                 // description:
 193                 //              Discards any unsaved changes.
 194                 //
 195                 // example:
 196                 //      |       var success = store.revert();
 197                 throw new Error('Unimplemented API: dojo.data.api.Write.revert');
 198         },
 199
 200         isDirty: function(/* item? */ item){
 201                 // summary:
 202                 //              Given an item, isDirty() returns true if the item has been modified
 203                 //              since the last save().  If isDirty() is called with no *item* argument,
 204                 //              then this function returns true if any item has been modified since
 205                 //              the last save().
 206                 //
 207                 // item:
 208                 //              The item to check.
 209                 //
 210                 // exceptions:
 211                 //              Throws an exception if isDirty() is passed an argument and the
 212                 //              argument is not an item.
 213                 // example:
 214                 //      |       var trueOrFalse = store.isDirty(kermit); // true if kermit is dirty
 215                 //      |       var trueOrFalse = store.isDirty();       // true if any item is dirty
 216                 throw new Error('Unimplemented API: dojo.data.api.Write.isDirty');
 217         }
 218 });
 219
 220 return dojo.data.api.Write;
 221 });