This API defines a set of APIs that all datastores that conform to the
Notifications API must implement. In general, most stores will implement
these APIs as no-op functions for users who wish to monitor them to be able
to connect to then via dojo.connect(). For non-users of dojo.connect,
they should be able to just replace the function on the store to obtain
notifications. Both read-only and read-write stores may implement
this feature. In the case of a read-only store, this feature makes sense if
the store itself does internal polling to a back-end server and periodically updates
its cache of items (deletes, adds, and updates).
|
|
|
close(
request
: dojo.data.api.Request
) :
void
The close() method is intended for instructing the store to 'close' out
any information associated with a particular request.
The close() method is intended for instructing the store to 'close' out
any information associated with a particular request. In general, this API
expects to recieve as a parameter a request object returned from a fetch.
It will then close out anything associated with that request, such as
clearing any internal datastore caches and closing any 'open' connections.
For some store implementations, this call may be a no-op.
Parameter |
Type |
Usage |
Description |
request |
dojo.data.api.Request |
required |
An instance of a request for the store to use to identify what to close out.
If no request is passed, then the store should clear all internal caches (if any)
and close out all 'open' connections. It does not render the store unusable from
there on, it merely cleans out any current data and resets the store to initial
state. |
Examples
|
|
|
|
containsValue(
item
: item
attribute
: attribute-name-string
value
: anything
) :
void
Returns true if the given *value* is one of the values that getValues()
would return.
Parameter |
Type |
Usage |
Description |
item |
item |
required |
The item to access values on. |
attribute |
attribute-name-string |
required |
The attribute to access represented as a string. |
value |
anything |
required |
The value to match as a value for the attribute. |
Examples
|
|
|
|
fetch(
keywordArgs
: Object
) :
void
Given a query and set of defined options, such as a start and count of items to return,
this method executes the query and makes the results available as data items.
The format and expectations of stores is that they operate in a generally asynchronous
manner, therefore callbacks are always used to return items located by the fetch parameters.
A Request object will always be returned and is returned immediately.
The basic request is nothing more than the keyword args passed to fetch and
an additional function attached, abort(). The returned request object may then be used
to cancel a fetch. All data items returns are passed through the callbacks defined in the
fetch parameters and are not present on the 'request' object.
This does not mean that custom stores can not add methods and properties to the request object
returned, only that the API does not require it. For more info about the Request API,
see dojo.data.api.Request
Parameter |
Type |
Usage |
Description |
keywordArgs |
Object |
required |
The keywordArgs parameter may either be an instance of
conforming to dojo.data.api.Request or may be a simple anonymous object |
Examples
|
|
|
|
getAttributes(
item
: item
) :
void
Returns an array with all the attributes that this item has. This
method will always return an array; if the item has no attributes
Parameter |
Type |
Usage |
Description |
item |
item |
required |
The item to access attributes on. |
Examples
|
|
|
|
getFeatures(
) :
void
See dojo.data.api.Read.getFeatures()
|
|
|
|
getLabel(
item
: item
) :
void
Method to inspect the item and return a user-readable 'label' for the item
that provides a general/adequate description of what the item is.
Method to inspect the item and return a user-readable 'label' for the item
that provides a general/adequate description of what the item is. In general
most labels will be a specific attribute value or collection of the attribute
values that combine to label the item in some manner. For example for an item
Parameter |
Type |
Usage |
Description |
item |
item |
required |
The item to return the label for. |
|
|
|
|
getLabelAttributes(
item
: item
) :
void
Method to inspect the item and return an array of what attributes of the item were used
to generate its label, if any.
Method to inspect the item and return an array of what attributes of the item were used
to generate its label, if any. This function is to assist UI developers in knowing what
attributes can be ignored out of the attributes an item has when displaying it, in cases
where the UI is using the label as an overall identifer should they wish to hide
redundant information.
Parameter |
Type |
Usage |
Description |
item |
item |
required |
The item to return the list of label attributes for. |
|
|
|
|
getValue(
item
: item
attribute
: attribute-name-string
defaultValue
: value
) :
void
Returns a single attribute value.
Returns defaultValue if and only if *item* does not have a value for *attribute*.
Returns null if and only if null was explicitly set as the attribute value.
Returns undefined if and only if the item does not have a value for the
given attribute (which is the same as saying the item does not have the attribute).
Saying that an "item x does not have a value for an attribute y"
is identical to saying that an "item x does not have attribute y".
It is an oxymoron to say "that attribute is present but has no values"
or "the item has that attribute but does not have any attribute values".
If store.hasAttribute(item, attribute) returns false, then
store.getValue(item, attribute) will return undefined.
Parameter |
Type |
Usage |
Description |
item |
item |
required |
The item to access values on. |
attribute |
attribute-name-string |
required |
The attribute to access represented as a string. |
defaultValue |
value |
optional |
Optional. A default value to use for the getValue return in the attribute does not exist or has no value. |
Examples
|
|
|
|
getValues(
item
: item
attribute
: attribute-name-string
) :
void
This getValues() method works just like the getValue() method, but getValues()
always returns an array rather than a single attribute value. The array
may be empty, may contain a single attribute value, or may contain
many attribute values.
If the item does not have a value for the given attribute, then getValues()
Parameter |
Type |
Usage |
Description |
item |
item |
required |
The item to access values on. |
attribute |
attribute-name-string |
required |
The attribute to access represented as a string. |
Examples
|
|
|
|
hasAttribute(
item
: item
attribute
: attribute-name-string
) :
void
Returns true if the given *item* has a value for the given *attribute*.
Parameter |
Type |
Usage |
Description |
item |
item |
required |
The item to access attributes on. |
attribute |
attribute-name-string |
required |
The attribute to access represented as a string. |
Examples
|
|
|
|
isItem(
something
: anything
) :
void
Returns true if *something* is an item and came from the store instance.
Returns false if *something* is a literal, an item from another store instance,
or is any object other than an item.
Parameter |
Type |
Usage |
Description |
something |
anything |
required |
Can be anything. |
Examples
|
|
|
|
isItemLoaded(
something
: anything
) :
void
Returns false if isItem(something) is false. Returns false if
if isItem(something) is true but the the item is not yet loaded
in local memory (for example, if the item has not yet been read
from the server).
Parameter |
Type |
Usage |
Description |
something |
anything |
required |
Can be anything. |
Examples
|
|
|
|
loadItem(
keywordArgs
: object
) :
void
Given an item, this method loads the item so that a subsequent call
to store.isItemLoaded(item) will return true. If a call to
isItemLoaded() returns true before loadItem() is even called,
then loadItem() need not do any work at all and will not even invoke
the callback handlers. So, before invoking this method, check that
the item has not already been loaded.
Parameter |
Type |
Usage |
Description |
keywordArgs |
object |
required |
An anonymous object that defines the item to load and callbacks to invoke when the |
|
|
|
|
onDelete(
deletedItem
: item
) :
void
This function is called any time an item is deleted from the store.
It is called immediately after the store deleteItem processing has completed.
This function is called any time an item is deleted from the store.
It is called immediately after the store deleteItem processing has completed.
Parameter |
Type |
Usage |
Description |
deletedItem |
item |
required |
The item deleted. |
|
|
|
|
onNew(
newItem
: item
parentInfo
: object
) :
void
This function is called any time a new item is created in the store.
It is called immediately after the store newItem processing has completed.
This function is called any time a new item is created in the store.
It is called immediately after the store newItem processing has completed.
Parameter |
Type |
Usage |
Description |
newItem |
item |
required |
The item created. |
parentInfo |
object |
optional |
An optional javascript object that is passed when the item created was placed in the store
hierarchy as a value f another item's attribute, instead of a root level item. Note that if this
function is invoked with a value for parentInfo, then onSet is not invoked stating the attribute of
the parent item was modified. This is to avoid getting two notification events occurring when a new item |
|
|
|
|
onSet(
item
: item
attribute
: attribute-name-string
oldValue
: object
newValue
: object
) :
void
This function is called any time an item is modified via setValue, setValues, unsetAttribute, etc.
This function is called any time an item is modified via setValue, setValues, unsetAttribute, etc.
Its purpose is to provide a hook point for those who wish to monitor actions on items in the store
in a simple manner. The general expected usage is to dojo.connect() to the store's
implementation and be called after the store function is called.
Parameter |
Type |
Usage |
Description |
item |
item |
required |
The item being modified. |
attribute |
attribute-name-string |
required |
The attribute being changed represented as a string name. |
oldValue |
object |
required |
The old value of the attribute. In the case of single value calls, such as setValue, unsetAttribute, etc,
this value will be generally be an atomic value of some sort (string, int, etc, object). In the case of
multi-valued attributes, it will be an array. |
newValue |
object |
required |
The new value of the attribute. In the case of single value calls, such as setValue, this value will be
generally be an atomic value of some sort (string, int, etc, object). In the case of multi-valued attributes,
it will be an array. In the case of unsetAttribute, the new value will be 'undefined'. |
|