dojo/store/api/Store.js

  • Provides:

    • dojo.store.api.Store

  • dojo.store.api.Store

    • type
      Function
    • summary
      This is an abstract API that data provider implementations conform to.
This file defines methods signatures and intentionally leaves all the
methods unimplemented.  For more information on the dojo.store APIs,
please visit: http://dojotoolkit.org/reference-guide/dojo/store.html
Every method and property is optional, and is only needed if the functionality
it provides is required.
Every method may return a promise for the specified return value if the
execution of the operation is asynchronous (except
for query() which already defines an async return value).

  • dojo.store.api.Store.idProperty

    • type
      String
    • summary
      If the store has a single primary key, this tndicates the property to use as the
identity property. The values of this property should be unique.

  • dojo.store.api.Store.queryEngine

    • type
      Function
    • summary
      If the store can be queried locally (on the client side in JS), this defines
the query engine to use for querying the data store.
This takes a query and query options and returns a function that can execute
the provided query on a JavaScript array. The queryEngine may be replace to
provide more sophisticated querying capabilities. For example:

 var query = store.queryEngine({foo:"bar"}, {count:10});
 query(someArray) -> filtered array
The returned query function may have a "matches" property that can be
used to determine if an object matches the query. For example:

 query.matches({id:"some-object", foo:"bar"}) -> true
 query.matches({id:"some-object", foo:"something else"}) -> false

  • dojo.store.api.Store.get

    • type
      Function
    • parameters:
      • id: (typeof Number)
        The identity to use to lookup the object
    • source: [view]
        // summary:
        //  Retrieves an object by its identity
        // id: Number
        //  The identity to use to lookup the object
        // returns: Object
        //  The object in the store that matches the given id.
    • summary
      Retrieves an object by its identity
    • return_summary
      Object
The object in the store that matches the given id.

  • dojo.store.api.Store.getIdentity

    • type
      Function
    • parameters:
      • object: (typeof Object)
        The object to get the identity from
    • source: [view]
        //  summary:
        //  Returns an object's identity
        //  object: Object
        //  The object to get the identity from
        // returns: String|Number
    • summary
      Returns an object's identity
    • return_summary
      String|Number

  • dojo.store.api.Store.put

    • type
      Function
    • parameters:
      • object: (typeof Object)
        The object to store.
      • directives: (typeof dojo.store.api.Store.PutDirectives)
        Additional directives for storing objects.
    • source: [view]
        //  summary:
        //  Stores an object
        //  object: Object
        //  The object to store.
        // directives: dojo.store.api.Store.PutDirectives?
        //  Additional directives for storing objects.
        // returns: Number|String
    • summary
      Stores an object
    • return_summary
      Number|String

  • dojo.store.api.Store.add

    • type
      Function
    • parameters:
      • object: (typeof Object)
        The object to store.
      • directives: (typeof dojo.store.api.Store.PutDirectives)
        Additional directives for creating objects.
    • source: [view]
        //  summary:
        //  Creates an object, throws an error if the object already exists
        //  object: Object
        //  The object to store.
        // directives: dojo.store.api.Store.PutDirectives?
        //  Additional directives for creating objects.
        // returns: Number|String
    • summary
      Creates an object, throws an error if the object already exists
    • return_summary
      Number|String

  • dojo.store.api.Store.remove

    • type
      Function
    • parameters:
      • id: (typeof Number)
        The identity to use to delete the object
    • source: [view]
        delete this.index[id];
        var data = this.data,
         idProperty = this.idProperty;
        for(var i = 0, l = data.length; i < l; i++){
         if(data[i][idProperty] == id){
          data.splice(i, 1);
          return;
         }
        }
    • summary
      Deletes an object by its identity

  • dojo.store.api.Store.query

    • type
      Function
    • parameters:
      • query: (typeof String|Object|Function)
        The query to use for retrieving objects from the store.
      • options: (typeof dojo.store.api.Store.QueryOptions)
        The optional arguments to apply to the resultset.
    • source: [view]
        //  summary:
        //  Queries the store for objects. This does not alter the store, but returns a
        //  set of data from the store.
        //  query: String|Object|Function
        //  The query to use for retrieving objects from the store.
        // options: dojo.store.api.Store.QueryOptions
        //  The optional arguments to apply to the resultset.
        // returns: dojo.store.api.Store.QueryResults
        //  The results of the query, extended with iterative methods.
        //
        //  example:
        //   Given the following store:
        //
        // ...find all items where "prime" is true:
        //
        // | store.query({ prime: true }).forEach(function(object){
        // |  // handle each object
        // | });
    • summary
      Queries the store for objects. This does not alter the store, but returns a
