]>
git.wh0rd.org - tt-rss.git/blob - lib/dojo/store/api/Store.js.uncompressed.js
1 define("dojo/store/api/Store", ["../../_base/declare"], function(declare
){
6 var Store
= declare(null, {
8 // This is an abstract API that data provider implementations conform to.
9 // This file defines methods signatures and intentionally leaves all the
10 // methods unimplemented. For more information on the ,
11 // please visit: http://dojotoolkit.org/reference-guide/dojo/store.html
12 // Every method and property is optional, and is only needed if the functionality
13 // it provides is required.
14 // Every method may return a promise for the specified return value if the
15 // execution of the operation is asynchronous (except
16 // for query() which already defines an async return value).
19 // If the store has a single primary key, this indicates the property to use as the
20 // identity property. The values of this property should be unique.
23 // queryEngine: Function
24 // If the store can be queried locally (on the client side in JS), this defines
25 // the query engine to use for querying the data store.
26 // This takes a query and query options and returns a function that can execute
27 // the provided query on a JavaScript array. The queryEngine may be replace to
28 // provide more sophisticated querying capabilities. For example:
29 // | var query = store.queryEngine({foo:"bar"}, {count:10});
30 // | query(someArray) -> filtered array
31 // The returned query function may have a "matches" property that can be
32 // used to determine if an object matches the query. For example:
33 // | query.matches({id:"some-object", foo:"bar"}) -> true
34 // | query.matches({id:"some-object", foo:"something else"}) -> false
39 // Retrieves an object by its identity
41 // The identity to use to lookup the object
43 // The object in the store that matches the given id.
45 getIdentity: function(object
){
47 // Returns an object's identity
49 // The object to get the identity from
50 // returns: String|Number
52 put: function(object
, directives
){
56 // The object to store.
57 // directives: dojo/store/api/Store.PutDirectives?
58 // Additional directives for storing objects.
59 // returns: Number|String
61 add: function(object
, directives
){
63 // Creates an object, throws an error if the object already exists
65 // The object to store.
66 // directives: dojo/store/api/Store.PutDirectives?
67 // Additional directives for creating objects.
68 // returns: Number|String
72 // Deletes an object by its identity
74 // The identity to use to delete the object
75 delete this.index
[id
];
77 idProperty
= this.idProperty
;
78 for(var i
= 0, l
= data
.length
; i
< l
; i
++){
79 if(data
[i
][idProperty
] == id
){
85 query: function(query
, options
){
87 // Queries the store for objects. This does not alter the store, but returns a
88 // set of data from the store.
89 // query: String|Object|Function
90 // The query to use for retrieving objects from the store.
91 // options: dojo/store/api/Store.QueryOptions
92 // The optional arguments to apply to the resultset.
93 // returns: dojo/store/api/Store.QueryResults
94 // The results of the query, extended with iterative methods.
97 // Given the following store:
99 // ...find all items where "prime" is true:
101 // | store.query({ prime: true }).forEach(function(object){
102 // | // handle each object
105 transaction: function(){
107 // Starts a new transaction.
108 // Note that a store user might not call transaction() prior to using put,
109 // delete, etc. in which case these operations effectively could be thought of
110 // as "auto-commit" style actions.
111 // returns: dojo/store/api/Store.Transaction
112 // This represents the new current transaction.
114 getChildren: function(parent
, options
){
116 // Retrieves the children of an object.
118 // The object to find the children of.
119 // options: dojo/store/api/Store.QueryOptions?
120 // Additional options to apply to the retrieval of the children.
121 // returns: dojo/store/api/Store.QueryResults
122 // A result set of the children of the parent object.
124 getMetadata: function(object
){
126 // Returns any metadata about the object. This may include attribution,
127 // cache directives, history, or version information.
129 // The object to return metadata for.
131 // An object containing metadata.
135 Store
.PutDirectives
= declare(null, {
137 // Directives passed to put() and add() handlers for guiding the update and
138 // creation of stored objects.
139 // id: String|Number?
140 // Indicates the identity of the object if a new object is created
142 // If the collection of objects in the store has a natural ordering,
143 // this indicates that the created or updated object should be placed before the
144 // object specified by the value of this property. A value of null indicates that the
145 // object should be last.
147 // If the store is hierarchical (with single parenting) this property indicates the
148 // new parent of the created or updated object.
149 // overwrite: Boolean?
150 // If this is provided as a boolean it indicates that the object should or should not
151 // overwrite an existing object. A value of true indicates that a new object
152 // should not be created, the operation should update an existing object. A
153 // value of false indicates that an existing object should not be updated, a new
154 // object should be created (which is the same as an add() operation). When
155 // this property is not provided, either an update or creation is acceptable.
158 Store
.SortInformation
= declare(null, {
160 // An object describing what attribute to sort on, and the direction of the sort.
162 // The name of the attribute to sort on.
163 // descending: Boolean
164 // The direction of the sort. Default is false.
167 Store
.QueryOptions
= declare(null, {
169 // Optional object with additional parameters for query results.
170 // sort: dojo/store/api/Store.SortInformation[]?
171 // A list of attributes to sort on, as well as direction
173 // | [{attribute:"price, descending: true}].
174 // If the sort parameter is omitted, then the natural order of the store may be
175 // applied if there is a natural order.
177 // The first result to begin iteration on
179 // The number of how many results should be returned.
182 Store
.QueryResults
= declare(null, {
184 // This is an object returned from query() calls that provides access to the results
185 // of a query. Queries may be executed asynchronously.
187 forEach: function(callback
, thisObject
){
189 // Iterates over the query results, based on
190 // https://developer.mozilla.org/en/Core_JavaScript_1.5_Reference/Objects/Array/forEach.
191 // Note that this may executed asynchronously. The callback may be called
192 // after this function returns.
194 // Function that is called for each object in the query results
196 // The object to use as |this| in the callback.
199 filter: function(callback
, thisObject
){
201 // Filters the query results, based on
202 // https://developer.mozilla.org/en/Core_JavaScript_1.5_Reference/Objects/Array/filter.
203 // Note that this may executed asynchronously. The callback may be called
204 // after this function returns.
206 // Function that is called for each object in the query results
208 // The object to use as |this| in the callback.
209 // returns: dojo/store/api/Store.QueryResults
211 map: function(callback
, thisObject
){
213 // Maps the query results, based on
214 // https://developer.mozilla.org/en/Core_JavaScript_1.5_Reference/Objects/Array/map.
215 // Note that this may executed asynchronously. The callback may be called
216 // after this function returns.
218 // Function that is called for each object in the query results
220 // The object to use as |this| in the callback.
221 // returns: dojo/store/api/Store.QueryResults
223 then: function(callback
, errorHandler
){
225 // This registers a callback for when the query is complete, if the query is asynchronous.
226 // This is an optional method, and may not be present for synchronous queries.
228 // This is called when the query is completed successfully, and is passed a single argument
229 // that is an array representing the query results.
231 // This is called if the query failed, and is passed a single argument that is the error
234 observe: function(listener
, includeAllUpdates
){
236 // This registers a callback for notification of when data is modified in the query results.
237 // This is an optional method, and is usually provided by dojo/store/Observable.
238 // listener: Function
239 // The listener function is called when objects in the query results are modified
240 // to affect the query result. The listener function is called with the following arguments:
241 // | listener(object, removedFrom, insertedInto);
243 // - The object parameter indicates the object that was create, modified, or deleted.
244 // - The removedFrom parameter indicates the index in the result array where
245 // the object used to be. If the value is -1, then the object is an addition to
246 // this result set (due to a new object being created, or changed such that it
247 // is a part of the result set).
248 // - The insertedInto parameter indicates the index in the result array where
249 // the object should be now. If the value is -1, then the object is a removal
250 // from this result set (due to an object being deleted, or changed such that it
251 // is not a part of the result set).
252 // includeAllUpdates:
253 // This indicates whether or not to include object updates that do not affect
254 // the inclusion or order of the object in the query results. By default this is false,
255 // which means that if any object is updated in such a way that it remains
256 // in the result set and it's position in result sets is not affected, then the listener
257 // will not be fired.
260 // total: Number|Promise?
261 // This property should be included in if the query options included the "count"
262 // property limiting the result set. This property indicates the total number of objects
263 // matching the query (as if "start" and "count" weren't present). This may be
264 // a promise if the query is asynchronous.
268 Store
.Transaction
= declare(null, {
270 // This is an object returned from transaction() calls that represents the current
275 // Commits the transaction. This may throw an error if it fails. Of if the operation
276 // is asynchronous, it may return a promise that represents the eventual success
277 // or failure of the commit.
279 abort: function(callback
, thisObject
){
281 // Aborts the transaction. This may throw an error if it fails. Of if the operation
282 // is asynchronous, it may return a promise that represents the eventual success
283 // or failure of the abort.