Skip to content

HTTPS clone URL

Subversion checkout URL

You can clone with HTTPS or Subversion.

Download ZIP
Newer
Older
100644 92 lines (55 sloc) 5.597 kb
fcc4fff @phiggins42 monster commit from moinconverter, which is always done prior to the svn...
phiggins42 authored
1 .. _dojo/data/api:
d608cc5 @phiggins42 \r\n -> \n conversion.
phiggins42 authored
2
b0d71a2 @phiggins42 headings
phiggins42 authored
3 =============
4 dojo.data API
9dd52dc @phiggins42 mondo whitespace change
phiggins42 authored
5 =============
d608cc5 @phiggins42 \r\n -> \n conversion.
phiggins42 authored
6
c15cbf2 @wkeese standardize spacing on directives like .. js
wkeese authored
7 .. contents ::
b0d71a2 @phiggins42 headings
phiggins42 authored
8 :depth: 2
d608cc5 @phiggins42 \r\n -> \n conversion.
phiggins42 authored
9
10
aa84a72 @wkeese dojo/ spelling
wkeese authored
11 Before diving directly into the APIs of dojo.data, the basic concepts behind the APIs need to be explored because some design decisions that were made might seem odd without an explanation as to why they were chosen. Therefore, read this page in its entirety before moving onto the individual APIs.
d608cc5 @phiggins42 \r\n -> \n conversion.
phiggins42 authored
12
9dd52dc @phiggins42 mondo whitespace change
phiggins42 authored
13 Concept 1: Data access is broken down into separate APIs
14 ========================================================
d608cc5 @phiggins42 \r\n -> \n conversion.
phiggins42 authored
15
9dd52dc @phiggins42 mondo whitespace change
phiggins42 authored
16 Data access is broken down into separate APIs because not every service or data backend is able to provide complete access and functions. So not all datastores could possibly implement functions such as read, write, identify, or notifications. To make it simple to see what features a store provides, each store must provide the 'getFeatures()' function. This function reports which APIs the store implements. The following list of basic APIs are defined:
d608cc5 @phiggins42 \r\n -> \n conversion.
phiggins42 authored
17
9dd52dc @phiggins42 mondo whitespace change
phiggins42 authored
18 **dojo.data.api.Read** (:ref:`Read API Reference <dojo/data/api/Read>`)
d608cc5 @phiggins42 \r\n -> \n conversion.
phiggins42 authored
19
9dd52dc @phiggins42 mondo whitespace change
phiggins42 authored
20 The ability to read data items and attributes of those data items. This also includes the ability to search, sort, and filter data items.
d608cc5 @phiggins42 \r\n -> \n conversion.
phiggins42 authored
21
9dd52dc @phiggins42 mondo whitespace change
phiggins42 authored
22 **dojo.data.api.Write** (:ref:`Write API Reference <dojo/data/api/Write>`)
d608cc5 @phiggins42 \r\n -> \n conversion.
phiggins42 authored
23
9dd52dc @phiggins42 mondo whitespace change
phiggins42 authored
24 The ability to create, delete, and update data items and attributes of those data items. Not all back end services allow for modification of data items. In fact, most public services like Flikr, Delicious, GoogleMaps, for example are primarily read-based data providers.
d608cc5 @phiggins42 \r\n -> \n conversion.
phiggins42 authored
25
9dd52dc @phiggins42 mondo whitespace change
phiggins42 authored
26 **dojo.data.api.Identity** (:ref:`Identity API Reference <dojo/data/api/Identity>`)
27 The ability to locate and look up an item based on its unique identifier, if it has one. Not all data formats have unique identifiers that can be used to look up data items.
d608cc5 @phiggins42 \r\n -> \n conversion.
phiggins42 authored
28
9dd52dc @phiggins42 mondo whitespace change
phiggins42 authored
29 **dojo.data.api.Notification** (:ref:`Notification API Reference <dojo/data/api/Notification>`)
d608cc5 @phiggins42 \r\n -> \n conversion.
phiggins42 authored
30
9dd52dc @phiggins42 mondo whitespace change
phiggins42 authored
31 The ability to notify listeners for change events on data items in a store. The basic change events for an item are create, delete, and update. These are particularly useful for cases such as a datastore that periodically polls a back end service for data refresh.
d608cc5 @phiggins42 \r\n -> \n conversion.
phiggins42 authored
32
9dd52dc @phiggins42 mondo whitespace change
phiggins42 authored
33 Future Features
34 ---------------
d608cc5 @phiggins42 \r\n -> \n conversion.
phiggins42 authored
35
9dd52dc @phiggins42 mondo whitespace change
phiggins42 authored
36 There are further functions that the Dojo development community would like to define as additional features stores which might be implemented. However, they have not been completely specified yet and are a work in progress. As such, they are not currently provided in the Dojo Toolkit. Note that the list can change at any time as decisions evolve about what capabilities the dojo.data APIs should provide. The following features are functions that the Dojo development community would like to define as additional features stores to implement:
d608cc5 @phiggins42 \r\n -> \n conversion.
phiggins42 authored
37
9dd52dc @phiggins42 mondo whitespace change
phiggins42 authored
38 **dojo.data.api.Schema**
d608cc5 @phiggins42 \r\n -> \n conversion.
phiggins42 authored
39
9dd52dc @phiggins42 mondo whitespace change
phiggins42 authored
40 **dojo.data.api.Attribution**
d608cc5 @phiggins42 \r\n -> \n conversion.
phiggins42 authored
41
9dd52dc @phiggins42 mondo whitespace change
phiggins42 authored
42 Creation and modification of timestamps, author, and other functions of data items.
d608cc5 @phiggins42 \r\n -> \n conversion.
phiggins42 authored
43
9dd52dc @phiggins42 mondo whitespace change
phiggins42 authored
44 **dojo.data.api.Versioning**
d608cc5 @phiggins42 \r\n -> \n conversion.
phiggins42 authored
45
9dd52dc @phiggins42 mondo whitespace change
phiggins42 authored
46 Tracking and accessing old versions of data items.
d608cc5 @phiggins42 \r\n -> \n conversion.
phiggins42 authored
47
9dd52dc @phiggins42 mondo whitespace change
phiggins42 authored
48 **dojo.data.api.Derivation**
49 Attributes derived from other attributes and calculated values
d608cc5 @phiggins42 \r\n -> \n conversion.
phiggins42 authored
50
9dd52dc @phiggins42 mondo whitespace change
phiggins42 authored
51 Concept 2: All items are operated on through store functions
52 ============================================================
d608cc5 @phiggins42 \r\n -> \n conversion.
phiggins42 authored
53
9dd52dc @phiggins42 mondo whitespace change
phiggins42 authored
54 **Note:** Attributes are never directly accessed from the item object.
d608cc5 @phiggins42 \r\n -> \n conversion.
phiggins42 authored
55
9dd52dc @phiggins42 mondo whitespace change
phiggins42 authored
56 This concept is likely one of the aspects of dojo.data that might seem confusing at first. The following code snippet shows this concept:
d608cc5 @phiggins42 \r\n -> \n conversion.
phiggins42 authored
57
9dd52dc @phiggins42 mondo whitespace change
phiggins42 authored
58 Correct access
59 --------------
d608cc5 @phiggins42 \r\n -> \n conversion.
phiggins42 authored
60
c49c87d @phiggins42 normalization
phiggins42 authored
61 .. js ::
d608cc5 @phiggins42 \r\n -> \n conversion.
phiggins42 authored
62
9dd52dc @phiggins42 mondo whitespace change
phiggins42 authored
63 var store = new some.data.Store();
64 var items;
c08f00e @wkeese normalize comment format, putting space after //
wkeese authored
65 ... // Assume in this time items is now an array populated by a call to store.fetch();
66 // To iterate over the items and print out the value of a 'foo' attribute, you would do the following:
67f7d9e @wkeese Fix spacing for braces, function(), if(), while(), for(), else, etc. to ...
wkeese authored
67 for(var i = 0; i < items.length; i++){
9dd52dc @phiggins42 mondo whitespace change
phiggins42 authored
68 var item = items[i];
69 console.log("For attribute 'foo' value was: [" + store.getValue(item, "foo") + "]");
70 }
d608cc5 @phiggins42 \r\n -> \n conversion.
phiggins42 authored
71
72
9dd52dc @phiggins42 mondo whitespace change
phiggins42 authored
73 This example might make you wonder why attributes are not accessed as shown in one of the following examples:
d608cc5 @phiggins42 \r\n -> \n conversion.
phiggins42 authored
74
9dd52dc @phiggins42 mondo whitespace change
phiggins42 authored
75 Incorrect access
76 ----------------
d608cc5 @phiggins42 \r\n -> \n conversion.
phiggins42 authored
77
9dd52dc @phiggins42 mondo whitespace change
phiggins42 authored
78 * var value = item["foo"];
79 * var value = item.foo;
80 * var value = item.getValue("foo");
d608cc5 @phiggins42 \r\n -> \n conversion.
phiggins42 authored
81
9dd52dc @phiggins42 mondo whitespace change
phiggins42 authored
82 Why is it a requirement to use a store accessor function in dojo.data? The reasons are many:
d608cc5 @phiggins42 \r\n -> \n conversion.
phiggins42 authored
83
9dd52dc @phiggins42 mondo whitespace change
phiggins42 authored
84 * Efficiency in accessing the values on the items: By requiring access to go through store functions, the store can hide the internal structure of the item. This allows the item to remain in a format that is most efficient for representing the datatype for a particular situation. For example, the items could be XML DOM elements and, in that case, the store would access the values using DOM APIs when store.getValue() is called.
d608cc5 @phiggins42 \r\n -> \n conversion.
phiggins42 authored
85
9dd52dc @phiggins42 mondo whitespace change
phiggins42 authored
86 As a second example, the item might be a simple JavaScript structure and the store can then access the values through normal JavaScript accessor notation. From the end-users perspective, the access is exactly the same: store.getValue(item, "attribute"). This provides a consistent look and feel to accessing a variety of data types. This also provides efficiency in accessing items by reducing item load times by avoiding conversion to a defined internal format that all stores would have to use.
d608cc5 @phiggins42 \r\n -> \n conversion.
phiggins42 authored
87
9dd52dc @phiggins42 mondo whitespace change
phiggins42 authored
88 * The store could use a very compact internal structure: This lessens the amount of memory required by a particular store to represent some item and its attribute values.
d608cc5 @phiggins42 \r\n -> \n conversion.
phiggins42 authored
89
9dd52dc @phiggins42 mondo whitespace change
phiggins42 authored
90 * Going through store accessor function provides the possibility of lazy-loading in of values as well as lazy reference resolution.
91 * Requiring items to be objects with accessor functions on the object for the value would be very expensive to construct, particularly for large data sets. Therefore, it is not a requirement.
Something went wrong with that request. Please try again.