jssource/src_files/include/javascript/yui3/build/datasource/datasource.js

   1 /*
   2 Copyright (c) 2009, Yahoo! Inc. All rights reserved.
   3 Code licensed under the BSD License:
   4 http://developer.yahoo.net/yui/license.txt
   5 version: 3.0.0
   6 build: 1549
   7 */
   8 YUI.add('datasource-local', function(Y) {
   9
  10 /**
  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.
  13  *
  14  * @module datasource
  15  */
  16
  17 /**
  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.
  21  *
  22  * @module datasource
  23  * @submodule datasource-local
  24  */
  25
  26 /**
  27  * Base class for the DataSource Utility.
  28  * @class DataSource.Local
  29  * @extends Base
  30  * @constructor
  31  */
  32 var LANG = Y.Lang,
  33
  34 DSLocal = function() {
  35     DSLocal.superclass.constructor.apply(this, arguments);
  36 };
  37
  38     /////////////////////////////////////////////////////////////////////////////
  39     //
  40     // DataSource static properties
  41     //
  42     /////////////////////////////////////////////////////////////////////////////
  43 Y.mix(DSLocal, {
  44     /**
  45      * Class name.
  46      *
  47      * @property NAME
  48      * @type String
  49      * @static
  50      * @final
  51      * @value "dataSourceLocal"
  52      */
  53     NAME: "dataSourceLocal",
  54
  55     /////////////////////////////////////////////////////////////////////////////
  56     //
  57     // DataSource Attributes
  58     //
  59     /////////////////////////////////////////////////////////////////////////////
  60
  61     ATTRS: {
  62         /**
  63         * @attribute source
  64         * @description Pointer to live data.
  65         * @type MIXED
  66         * @default null
  67         */
  68         source: {
  69             value: null
  70         }
  71     },
  72
  73     /**
  74      * Global transaction counter.
  75      *
  76      * @property DataSource._tId
  77      * @type Number
  78      * @static
  79      * @private
  80      * @default 0
  81      */
  82     _tId: 0,
  83
  84     /**
  85      * Executes a given callback.  The third param determines whether to execute
  86      *
  87      * @method DataSource.issueCallback
  88      * @param callback {Object} The callback object.
  89      * @param params {Array} params to be passed to the callback method
  90      * @param error {Boolean} whether an error occurred
  91      * @static
  92      */
  93     issueCallback: function (e) {
  94         if(e.callback) {
  95             var callbackFunc = (e.error && e.callback.failure) || e.callback.success;
  96             if (callbackFunc) {
  97                 callbackFunc(e);
  98             }
  99         }
 100     }
 101 });
 102
 103 Y.extend(DSLocal, Y.Base, {
 104     /**
 105     * Internal init() handler.
 106     *
 107     * @method initializer
 108     * @param config {Object} Config object.
 109     * @private
 110     */
 111     initializer: function(config) {
 112         this._initEvents();
 113     },
 114
 115     /**
 116     * This method creates all the events for this module.
 117     * @method _initEvents
 118     * @private
 119     */
 120     _initEvents: function() {
 121         /**
 122          * Fired when a data request is received.
 123          *
 124          * @event request
 125          * @param e {Event.Facade} Event Facade with the following properties:
 126          * <dl>
 127          * <dt>tId (Number)</dt> <dd>Unique transaction ID.</dd>
 128          * <dt>request (Object)</dt> <dd>The request.</dd>
 129          * <dt>callback (Object)</dt> <dd>The callback object.</dd>
 130          * <dt>cfg (Object)</dt> <dd>Configuration object.</dd>
 131          * </dl>
 132          * @preventable _defRequestFn
 133          */
 134         this.publish("request", {defaultFn: Y.bind("_defRequestFn", this), queuable:true});
 135
 136         /**
 137          * Fired when raw data is received.
 138          *
 139          * @event data
 140          * @param e {Event.Facade} Event Facade with the following properties:
 141          * <dl>
 142          * <dt>tId (Number)</dt> <dd>Unique transaction ID.</dd>
 143          * <dt>request (Object)</dt> <dd>The request.</dd>
 144          * <dt>callback (Object)</dt> <dd>The callback object with the following properties:
 145          *     <dl>
 146          *         <dt>success (Function)</dt> <dd>Success handler.</dd>
 147          *         <dt>failure (Function)</dt> <dd>Failure handler.</dd>
 148          *     </dl>
 149          * </dd>
 150          * <dt>cfg (Object)</dt> <dd>Configuration object.</dd>
 151          * <dt>data (Object)</dt> <dd>Raw data.</dd>
 152          * </dl>
 153          * @preventable _defDataFn
 154          */
 155         this.publish("data", {defaultFn: Y.bind("_defDataFn", this), queuable:true});
 156
 157         /**
 158          * Fired when response is returned.
 159          *
 160          * @event response
 161          * @param e {Event.Facade} Event Facade with the following properties:
 162          * <dl>
 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>The callback object with the following properties:
 166          *     <dl>
 167          *         <dt>success (Function)</dt> <dd>Success handler.</dd>
 168          *         <dt>failure (Function)</dt> <dd>Failure handler.</dd>
 169          *     </dl>
 170          * </dd>
 171          * <dt>cfg (Object)</dt> <dd>Configuration object.</dd>
 172          * <dt>data (Object)</dt> <dd>Raw data.</dd>
 173          * <dt>response (Object)</dt> <dd>Normalized response object with the following properties:
 174          *     <dl>
 175          *         <dt>results (Object)</dt> <dd>Parsed results.</dd>
 176          *         <dt>meta (Object)</dt> <dd>Parsed meta data.</dd>
 177          *         <dt>error (Boolean)</dt> <dd>Error flag.</dd>
 178          *     </dl>
 179          * </dd>
 180          * </dl>
 181          * @preventable _defResponseFn
 182          */
 183          this.publish("response", {defaultFn: Y.bind("_defResponseFn", this), queuable:true});
 184
 185         /**
 186          * Fired when an error is encountered.
 187          *
 188          * @event error
 189          * @param e {Event.Facade} Event Facade with the following properties:
 190          * <dl>
 191          * <dt>tId (Number)</dt> <dd>Unique transaction ID.</dd>
 192          * <dt>request (Object)</dt> <dd>The request.</dd>
 193          * <dt>callback (Object)</dt> <dd>The callback object with the following properties:
 194          *     <dl>
 195          *         <dt>success (Function)</dt> <dd>Success handler.</dd>
 196          *         <dt>failure (Function)</dt> <dd>Failure handler.</dd>
 197          *     </dl>
 198          * </dd>
 199          * <dt>cfg (Object)</dt> <dd>Configuration object.</dd>
 200          * <dt>data (Object)</dt> <dd>Raw data.</dd>
 201          * <dt>response (Object)</dt> <dd>Normalized response object with the following properties:
 202          *     <dl>
 203          *         <dt>results (Object)</dt> <dd>Parsed results.</dd>
 204          *         <dt>meta (Object)</dt> <dd>Parsed meta data.</dd>
 205          *         <dt>error (Object)</dt> <dd>Error object.</dd>
 206          *     </dl>
 207          * </dd>
 208          * </dl>
 209          */
 210
 211     },
 212
 213     /**
 214      * Manages request/response transaction. Must fire <code>response</code>
 215      * event when response is received. This method should be implemented by
 216      * subclasses to achieve more complex behavior such as accessing remote data.
 217      *
 218      * @method _defRequestFn
 219      * @param e {Event.Facade} Event Facadewith the following properties:
 220      * <dl>
 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>The callback object with the following properties:
 224      *     <dl>
 225      *         <dt>success (Function)</dt> <dd>Success handler.</dd>
 226      *         <dt>failure (Function)</dt> <dd>Failure handler.</dd>
 227      *     </dl>
 228      * </dd>
 229      * <dt>cfg (Object)</dt> <dd>Configuration object.</dd>
 230      * </dl>
 231      * @protected
 232      */
 233     _defRequestFn: function(e) {
 234         var data = this.get("source");
 235
 236         // Problematic data
 237         if(LANG.isUndefined(data)) {
 238             e.error = new Error("Local source undefined");
 239         }
 240         if(e.error) {
 241             this.fire("error", e);
 242         }
 243
 244         this.fire("data", Y.mix({data:data}, e));
 245     },
 246
 247     /**
 248      * Normalizes raw data into a response that includes results and meta properties.
 249      *
 250      * @method _defDataFn
 251      * @param e {Event.Facade} Event Facade with the following properties:
 252      * <dl>
 253      * <dt>tId (Number)</dt> <dd>Unique transaction ID.</dd>
 254      * <dt>request (Object)</dt> <dd>The request.</dd>
 255      * <dt>callback (Object)</dt> <dd>The callback object with the following properties:
 256      *     <dl>
 257      *         <dt>success (Function)</dt> <dd>Success handler.</dd>
 258      *         <dt>failure (Function)</dt> <dd>Failure handler.</dd>
 259      *     </dl>
 260      * </dd>
 261      * <dt>cfg (Object)</dt> <dd>Configuration object.</dd>
 262      * <dt>data (Object)</dt> <dd>Raw data.</dd>
 263      * </dl>
 264      * @protected
 265      */
 266     _defDataFn: function(e) {
 267         var data = e.data,
 268             meta = e.meta,
 269             response = {
 270                 results: (LANG.isArray(data)) ? data : [data],
 271                 meta: (meta) ? meta : {}
 272             };
 273
 274         this.fire("response", Y.mix({response: response}, e));
 275     },
 276
 277     /**
 278      * Sends data as a normalized response to callback.
 279      *
 280      * @method _defResponseFn
 281      * @param e {Event.Facade} Event Facade with the following properties:
 282      * <dl>
 283      * <dt>tId (Number)</dt> <dd>Unique transaction ID.</dd>
 284      * <dt>request (Object)</dt> <dd>The request.</dd>
 285      * <dt>callback (Object)</dt> <dd>The callback object with the following properties:
 286      *     <dl>
 287      *         <dt>success (Function)</dt> <dd>Success handler.</dd>
 288      *         <dt>failure (Function)</dt> <dd>Failure handler.</dd>
 289      *     </dl>
 290      * </dd>
 291      * <dt>cfg (Object)</dt> <dd>Configuration object.</dd>
 292      * <dt>data (Object)</dt> <dd>Raw data.</dd>
 293      * <dt>response (Object)</dt> <dd>Normalized response object with the following properties:
 294      *     <dl>
 295      *         <dt>results (Object)</dt> <dd>Parsed results.</dd>
 296      *         <dt>meta (Object)</dt> <dd>Parsed meta data.</dd>
 297      *         <dt>error (Boolean)</dt> <dd>Error flag.</dd>
 298      *     </dl>
 299      * </dd>
 300      * </dl>
 301      * @protected
 302      */
 303     _defResponseFn: function(e) {
 304         // Send the response back to the callback
 305         DSLocal.issueCallback(e);
 306     },
 307
 308     /**
 309      * Generates a unique transaction ID and fires <code>request</code> event.
 310      *
 311      * @method sendRequest
 312      * @param request {Object} Request.
 313      * @param callback {Object} An object literal with the following properties:
 314      *     <dl>
 315      *     <dt><code>success</code></dt>
 316      *     <dd>The function to call when the data is ready.</dd>
 317      *     <dt><code>failure</code></dt>
 318      *     <dd>The function to call upon a response failure condition.</dd>
 319      *     <dt><code>argument</code></dt>
 320      *     <dd>Arbitrary data payload that will be passed back to the success and failure handlers.</dd>
 321      *     </dl>
 322      * @param cfg {Object} Configuration object
 323      * @return {Number} Transaction ID.
 324      */
 325     sendRequest: function(request, callback, cfg) {
 326         var tId = DSLocal._tId++;
 327         this.fire("request", {tId:tId, request:request, callback:callback, cfg:cfg || {}});
 328         return tId;
 329     }
 330 });
 331
 332 Y.namespace("DataSource").Local = DSLocal;
 333
 334
 335
 336 }, '3.0.0' ,{requires:['base']});
 337
 338 YUI.add('datasource-io', function(Y) {
 339
 340 /**
 341  * Provides a DataSource implementation which can be used to retrieve data via the IO Utility.
 342  *
 343  * @module datasource
 344  * @submodule datasource-io
 345  */
 346
 347 /**
 348  * IO subclass for the DataSource Utility.
 349  * @class DataSource.IO
 350  * @extends DataSource.Local
 351  * @constructor
 352  */
 353 var DSIO = function() {
 354     DSIO.superclass.constructor.apply(this, arguments);
 355 };
 356
 357
 358     /////////////////////////////////////////////////////////////////////////////
 359     //
 360     // DataSource.IO static properties
 361     //
 362     /////////////////////////////////////////////////////////////////////////////
 363 Y.mix(DSIO, {
 364     /**
 365      * Class name.
 366      *
 367      * @property NAME
 368      * @type String
 369      * @static
 370      * @final
 371      * @value "dataSourceIO"
 372      */
 373     NAME: "dataSourceIO",
 374
 375
 376     /////////////////////////////////////////////////////////////////////////////
 377     //
 378     // DataSource.IO Attributes
 379     //
 380     /////////////////////////////////////////////////////////////////////////////
 381
 382     ATTRS: {
 383         /**
 384          * Pointer to IO Utility.
 385          *
 386          * @attribute io
 387          * @type Y.io
 388          * @default Y.io
 389          */
 390         io: {
 391             value: Y.io,
 392             cloneDefaultValue: false
 393         }
 394     }
 395 });
 396
 397 Y.extend(DSIO, Y.DataSource.Local, {
 398     /**
 399     * Internal init() handler.
 400     *
 401     * @method initializer
 402     * @param config {Object} Config object.
 403     * @private
 404     */
 405     initializer: function(config) {
 406         this._queue = {interval:null, conn:null, requests:[]};
 407     },
 408
 409     /**
 410     * @property _queue
 411     * @description Object literal to manage asynchronous request/response
 412     * cycles enabled if queue needs to be managed (asyncMode/ioConnMode):
 413     * <dl>
 414     *     <dt>interval {Number}</dt>
 415     *         <dd>Interval ID of in-progress queue.</dd>
 416     *     <dt>conn</dt>
 417     *         <dd>In-progress connection identifier (if applicable).</dd>
 418     *     <dt>requests {Object[]}</dt>
 419     *         <dd>Array of queued request objects: {request:request, callback:callback}.</dd>
 420     * </dl>
 421     * @type Object
 422     * @default {interval:null, conn:null, requests:[]}
 423     * @private
 424     */
 425     _queue: null,
 426
 427     /**
 428      * Passes query string to IO. Fires <code>response</code> event when
 429      * response is received asynchronously.
 430      *
 431      * @method _defRequestFn
 432      * @param e {Event.Facade} Event Facade with the following properties:
 433      * <dl>
 434      * <dt>tId (Number)</dt> <dd>Unique transaction ID.</dd>
 435      * <dt>request (Object)</dt> <dd>The request.</dd>
 436      * <dt>callback (Object)</dt> <dd>The callback object with the following properties:
 437      *     <dl>
 438      *         <dt>success (Function)</dt> <dd>Success handler.</dd>
 439      *         <dt>failure (Function)</dt> <dd>Failure handler.</dd>
 440      *     </dl>
 441      * </dd>
 442      * <dt>cfg (Object)</dt> <dd>Configuration object.</dd>
 443      * </dl>
 444      * @protected
 445      */
 446     _defRequestFn: function(e) {
 447         var uri = this.get("source"),
 448             io = this.get("io"),
 449             request = e.request,
 450             cfg = Y.mix(e.cfg, {
 451                 on: {
 452                     success: function (id, response, e) {
 453                         this.fire("data", Y.mix({data:response}, e));
 454                     },
 455                     failure: function (id, response, e) {
 456                         e.error = new Error("IO data failure");
 457                         this.fire("error", Y.mix({data:response}, e));
 458                         this.fire("data", Y.mix({data:response}, e));
 459                     }
 460                 },
 461                 context: this,
 462                 arguments: e
 463             });
 464
 465         // Support for POST transactions
 466         if(Y.Lang.isString(request)) {
 467             if(cfg.method && (cfg.method.toUpperCase() === "POST")) {
 468                 cfg.data = cfg.data ? cfg.data+request : request;
 469             }
 470             else {
 471                 uri += request;
 472             }
 473         }
 474         io(uri, cfg);
 475         return e.tId;
 476     }
 477 });
 478
 479 Y.DataSource.IO = DSIO;
 480
 481
 482
 483
 484 }, '3.0.0' ,{requires:['datasource-local', 'io']});
 485
 486 YUI.add('datasource-get', function(Y) {
 487
 488 /**
 489  * Provides a DataSource implementation which can be used to retrieve data via the Get Utility.
 490  *
 491  * @module datasource
 492  * @submodule datasource-get
 493  */
 494
 495 /**
 496  * Get Utility subclass for the DataSource Utility.
 497  * @class DataSource.Get
 498  * @extends DataSource.Local
 499  * @constructor
 500  */
 501 var DSGet = function() {
 502     DSGet.superclass.constructor.apply(this, arguments);
 503 };
 504
 505
 506     /////////////////////////////////////////////////////////////////////////////
 507     //
 508     // DataSource.Get static properties
 509     //
 510     /////////////////////////////////////////////////////////////////////////////
 511 Y.mix(DSGet, {
 512     /**
 513      * Class name.
 514      *
 515      * @property NAME
 516      * @type String
 517      * @static
 518      * @final
 519      * @value "dataSourceGet"
 520      */
 521     NAME: "dataSourceGet",
 522
 523
 524     /////////////////////////////////////////////////////////////////////////////
 525     //
 526     // DataSource.Get Attributes
 527     //
 528     /////////////////////////////////////////////////////////////////////////////
 529
 530     ATTRS: {
 531         /**
 532          * Pointer to Get Utility.
 533          *
 534          * @attribute get
 535          * @type Y.Get
 536          * @default Y.Get
 537          */
 538         get: {
 539             value: Y.Get,
 540             cloneDefaultValue: false
 541         },
 542
 543 /**
 544  * Defines request/response management in the following manner:
 545  * <dl>
 546  *     <!--<dt>queueRequests</dt>
 547  *     <dd>If a request is already in progress, wait until response is returned before sending the next request.</dd>
 548  *     <dt>cancelStaleRequests</dt>
 549  *     <dd>If a request is already in progress, cancel it before sending the next request.</dd>-->
 550  *     <dt>ignoreStaleResponses</dt>
 551  *     <dd>Send all requests, but handle only the response for the most recently sent request.</dd>
 552  *     <dt>allowAll</dt>
 553  *     <dd>Send all requests and handle all responses.</dd>
 554  * </dl>
 555  *
 556  * @attribute asyncMode
 557  * @type String
 558  * @default "allowAll"
 559  */
 560 asyncMode: {
 561     value: "allowAll"
 562 },
 563
 564 /**
 565  * Callback string parameter name sent to the remote script. By default,
 566  * requests are sent to
 567  * &#60;URI&#62;?&#60;scriptCallbackParam&#62;=callbackFunction
 568  *
 569  * @attribute scriptCallbackParam
 570  * @type String
 571  * @default "callback"
 572  */
 573 scriptCallbackParam : {
 574     value: "callback"
 575 },
 576
 577 /**
 578  * Accepts the DataSource instance and a callback ID, and returns a callback
 579  * param/value string that gets appended to the script URI. Implementers
 580  * can customize this string to match their server's query syntax.
 581  *
 582  * @attribute generateRequestCallback
 583  * @type Function
 584  */
 585 generateRequestCallback : {
 586     value: function(self, id) {
 587         return "&" + self.get("scriptCallbackParam") + "=YUI.Env.DataSource.callbacks["+id+"]" ;
 588     }
 589 }
 590
 591
 592
 593
 594
 595     },
 596
 597     /**
 598      * Global array of callback functions, one for each request sent.
 599      *
 600      * @property callbacks
 601      * @type Function[]
 602      * @static
 603      */
 604     callbacks : [],
 605
 606     /**
 607      * Unique ID to track requests.
 608      *
 609      * @property _tId
 610      * @type Number
 611      * @private
 612      * @static
 613      */
 614     _tId : 0
 615 });
 616
 617 Y.extend(DSGet, Y.DataSource.Local, {
 618     /**
 619      * Passes query string to Get Utility. Fires <code>response</code> event when
 620      * response is received asynchronously.
 621      *
 622      * @method _defRequestFn
 623      * @param e {Event.Facade} Event Facade with the following properties:
 624      * <dl>
 625      * <dt>tId (Number)</dt> <dd>Unique transaction ID.</dd>
 626      * <dt>request (Object)</dt> <dd>The request.</dd>
 627      * <dt>callback (Object)</dt> <dd>The callback object with the following properties:
 628      *     <dl>
 629      *         <dt>success (Function)</dt> <dd>Success handler.</dd>
 630      *         <dt>failure (Function)</dt> <dd>Failure handler.</dd>
 631      *     </dl>
 632      * </dd>
 633      * <dt>cfg (Object)</dt> <dd>Configuration object.</dd>
 634      * </dl>
 635      * @protected
 636      */
 637     _defRequestFn: function(e) {
 638         var uri = this.get("source"),
 639             get = this.get("get"),
 640             id = DSGet._tId++,
 641             self = this;
 642
 643
 644
 645
 646
 647
 648
 649
 650
 651
 652
 653
 654
 655     // Dynamically add handler function with a closure to the callback stack
 656     YUI.Env.DataSource.callbacks[id] = Y.rbind(function(response) {
 657         if((self.get("asyncMode") !== "ignoreStaleResponses")||
 658                 (id === DSGet.callbacks.length-1)) { // Must ignore stale responses
 659
 660             self.fire("data", Y.mix({data:response}, e));
 661         }
 662         else {
 663         }
 664
 665         delete DSGet.callbacks[id];
 666     }, this, id);
 667
 668     // We are now creating a request
 669     uri += e.request + this.get("generateRequestCallback")(this, id);
 670     //uri = this.doBefore(sUri);
 671     get.script(uri, {
 672         autopurge: true,
 673         // Works in Firefox only....
 674         onFailure: Y.bind(function(e) {
 675             e.error = new Error("Script node data failure");
 676             this.fire("error", e);
 677         }, this, e)
 678     });
 679
 680
 681
 682
 683
 684
 685
 686
 687
 688
 689
 690
 691
 692
 693
 694         return e.tId;
 695     }
 696 });
 697
 698 Y.DataSource.Get = DSGet;
 699 YUI.namespace("Env.DataSource.callbacks");
 700
 701
 702
 703
 704 }, '3.0.0' ,{requires:['datasource-local', 'get']});
 705
 706 YUI.add('datasource-function', function(Y) {
 707
 708 /**
 709  * Provides a DataSource implementation which can be used to retrieve data from a custom function.
 710  *
 711  * @module datasource
 712  * @submodule datasource-function
 713  */
 714
 715 /**
 716  * Function subclass for the DataSource Utility.
 717  * @class DataSource.Function
 718  * @extends DataSource.Local
 719  * @constructor
 720  */
 721 var LANG = Y.Lang,
 722
 723     DSFn = function() {
 724         DSFn.superclass.constructor.apply(this, arguments);
 725     };
 726
 727
 728     /////////////////////////////////////////////////////////////////////////////
 729     //
 730     // DataSource.Function static properties
 731     //
 732     /////////////////////////////////////////////////////////////////////////////
 733 Y.mix(DSFn, {
 734     /**
 735      * Class name.
 736      *
 737      * @property NAME
 738      * @type String
 739      * @static
 740      * @final
 741      * @value "dataSourceFunction"
 742      */
 743     NAME: "dataSourceFunction",
 744
 745
 746     /////////////////////////////////////////////////////////////////////////////
 747     //
 748     // DataSource.Function Attributes
 749     //
 750     /////////////////////////////////////////////////////////////////////////////
 751
 752     ATTRS: {
 753         /**
 754         * @attribute source
 755         * @description Pointer to live data.
 756         * @type MIXED
 757         * @default null
 758         */
 759         source: {
 760             validator: LANG.isFunction
 761         }
 762     }
 763 });
 764
 765 Y.extend(DSFn, Y.DataSource.Local, {
 766     /**
 767      * Passes query string to IO. Fires <code>response</code> event when
 768      * response is received asynchronously.
 769      *
 770      * @method _defRequestFn
 771      * @param e {Event.Facade} Event Facade with the following properties:
 772      * <dl>
 773      * <dt>tId (Number)</dt> <dd>Unique transaction ID.</dd>
 774      * <dt>request (Object)</dt> <dd>The request.</dd>
 775      * <dt>callback (Object)</dt> <dd>The callback object with the following properties:
 776      *     <dl>
 777      *         <dt>success (Function)</dt> <dd>Success handler.</dd>
 778      *         <dt>failure (Function)</dt> <dd>Failure handler.</dd>
 779      *     </dl>
 780      * </dd>
 781      * <dt>cfg (Object)</dt> <dd>Configuration object.</dd>
 782      * </dl>
 783      * @protected
 784      */
 785     _defRequestFn: function(e) {
 786         var fn = this.get("source"),
 787             response;
 788
 789             if(fn) {
 790                 try {
 791                     response = fn(e.request, this, e);
 792                     this.fire("data", Y.mix({data:response}, e));
 793                 }
 794                 catch(error) {
 795                     e.error = error;
 796                     this.fire("error", e);
 797                 }
 798             }
 799             else {
 800                 e.error = new Error("Function data failure");
 801                 this.fire("error", e);
 802             }
 803
 804         return e.tId;
 805     }
 806 });
 807
 808 Y.DataSource.Function = DSFn;
 809
 810
 811
 812
 813 }, '3.0.0' ,{requires:['datasource-local']});
 814
 815 YUI.add('datasource-cache', function(Y) {
 816
 817 /**
 818  * Extends DataSource with caching functionality.
 819  *
 820  * @module datasource
 821  * @submodule datasource-cache
 822  */
 823
 824 /**
 825  * Adds cacheability to the DataSource Utility.
 826  * @class DataSourceCache
 827  * @extends Cache
 828  */
 829 var DataSourceCache = function() {
 830     DataSourceCache.superclass.constructor.apply(this, arguments);
 831 };
 832
 833 Y.mix(DataSourceCache, {
 834     /**
 835      * The namespace for the plugin. This will be the property on the host which
 836      * references the plugin instance.
 837      *
 838      * @property NS
 839      * @type String
 840      * @static
 841      * @final
 842      * @value "cache"
 843      */
 844     NS: "cache",
 845
 846     /**
 847      * Class name.
 848      *
 849      * @property NAME
 850      * @type String
 851      * @static
 852      * @final
 853      * @value "dataSourceCache"
 854      */
 855     NAME: "dataSourceCache",
 856
 857     /////////////////////////////////////////////////////////////////////////////
 858     //
 859     // DataSourceCache Attributes
 860     //
 861     /////////////////////////////////////////////////////////////////////////////
 862
 863     ATTRS: {
 864
 865     }
 866 });
 867
 868 Y.extend(DataSourceCache, Y.Cache, {
 869     /**
 870     * Internal init() handler.
 871     *
 872     * @method initializer
 873     * @param config {Object} Config object.
 874     * @private
 875     */
 876     initializer: function(config) {
 877         this.doBefore("_defRequestFn", this._beforeDefRequestFn);
 878         this.doBefore("_defResponseFn", this._beforeDefResponseFn);
 879     },
 880
 881     /**
 882      * First look for cached response, then send request to live data.
 883      *
 884      * @method _beforeDefRequestFn
 885      * @param e {Event.Facade} Event Facade with the following properties:
 886      * <dl>
 887      * <dt>tId (Number)</dt> <dd>Unique transaction ID.</dd>
 888      * <dt>request (Object)</dt> <dd>The request.</dd>
 889      * <dt>callback (Object)</dt> <dd>The callback object.</dd>
 890      * <dt>cfg (Object)</dt> <dd>Configuration object.</dd>
 891      * </dl>
 892      * @protected
 893      */
 894     _beforeDefRequestFn: function(e) {
 895         // Is response already in the Cache?
 896         var entry = (this.retrieve(e.request)) || null;
 897         if(entry && entry.response) {
 898             this.get("host").fire("response", Y.mix({response: entry.response}, e));
 899             return new Y.Do.Halt("DataSourceCache plugin halted _defRequestFn");
 900         }
 901     },
 902
 903     /**
 904      * Adds data to cache before returning data.
 905      *
 906      * @method _beforeDefResponseFn
 907      * @param e {Event.Facade} Event Facade with the following properties:
 908      * <dl>
 909      * <dt>tId (Number)</dt> <dd>Unique transaction ID.</dd>
 910      * <dt>request (Object)</dt> <dd>The request.</dd>
 911      * <dt>callback (Object)</dt> <dd>The callback object with the following properties:
 912      *     <dl>
 913      *         <dt>success (Function)</dt> <dd>Success handler.</dd>
 914      *         <dt>failure (Function)</dt> <dd>Failure handler.</dd>
 915      *     </dl>
 916      * </dd>
 917      * <dt>data (Object)</dt> <dd>Raw data.</dd>
 918      * <dt>response (Object)</dt> <dd>Normalized response object with the following properties:
 919      *     <dl>
 920      *         <dt>cached (Object)</dt> <dd>True when response is cached.</dd>
 921      *         <dt>results (Object)</dt> <dd>Parsed results.</dd>
 922      *         <dt>meta (Object)</dt> <dd>Parsed meta data.</dd>
 923      *         <dt>error (Object)</dt> <dd>Error object.</dd>
 924      *     </dl>
 925      * </dd>
 926      * <dt>cfg (Object)</dt> <dd>Configuration object.</dd>
 927      * </dl>
 928      * @protected
 929      */
 930      _beforeDefResponseFn: function(e) {
 931         // Add to Cache before returning
 932         if(e.response && !e.response.cached) {
 933             e.response.cached = true;
 934             this.add(e.request, e.response, (e.callback && e.callback.argument));
 935         }
 936      }
 937 });
 938
 939 Y.namespace('Plugin').DataSourceCache = DataSourceCache;
 940
 941
 942
 943 }, '3.0.0' ,{requires:['datasource-local', 'cache']});
 944
 945 YUI.add('datasource-jsonschema', function(Y) {
 946
 947 /**
 948  * Extends DataSource with schema-parsing on JSON data.
 949  *
 950  * @module datasource
 951  * @submodule datasource-jsonschema
 952  */
 953
 954 /**
 955  * Adds schema-parsing to the DataSource Utility.
 956  * @class DataSourceJSONSchema
 957  * @extends Plugin.Base
 958  */
 959 var DataSourceJSONSchema = function() {
 960     DataSourceJSONSchema.superclass.constructor.apply(this, arguments);
 961 };
 962
 963 Y.mix(DataSourceJSONSchema, {
 964     /**
 965      * The namespace for the plugin. This will be the property on the host which
 966      * references the plugin instance.
 967      *
 968      * @property NS
 969      * @type String
 970      * @static
 971      * @final
 972      * @value "schema"
 973      */
 974     NS: "schema",
 975
 976     /**
 977      * Class name.
 978      *
 979      * @property NAME
 980      * @type String
 981      * @static
 982      * @final
 983      * @value "dataSourceJSONSchema"
 984      */
 985     NAME: "dataSourceJSONSchema",
 986
 987     /////////////////////////////////////////////////////////////////////////////
 988     //
 989     // DataSourceJSONSchema Attributes
 990     //
 991     /////////////////////////////////////////////////////////////////////////////
 992
 993     ATTRS: {
 994         schema: {
 995             //value: {}
 996         }
 997     }
 998 });
 999
1000 Y.extend(DataSourceJSONSchema, Y.Plugin.Base, {
1001     /**
1002     * Internal init() handler.
1003     *
1004     * @method initializer
1005     * @param config {Object} Config object.
1006     * @private
1007     */
1008     initializer: function(config) {
1009         this.doBefore("_defDataFn", this._beforeDefDataFn);
1010     },
1011
1012     /**
1013      * Parses raw data into a normalized response.
1014      *
1015      * @method _beforeDefDataFn
1016      * <dl>
1017      * <dt>tId (Number)</dt> <dd>Unique transaction ID.</dd>
1018      * <dt>request (Object)</dt> <dd>The request.</dd>
1019      * <dt>callback (Object)</dt> <dd>The callback object with the following properties:
1020      *     <dl>
1021      *         <dt>success (Function)</dt> <dd>Success handler.</dd>
1022      *         <dt>failure (Function)</dt> <dd>Failure handler.</dd>
1023      *     </dl>
1024      * </dd>
1025      * <dt>data (Object)</dt> <dd>Raw data.</dd>
1026      * </dl>
1027      * @protected
1028      */
1029     _beforeDefDataFn: function(e) {
1030         var data = (Y.DataSource.IO && (this.get("host") instanceof Y.DataSource.IO) && Y.Lang.isString(e.data.responseText)) ? e.data.responseText : e.data,
1031             response = Y.DataSchema.JSON.apply(this.get("schema"), data);
1032
1033         // Default
1034         if(!response) {
1035             response = {
1036                 meta: {},
1037                 results: data
1038             };
1039         }
1040
1041         this.get("host").fire("response", Y.mix({response:response}, e));
1042         return new Y.Do.Halt("DataSourceJSONSchema plugin halted _defDataFn");
1043     }
1044 });
1045
1046 Y.namespace('Plugin').DataSourceJSONSchema = DataSourceJSONSchema;
1047
1048
1049
1050 }, '3.0.0' ,{requires:['plugin', 'datasource-local', 'dataschema-json']});
1051
1052 YUI.add('datasource-xmlschema', function(Y) {
1053
1054 /**
1055  * Extends DataSource with schema-parsing on XML data.
1056  *
1057  * @module datasource
1058  * @submodule datasource-xmlschema
1059  */
1060
1061 /**
1062  * Adds schema-parsing to the DataSource Utility.
1063  * @class DataSourceXMLSchema
1064  * @extends Plugin.Base
1065  */
1066 var DataSourceXMLSchema = function() {
1067     DataSourceXMLSchema.superclass.constructor.apply(this, arguments);
1068 };
1069
1070 Y.mix(DataSourceXMLSchema, {
1071     /**
1072      * The namespace for the plugin. This will be the property on the host which
1073      * references the plugin instance.
1074      *
1075      * @property NS
1076      * @type String
1077      * @static
1078      * @final
1079      * @value "schema"
1080      */
1081     NS: "schema",
1082
1083     /**
1084      * Class name.
1085      *
1086      * @property NAME
1087      * @type String
1088      * @static
1089      * @final
1090      * @value "dataSourceXMLSchema"
1091      */
1092     NAME: "dataSourceXMLSchema",
1093
1094     /////////////////////////////////////////////////////////////////////////////
1095     //
1096     // DataSourceXMLSchema Attributes
1097     //
1098     /////////////////////////////////////////////////////////////////////////////
1099
1100     ATTRS: {
1101         schema: {
1102             //value: {}
1103         }
1104     }
1105 });
1106
1107 Y.extend(DataSourceXMLSchema, Y.Plugin.Base, {
1108     /**
1109     * Internal init() handler.
1110     *
1111     * @method initializer
1112     * @param config {Object} Config object.
1113     * @private
1114     */
1115     initializer: function(config) {
1116         this.doBefore("_defDataFn", this._beforeDefDataFn);
1117     },
1118
1119     /**
1120      * Parses raw data into a normalized response.
1121      *
1122      * @method _beforeDefDataFn
1123      * <dl>
1124      * <dt>tId (Number)</dt> <dd>Unique transaction ID.</dd>
1125      * <dt>request (Object)</dt> <dd>The request.</dd>
1126      * <dt>callback (Object)</dt> <dd>The callback object with the following properties:
1127      *     <dl>
1128      *         <dt>success (Function)</dt> <dd>Success handler.</dd>
1129      *         <dt>failure (Function)</dt> <dd>Failure handler.</dd>
1130      *     </dl>
1131      * </dd>
1132      * <dt>data (Object)</dt> <dd>Raw data.</dd>
1133      * </dl>
1134      * @protected
1135      */
1136     _beforeDefDataFn: function(e) {
1137         var data = (Y.DataSource.IO && (this.get("host") instanceof Y.DataSource.IO) && e.data.responseXML && (e.data.responseXML.nodeType === 9)) ? e.data.responseXML : e.data,
1138             response = Y.DataSchema.XML.apply(this.get("schema"), data);
1139
1140         // Default
1141         if(!response) {
1142             response = {
1143                 meta: {},
1144                 results: data
1145             };
1146         }
1147
1148         this.get("host").fire("response", Y.mix({response:response}, e));
1149         return new Y.Do.Halt("DataSourceXMLSchema plugin halted _defDataFn");
1150     }
1151 });
1152
1153 Y.namespace('Plugin').DataSourceXMLSchema = DataSourceXMLSchema;
1154
1155
1156
1157 }, '3.0.0' ,{requires:['plugin', 'datasource-local', 'dataschema-xml']});
1158
1159 YUI.add('datasource-arrayschema', function(Y) {
1160
1161 /**
1162  * Extends DataSource with schema-parsing on array data.
1163  *
1164  * @module datasource
1165  * @submodule datasource-arrayschema
1166  */
1167
1168 /**
1169  * Adds schema-parsing to the DataSource Utility.
1170  * @class DataSourceArraySchema
1171  * @extends Plugin.Base
1172  */
1173 var DataSourceArraySchema = function() {
1174     DataSourceArraySchema.superclass.constructor.apply(this, arguments);
1175 };
1176
1177 Y.mix(DataSourceArraySchema, {
1178     /**
1179      * The namespace for the plugin. This will be the property on the host which
1180      * references the plugin instance.
1181      *
1182      * @property NS
1183      * @type String
1184      * @static
1185      * @final
1186      * @value "schema"
1187      */
1188     NS: "schema",
1189
1190     /**
1191      * Class name.
1192      *
1193      * @property NAME
1194      * @type String
1195      * @static
1196      * @final
1197      * @value "dataSourceArraySchema"
1198      */
1199     NAME: "dataSourceArraySchema",
1200
1201     /////////////////////////////////////////////////////////////////////////////
1202     //
1203     // DataSourceArraySchema Attributes
1204     //
1205     /////////////////////////////////////////////////////////////////////////////
1206
1207     ATTRS: {
1208         schema: {
1209             //value: {}
1210         }
1211     }
1212 });
1213
1214 Y.extend(DataSourceArraySchema, Y.Plugin.Base, {
1215     /**
1216     * Internal init() handler.
1217     *
1218     * @method initializer
1219     * @param config {Object} Config object.
1220     * @private
1221     */
1222     initializer: function(config) {
1223         this.doBefore("_defDataFn", this._beforeDefDataFn);
1224     },
1225
1226     /**
1227      * Parses raw data into a normalized response.
1228      *
1229      * @method _beforeDefDataFn
1230      * <dl>
1231      * <dt>tId (Number)</dt> <dd>Unique transaction ID.</dd>
1232      * <dt>request (Object)</dt> <dd>The request.</dd>
1233      * <dt>callback (Object)</dt> <dd>The callback object with the following properties:
1234      *     <dl>
1235      *         <dt>success (Function)</dt> <dd>Success handler.</dd>
1236      *         <dt>failure (Function)</dt> <dd>Failure handler.</dd>
1237      *     </dl>
1238      * </dd>
1239      * <dt>data (Object)</dt> <dd>Raw data.</dd>
1240      * </dl>
1241      * @protected
1242      */
1243     _beforeDefDataFn: function(e) {
1244         var data = (Y.DataSource.IO && (this.get("host") instanceof Y.DataSource.IO) && Y.Lang.isString(e.data.responseText)) ? e.data.responseText : e.data,
1245             response = Y.DataSchema.Array.apply(this.get("schema"), data);
1246
1247         // Default
1248         if(!response) {
1249             response = {
1250                 meta: {},
1251                 results: data
1252             };
1253         }
1254
1255         this.get("host").fire("response", Y.mix({response:response}, e));
1256         return new Y.Do.Halt("DataSourceArraySchema plugin halted _defDataFn");
1257     }
1258 });
1259
1260 Y.namespace('Plugin').DataSourceArraySchema = DataSourceArraySchema;
1261
1262
1263
1264 }, '3.0.0' ,{requires:['plugin', 'datasource-local', 'dataschema-array']});
1265
1266 YUI.add('datasource-textschema', function(Y) {
1267
1268 /**
1269  * Extends DataSource with schema-parsing on text data.
1270  *
1271  * @module datasource
1272  * @submodule datasource-textschema
1273  */
1274
1275 /**
1276  * Adds schema-parsing to the DataSource Utility.
1277  * @class DataSourceTextSchema
1278  * @extends Plugin.Base
1279  */
1280 var DataSourceTextSchema = function() {
1281     DataSourceTextSchema.superclass.constructor.apply(this, arguments);
1282 };
1283
1284 Y.mix(DataSourceTextSchema, {
1285     /**
1286      * The namespace for the plugin. This will be the property on the host which
1287      * references the plugin instance.
1288      *
1289      * @property NS
1290      * @type String
1291      * @static
1292      * @final
1293      * @value "schema"
1294      */
1295     NS: "schema",
1296
1297     /**
1298      * Class name.
1299      *
1300      * @property NAME
1301      * @type String
1302      * @static
1303      * @final
1304      * @value "dataSourceTextSchema"
1305      */
1306     NAME: "dataSourceTextSchema",
1307
1308     /////////////////////////////////////////////////////////////////////////////
1309     //
1310     // DataSourceTextSchema Attributes
1311     //
1312     /////////////////////////////////////////////////////////////////////////////
1313
1314     ATTRS: {
1315         schema: {
1316             //value: {}
1317         }
1318     }
1319 });
1320
1321 Y.extend(DataSourceTextSchema, Y.Plugin.Base, {
1322     /**
1323     * Internal init() handler.
1324     *
1325     * @method initializer
1326     * @param config {Object} Config object.
1327     * @private
1328     */
1329     initializer: function(config) {
1330         this.doBefore("_defDataFn", this._beforeDefDataFn);
1331     },
1332
1333     /**
1334      * Parses raw data into a normalized response.
1335      *
1336      * @method _beforeDefDataFn
1337      * <dl>
1338      * <dt>tId (Number)</dt> <dd>Unique transaction ID.</dd>
1339      * <dt>request (Object)</dt> <dd>The request.</dd>
1340      * <dt>callback (Object)</dt> <dd>The callback object with the following properties:
1341      *     <dl>
1342      *         <dt>success (Function)</dt> <dd>Success handler.</dd>
1343      *         <dt>failure (Function)</dt> <dd>Failure handler.</dd>
1344      *     </dl>
1345      * </dd>
1346      * <dt>data (Object)</dt> <dd>Raw data.</dd>
1347      * </dl>
1348      * @protected
1349      */
1350     _beforeDefDataFn: function(e) {
1351         var data = (Y.DataSource.IO && (this.get("host") instanceof Y.DataSource.IO) && Y.Lang.isString(e.data.responseText)) ? e.data.responseText : e.data,
1352             response = Y.DataSchema.Text.apply(this.get("schema"), data);
1353
1354         // Default
1355         if(!response) {
1356             response = {
1357                 meta: {},
1358                 results: data
1359             };
1360         }
1361
1362         this.get("host").fire("response", Y.mix({response:response}, e));
1363         return new Y.Do.Halt("DataSourceTextSchema plugin halted _defDataFn");
1364     }
1365 });
1366
1367 Y.namespace('Plugin').DataSourceTextSchema = DataSourceTextSchema;
1368
1369
1370
1371 }, '3.0.0' ,{requires:['plugin', 'datasource-local', 'dataschema-text']});
1372
1373 YUI.add('datasource-polling', function(Y) {
1374
1375 /**
1376  * Extends DataSource with polling functionality.
1377  *
1378  * @module datasource
1379  * @submodule datasource-polling
1380  */
1381
1382 /**
1383  * Adds polling to the DataSource Utility.
1384  * @class Pollable
1385  * @extends DataSource.Local
1386  */
1387 var LANG = Y.Lang,
1388
1389     Pollable = function() {
1390         this._intervals = {};
1391     };
1392
1393 Pollable.prototype = {
1394
1395     /**
1396     * @property _intervals
1397     * @description Hash of polling interval IDs that have been enabled,
1398     * stored here to be able to clear all intervals.
1399     * @private
1400     */
1401     _intervals: null,
1402
1403     /**
1404      * Sets up a polling mechanism to send requests at set intervals and forward
1405      * responses to given callback.
1406      *
1407      * @method setInterval
1408      * @param msec {Number} Length of interval in milliseconds.
1409      * @param request {Object} Request object.
1410      * @param callback {Object} An object literal with the following properties:
1411      *     <dl>
1412      *     <dt><code>success</code></dt>
1413      *     <dd>The function to call when the data is ready.</dd>
1414      *     <dt><code>failure</code></dt>
1415      *     <dd>The function to call upon a response failure condition.</dd>
1416      *     <dt><code>argument</code></dt>
1417      *     <dd>Arbitrary data that will be passed back to the success and failure handlers.</dd>
1418      *     </dl>
1419      * @return {Number} Interval ID.
1420      */
1421     setInterval: function(msec, request, callback) {
1422         var x = Y.later(msec, this, this.sendRequest, [request, callback], true);
1423         this._intervals[x.id] = x;
1424         return x.id;
1425     },
1426
1427     /**
1428      * Disables polling mechanism associated with the given interval ID.
1429      *
1430      * @method clearInterval
1431      * @param id {Number} Interval ID.
1432      */
1433     clearInterval: function(id, key) {
1434         // In case of being called by clearAllIntervals()
1435         id = key || id;
1436         if(this._intervals[id]) {
1437             // Clear the interval
1438             this._intervals[id].cancel();
1439             // Clear from tracker
1440             delete this._intervals[id];
1441         }
1442     },
1443
1444     /**
1445      * Clears all intervals.
1446      *
1447      * @method clearAllIntervals
1448      */
1449     clearAllIntervals: function() {
1450         Y.each(this._intervals, this.clearInterval, this);
1451     }
1452 };
1453
1454 Y.augment(Y.DataSource.Local, Pollable);
1455
1456
1457
1458 }, '3.0.0' ,{requires:['datasource-local']});
1459
1460
1461
1462 YUI.add('datasource', function(Y){}, '3.0.0' ,{use:['datasource-local','datasource-io','datasource-get','datasource-function','datasource-cache','datasource-jsonschema','datasource-xmlschema','datasource-arrayschema','datasource-textschema','datasource-polling']});
1463