[Summary view] [Print] [Text view]

   1  /*
   2  YUI 3.17.2 (build 9c3c78e)
   3  Copyright 2014 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.17.2', {"requires": ["base-pluginhost", "plugin", "tree"]});