3
Copyright 2011 Yahoo! Inc. All rights reserved.
4
Licensed under the BSD License.
5
http://yuilibrary.com/license/
7
YUI.add('datasource-local', function(Y) {
10
* The DataSource utility provides a common configurable interface for widgets to
11
* access a variety of data, from JavaScript arrays to online database servers.
18
* Provides the base DataSource implementation, which can be extended to
19
* create DataSources for specific data protocols, such as the IO Utility, the
20
* Get Utility, or custom functions.
23
* @submodule datasource-local
27
* Base class for the DataSource Utility.
28
* @class DataSource.Local
34
DSLocal = function() {
35
DSLocal.superclass.constructor.apply(this, arguments);
38
/////////////////////////////////////////////////////////////////////////////
40
// DataSource static properties
42
/////////////////////////////////////////////////////////////////////////////
51
* @value "dataSourceLocal"
53
NAME: "dataSourceLocal",
55
/////////////////////////////////////////////////////////////////////////////
57
// DataSource Attributes
59
/////////////////////////////////////////////////////////////////////////////
64
* @description Pointer to live data.
74
* Global transaction counter.
85
* Global in-progress transaction objects.
87
* @property transactions
94
* Returns data to callback.
96
* @method issueCallback
97
* @param e {EventFacade} Event Facade.
98
* @param caller {DataSource} Calling DataSource instance.
101
issueCallback: function (e, caller) {
102
var callbacks = e.on || e.callback,
103
callback = callbacks && callbacks.success,
104
payload = e.details[0];
106
payload.error = (e.error || e.response.error);
109
caller.fire("error", payload);
110
callback = callbacks && callbacks.failure;
114
//TODO: this should be executed from a specific context
120
Y.extend(DSLocal, Y.Base, {
122
* Internal init() handler.
124
* @method initializer
125
* @param config {Object} Config object.
128
initializer: function(config) {
133
* This method creates all the events for this module.
134
* @method _initEvents
137
_initEvents: function() {
139
* Fired when a data request is received.
142
* @param e {Event.Facade} Event Facade with the following properties:
144
* <dt>tId (Number)</dt> <dd>Unique transaction ID.</dd>
145
* <dt>request (Object)</dt> <dd>The request.</dd>
146
* <dt>callback (Object)</dt> <dd>The callback object
147
* (deprecated, refer to <strong>on</strong></dd>
148
* <dt>on (Object)</dt> <dd>The map of configured callback
150
* <dt>cfg (Object)</dt> <dd>Configuration object.</dd>
152
* @preventable _defRequestFn
154
this.publish("request", {defaultFn: Y.bind("_defRequestFn", this), queuable:true});
157
* Fired when raw data is received.
160
* @param e {Event.Facade} Event Facade with the following properties:
162
* <dt>tId (Number)</dt> <dd>Unique transaction ID.</dd>
163
* <dt>request (Object)</dt> <dd>The request.</dd>
164
* <dt>callback (Object)</dt> <dd>Deprecated alias for the
165
* <strong>on</strong> property</dd>
166
* <dt>on (Object)</dt> <dd>The map of configured transaction
167
* callbacks. An object with the following properties:
169
* <dt>success (Function)</dt> <dd>Success handler.</dd>
170
* <dt>failure (Function)</dt> <dd>Failure handler.</dd>
173
* <dt>cfg (Object)</dt> <dd>Configuration object.</dd>
174
* <dt>data (Object)</dt> <dd>Raw data.</dd>
176
* @preventable _defDataFn
178
this.publish("data", {defaultFn: Y.bind("_defDataFn", this), queuable:true});
181
* Fired when response is returned.
184
* @param e {Event.Facade} Event Facade with the following properties:
186
* <dt>tId (Number)</dt> <dd>Unique transaction ID.</dd>
187
* <dt>request (Object)</dt> <dd>The request.</dd>
188
* <dt>callback (Object)</dt> <dd>Deprecated alias for the
189
* <strong>on</strong> property</dd>
190
* <dt>on (Object)</dt> <dd>The map of configured transaction
191
* callbacks. An object with the following properties:
193
* <dt>success (Function)</dt> <dd>Success handler.</dd>
194
* <dt>failure (Function)</dt> <dd>Failure handler.</dd>
197
* <dt>cfg (Object)</dt> <dd>Configuration object.</dd>
198
* <dt>data (Object)</dt> <dd>Raw data.</dd>
199
* <dt>response (Object)</dt>
200
* <dd>Normalized response object with the following properties:
202
* <dt>results (Object)</dt> <dd>Parsed results.</dd>
203
* <dt>meta (Object)</dt> <dd>Parsed meta data.</dd>
204
* <dt>error (Boolean)</dt> <dd>Error flag.</dd>
208
* <dd>Any error that occurred along the transaction lifecycle.</dd>
210
* @preventable _defResponseFn
212
this.publish("response", {defaultFn: Y.bind("_defResponseFn", this), queuable:true});
215
* Fired when an error is encountered.
218
* @param e {Event.Facade} Event Facade with the following properties:
220
* <dt>tId (Number)</dt> <dd>Unique transaction ID.</dd>
221
* <dt>request (Object)</dt> <dd>The request.</dd>
222
* <dt>callback (Object)</dt> <dd>Deprecated alias for the
223
* <strong>on</strong> property</dd>
224
* <dt>on (Object)</dt> <dd>The map of configured transaction
225
* callbacks. An object with the following properties:
227
* <dt>success (Function)</dt> <dd>Success handler.</dd>
228
* <dt>failure (Function)</dt> <dd>Failure handler.</dd>
231
* <dt>cfg (Object)</dt> <dd>Configuration object.</dd>
232
* <dt>data (Object)</dt> <dd>Raw data.</dd>
233
* <dt>response (Object)</dt>
234
* <dd>Normalized response object with the following properties:
236
* <dt>results (Object)</dt> <dd>Parsed results.</dd>
237
* <dt>meta (Object)</dt> <dd>Parsed meta data.</dd>
238
* <dt>error (Object)</dt> <dd>Error object.</dd>
242
* <dd>Any error that occurred along the transaction lifecycle.</dd>
249
* Manages request/response transaction. Must fire <code>response</code>
250
* event when response is received. This method should be implemented by
251
* subclasses to achieve more complex behavior such as accessing remote data.
253
* @method _defRequestFn
254
* @param e {Event.Facade} Event Facadewith the following properties:
256
* <dt>tId (Number)</dt> <dd>Unique transaction ID.</dd>
257
* <dt>request (Object)</dt> <dd>The request.</dd>
258
* <dt>callback (Object)</dt> <dd>Deprecated alias for the
259
* <strong>on</strong> property</dd>
260
* <dt>on (Object)</dt> <dd>The map of configured transaction
261
* callbacks. An object with the following properties:
263
* <dt>success (Function)</dt> <dd>Success handler.</dd>
264
* <dt>failure (Function)</dt> <dd>Failure handler.</dd>
267
* <dt>cfg (Object)</dt> <dd>Configuration object.</dd>
271
_defRequestFn: function(e) {
272
var data = this.get("source"),
273
payload = e.details[0];
276
if(LANG.isUndefined(data)) {
277
payload.error = new Error("Local source undefined");
278
Y.log("Local source undefined", "error", "datasource-local");
282
this.fire("data", payload);
283
Y.log("Transaction " + e.tId + " complete. Request: " +
284
Y.dump(e.request) + " . Response: " + Y.dump(e.response), "info", "datasource-local");
288
* Normalizes raw data into a response that includes results and meta properties.
291
* @param e {Event.Facade} Event Facade with the following properties:
293
* <dt>tId (Number)</dt> <dd>Unique transaction ID.</dd>
294
* <dt>request (Object)</dt> <dd>The request.</dd>
295
* <dt>callback (Object)</dt> <dd>Deprecated alias for the
296
* <strong>on</strong> property</dd>
297
* <dt>on (Object)</dt> <dd>The map of configured transaction
298
* callbacks. An object with the following properties:
300
* <dt>success (Function)</dt> <dd>Success handler.</dd>
301
* <dt>failure (Function)</dt> <dd>Failure handler.</dd>
304
* <dt>cfg (Object)</dt> <dd>Configuration object.</dd>
305
* <dt>data (Object)</dt> <dd>Raw data.</dd>
309
_defDataFn: function(e) {
313
results: (LANG.isArray(data)) ? data : [data],
314
meta: (meta) ? meta : {}
316
payload = e.details[0];
318
payload.response = response;
319
this.fire("response", payload);
323
* Sends data as a normalized response to callback.
325
* @method _defResponseFn
326
* @param e {Event.Facade} Event Facade with the following properties:
328
* <dt>tId (Number)</dt> <dd>Unique transaction ID.</dd>
329
* <dt>request (Object)</dt> <dd>The request.</dd>
330
* <dt>callback (Object)</dt> <dd>Deprecated alias for the
331
* <strong>on</strong> property</dd>
332
* <dt>on (Object)</dt> <dd>The map of configured transaction
333
* callbacks. An object with the following properties:
335
* <dt>success (Function)</dt> <dd>Success handler.</dd>
336
* <dt>failure (Function)</dt> <dd>Failure handler.</dd>
339
* <dt>cfg (Object)</dt> <dd>Configuration object.</dd>
340
* <dt>data (Object)</dt> <dd>Raw data.</dd>
341
* <dt>response (Object)</dt> <dd>Normalized response object with the following properties:
343
* <dt>results (Object)</dt> <dd>Parsed results.</dd>
344
* <dt>meta (Object)</dt> <dd>Parsed meta data.</dd>
345
* <dt>error (Boolean)</dt> <dd>Error flag.</dd>
351
_defResponseFn: function(e) {
352
// Send the response back to the callback
353
DSLocal.issueCallback(e, this);
357
* Generates a unique transaction ID and fires <code>request</code> event.
358
* <strong>Note</strong>: the property <code>callback</code> is a
359
* deprecated alias for the <code>on</code> transaction configuration
360
* property described below.
362
* @method sendRequest
363
* @param request {Object} An object literal with the following properties:
365
* <dt><code>request</code></dt>
366
* <dd>The request to send to the live data source, if any.</dd>
367
* <dt><code>on</code></dt>
368
* <dd>An object literal with the following properties:
370
* <dt><code>success</code></dt>
371
* <dd>The function to call when the data is ready.</dd>
372
* <dt><code>failure</code></dt>
373
* <dd>The function to call upon a response failure condition.</dd>
374
* <dt><code>argument</code></dt>
375
* <dd>Arbitrary data payload that will be passed back to the success and failure handlers.</dd>
378
* <dt><code>cfg</code></dt>
379
* <dd>Configuration object, if any.</dd>
381
* @return {Number} Transaction ID.
383
sendRequest: function(request) {
384
var tId = DSLocal._tId++,
387
request = request || {};
389
callbacks = request.on || request.callback;
391
this.fire("request", {
393
request: request.request,
396
cfg: request.cfg || {}
399
Y.log("Transaction " + tId + " sent request: " + Y.dump(request.request), "info", "datasource-local");
405
Y.namespace("DataSource").Local = DSLocal;
408
}, '3.4.1' ,{requires:['base']});