The OpenSearch store implements only the Read dojo.data API. See the following reference documentation for the API. This documentation comes from the dojo.data.api.Read file and is generic to all stores. The only limitation to the OpenSearch store is attributes. There is only one attribute defined for any item in the OpenSearch store, labeled content, which is the content of that search result. These results include the content element in an Atom feed, the description element in an RSS feed, and the HTML content of an individual row in the results for an HTML return type.
This is an abstract API to which data provider implementations conform to. For more information on the dojo.data APIs, visit: http://www.dojotoolkit.org/node/98
Function summary | |
---|---|
Object | getValue(Object item, String attribute, String defaultValue) Retrieves the value of the named attribute on the given item. |
Array | getValues(Object item, String attribute) Retrieves the values of the named attribute on the given item. |
Array | getAttributes(Object item) Returns an array with all the attributes that this item has. |
Boolean | hasAttribute(Object item, String attribute) Returns true if the given item has a value for the given attribute. |
Boolean | containsValue(Object item, String attribute, Object value) Returns true if the given value is one of the values that getValues() would return. |
Boolean | isItem(Object something) Returns whether *something* is an item and came from this store instance. |
Boolean | isItemLoaded(Object something) Returns whether *something* is loaded in local memory. |
void | loadItem(Object keywordArgs) Given an item, this method loads the item so that a subsequent call to store.isItemLoaded(item) returns true. |
Object | fetch(Object keywordArgs) Given a query and set of defined options, such as a start and count of items to return, this method runs the query and makes the results available as data items. |
Object | getFeatures() Returns a simple keyword value object that specifies what interface features the data store implements. |
void | close(Object request) Instructs the store to close out any information associated with a particular request. |
String | getLabel(Object item) Method to inspect the item and return a user-readable label for the item that provides a general description of what the item is. |
Array | getLabelAttributes(Object item) Method to inspect the item and return an array of what attributes of the item were used to generate its label, if any attributes exist. |
Function detail |
---|
Returns a single attribute value. Returns defaultValue if item does not have a value for attribute. Returns null if null was set as the attribute value. Returns undefined if the item does not have a value for the given attribute, which is the same as indicating that the item does not have the attribute.
Specifying that an item x does not have a value for an attribute y
is identical to specifying that an item x does not have attribute y.
It is an oxymoron to specify that an 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) returns undefined.
var darthVader = store.getValue(lukeSkywalker, "father");
This getValues() method works like the getValue() method, but getValues() always returns an array rather than a single attribute value. The array might be empty, might contain a single attribute value, or might contain many attribute values. If the item does not have a value for the given attribute, then getValues() returns an empty array: []. If store.hasAttribute(item, attribute) returns false, then store.getValues(item, attribute) returns [].)
var friendsOfLuke = store.getValues(lukeSkywalker, "friends");
Returns an array with all the attributes that this item has. This method returns an array; if the item has no attributes at all, getAttributes() returns an empty array: [].
var array = store.getAttributes(kermit);
Returns true if the given item has a value for the given attribute.
var trueOrFalse = store.hasAttribute(kermit, "color");
Returns true if the given value is one of the values that getValues() returns.
var trueOrFalse = store.containsValue(kermit, "color", "green");
Returns true if the something parameter is an item and came from the store instance. Returns false if the something parameter is a literal, an item from another store instance, or is any object other than an item.
var yes = store.isItem(store.newItem()); var no = store.isItem("green");
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.
var yes = store.isItemLoaded(store.newItem()); var no = store.isItemLoaded("green");
Given an item, this method loads the item so that a subsequent call to store.isItemLoaded(item) returns true. If a call to isItemLoaded() returns true before loadItem() is even called, then the loadItem() object completes no work and does not invoke the callback handlers. Therefore, before invoking this method, check that the item has not already been loaded.
{ item: object, onItem: Function, onError: Function, scope: object }
Given a query and set of defined options, such as a start and count of items to return, this method runs 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 is returned and is returned immediately. The basic request is the keyword args passed to fetch and an additional function attached, abort(). Use the returned request object to cancel a fetch. All data item 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 cannot add methods and properties to the request object returned, only that the API does not require it. For more information about the Request API, see dojo.data.api.Request.
{ query: query-string or query-object, queryOptions: object, onBegin: Function, onItem: Function, onComplete: Function, onError: Function, scope: object, start: int count: int sort: array }
{ ignoreCase: boolean, //Whether the query matches case sensitivity. Default behaviour is false. deep: boolean //Whether a fetch does a deep search of items and each child //item instead of only root-level items in a data store. Default is false. }
{ attribute: attribute || attribute-name-string, descending: true|false; // Optional. Default is false. }When comparing attributes, if an item contains no value for the attribute (undefined), then it the default ascending sort logic pushes that item to the end of the list. In the descending order case, such items are displayed at the top of the list.
The fetch() method returns a JavaScript object conforming to the API defined in dojo.data.api.Request. In general, it is the keywordArgs object returned with the required functions in Request.js attached. The general purpose is to provide a convenient way for a caller to end an ongoing fetch.
The request object can also have additional properties when it is returned, such as request.store property, which is a pointer to the data store object and of which fetch() is a method.
// Fetch all books identified by the query and call 'showBooks' when complete var request = store.fetch({query:"all books", onComplete: showBooks}); // Fetch all items in the story and call 'showEverything' when complete. var request = store.fetch(onComplete: showEverything); // Fetch only 10 books that match the query 'all books', starting at the fifth book found during the search. // This demonstrates how paging can be done for specific queries. var request = store.fetch({query:"all books", start: 4, count: 10, onComplete: showBooks}); // Fetch all items that match the query, calling 'callback' each time an item is located. var request = store.fetch({query:"foo/bar", onItem:callback}); // Fetch the first 100 books by author King; call showKing when up to 100 items have been located. var request = store.fetch({query:{author:"King"}, start: 0, count:100, onComplete: showKing}); // Locate the books written by Author King; sort on title and publisher, then return the first 100 items from the sorted items. var request = store.fetch({query:{author:"King"}, sort: [{ attribute: "title", descending: true}, {attribute: "publisher"}], ,start: 0, count:100, onComplete: 'showKing'}); // Fetch the first 100 books by authors starting with the name King, then call showKing when up to 100 items have been located. var request = store.fetch({query:{author:"King*"}, start: 0, count:100, onComplete: showKing}); // Fetch the first 100 books by authors ending with 'ing', but only have one character before it (King, Bing, Ling, Sing, etc.), then call showBooks when up to 100 items have been located. var request = store.fetch({query:{author:"?ing"}, start: 0, count:100, onComplete: showBooks}); // Fetch the first 100 books by author King, where the name is displayed as King, king, KING, kInG, and so on, then call showKing when up to 100 items have been located. var request = store.fetch({query:{author:"King"}, queryOptions:(ignoreCase: true}, start: 0, count:100, onComplete: showKing}); // Paging: var store = new dojo.data.LargeRdbmsStore({url:"jdbc:odbc:foobar"}); var fetchArgs = { query: {type:"employees", name:"Hillary *"}, // string matching sort: [{attribute:"department", descending:true}], start: 0, count: 20, scope: displayer, onBegin: showThrobber, onItem: displayItem, onComplete: stopThrobber, onError: handleFetchError, }; store.fetch(fetchArgs); // ... // When the user presses the "Next Page" button fetchArgs.start += 20; store.fetch(fetchArgs); // Get the next 20 items
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 then closes out anything associated with that request, such as clearing any internal data store caches and closing any 'open' connections. For some store implementations, this call may be a no-op.
var request = store.fetch({onComplete: doSomething}); //... store.close(request);
Method to inspect the item and return a user-readable label for the item that provides a general or adequate description of the item.
In general, most labels are a specific attribute value or collection of the attribute values that combine to label the item in some manner. For example, for an item that represents a user, the methods might return the label as: first_name last_name where the first_name and last_name are attributes on the item. If the store is unable to determine an adequate human readable label, returns undefined. Users that want to customize how a store instance labels items can replace the getLabel() function on their instance of the store, or extend the store and replace the function in the extension class.
Method to inspect the item and return an array of which item attributes were used to generate its label, if any exist.
This function is to assist user interface developers in knowing which item attributes can be ignored when displaying that item. This situation happens when the UI is using the label as an overall identifer to hide redundant information.