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