lib/yuilib/3.13.0/tree-lazy/tree-lazy-debug.js

   1 /*
   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/
   6 */
   7
   8 YUI.add('tree-lazy', function (Y, NAME) {
   9
  10 /*jshint expr:true, maxlen:200, onevar:false */
  11
  12 /**
  13 Provides `Plugin.Tree.Lazy`, a plugin for `Tree.Openable` that makes it easy to
  14 lazily load and populate the contents of tree nodes the first time they're
  15 opened.
  16
  17 @module tree
  18 @submodule tree-lazy
  19 **/
  20
  21 /**
  22 A plugin for `Tree.Openable` that makes it easy to lazily load and populate the
  23 contents of tree nodes the first time they're opened.
  24
  25 ### Example
  26
  27     YUI().use('jsonp', 'tree-openable', 'tree-lazy', function (Y) {
  28         var Tree = Y.Base.create('openableTree', Y.Tree, [Y.Tree.Openable]),
  29             tree = new Tree();
  30
  31         tree.plug(Y.Plugin.Tree.Lazy, {
  32
  33             // Custom function that Plugin.Tree.Lazy will call when it needs to
  34             // load the children for a node.
  35             load: function (node, callback) {
  36                 // Request the data for this node's children via JSONP.
  37                 Y.jsonp('http://example.com/api/data?callback={callback}', function (data) {
  38                     // If we didn't get any data back, treat this as an error.
  39                     if (!data) {
  40                         callback(new Error('No data!'));
  41                         return;
  42                     }
  43
  44                     // Append the children to the node (assume `data.children` is
  45                     // an array of child node data for the sake of this example).
  46                     node.append(data.children);
  47
  48                     // Call the callback function to tell Plugin.Tree.Lazy that
  49                     // we're done loading data.
  50                     callback();
  51                 });
  52             }
  53
  54         });
  55     });
  56
  57 @class Plugin.Tree.Lazy
  58 @param {Object} config Config object.
  59
  60     @param {Function} config.load Custom `load()` function that will be called
  61         when a node's children need to be loaded. This function must call the
  62         provided callback to indicate completion.
  63
  64         @param {Function} config.load.callback Callback function. The custom
  65             `load()` function must call this callback to indicate completion.
  66
  67             @param {Error} [config.load.callback.err] Error object. If provided,
  68                 the load action will be considered a failure, and an `error`
  69                 event will be fired. Omit this argument (or set it to `null`) to
  70                 indicate success.
  71
  72 @extends Plugin.Base
  73 @constructor
  74 **/
  75
  76 /**
  77 Fired just before the custom `load()` method is called to load child nodes for a
  78 node.
  79
  80 Calling `preventDefault()` on this event's facade will cancel the load action
  81 and prevent the `load()` method from being called.
  82
  83 @event beforeLoad
  84 @param {Tree.Node} node Tree node whose children will be loaded.
  85 @preventable _defBeforeLoadFn
  86 **/
  87 var EVT_BEFORE_LOAD = 'beforeLoad';
  88
  89 /**
  90 Fired when the `load()` method indicates there was an error loading child nodes.
  91
  92 @event error
  93 @param {Error} error Error provided by the `load()` method.
  94 @param {String} src Source of the error (defaults to "load").
  95 **/
  96 var EVT_ERROR = 'error';
  97
  98 /**
  99 Fired after child nodes have finished loading and have been added to the tree.
 100
 101 @event load
 102 @param {Tree.Node} node Tree node whose children have been loaded.
 103 **/
 104 var EVT_LOAD = 'load';
 105
 106 Y.namespace('Plugin.Tree').Lazy = Y.Base.create('lazyTreePlugin', Y.Plugin.Base, [], {
 107     // -- Lifecycle Methods ----------------------------------------------------
 108     initializer: function (config) {
 109         this._host = config.host;
 110
 111         if (config.load) {
 112             this.load = config.load;
 113         }
 114
 115         // Make sure we've been plugged into a Tree that mixes in the
 116         // Tree.Openable extension.
 117         if (!this._host.openNode) {
 118             Y.log("Plugin.Tree.Lazy was plugged into a Tree that doesn't mix in the Tree.Openable extension. This probably won't do you much good.", 'warn', 'tree-lazy');
 119         }
 120
 121         this._published = {};
 122         this._attachEvents();
 123     },
 124
 125     // -- Public Methods -------------------------------------------------------
 126     load: function (node, callback) {
 127         callback(new Error('Plugin.Tree.Lazy: Please provide a custom `load` method when instantiating this plugin.'));
 128     },
 129
 130     // -- Protected Methods ----------------------------------------------------
 131     _attachEvents: function () {
 132         this.onHostEvent('open', this._onOpen);
 133     },
 134
 135     // -- Protected Event Handlers ---------------------------------------------
 136     _onOpen: function (e) {
 137         var node = e.node;
 138
 139         // Nothing to do if this node can't have children or if its children
 140         // have already been (or are already being) loaded.
 141         if (!node.canHaveChildren || node.state.loaded || node.state.loading) {
 142             return;
 143         }
 144
 145         if (!this._published[EVT_BEFORE_LOAD]) {
 146             this._published[EVT_BEFORE_LOAD] = this.publish(EVT_BEFORE_LOAD, {
 147                 defaultFn: this._defLoadingFn
 148             });
 149         }
 150
 151         this.fire(EVT_BEFORE_LOAD, {node: node});
 152     },
 153
 154     // -- Default Event Handlers -----------------------------------------------
 155     _defLoadingFn: function (e) {
 156         var node = e.node,
 157             self = this;
 158
 159         node.state.loading = true;
 160
 161         this.load(node, function (err) {
 162             delete node.state.loading;
 163
 164             if (err) {
 165                 self.fire(EVT_ERROR, {
 166                     error: err,
 167                     src  : 'load'
 168                 });
 169
 170                 return;
 171             }
 172
 173             node.state.loaded = true;
 174
 175             self.fire(EVT_LOAD, {node: node});
 176         });
 177     }
 178 }, {
 179     NS: 'lazy'
 180 });
 181
 182
 183 }, '3.13.0', {"requires": ["base-pluginhost", "plugin", "tree"]});