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