set of data from the store.
    • return_summary
      dojo.store.api.Store.QueryResults
The results of the query, extended with iterative methods.
    • example
      Given the following store:

...find all items where "prime" is true:

	store.query({ prime: true }).forEach(function(object){
		// handle each object
	});

  • dojo.store.api.Store.transaction

    • type
      Function
    • source: [view]
        // summary:
        //   Starts a new transaction.
        //  Note that a store user might not call transaction() prior to using put,
        //   delete, etc. in which case these operations effectively could be thought of
        //   as "auto-commit" style actions.
        // returns: dojo.store.api.Store.Transaction
        //  This represents the new current transaction.
    • summary
      Starts a new transaction.
Note that a store user might not call transaction() prior to using put,
delete, etc. in which case these operations effectively could be thought of
as &quot;auto-commit&quot; style actions.
    • return_summary
      dojo.store.api.Store.Transaction
This represents the new current transaction.

  • dojo.store.api.Store.getChildren

    • type
      Function
    • parameters:
      • parent: (typeof Object)
        The object to find the children of.
      • options: (typeof dojo.store.api.Store.QueryOptions)
        Additional options to apply to the retrieval of the children.
    • source: [view]
        // summary:
        //  Retrieves the children of an object.
        // parent: Object
        //   The object to find the children of.
        // options: dojo.store.api.Store.QueryOptions?
        //   Additional options to apply to the retrieval of the children.
        // returns: dojo.store.api.Store.QueryResults
        //   A result set of the children of the parent object.
    • summary
      Retrieves the children of an object.
    • return_summary
      dojo.store.api.Store.QueryResults
A result set of the children of the parent object.

  • dojo.store.api.Store.getMetadata

    • type
      Function
    • parameters:
      • object: (typeof Object)
        The object to return metadata for.
    • source: [view]
        // summary:
        //  Returns any metadata about the object. This may include attribution,
        //   cache directives, history, or version information.
        // object: Object
        //  The object to return metadata for.
        // returns: Object
        //  An object containing metadata.
    • summary
      Returns any metadata about the object. This may include attribution,
cache directives, history, or version information.
    • return_summary
      Object
An object containing metadata.

  • dojo.store.api.Store.QueryResults

    • type
      Function
    • summary
      This is an object returned from query() calls that provides access to the results
of a query. Queries may be executed asynchronously.

  • dojo.store.api.Store.QueryResults.forEach

    • type
      Function
    • parameters:
      • callback: (typeof Function)
        that is called for each object in the query results
      • thisObject: (typeof The)
        object to use as |this| in the callback.
    • source: [view]
        // summary:
        //  Iterates over the query results, based on
        //   https://developer.mozilla.org/en/Core_JavaScript_1.5_Reference/Objects/Array/forEach.
        //  Note that this may executed asynchronously. The callback may be called
        //  after this function returns.
        // callback:
        //  Function that is called for each object in the query results
        // thisObject:
        //  The object to use as |this| in the callback.
    • summary
      Iterates over the query results, based on
https://developer.mozilla.org/en/Core_JavaScript_1.5_Reference/Objects/Array/forEach.
Note that this may executed asynchronously. The callback may be called
after this function returns.

  • dojo.store.api.Store.QueryResults.filter

    • type
      Function
    • parameters:
      • callback: (typeof Function)
        that is called for each object in the query results
      • thisObject: (typeof The)
        object to use as |this| in the callback.
    • source: [view]
        // summary:
        //  Filters the query results, based on
        //   https://developer.mozilla.org/en/Core_JavaScript_1.5_Reference/Objects/Array/filter.
        //  Note that this may executed asynchronously. The callback may be called
        //  after this function returns.
        // callback:
        //  Function that is called for each object in the query results
        // thisObject:
        //  The object to use as |this| in the callback.
        // returns: dojo.store.api.Store.QueryResults
    • summary
      Filters the query results, based on
https://developer.mozilla.org/en/Core_JavaScript_1.5_Reference/Objects/Array/filter.
Note that this may executed asynchronously. The callback may be called
after this function returns.
    • return_summary
      dojo.store.api.Store.QueryResults

  • dojo.store.api.Store.QueryResults.map

    • type
      Function
    • parameters:
      • callback: (typeof Function)
        that is called for each object in the query results
      • thisObject: (typeof The)
        object to use as |this| in the callback.
    • source: [view]
        // summary:
        //  Maps the query results, based on
        //   https://developer.mozilla.org/en/Core_JavaScript_1.5_Reference/Objects/Array/map.
        //  Note that this may executed asynchronously. The callback may be called
        //  after this function returns.
        // callback:
        //  Function that is called for each object in the query results
        // thisObject:
        //  The object to use as |this| in the callback.
        // returns: dojo.store.api.Store.QueryResults
    • summary
      Maps the query results, based on
