2 YUI 3.13.0 (build 508226d)
3 Copyright 2013 Yahoo! Inc. All rights reserved.
4 Licensed under the BSD License.
5 http://yuilibrary.com/license/
8 YUI.add('datasource-local', function (Y, NAME) {
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.
19 * Provides the base DataSource implementation, which can be extended to
20 * create DataSources for specific data protocols, such as the IO Utility, the
21 * Get Utility, or custom functions.
24 * @submodule datasource-local
28 * Base class for the DataSource Utility.
29 * @class DataSource.Local
35 DSLocal = function() {
36 DSLocal.superclass.constructor.apply(this, arguments);
39 /////////////////////////////////////////////////////////////////////////////
41 // DataSource static properties
43 /////////////////////////////////////////////////////////////////////////////
52 * @value "dataSourceLocal"
54 NAME: "dataSourceLocal",
56 /////////////////////////////////////////////////////////////////////////////
58 // DataSource Attributes
60 /////////////////////////////////////////////////////////////////////////////
65 * @description Pointer to live data.
75 * Global transaction counter.
86 * Global in-progress transaction objects.
88 * @property transactions
95 * Returns data to callback.
97 * @method issueCallback
98 * @param e {EventFacade} Event Facade.
99 * @param caller {DataSource} Calling DataSource instance.
102 issueCallback: function (e, caller) {
103 var callbacks = e.on || e.callback,
104 callback = callbacks && callbacks.success,
105 payload = e.details[0];
107 payload.error = (e.error || e.response.error);
110 caller.fire("error", payload);
111 callback = callbacks && callbacks.failure;
115 //TODO: this should be executed from a specific context
121 Y.extend(DSLocal, Y.Base, {
123 * Internal init() handler.
125 * @method initializer
126 * @param config {Object} Config object.
129 initializer: function(config) {
134 * This method creates all the events for this module.
135 * @method _initEvents
138 _initEvents: function() {
140 * Fired when a data request is received.
143 * @param e {Event.Facade} Event Facade with the following properties:
145 * <dt>tId (Number)</dt> <dd>Unique transaction ID.</dd>
146 * <dt>request (Object)</dt> <dd>The request.</dd>
147 * <dt>callback (Object)</dt> <dd>The callback object
148 * (deprecated, refer to <strong>on</strong></dd>
149 * <dt>on (Object)</dt> <dd>The map of configured callback
151 * <dt>cfg (Object)</dt> <dd>Configuration object.</dd>
153 * @preventable _defRequestFn
155 this.publish("request", {defaultFn: Y.bind("_defRequestFn", this), queuable:true});
158 * Fired when raw data is received.
161 * @param e {Event.Facade} Event Facade with the following properties:
163 * <dt>tId (Number)</dt> <dd>Unique transaction ID.</dd>
164 * <dt>request (Object)</dt> <dd>The request.</dd>
165 * <dt>callback (Object)</dt> <dd>Deprecated alias for the
166 * <strong>on</strong> property</dd>
167 * <dt>on (Object)</dt> <dd>The map of configured transaction
168 * callbacks. An object with the following properties:
170 * <dt>success (Function)</dt> <dd>Success handler.</dd>
171 * <dt>failure (Function)</dt> <dd>Failure handler.</dd>
174 * <dt>cfg (Object)</dt> <dd>Configuration object.</dd>
175 * <dt>data (Object)</dt> <dd>Raw data.</dd>
177 * @preventable _defDataFn
179 this.publish("data", {defaultFn: Y.bind("_defDataFn", this), queuable:true});
182 * Fired when response is returned.
185 * @param e {Event.Facade} Event Facade with the following properties:
187 * <dt>tId (Number)</dt> <dd>Unique transaction ID.</dd>
188 * <dt>request (Object)</dt> <dd>The request.</dd>
189 * <dt>callback (Object)</dt> <dd>Deprecated alias for the
190 * <strong>on</strong> property</dd>
191 * <dt>on (Object)</dt> <dd>The map of configured transaction
192 * callbacks. An object with the following properties:
194 * <dt>success (Function)</dt> <dd>Success handler.</dd>
195 * <dt>failure (Function)</dt> <dd>Failure handler.</dd>
198 * <dt>cfg (Object)</dt> <dd>Configuration object.</dd>
199 * <dt>data (Object)</dt> <dd>Raw data.</dd>
200 * <dt>response (Object)</dt>
201 * <dd>Normalized response object with the following properties:
203 * <dt>results (Object)</dt> <dd>Parsed results.</dd>
204 * <dt>meta (Object)</dt> <dd>Parsed meta data.</dd>
205 * <dt>error (Boolean)</dt> <dd>Error flag.</dd>
209 * <dd>Any error that occurred along the transaction lifecycle.</dd>
211 * @preventable _defResponseFn
213 this.publish("response", {defaultFn: Y.bind("_defResponseFn", this), queuable:true});
216 * Fired when an error is encountered.
219 * @param e {Event.Facade} Event Facade with the following properties:
221 * <dt>tId (Number)</dt> <dd>Unique transaction ID.</dd>
222 * <dt>request (Object)</dt> <dd>The request.</dd>
223 * <dt>callback (Object)</dt> <dd>Deprecated alias for the
224 * <strong>on</strong> property</dd>
225 * <dt>on (Object)</dt> <dd>The map of configured transaction
226 * callbacks. An object with the following properties:
228 * <dt>success (Function)</dt> <dd>Success handler.</dd>
229 * <dt>failure (Function)</dt> <dd>Failure handler.</dd>
232 * <dt>cfg (Object)</dt> <dd>Configuration object.</dd>
233 * <dt>data (Object)</dt> <dd>Raw data.</dd>
234 * <dt>response (Object)</dt>
235 * <dd>Normalized response object with the following properties:
237 * <dt>results (Object)</dt> <dd>Parsed results.</dd>
238 * <dt>meta (Object)</dt> <dd>Parsed meta data.</dd>
239 * <dt>error (Object)</dt> <dd>Error object.</dd>
243 * <dd>Any error that occurred along the transaction lifecycle.</dd>
250 * Manages request/response transaction. Must fire <code>response</code>
251 * event when response is received. This method should be implemented by
252 * subclasses to achieve more complex behavior such as accessing remote data.
254 * @method _defRequestFn
255 * @param e {Event.Facade} Event Facadewith the following properties:
257 * <dt>tId (Number)</dt> <dd>Unique transaction ID.</dd>
258 * <dt>request (Object)</dt> <dd>The request.</dd>
259 * <dt>callback (Object)</dt> <dd>Deprecated alias for the
260 * <strong>on</strong> property</dd>
261 * <dt>on (Object)</dt> <dd>The map of configured transaction
262 * callbacks. An object with the following properties:
264 * <dt>success (Function)</dt> <dd>Success handler.</dd>
265 * <dt>failure (Function)</dt> <dd>Failure handler.</dd>
268 * <dt>cfg (Object)</dt> <dd>Configuration object.</dd>
272 _defRequestFn: function(e) {
273 var data = this.get("source"),
274 payload = e.details[0];
277 if(LANG.isUndefined(data)) {
278 payload.error = new Error("Local source undefined");
279 Y.log("Local source undefined", "error", "datasource-local");
283 this.fire("data", payload);
284 Y.log("Transaction " + e.tId + " complete. Request: " +
285 Y.dump(e.request) + " . Response: " + Y.dump(e.response), "info", "datasource-local");
289 * Normalizes raw data into a response that includes results and meta properties.
292 * @param e {Event.Facade} Event Facade with the following properties:
294 * <dt>tId (Number)</dt> <dd>Unique transaction ID.</dd>
295 * <dt>request (Object)</dt> <dd>The request.</dd>
296 * <dt>callback (Object)</dt> <dd>Deprecated alias for the
297 * <strong>on</strong> property</dd>
298 * <dt>on (Object)</dt> <dd>The map of configured transaction
299 * callbacks. An object with the following properties:
301 * <dt>success (Function)</dt> <dd>Success handler.</dd>
302 * <dt>failure (Function)</dt> <dd>Failure handler.</dd>
305 * <dt>cfg (Object)</dt> <dd>Configuration object.</dd>
306 * <dt>data (Object)</dt> <dd>Raw data.</dd>
310 _defDataFn: function(e) {
314 results: (LANG.isArray(data)) ? data : [data],
315 meta: (meta) ? meta : {}
317 payload = e.details[0];
319 payload.response = response;
320 this.fire("response", payload);
324 * Sends data as a normalized response to callback.
326 * @method _defResponseFn
327 * @param e {Event.Facade} Event Facade with the following properties:
329 * <dt>tId (Number)</dt> <dd>Unique transaction ID.</dd>
330 * <dt>request (Object)</dt> <dd>The request.</dd>
331 * <dt>callback (Object)</dt> <dd>Deprecated alias for the
332 * <strong>on</strong> property</dd>
333 * <dt>on (Object)</dt> <dd>The map of configured transaction
334 * callbacks. An object with the following properties:
336 * <dt>success (Function)</dt> <dd>Success handler.</dd>
337 * <dt>failure (Function)</dt> <dd>Failure handler.</dd>
340 * <dt>cfg (Object)</dt> <dd>Configuration object.</dd>
341 * <dt>data (Object)</dt> <dd>Raw data.</dd>
342 * <dt>response (Object)</dt> <dd>Normalized response object with the following properties:
344 * <dt>results (Object)</dt> <dd>Parsed results.</dd>
345 * <dt>meta (Object)</dt> <dd>Parsed meta data.</dd>
346 * <dt>error (Boolean)</dt> <dd>Error flag.</dd>
352 _defResponseFn: function(e) {
353 // Send the response back to the callback
354 DSLocal.issueCallback(e, this);
358 * Generates a unique transaction ID and fires <code>request</code> event.
359 * <strong>Note</strong>: the property <code>callback</code> is a
360 * deprecated alias for the <code>on</code> transaction configuration
361 * property described below.
363 * @method sendRequest
364 * @param [request] {Object} An object literal with the following properties:
366 * <dt><code>request</code></dt>
367 * <dd>The request to send to the live data source, if any.</dd>
368 * <dt><code>on</code></dt>
369 * <dd>An object literal with the following properties:
371 * <dt><code>success</code></dt>
372 * <dd>The function to call when the data is ready.</dd>
373 * <dt><code>failure</code></dt>
374 * <dd>The function to call upon a response failure condition.</dd>
375 * <dt><code>argument</code></dt>
376 * <dd>Arbitrary data payload that will be passed back to the success and failure handlers.</dd>
379 * <dt><code>cfg</code></dt>
380 * <dd>Configuration object, if any.</dd>
382 * @return {Number} Transaction ID.
384 sendRequest: function(request) {
385 var tId = DSLocal._tId++,
388 request = request || {};
390 callbacks = request.on || request.callback;
392 this.fire("request", {
394 request: request.request,
397 cfg: request.cfg || {}
400 Y.log("Transaction " + tId + " sent request: " + Y.dump(request.request), "info", "datasource-local");
406 Y.namespace("DataSource").Local = DSLocal;
409 }, '3.13.0', {"requires": ["base"]});