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