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