A data store for XML based services or documents
A data store for XML based services or documents
Parameter | Type | Description |
---|---|---|
args | object | An anonymous object to initialize properties. It expects the following values:
|
See the dojox/data/XmlStore reference documentation for more information.
Fetch items (XML elements) that match to a query
If 'sendQuery' is true, an XML document is loaded from 'url' with a query string. Otherwise, an XML document is loaded and list XML elements that match to a query (set of element names and their text attribute values that the items to contain). A wildcard, "*" can be used to query values to match all occurrences. If 'rootItem' is specified, it is used to fetch items.
Parameter | Type | Description |
---|---|---|
request | undefined | A request object |
fetchHandler | undefined | A function to call for fetched items |
errorHandler | undefined | A function to call on error |
Function used to flatten a hierarchy of XML nodes into a single list for querying over. Used when deep = true;
Parameter | Type | Description |
---|---|---|
nodes | undefined |
Parameter | Type | Description |
---|---|---|
tagName | undefined | |
attribute | undefined |
Generate a URL for delete
This default implementation returns 'url' with 'keyAttribute' as a query string. Sub-classes may override this method for the custom URL based on changes (new, deleted, or modified).
Parameter | Type | Description |
---|---|---|
item | undefined | An item to delete |
A delete URL
Parameter | Type | Description |
---|---|---|
element | undefined |
Generate a URL for fetch
This default implementation generates a query string in the form of "?name1=value1&name2=value2..." off properties of 'query' object specified in 'request' and appends it to 'url', if 'sendQuery' is set to false. Otherwise, 'url' is returned as is. Sub-classes may override this method for the custom URL generation.
Parameter | Type | Description |
---|---|---|
request | undefined | A request object |
A fetch URL
Parameter | Type | Description |
---|---|---|
items | undefined | |
element | undefined |
Fetch items (XML elements) in an XML document based on a request
This default implementation walks through child elements of the document element to see if all properties of 'query' object match corresponding attributes of the element (item). If 'request' is not specified, all child elements are returned. Sub-classes may override this method for the custom search in an XML document.
Parameter | Type | Description |
---|---|---|
document | undefined | An XML document |
request | undefined | A request object |
An array of items
Generate a content to post
This default implementation generates an XML document for one (the first only) new or modified element. Sub-classes may override this method for the custom post content generation.
Parameter | Type | Description |
---|---|---|
item | undefined | An item to save |
A post content
Generate a URL for post
This default implementation just returns 'url'. Sub-classes may override this method for the custom URL.
Parameter | Type | Description |
---|---|---|
item | undefined | An item to save |
A post URL
Generate a content to put
This default implementation generates an XML document for one (the first only) new or modified element. Sub-classes may override this method for the custom put content generation.
Parameter | Type | Description |
---|---|---|
item | undefined | An item to save |
A post content
Generate a URL for put
This default implementation just returns 'url'. Sub-classes may override this method for the custom URL.
Parameter | Type | Description |
---|---|---|
item | undefined | An item to save |
A put URL
A function to compute the xpath of a node in a DOM document.
A function to compute the xpath of a node in a DOM document. Used for Client side query handling and identity.
Parameter | Type | Description |
---|---|---|
element | undefined |
Parameter | Type | Description |
---|---|---|
item | undefined | |
keywordArgs | undefined | |
method | undefined |
See dojo/data/api/Read.close()
Parameter | Type | Description |
---|---|---|
request | dojo/data/api/Request | Object |
Optional
|
Check whether the attribute values contain the value
Parameter | Type | Description |
---|---|---|
item | dojo/data/api/Item | An object to check |
attribute | attribute | attribute-name-string | A tag name of a child element, An XML attribute name or one of special names |
value | anything |
True if the attribute values contain the value, otherwise false
Delete an dojox.data.XmlItem (wrapper to a XML element).
Parameter | Type | Description |
---|---|---|
item | dojo/data/api/Item | An XML element to delete |
True
The error handler when there is an error fetching items. This function should not be called directly and is used by simpleFetch.fetch().
Parameter | Type | Description |
---|---|---|
errorData | Object | |
requestObject | Object |
The simpleFetch mixin is designed to serve as a set of function(s) that can be mixed into other datastore implementations to accelerate their development.
The simpleFetch mixin should work well for any datastore that can respond to a _fetchItems() call by returning an array of all the found items that matched the query. The simpleFetch mixin is not designed to work for datastores that respond to a fetch() call by incrementally loading items, or sequentially loading partial batches of the result set. For datastores that mixin simpleFetch, simpleFetch implements a fetch method that automatically handles eight of the fetch() arguments -- onBegin, onItem, onComplete, onError, start, count, sort and scope The class mixing in simpleFetch should not implement fetch(), but should instead implement a _fetchItems() method. The _fetchItems() method takes three arguments, the keywordArgs object that was passed to fetch(), a callback function to be called when the result array is available, and an error callback to be called if something goes wrong. The _fetchItems() method should ignore any keywordArgs parameters for start, count, onBegin, onItem, onComplete, onError, sort, and scope. The _fetchItems() method needs to correctly handle any other keywordArgs parameters, including the query parameter and any optional parameters (such as includeChildren). The _fetchItems() method should create an array of result items and pass it to the fetchHandler along with the original request object -- or, the _fetchItems() method may, if it wants to, create an new request object with other specifics about the request that are specific to the datastore and pass that as the request object to the handler.
For more information on this specific function, see dojo/data/api/Read.fetch()
Parameter | Type | Description |
---|---|---|
request | Object |
Optional The keywordArgs parameter may either be an instance of conforming to dojo/data/api/Request or may be a simple anonymous object that may contain any of the following: { query: query-object or query-string, queryOptions: object, onBegin: Function, onItem: Function, onComplete: Function, onError: Function, scope: object, start: int count: int sort: array } All implementations should accept keywordArgs objects with any of the 9 standard properties: query, onBegin, onItem, onComplete, onError scope, sort, start, and count. Some implementations may accept additional properties in the keywordArgs object as valid parameters, such as {includeOutliers:true}. The query parameterThe query may be optional in some data store implementations. The dojo/data/api/Read API does not specify the syntax or semantics of the query itself -- each different data store implementation may have its own notion of what a query should look like. However, as of dojo 0.9, 1.0, and 1.1, all the provided datastores in dojo.data and dojox.data support an object structure query, where the object is a set of name/value parameters such as { attrFoo: valueBar, attrFoo1: valueBar1}. Most of the dijit widgets, such as ComboBox assume this to be the case when working with a datastore when they dynamically update the query. Therefore, for maximum compatibility with dijit widgets the recommended query parameter is a key/value object. That does not mean that the the datastore may not take alternative query forms, such as a simple string, a Date, a number, or a mix of such. Ultimately, The dojo/data/api/Read API is agnostic about what the query format. Further note: In general for query objects that accept strings as attribute value matches, the store should also support basic filtering capability, such as (match any character) and ? (match single character). An example query that is a query object would be like: { attrFoo: "value"}. Which generally means match all items where they have an attribute named attrFoo, with a value that starts with 'value'. The queryOptions parameterThe queryOptions parameter is an optional parameter used to specify options that may modify the query in some fashion, such as doing a case insensitive search, or doing a deep search where all items in a hierarchical representation of data are scanned instead of just the root items. It currently defines two options that all datastores should attempt to honor if possible: { ignoreCase: boolean, // Whether or not the query should match case sensitively or not. Default behaviour is false. deep: boolean // Whether or not a fetch should do a deep search of items and all child // items instead of just root-level items in a datastore. Default is false. } The onBegin parameter.function(size, request); If an onBegin callback function is provided, the callback function will be called just once, before the first onItem callback is called. The onBegin callback function will be passed two arguments, the the total number of items identified and the Request object. If the total number is unknown, then size will be -1. Note that size is not necessarily the size of the collection of items returned from the query, as the request may have specified to return only a subset of the total set of items through the use of the start and count parameters. The onItem parameter.function(item, request); If an onItem callback function is provided, the callback function will be called as each item in the result is received. The callback function will be passed two arguments: the item itself, and the Request object. The onComplete parameter.function(items, request); If an onComplete callback function is provided, the callback function will be called just once, after the last onItem callback is called. Note that if the onItem callback is not present, then onComplete will be passed an array containing all items which matched the query and the request object. If the onItem callback is present, then onComplete is called as: onComplete(null, request). The onError parameter.function(errorData, request); If an onError callback function is provided, the callback function will be called if there is any sort of error while attempting to execute the query. The onError callback function will be passed two arguments: an Error object and the Request object. The scope parameter.If a scope object is provided, all of the callback functions (onItem, onComplete, onError, etc) will be invoked in the context of the scope object. In the body of the callback function, the value of the "this" keyword will be the scope object. If no scope object is provided, the callback functions will be called in the context of dojo.global(). For example, onItem.call(scope, item, request) vs. onItem.call(dojo.global(), item, request) The start parameter.If a start parameter is specified, this is a indication to the datastore to only start returning items once the start number of items have been located and skipped. When this parameter is paired with 'count', the store should be able to page across queries with millions of hits by only returning subsets of the hits for each query The count parameter.If a count parameter is specified, this is a indication to the datastore to only return up to that many items. This allows a fetch call that may have millions of item matches to be paired down to something reasonable. The sort parameter.If a sort parameter is specified, this is a indication to the datastore to sort the items in some manner before returning the items. The array is an array of javascript objects that must conform to the following format to be applied to the fetching of items: { attribute: attribute || attribute-name-string, descending: true|false; // Optional. Default is false. } Note that when comparing attributes, if an item contains no value for the attribute (undefined), then it the default ascending sort logic should push it to the bottom of the list. In the descending order case, it such items should appear at the top of the list. |
The handler when items are successfully fetched. This function should not be called directly and is used by simpleFetch.fetch().
Parameter | Type | Description |
---|---|---|
items | Array | |
requestObject | Object |
See dojo/data/api/Identity.fetchItemByIdentity(keywordArgs)
Parameter | Type | Description |
---|---|---|
keywordArgs | object |
Return an array of attribute names
'item' must be an instance of a dojox.data.XmlItem from the store instance. tag names of child elements and XML attribute names of attributes specified to the element are returned along with special attribute names applicable to the element including "tagName", "childNodes" if the element has child elements, "text()" if the element has child text nodes, and attribute names in '_attributeMap' that match the tag name of the element.
Parameter | Type | Description |
---|---|---|
item | dojo/data/api/Item | An XML element |
An array of attributes found
Return supported data APIs
"dojo.data.api.Read" and "dojo.data.api.Write"
Returns a unique identifier for an item.
Parameter | Type | Description |
---|---|---|
item | dojo/data/api/Item | The XML Item from the store from which to obtain its identifier. |
Returns an array of attribute names that are used to generate the identity.
For XmlStore, if sendQuery is false and no keyAttribute was set, then this function returns null, as xpath is used for the identity, which is not a public attribute of the item. If sendQuery is true and keyAttribute is set, then this function returns an array of one attribute name: keyAttribute. This means the server side implementation must apply a keyAttribute to a returned node that always allows it to be looked up again.
Parameter | Type | Description |
---|---|---|
item | dojo/data/api/Item | The item from the store from which to obtain the array of public attributes that compose the identifier, if any. |
See dojo/data/api/Read.getLabel()
Parameter | Type | Description |
---|---|---|
item | dojo/data/api/Item |
See dojo/data/api/Read.getLabelAttributes()
Parameter | Type | Description |
---|---|---|
item | dojo/data/api/Item |
Return an attribute value
'item' must be an instance of a dojox.data.XmlItem from the store instance. If 'attribute' specifies "tagName", the tag name of the element is returned. If 'attribute' specifies "childNodes", the first element child is returned. If 'attribute' specifies "text()", the value of the first text child is returned. For generic attributes, if '_attributeMap' is specified, an actual attribute name is looked up with the tag name of the element and 'attribute' (concatenated with '.'). Then, if 'attribute' starts with "@", the value of the XML attribute is returned. Otherwise, the first child element of the tag name specified with 'attribute' is returned.
Parameter | Type | Description |
---|---|---|
item | dojo/data/api/Item | An XML element that holds the attribute |
attribute | attribute | attribute-name-string | A tag name of a child element, An XML attribute name or one of special names |
defaultValue | value |
Optional A default value |
An attribute value found, otherwise 'defaultValue'
Return an array of attribute values
'item' must be an instance of a dojox.data.XmlItem from the store instance. If 'attribute' specifies "tagName", the tag name of the element is returned. If 'attribute' specifies "childNodes", child elements are returned. If 'attribute' specifies "text()", the values of child text nodes are returned. For generic attributes, if 'attributeMap' is specified, an actual attribute name is looked up with the tag name of the element and 'attribute' (concatenated with '.'). Then, if 'attribute' starts with "@", the value of the XML attribute is returned. Otherwise, child elements of the tag name specified with 'attribute' are returned.
Parameter | Type | Description |
---|---|---|
item | dojo/data/api/Item | An XML element that holds the attribute |
attribute | attribute | attribute-name-string | A tag name of child elements, An XML attribute name or one of special names |
An array of attribute values found, otherwise an empty array
Check whether an element has the attribute
Parameter | Type | Description |
---|---|---|
item | dojo/data/api/Item | 'item' must be an instance of a dojox.data.XmlItem from the store instance. |
attribute | attribute | attribute-name-string | A tag name of a child element, An XML attribute name or one of special names |
True if the element has the attribute, otherwise false
Check whether an item is new, modified or deleted
If 'item' is specified, true is returned if the item is new, modified or deleted. Otherwise, true is returned if there are any new, modified or deleted items.
Parameter | Type | Description |
---|---|---|
item | item |
Optional An item (XML element) to check |
True if an item or items are new, modified or deleted, otherwise false
Check whether the object is an item (XML element)
Parameter | Type | Description |
---|---|---|
something | anything |
True if the object is an XML element, otherwise false
Check whether the object is an item (XML element) and loaded
Parameter | Type | Description |
---|---|---|
something | anything |
True if the object is an XML element, otherwise false
Load an item (XML element)
Parameter | Type | Description |
---|---|---|
keywordArgs | object | object containing the args for loadItem. See dojo/data/api/Read.loadItem() |
Return a new dojox.data.XmlItem
At least, 'keywordArgs' must contain "tagName" to be used for the new element. Other attributes in 'keywordArgs' are set to the new element, including "text()", but excluding "childNodes".
Parameter | Type | Description |
---|---|---|
keywordArgs | object |
Optional An object containing initial attributes |
parentInfo | undefined |
An XML element
Invalidate changes (new and/or modified elements)
True
Save new and/or modified items (XML elements)
'url' is used to save XML documents for new, modified and/or deleted XML elements.
Parameter | Type | Description |
---|---|---|
keywordArgs | object | An object for callbacks |
Set an attribute value
'item' must be an instance of a dojox.data.XmlItem from the store instance. If 'attribute' specifies "tagName", nothing is set and false is returned. If 'attribute' specifies "childNodes", the value (XML element) is added to the element. If 'attribute' specifies "text()", a text node is created with the value and set it to the element as a child. For generic attributes, if '_attributeMap' is specified, an actual attribute name is looked up with the tag name of the element and 'attribute' (concatenated with '.'). Then, if 'attribute' starts with "@", the value is set to the XML attribute. Otherwise, a text node is created with the value and set it to the first child element of the tag name specified with 'attribute'. If the child element does not exist, it is created.
Parameter | Type | Description |
---|---|---|
item | dojo/data/api/Item | An XML element that holds the attribute |
attribute | attribute | String | A tag name of a child element, An XML attribute name or one of special names |
value | almost anything | A attribute value to set |
False for "tagName", otherwise true
Set attribute values
'item' must be an instance of a dojox.data.XmlItem from the store instance. If 'attribute' specifies "tagName", nothing is set and false is returned. If 'attribute' specifies "childNodes", the value (array of XML elements) is set to the element's childNodes. If 'attribute' specifies "text()", a text node is created with the values and set it to the element as a child. For generic attributes, if '_attributeMap' is specified, an actual attribute name is looked up with the tag name of the element and 'attribute' (concatenated with '.'). Then, if 'attribute' starts with "@", the first value is set to the XML attribute. Otherwise, child elements of the tag name specified with 'attribute' are replaced with new child elements and their child text nodes of values.
Parameter | Type | Description |
---|---|---|
item | dojo/data/api/Item | An XML element that holds the attribute |
attribute | attribute | String | A tag name of child elements, an XML attribute name or one of special names |
values | Array |
False for "tagName", otherwise true
Remove an attribute
'item' must be an instance of a dojox.data.XmlItem from the store instance. 'attribute' can be an XML attribute name of the element or one of special names described below. If 'attribute' specifies "tagName", nothing is removed and false is returned. If 'attribute' specifies "childNodes" or "text()", all child nodes are removed. For generic attributes, if '_attributeMap' is specified, an actual attribute name is looked up with the tag name of the element and 'attribute' (concatenated with '.'). Then, if 'attribute' starts with "@", the XML attribute is removed. Otherwise, child elements of the tag name specified with 'attribute' are removed.
Parameter | Type | Description |
---|---|---|
item | dojo/data/api/Item | An XML element that holds the attribute |
attribute | attribute | String | A tag name of child elements, an XML attribute name or one of special names |
False for "tagName", otherwise true