git.pond.sub.org Git - eow/blob - static/dojo-release-1.1.1/dojo/data/api/Write.js

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