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");
6 dojo.declare("dojo.data.api.Write", dojo.data.api.Read, {
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.
12 getFeatures: function(){
14 // See dojo.data.api.Read.getFeatures()
16 'dojo.data.api.Read': true,
17 'dojo.data.api.Write': true
21 newItem: function(/* Object? */ keywordArgs, /*Object?*/ parentInfo){
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.
34 // A javascript object defining the initial content of the item as a set of JavaScript 'property name: value' pairs.
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:
42 // attribute: "attribute-name-string"
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.
51 // | var kermit = store.newItem({name: "Kermit", color:[blue, green]});
54 throw new Error('Unimplemented API: dojo.data.api.Write.newItem');
55 return newItem; // item
58 deleteItem: function(/* item */ item){
60 // Deletes an item from the store.
63 // The item to delete.
66 // Throws an exception if the argument *item* is not an item
67 // (if store.isItem(item) returns false).
69 // | var success = store.deleteItem(kermit);
70 throw new Error('Unimplemented API: dojo.data.api.Write.deleteItem');
71 return false; // boolean
74 setValue: function( /* item */ item,
75 /* string */ attribute,
76 /* almost anything */ value){
78 // Sets the value of an attribute on an item.
79 // Replaces any previous value or values.
82 // The item to modify.
84 // The attribute of the item to change represented as a string name.
86 // The value to assign to the item.
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.
93 // | var success = store.set(kermit, "color", "green");
94 throw new Error('Unimplemented API: dojo.data.api.Write.setValue');
95 return false; // boolean
98 setValues: function(/* item */ item,
99 /* string */ attribute,
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).
109 // The item to modify.
111 // The attribute of the item to change represented as a string name.
113 // An array of values to assign to the attribute..
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.
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
126 unsetAttribute: function( /* item */ item,
127 /* string */ attribute){
129 // Deletes all the values of an attribute on an item.
132 // The item to modify.
134 // The attribute of the item to unset represented as a string.
137 // Throws an exception if *item* is not an item, or if *attribute*
138 // is neither an attribute object or a string.
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
146 save: function(/* object */ keywordArgs){
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.
155 // onComplete: function
160 // The *onComplete* parameter.
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.
167 // The *onError* parameter.
168 // function(errorData);
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
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)
185 // Nothing. Since the saves are generally asynchronous, there is
186 // no need to return anything. All results are passed via callbacks.
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');
195 // Discards any unsaved changes.
197 // Discards any unsaved changes.
200 // | var success = store.revert();
201 throw new Error('Unimplemented API: dojo.data.api.Write.revert');
202 return false; // boolean
205 isDirty: function(/* item? */ item){
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
213 // The item to check.
216 // Throws an exception if isDirty() is passed an argument and the
217 // argument is not an item.
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