https://developer.mozilla.org/en/Core_JavaScript_1.5_Reference/Objects/Array/map.
Note that this may executed asynchronously. The callback may be called
after this function returns.
    • return_summary
      dojo.store.api.Store.QueryResults

  • dojo.store.api.Store.QueryResults.then

    • type
      Function
    • parameters:
      • callback: (typeof This)
        is called when the query is completed successfully, and is passed a single argument
that is an array representing the query results.
      • errorHandler: (typeof This)
        is called if the query failed, and is passed a single argument that is the error
for the failure.
    • source: [view]
        // summary:
        //  This registers a callback for when the query is complete, if the query is asynchronous.
        //  This is an optional method, and may not be present for synchronous queries.
        // callback:
        //  This is called when the query is completed successfully, and is passed a single argument
        //   that is an array representing the query results.
        // errorHandler:
        //  This is called if the query failed, and is passed a single argument that is the error
        //  for the failure.
    • summary
      This registers a callback for when the query is complete, if the query is asynchronous.
This is an optional method, and may not be present for synchronous queries.

  • dojo.store.api.Store.QueryResults.observe

    • type
      Function
    • parameters:
      • listener: (typeof Function)
        The listener function is called when objects in the query results are modified
to affect the query result. The listener function is called with the following
arguments:

 listener(object, removedFrom, insertedInto);
* The object parameter indicates the object that was create, modified, or deleted.
* The removedFrom parameter indicates the index in the result array where
the object used to be. If the value is -1, then the object is an addition to
this result set (due to a new object being created, or changed such that it
is a part of the result set).
* The insertedInto parameter indicates the index in the result array where
the object should be now. If the value is -1, then the object is a removal
from this result set (due to an object being deleted, or changed such that it
is not a part of the result set).
      • includeAllUpdates: (typeof This)
        indicates whether or not to include object updates that do not affect
the inclusion or order of the object in the query results. By default this is false,
which means that if any object is updated in such a way that it remains
in the result set and it's position in result sets is not affected, then the listener
will not be fired.
    • source: [view]
        // summary:
        //  This registers a callback for notification of when data is modified in the query results.
        //  This is an optional method, and is usually provided by dojo.store.Observable.
        // listener: Function
        //  The listener function is called when objects in the query results are modified
        //   to affect the query result. The listener function is called with the following
        //   arguments:
        //   | listener(object, removedFrom, insertedInto);
        //  * The object parameter indicates the object that was create, modified, or deleted.
        //  * The removedFrom parameter indicates the index in the result array where
        //   the object used to be. If the value is -1, then the object is an addition to
        //   this result set (due to a new object being created, or changed such that it
        //   is a part of the result set).
        //  * The insertedInto parameter indicates the index in the result array where
        //   the object should be now. If the value is -1, then the object is a removal
        //   from this result set (due to an object being deleted, or changed such that it
        //   is not a part of the result set).
        // includeAllUpdates:
        //  This indicates whether or not to include object updates that do not affect
        //  the inclusion or order of the object in the query results. By default this is false,
        //  which means that if any object is updated in such a way that it remains
        //  in the result set and it's position in result sets is not affected, then the listener
        //   will not be fired.
    • summary
      This registers a callback for notification of when data is modified in the query results.
This is an optional method, and is usually provided by dojo.store.Observable.

  • dojo.store.api.Store.QueryResults.total

    • type
      Number|Promise
    • summary
      This property should be included in if the query options included the &quot;count&quot;
