2 Copyright (c) 2010, Yahoo! Inc. All rights reserved.
3 Code licensed under the BSD License:
4 http://developer.yahoo.com/yui/license.html
8 YUI.add('datasource-local', function(Y) {
11 * The DataSource utility provides a common configurable interface for widgets to
12 * 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.
76 * @property DataSource._tId
85 * Global in-progress transaction objects.
87 * @property DataSource.transactions
94 * Returns data to callback.
96 * @method DataSource.issueCallback
97 * @param e {EventFacade} Event Facade.
98 * @param caller {DataSource} Calling DataSource instance.
101 issueCallback: function (e, caller) {
102 var error = (e.error || e.response.error);
104 e.error = e.error || e.response.error;
105 caller.fire("error", e);
108 var callbackFunc = (error && e.callback.failure) || e.callback.success;
116 Y.extend(DSLocal, Y.Base, {
118 * Internal init() handler.
120 * @method initializer
121 * @param config {Object} Config object.
124 initializer: function(config) {
129 * This method creates all the events for this module.
130 * @method _initEvents
133 _initEvents: function() {
135 * Fired when a data request is received.
138 * @param e {Event.Facade} Event Facade with the following properties:
140 * <dt>tId (Number)</dt> <dd>Unique transaction ID.</dd>
141 * <dt>request (Object)</dt> <dd>The request.</dd>
142 * <dt>callback (Object)</dt> <dd>The callback object.</dd>
143 * <dt>cfg (Object)</dt> <dd>Configuration object.</dd>
145 * @preventable _defRequestFn
147 this.publish("request", {defaultFn: Y.bind("_defRequestFn", this), queuable:true});
150 * Fired when raw data is received.
153 * @param e {Event.Facade} Event Facade with the following properties:
155 * <dt>tId (Number)</dt> <dd>Unique transaction ID.</dd>
156 * <dt>request (Object)</dt> <dd>The request.</dd>
157 * <dt>callback (Object)</dt> <dd>The callback object with the following properties:
159 * <dt>success (Function)</dt> <dd>Success handler.</dd>
160 * <dt>failure (Function)</dt> <dd>Failure handler.</dd>
163 * <dt>cfg (Object)</dt> <dd>Configuration object.</dd>
164 * <dt>data (Object)</dt> <dd>Raw data.</dd>
166 * @preventable _defDataFn
168 this.publish("data", {defaultFn: Y.bind("_defDataFn", this), queuable:true});
171 * Fired when response is returned.
174 * @param e {Event.Facade} Event Facade with the following properties:
176 * <dt>tId (Number)</dt> <dd>Unique transaction ID.</dd>
177 * <dt>request (Object)</dt> <dd>The request.</dd>
178 * <dt>callback (Object)</dt> <dd>The callback object with the following properties:
180 * <dt>success (Function)</dt> <dd>Success handler.</dd>
181 * <dt>failure (Function)</dt> <dd>Failure handler.</dd>
184 * <dt>cfg (Object)</dt> <dd>Configuration object.</dd>
185 * <dt>data (Object)</dt> <dd>Raw data.</dd>
186 * <dt>response (Object)</dt> <dd>Normalized response object with the following properties:
188 * <dt>results (Object)</dt> <dd>Parsed results.</dd>
189 * <dt>meta (Object)</dt> <dd>Parsed meta data.</dd>
190 * <dt>error (Boolean)</dt> <dd>Error flag.</dd>
194 * @preventable _defResponseFn
196 this.publish("response", {defaultFn: Y.bind("_defResponseFn", this), queuable:true});
199 * Fired when an error is encountered.
202 * @param e {Event.Facade} Event Facade with the following properties:
204 * <dt>tId (Number)</dt> <dd>Unique transaction ID.</dd>
205 * <dt>request (Object)</dt> <dd>The request.</dd>
206 * <dt>callback (Object)</dt> <dd>The callback object with the following properties:
208 * <dt>success (Function)</dt> <dd>Success handler.</dd>
209 * <dt>failure (Function)</dt> <dd>Failure handler.</dd>
212 * <dt>cfg (Object)</dt> <dd>Configuration object.</dd>
213 * <dt>data (Object)</dt> <dd>Raw data.</dd>
214 * <dt>response (Object)</dt> <dd>Normalized response object with the following properties:
216 * <dt>results (Object)</dt> <dd>Parsed results.</dd>
217 * <dt>meta (Object)</dt> <dd>Parsed meta data.</dd>
218 * <dt>error (Object)</dt> <dd>Error object.</dd>
227 * Manages request/response transaction. Must fire <code>response</code>
228 * event when response is received. This method should be implemented by
229 * subclasses to achieve more complex behavior such as accessing remote data.
231 * @method _defRequestFn
232 * @param e {Event.Facade} Event Facadewith the following properties:
234 * <dt>tId (Number)</dt> <dd>Unique transaction ID.</dd>
235 * <dt>request (Object)</dt> <dd>The request.</dd>
236 * <dt>callback (Object)</dt> <dd>The callback object with the following properties:
238 * <dt>success (Function)</dt> <dd>Success handler.</dd>
239 * <dt>failure (Function)</dt> <dd>Failure handler.</dd>
242 * <dt>cfg (Object)</dt> <dd>Configuration object.</dd>
246 _defRequestFn: function(e) {
247 var data = this.get("source");
250 if(LANG.isUndefined(data)) {
251 e.error = new Error("Local source undefined");
254 this.fire("data", Y.mix({data:data}, e));
258 * Normalizes raw data into a response that includes results and meta properties.
261 * @param e {Event.Facade} Event Facade with the following properties:
263 * <dt>tId (Number)</dt> <dd>Unique transaction ID.</dd>
264 * <dt>request (Object)</dt> <dd>The request.</dd>
265 * <dt>callback (Object)</dt> <dd>The callback object with the following properties:
267 * <dt>success (Function)</dt> <dd>Success handler.</dd>
268 * <dt>failure (Function)</dt> <dd>Failure handler.</dd>
271 * <dt>cfg (Object)</dt> <dd>Configuration object.</dd>
272 * <dt>data (Object)</dt> <dd>Raw data.</dd>
276 _defDataFn: function(e) {
280 results: (LANG.isArray(data)) ? data : [data],
281 meta: (meta) ? meta : {}
284 this.fire("response", Y.mix({response: response}, e));
288 * Sends data as a normalized response to callback.
290 * @method _defResponseFn
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>The callback object with the following properties:
297 * <dt>success (Function)</dt> <dd>Success handler.</dd>
298 * <dt>failure (Function)</dt> <dd>Failure handler.</dd>
301 * <dt>cfg (Object)</dt> <dd>Configuration object.</dd>
302 * <dt>data (Object)</dt> <dd>Raw data.</dd>
303 * <dt>response (Object)</dt> <dd>Normalized response object with the following properties:
305 * <dt>results (Object)</dt> <dd>Parsed results.</dd>
306 * <dt>meta (Object)</dt> <dd>Parsed meta data.</dd>
307 * <dt>error (Boolean)</dt> <dd>Error flag.</dd>
313 _defResponseFn: function(e) {
314 // Send the response back to the callback
315 DSLocal.issueCallback(e, this);
319 * Generates a unique transaction ID and fires <code>request</code> event.
321 * @method sendRequest
322 * @param request {Object} An object literal with the following properties:
324 * <dt><code>request</code></dt>
325 * <dd>The request to send to the live data source, if any.</dd>
326 * <dt><code>callback</code></dt>
327 * <dd>An object literal with the following properties:
329 * <dt><code>success</code></dt>
330 * <dd>The function to call when the data is ready.</dd>
331 * <dt><code>failure</code></dt>
332 * <dd>The function to call upon a response failure condition.</dd>
333 * <dt><code>argument</code></dt>
334 * <dd>Arbitrary data payload that will be passed back to the success and failure handlers.</dd>
337 * <dt><code>cfg</code></dt>
338 * <dd>Configuration object, if any.</dd>
340 * @return {Number} Transaction ID.
342 sendRequest: function(request) {
343 request = request || {};
344 var tId = DSLocal._tId++;
345 this.fire("request", {tId:tId, request:request.request, callback:request.callback, cfg:request.cfg || {}});
350 Y.namespace("DataSource").Local = DSLocal;
354 }, '3.3.0' ,{requires:['base']});