]>
git.wh0rd.org - tt-rss.git/blob - lib/dojo/store/api/Store.js.uncompressed.js
1 define("dojo/store/api/Store", ["dojo/_base/declare"], function(declare
) {
3 // dojo/store/api/Store
5 // The module defines the Dojo object store interface.
7 var Store
= declare("dojo.store.api.Store", null, {
9 // This is an abstract API that data provider implementations conform to.
10 // This file defines methods signatures and intentionally leaves all the
11 // methods unimplemented. For more information on the dojo.store APIs,
12 // please visit: http://dojotoolkit.org/reference-guide/dojo/store.html
13 // Every method and property is optional, and is only needed if the functionality
14 // it provides is required.
15 // Every method may return a promise for the specified return value if the
16 // execution of the operation is asynchronous (except
17 // for query() which already defines an async return value).
20 // If the store has a single primary key, this tndicates the property to use as the
21 // identity property. The values of this property should be unique.
24 // queryEngine: Function
25 // If the store can be queried locally (on the client side in JS), this defines
26 // the query engine to use for querying the data store.
27 // This takes a query and query options and returns a function that can execute
28 // the provided query on a JavaScript array. The queryEngine may be replace to
29 // provide more sophisticated querying capabilities. For example:
30 // | var query = store.queryEngine({foo:"bar"}, {count:10});
31 // | query(someArray) -> filtered array
32 // The returned query function may have a "matches" property that can be
33 // used to determine if an object matches the query. For example:
34 // | query.matches({id:"some-object", foo:"bar"}) -> true
35 // | query.matches({id:"some-object", foo:"something else"}) -> false
40 // Retrieves an object by its identity
42 // The identity to use to lookup the object
44 // The object in the store that matches the given id.
46 getIdentity: function(object
){
48 // Returns an object's identity
50 // The object to get the identity from
51 // returns: String|Number
53 put: function(object
, directives
){
57 // The object to store.
58 // directives: dojo.store.api.Store.PutDirectives?
59 // Additional directives for storing objects.
60 // returns: Number|String
62 add: function(object
, directives
){
64 // Creates an object, throws an error if the object already exists
66 // The object to store.
67 // directives: dojo.store.api.Store.PutDirectives?
68 // Additional directives for creating objects.
69 // returns: Number|String
73 // Deletes an object by its identity
75 // The identity to use to delete the object
76 delete this.index
[id
];
78 idProperty
= this.idProperty
;
79 for(var i
= 0, l
= data
.length
; i
< l
; i
++){
80 if(data
[i
][idProperty
] == id
){
86 query: function(query
, options
){
88 // Queries the store for objects. This does not alter the store, but returns a
89 // set of data from the store.
90 // query: String|Object|Function
91 // The query to use for retrieving objects from the store.
92 // options: dojo.store.api.Store.QueryOptions
93 // The optional arguments to apply to the resultset.
94 // returns: dojo.store.api.Store.QueryResults
95 // The results of the query, extended with iterative methods.
98 // Given the following store:
100 // ...find all items where "prime" is true:
102 // | store.query({ prime: true }).forEach(function(object){
103 // | // handle each object
106 transaction: function(){
108 // Starts a new transaction.
109 // Note that a store user might not call transaction() prior to using put,
110 // delete, etc. in which case these operations effectively could be thought of
111 // as "auto-commit" style actions.
112 // returns: dojo.store.api.Store.Transaction
113 // This represents the new current transaction.
115 getChildren: function(parent
, options
){
117 // Retrieves the children of an object.
119 // The object to find the children of.
120 // options: dojo.store.api.Store.QueryOptions?
121 // Additional options to apply to the retrieval of the children.
122 // returns: dojo.store.api.Store.QueryResults
123 // A result set of the children of the parent object.
125 getMetadata: function(object
){
127 // Returns any metadata about the object. This may include attribution,
128 // cache directives, history, or version information.
130 // The object to return metadata for.
132 // An object containing metadata.
136 Store
.PutDirectives = function(id
, before
, parent
, overwrite
){
138 // Directives passed to put() and add() handlers for guiding the update and
139 // creation of stored objects.
140 // id: String|Number?
141 // Indicates the identity of the object if a new object is created
143 // If the collection of objects in the store has a natural ordering,
144 // this indicates that the created or updated object should be placed before the
145 // object specified by the value of this property. A value of null indicates that the
146 // object should be last.
148 // If the store is hierarchical (with single parenting) this property indicates the
149 // new parent of the created or updated object.
150 // overwrite: Boolean?
151 // If this is provided as a boolean it indicates that the object should or should not
152 // overwrite an existing object. A value of true indicates that a new object
153 // should not be created, the operation should update an existing object. A
154 // value of false indicates that an existing object should not be updated, a new
155 // object should be created (which is the same as an add() operation). When
156 // this property is not provided, either an update or creation is acceptable.
158 this.before
= before
;
159 this.parent
= parent
;
160 this.overwrite
= overwrite
;
163 Store
.SortInformation = function(attribute
, descending
){
165 // An object describing what attribute to sort on, and the direction of the sort.
167 // The name of the attribute to sort on.
168 // descending: Boolean
169 // The direction of the sort. Default is false.
170 this.attribute
= attribute
;
171 this.descending
= descending
;
174 Store
.QueryOptions = function(sort
, start
, count
){
176 // Optional object with additional parameters for query results.
177 // sort: dojo.store.api.Store.SortInformation[]?
178 // A list of attributes to sort on, as well as direction
180 // | [{attribute:"price, descending: true}].
181 // If the sort parameter is omitted, then the natural order of the store may be
182 // applied if there is a natural order.
184 // The first result to begin iteration on
186 // The number of how many results should be returned.
192 declare("dojo.store.api.Store.QueryResults", null, {
194 // This is an object returned from query() calls that provides access to the results
195 // of a query. Queries may be executed asynchronously.
197 forEach: function(callback
, thisObject
){
199 // Iterates over the query results, based on
200 // https://developer.mozilla.org/en/Core_JavaScript_1.5_Reference/Objects/Array/forEach.
201 // Note that this may executed asynchronously. The callback may be called
202 // after this function returns.
204 // Function that is called for each object in the query results
206 // The object to use as |this| in the callback.
209 filter: function(callback
, thisObject
){
211 // Filters the query results, based on
212 // https://developer.mozilla.org/en/Core_JavaScript_1.5_Reference/Objects/Array/filter.
213 // Note that this may executed asynchronously. The callback may be called
214 // after this function returns.
216 // Function that is called for each object in the query results
218 // The object to use as |this| in the callback.
219 // returns: dojo.store.api.Store.QueryResults
221 map: function(callback
, thisObject
){
223 // Maps the query results, based on
224 // https://developer.mozilla.org/en/Core_JavaScript_1.5_Reference/Objects/Array/map.
225 // Note that this may executed asynchronously. The callback may be called
226 // after this function returns.
228 // Function that is called for each object in the query results
230 // The object to use as |this| in the callback.
231 // returns: dojo.store.api.Store.QueryResults
233 then: function(callback
, errorHandler
){
235 // This registers a callback for when the query is complete, if the query is asynchronous.
236 // This is an optional method, and may not be present for synchronous queries.
238 // This is called when the query is completed successfully, and is passed a single argument
239 // that is an array representing the query results.
241 // This is called if the query failed, and is passed a single argument that is the error
244 observe: function(listener
, includeAllUpdates
){
246 // This registers a callback for notification of when data is modified in the query results.
247 // This is an optional method, and is usually provided by dojo.store.Observable.
248 // listener: Function
249 // The listener function is called when objects in the query results are modified
250 // to affect the query result. The listener function is called with the following
252 // | listener(object, removedFrom, insertedInto);
253 // * The object parameter indicates the object that was create, modified, or deleted.
254 // * The removedFrom parameter indicates the index in the result array where
255 // the object used to be. If the value is -1, then the object is an addition to
256 // this result set (due to a new object being created, or changed such that it
257 // is a part of the result set).
258 // * The insertedInto parameter indicates the index in the result array where
259 // the object should be now. If the value is -1, then the object is a removal
260 // from this result set (due to an object being deleted, or changed such that it
261 // is not a part of the result set).
262 // includeAllUpdates:
263 // This indicates whether or not to include object updates that do not affect
264 // the inclusion or order of the object in the query results. By default this is false,
265 // which means that if any object is updated in such a way that it remains
266 // in the result set and it's position in result sets is not affected, then the listener
267 // will not be fired.
270 // total: Number|Promise?
271 // This property should be included in if the query options included the "count"
272 // property limiting the result set. This property indicates the total number of objects
273 // matching the query (as if "start" and "count" weren't present). This may be
274 // a promise if the query is asynchronous.
278 declare("dojo.store.api.Store.Transaction", null, {
280 // This is an object returned from transaction() calls that represents the current
285 // Commits the transaction. This may throw an error if it fails. Of if the operation
286 // is asynchronous, it may return a promise that represents the eventual success
287 // or failure of the commit.
289 abort: function(callback
, thisObject
){
291 // Aborts the transaction. This may throw an error if it fails. Of if the operation
292 // is asynchronous, it may return a promise that represents the eventual success
293 // or failure of the abort.