property limiting the result set. This property indicates the total number of objects
matching the query (as if &quot;start&quot; and &quot;count&quot; weren't present). This may be
a promise if the query is asynchronous.

  • dojo.store.api.Store.Transaction

    • type
      Function
    • summary
      This is an object returned from transaction() calls that represents the current
transaction.

  • dojo.store.api.Store.Transaction.commit

    • type
      Function
    • source: [view]
        // summary:
        //  Commits the transaction. This may throw an error if it fails. Of if the operation
        //   is asynchronous, it may return a promise that represents the eventual success
        //  or failure of the commit.  
    • summary
      Commits the transaction. This may throw an error if it fails. Of if the operation
is asynchronous, it may return a promise that represents the eventual success
or failure of the commit.

  • dojo.store.api.Store.Transaction.abort

    • type
      Function
    • parameters:
      • callback: (typeof )
      • thisObject: (typeof )
    • source: [view]
        // summary:
        //  Aborts the transaction. This may throw an error if it fails. Of if the operation
        //   is asynchronous, it may return a promise that represents the eventual success
        //  or failure of the abort.
    • summary
      Aborts the transaction. This may throw an error if it fails. Of if the operation
is asynchronous, it may return a promise that represents the eventual success
or failure of the abort.

  • dojo.store.api.Store.PutDirectives

    • type
      Function
    • parameters:
      • id: (typeof String|Number)
        Indicates the identity of the object if a new object is created
      • before: (typeof Object)
        If the collection of objects in the store has a natural ordering,
this indicates that the created or updated object should be placed before the
object specified by the value of this property. A value of null indicates that the
object should be last.
      • parent: (typeof Object)
        If the store is hierarchical (with single parenting) this property indicates the
new parent of the created or updated object.
      • overwrite: (typeof Boolean)
        If this is provided as a boolean it indicates that the object should or should not
overwrite an existing object. A value of true indicates that a new object
should not be created, the operation should update an existing object. A
value of false indicates that an existing object should not be updated, a new
object should be created (which is the same as an add() operation). When
this property is not provided, either an update or creation is acceptable.
    • source: [view]
       this.id = id;
       this.before = before;
       this.parent = parent;
       this.overwrite = overwrite;
    • summary
      Directives passed to put() and add() handlers for guiding the update and
creation of stored objects.

  • dojo.store.api.Store.PutDirectives.id

    • type
      String|Number?
    • summary
      Indicates the identity of the object if a new object is created

  • dojo.store.api.Store.PutDirectives.before

    • type
      Object?
    • summary
      If the collection of objects in the store has a natural ordering,
this indicates that the created or updated object should be placed before the
object specified by the value of this property. A value of null indicates that the
object should be last.

  • dojo.store.api.Store.PutDirectives.parent

    • type
      Object?
    • summary
      If the store is hierarchical (with single parenting) this property indicates the
new parent of the created or updated object.

  • dojo.store.api.Store.PutDirectives.overwrite

    • type
      Boolean?
    • summary
      If this is provided as a boolean it indicates that the object should or should not
overwrite an existing object. A value of true indicates that a new object
should not be created, the operation should update an existing object. A
value of false indicates that an existing object should not be updated, a new
object should be created (which is the same as an add() operation). When
this property is not provided, either an update or creation is acceptable.

  • dojo.store.api.Store.SortInformation

    • type
      Function
    • parameters:
      • attribute: (typeof String)
        The name of the attribute to sort on.
      • descending: (typeof Boolean)
        The direction of the sort.  Default is false.
    • source: [view]
       this.attribute = attribute;
       this.descending = descending;
    • summary
      An object describing what attribute to sort on, and the direction of the sort.

  • dojo.store.api.Store.SortInformation.attribute

    • type
      String
    • summary
      The name of the attribute to sort on.

  • dojo.store.api.Store.SortInformation.descending

    • type
      Boolean
    • summary
      The direction of the sort.  Default is false.

  • dojo.store.api.Store.QueryOptions

    • type
      Function
    • parameters:
      • sort: (typeof dojo.store.api.Store.SortInformation[])
        A list of attributes to sort on, as well as direction
For example:

 [{attribute:&quot;price, descending: true}].
If the sort parameter is omitted, then the natural order of the store may be
applied if there is a natural order.
      • start: (typeof Number)
        The first result to begin iteration on
      • count: (typeof Number)
        The number of how many results should be returned.
    • source: [view]
       this.sort = sort;
       this.start = start;
       this.count = count;
    • summary
      Optional object with additional parameters for query results.

  • dojo.store.api.Store.QueryOptions.sort

    • type
      dojo.store.api.Store.SortInformation[]?
    • summary
      A list of attributes to sort on, as well as direction
For example:

 [{attribute:&quot;price, descending: true}].
If the sort parameter is omitted, then the natural order of the store may be
applied if there is a natural order.

  • dojo.store.api.Store.QueryOptions.start

    • type
      Number?
    • summary
      The first result to begin iteration on

  • dojo.store.api.Store.QueryOptions.count

    • type
      Number?
    • summary
      The number of how many results should be returned.

  • dojo.store.api

    • type
      Object
    • summary
  • dojo.store
       
    • type
      Object
    • summary
  • dojo
       
    • type
      Object
    • summary