]>
Commit | Line | Data |
---|---|---|
2f01fe57 AD |
1 | /* |
2 | Copyright (c) 2004-2010, The Dojo Foundation All Rights Reserved. | |
3 | Available via Academic Free License >= 2.1 OR the modified BSD license. | |
4 | see: http://dojotoolkit.org/license for details | |
5 | */ | |
6 | ||
7 | ||
a089699c AD |
8 | if(!dojo._hasResource["dojo.data.api.Notification"]){ //_hasResource checks added by build. Do not use _hasResource directly in your code. |
9 | dojo._hasResource["dojo.data.api.Notification"] = true; | |
2f01fe57 AD |
10 | dojo.provide("dojo.data.api.Notification"); |
11 | dojo.require("dojo.data.api.Read"); | |
a089699c AD |
12 | |
13 | dojo.declare("dojo.data.api.Notification", dojo.data.api.Read, { | |
14 | // summary: | |
15 | // This is an abstract API that data provider implementations conform to. | |
16 | // This file defines functions signatures and intentionally leaves all the | |
17 | // functions unimplemented. | |
18 | // | |
19 | // description: | |
20 | // This API defines a set of APIs that all datastores that conform to the | |
21 | // Notifications API must implement. In general, most stores will implement | |
22 | // these APIs as no-op functions for users who wish to monitor them to be able | |
23 | // to connect to then via dojo.connect(). For non-users of dojo.connect, | |
24 | // they should be able to just replace the function on the store to obtain | |
25 | // notifications. Both read-only and read-write stores may implement | |
26 | // this feature. In the case of a read-only store, this feature makes sense if | |
27 | // the store itself does internal polling to a back-end server and periodically updates | |
28 | // its cache of items (deletes, adds, and updates). | |
29 | // | |
30 | // example: | |
31 | // | |
32 | // | function onSet(item, attribute, oldValue, newValue) { | |
33 | // | //Do something with the information... | |
34 | // | }; | |
35 | // | var store = new some.newStore(); | |
36 | // | dojo.connect(store, "onSet", onSet); | |
37 | ||
38 | getFeatures: function(){ | |
39 | // summary: | |
40 | // See dojo.data.api.Read.getFeatures() | |
41 | return { | |
42 | 'dojo.data.api.Read': true, | |
43 | 'dojo.data.api.Notification': true | |
44 | }; | |
45 | }, | |
46 | ||
47 | onSet: function(/* item */ item, | |
48 | /* attribute-name-string */ attribute, | |
49 | /* object | array */ oldValue, | |
50 | /* object | array */ newValue){ | |
51 | // summary: | |
52 | // This function is called any time an item is modified via setValue, setValues, unsetAttribute, etc. | |
53 | // description: | |
54 | // This function is called any time an item is modified via setValue, setValues, unsetAttribute, etc. | |
55 | // Its purpose is to provide a hook point for those who wish to monitor actions on items in the store | |
56 | // in a simple manner. The general expected usage is to dojo.connect() to the store's | |
57 | // implementation and be called after the store function is called. | |
58 | // | |
59 | // item: | |
60 | // The item being modified. | |
61 | // attribute: | |
62 | // The attribute being changed represented as a string name. | |
63 | // oldValue: | |
64 | // The old value of the attribute. In the case of single value calls, such as setValue, unsetAttribute, etc, | |
65 | // this value will be generally be an atomic value of some sort (string, int, etc, object). In the case of | |
66 | // multi-valued attributes, it will be an array. | |
67 | // newValue: | |
68 | // The new value of the attribute. In the case of single value calls, such as setValue, this value will be | |
69 | // generally be an atomic value of some sort (string, int, etc, object). In the case of multi-valued attributes, | |
70 | // it will be an array. In the case of unsetAttribute, the new value will be 'undefined'. | |
71 | // | |
72 | // returns: | |
73 | // Nothing. | |
74 | throw new Error('Unimplemented API: dojo.data.api.Notification.onSet'); | |
75 | }, | |
76 | ||
77 | onNew: function(/* item */ newItem, /*object?*/ parentInfo){ | |
78 | // summary: | |
79 | // This function is called any time a new item is created in the store. | |
80 | // It is called immediately after the store newItem processing has completed. | |
81 | // description: | |
82 | // This function is called any time a new item is created in the store. | |
83 | // It is called immediately after the store newItem processing has completed. | |
84 | // | |
85 | // newItem: | |
86 | // The item created. | |
87 | // parentInfo: | |
88 | // An optional javascript object that is passed when the item created was placed in the store | |
89 | // hierarchy as a value f another item's attribute, instead of a root level item. Note that if this | |
90 | // function is invoked with a value for parentInfo, then onSet is not invoked stating the attribute of | |
91 | // the parent item was modified. This is to avoid getting two notification events occurring when a new item | |
92 | // with a parent is created. The structure passed in is as follows: | |
93 | // { | |
94 | // item: someItem, //The parent item | |
95 | // attribute: "attribute-name-string", //The attribute the new item was assigned to. | |
96 | // oldValue: something //Whatever was the previous value for the attribute. | |
97 | // //If it is a single-value attribute only, then this value will be a single value. | |
98 | // //If it was a multi-valued attribute, then this will be an array of all the values minues the new one. | |
99 | // newValue: something //The new value of the attribute. In the case of single value calls, such as setValue, this value will be | |
100 | // //generally be an atomic value of some sort (string, int, etc, object). In the case of multi-valued attributes, | |
101 | // //it will be an array. | |
102 | // } | |
103 | // | |
104 | // returns: | |
105 | // Nothing. | |
106 | throw new Error('Unimplemented API: dojo.data.api.Notification.onNew'); | |
107 | }, | |
108 | ||
109 | onDelete: function(/* item */ deletedItem){ | |
110 | // summary: | |
111 | // This function is called any time an item is deleted from the store. | |
112 | // It is called immediately after the store deleteItem processing has completed. | |
113 | // description: | |
114 | // This function is called any time an item is deleted from the store. | |
115 | // It is called immediately after the store deleteItem processing has completed. | |
116 | // | |
117 | // deletedItem: | |
118 | // The item deleted. | |
119 | // | |
120 | // returns: | |
121 | // Nothing. | |
122 | throw new Error('Unimplemented API: dojo.data.api.Notification.onDelete'); | |
123 | } | |
124 | }); | |
125 | ||
2f01fe57 | 126 | } |