Skip to content

Store API

Jump to bottom
Peter Jekel edited this page May 18, 2013 · 22 revisions

The cbtree/store/api/Store API is an extension to the dojo/store/api/Store API. Therefore, any store that exposes the dojo/store/api/Store API is by default compliant with this API definition.

IMPORTANT

This API defines function signatures ONLY without providing implementation details. All store functions and properties defined in this API are optional and require implemention ONLY if the store is to offer the functionality. Therefore, your store of choice may only support a subset of this API.

Except for hasChildren() and isItem(), every function, whose return value isn't already a promise or void, MUST return a promise as its return value if the execution of the function is asynchronous. Whenever a store function returns a promise, the following conditions MUST be met:

  1. On successful completion of the function the promise must resolve with the specified synchronous return value as its result.
  2. On exception, the promise is rejected with the error condition (exception) as its result.

Please refer to the store specific documentation and Store API Matrix to see which properties and functions are supported.

In the context of this API, property values, arguments and operand types are defined as follows:

Operand Definition
Boolean JavaScript operand of type Boolean
id String or Number
Number JavaScript operand of type Number
Object JavaScript key:value pairs object (hash).
String JavaScript operand of type String
void JavaScript operand of type Undefined

Content

* [Store Properties](#store-properties) * [Store Functions](#store-functions) * [Store Directives](#store-directives)

Store Properties

Store properties enable or disable specific features or define characteristics of a store. The property names also represent properties in the keyword object passed to the store constructor. For example: 
require(["cbtree/store/Memory"], function (Memory) {
  var keywordArgs = {url:"some/path/myData", multiParented:true, defaultProperties:{checked:true}};
  var store = new Memory( keywordArgs );
}

autoLoad:

> **_TYPE_**: Boolean

Indicates if the store data should be loaded immediately when available or deferred until the store method load() is called. See the store load function for additional information.

DEFAULT: true

clearOnClose:

> **_TYPE_**: Boolean

Indicates if the store content is to be deleted when the store is closed. The store is closed by calling the store close() function.

DEFAULT: false

data:

> **_TYPE_**: Object [] | Any

An array of JavaScript key:value pairs objects to be loaded into the store as the initial store content. If data is any other data type, the store must also implement dataHandler and handleAs. See also url

DEFAULT: null

dataHandler:

> **_TYPE_**: Function | Object

The data handler for the store data or server response. A data handler convert an arbitrary data format into an array of JavaScript key:value pairs objects ready for consumption by the store. If dataHandler is an key:value pairs object, the object should support the following properties:

  { handler: Function|Object,
    options: Object?
  }

If the handler property is an object the object MUST have a property named 'handler' whose value is a function. In this case the handler object provides the scope/closure for the handler function and the options, if any, are mixed into the scope. For example:

dataHandler: { handler: csvHandler,
               options: { fieldNames:["col1", "col2"] }
             }

The handler function has the following signature:

  handler( response )

The response argument is a JavaScript key:value pairs object with a "text" and/or "data" property.

DEFAULT: null

defaultProperties:

> **_TYPE_**: Object

A JavaScript key:values pairs object whose properties and their value are added to new store objects if such properties are missing from a new store object.

DEFAULT: null

filter:

> **_TYPE_**: Object | Function

Query style filter object or function applied to the store data prior to populating the store. The filter property can be used to load a subset of objects into the store. See also LoadDirectives

DEFAULT: null

handleAs:

> **_TYPE_**: String

Specifies how to interpret the payload returned in a server response or the data passed to a store method responsible for populating the store, if any. (typically the store constructor or load() method).

DEFAULT: null

hierarchical:

> **_TYPE_**: Boolean (read-only)

Indicates if the store is capable of maintaining an object hierarchy. The cbtree Models tests for the presence of this property in order to determine if it has to set the parent property of an object or if the store will handle it. If true, the store MUST implement all logic required to support the PutDirective property "parent" and optionally the store property parentProperty.

DEFAULT: false

idProperty:

> **_TYPE_**: String | Number

If the store has a single primary key, this indicates the property to use as the identity property. The values of this property should be unique.

DEFAULT: "id"

multiParented:

> **_TYPE_**: Boolean | String

Indicates if the store is to support multi-parented objects. Multi Parented objects are objects that can have more than one parent.

DEFAULT: false

parentProperty:

> **_TYPE_**: String

The property name of an object whose value represents the object's parent id or ids.

DEFAULT: "parent"

queryEngine:

> **_TYPE_**: Function

If the store can be queried locally (on the client side in JS), this property defines the query engine to use for querying the store data. The signature of the queryEngine function is as follows:

  queryEngineFunction( queryObject, queryOptions? )

The queryEngine function MUST return a function that can execute the provided query on an array of objects. 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

DEFAULT: null

url:

> **_TYPE_**: String

The Universal Resource Location (URL) to retrieve the store data from.

DEFAULT: null

Store Functions

As stated above, all store functions are optional and may return a dojo/promise/Promise which then resolves with the synchronous result of the store function.

add( object, options? )

> Add a new object to the store, throws an exception if an object with the same identifier already exists.

object: Object

The object to be added to the store.

options: PutDirectives?

Additional directives for creating objects.

returns: id

addParent( child, parents )

> Add parent or parents to the list of parents of child.

child: Object

Store object to which the parent(s) are added.

parents: (Object | Id) []?

Object or id or an array of objects or ids to be added as the parent(s) of child.

returns: Boolean

true if parents were successfully added otherwise false.

close( clear? )

> Close the store. Unless the parameter *clear* is set to `true` this function > has no effect.

clear: Boolean

Indicates if the store content is to be deleted. If omitted the store property clearOnClose is used instead.

destroy()

> Release all memory and mark store as destroyed.

get( id )

> Retrieves an object by its identity

id: String | Number

returns: Object | void

The object found otherwise void.

getChildren( parent, options? )

> Retrieves the children of an object.

parent: Object

The object to retrieve the children for.

options: QueryDirectives?

Additional options to apply to the retrieval of the children.

returns: dojo/store/api/Store.QueryResults

Note: An empty QueryResults may indicate the parent does not have children or the parent itself was not found in the store.

getIdentity( object )

> Returns an object's identity. See also the store property "idProperty"

object: Object

The object to get the identity from.

returns: id | void

getParents( child )

> Retrieve the parent(s) of a store object.

child: Object

The store object to retrieve the parent(s) for.

returns: Object[] | void

hasChildren( parent )

> Returns boolean true if a parent object has known children otherwise false.

parent: Object

The object to evaluate.

returns: Boolean

true if the parent object has known children otherwise false.

isItem( object )

> Evaluate if an object is a valid member of this store, that is, it came from this store > instance. This method MUST execute synchronously.

object: Object

Object to evaluate

returns: Boolean

true if the object is a member of this store otherwise false.

load( options? )

> Load the store data using the data identified by the store property [data](#data) > or [url](#url).

options: LoadDirectives?

Optional load directives.

returns: dojo/promise/Promise

On successful completion the promise resolves to void. On error the promise is rejected with the error condition as its result.

put( object, options? )

> Stores an object. Throws an exception if an object with the same identification > already exists **AND** the PutDirective.overwrite is set to false.

object: Object

The object to store.

options: PutDirectives?

Additional directives for storing objects.

returns: id

query( query, options? )

> Queries the store for objects. The query function does not alter the store, but returns a set > of objects from the store.

query: String | Object | Function

The query to use for retrieving objects from the store.

options: QueryDirectives?

The optional arguments to apply to the resultset.

returns: dojo/store/api/Store.QueryResults

The results of the query, extended with iterative methods.

ready( callback?, errback?, scope? )

> Execute the callback when the store data has been loaded. If an error occurred > during the loading process errback is called instead.

callback: Function

Function called on successful load of the store data.

errback: Function

Function called if an error occurred during the store load.

scope: Object

The scope or context in which the callback and errback functions are executed. If omitted both functions will be executed in the scope of the store.

returns: dojo/promise/Promise

remove( id )

> Deletes an object by its identity.

id: String | Number

The identity to use to delete the object

removeParent( child, parents )

> Remove parent(s) from the list of parents of child.

child: Object

Store object from which the parent(s) are to be removed.

parents: (Object | Id) []?

Object or id or an array of objects or ids to be removed from the parent(s) of child.

returns: Boolean

true if the parent(s) are successfully removed otherwise false.

Store Directives

Store Directives are JavaScript objects whose key:value pairs serve as additional parameters to store operations. In general, directive objects are passed to store functions as an optional argument.

### LoadDirectives > Directives passed to the load() method.

all: Boolean?

Indicates if all available data should be loaded. If set to true, overrides the filter property.

data: any?

Identifies the data to be loaded.

filter: (Object | Function)?

If specified, the objects that match the filter are loaded into the store. If filter is a key:value pairs object, each key:value pair is matched with the corresponding key:value pair of the store data being loaded. If filter is a function, the function is called once for every object to be loaded as: func( object ). The function must return either true or false.

handleAs: String?

Specifies how to interpret the payload returned in a server response or the data passed to a store method responsible for populating the store.

url: String?

The Universal Resource Location (URL) to retrieve the store data from.

### PutDirectives > Directives passed to put() and add() functions for guiding the update and > creation of store objects. PutDirectives is a JavaScript key:value pairs > object with the following optional properties:

id: (String | Number)?

Indicates the identity of the object if a new object is created.

before: (Object | id)?

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. The property value can be an object or id. If omitted or null indicates that the object should be last.

parent: Any?

If the store is hierarchical this property indicates the new parent(s) of the created or updated object. This property value can be an Id or object or an array of ids or objects.

overwrite: 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, instead 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.

Example:

{ parent:"Homer", before:"Bart", overwrite:true }

### QueryDirectives > Optional object with additional parameters for query results. QueryDirectives > is a JavaScript key:value pairs object with the following optional properties:

sort: (SortDirective[] | Function)?

An array of one or more sort directives. If more than one sort directive is provided the sort directives are processed in the order in which they appear in the sort array. If a comparison function is specified, the array elements are sorted according to the return value of the comparison function. See the JavaScript Array.sort() function for details.

start: Number?

The first result to begin iteration on. Start identifies an index number in the array of result.

count: Number?

The maximum number of results that should be returned. If there are less than count results all available results are returned.

ignoreCase: Boolean?

Match object properties case insensitive. Default is false.

cacheOnly: Boolean?

If the store maintains an internal cache and cacheOnly is set to true only the cache is searched without fetching any data from an external data source like a back-end server. Default is false.

Example:

{ sort:[{attribute:"directory"}, {attribute:"name", ignoreCase:true}], count: 10 }

### SortDirective > An object describing what object property to sort on, and the direction of the sort.

property: String

The name of the property to sort on.

attribue: String (dojo compatibility only)

The name of the property to sort on. Note: This property is provided for dojo/store compatibility only, use property instead.

descending: Boolean?

The direction of the sort. Default is false.

ignoreCase: Boolean?

Compare attribute/property values case insensitive. Default is false.

Example:

{ attribute:"name", descending:true, ignoreCase:true }

Clone this wiki locally