1 /*

     2 YUI 3.10.3 (build 2fb5187)

     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-selectable', function (Y, NAME) {

     9 

    10 /*jshint expr:true, onevar:false */

    11 

    12 /**

    13 Extension for `Tree` that adds the concept of selection state for nodes.

    14 

    15 @module tree

    16 @submodule tree-selectable

    17 @main tree-selectable

    18 **/

    19 

    20 var Do = Y.Do;

    21 

    22 /**

    23 Extension for `Tree` that adds the concept of selection state for nodes.

    24 

    25 @class Tree.Selectable

    26 @constructor

    27 @extensionfor Tree

    28 **/

    29 

    30 /**

    31 Fired when a node is selected.

    32 

    33 @event select

    34 @param {Tree.Node} node Node being selected.

    35 @preventable _defSelectFn

    36 **/

    37 var EVT_SELECT = 'select';

    38 

    39 /**

    40 Fired when a node is unselected.

    41 

    42 @event unselect

    43 @param {Tree.Node} node Node being unselected.

    44 @preventable _defUnselectFn

    45 **/

    46 var EVT_UNSELECT = 'unselect';

    47 

    48 function Selectable() {}

    49 

    50 Selectable.prototype = {

    51     // -- Protected Properties -------------------------------------------------

    52 

    53     /**

    54     Mapping of node ids to node instances for nodes in this tree that are

    55     currently selected.

    56 

    57     @property {Object} _selectedMap

    58     @protected

    59     **/

    60 

    61     // -- Lifecycle ------------------------------------------------------------

    62     initializer: function () {

    63         this.nodeExtensions = this.nodeExtensions.concat(Y.Tree.Node.Selectable);

    64         this._selectedMap   = {};

    65 

    66         Do.after(this._selectableAfterDefAddFn, this, '_defAddFn');

    67         Do.after(this._selectableAfterDefClearFn, this, '_defClearFn');

    68         Do.after(this._selectableAfterDefRemoveFn, this, '_defRemoveFn');

    69 

    70         this._selectableEvents = [

    71             this.after('multiSelectChange', this._afterMultiSelectChange)

    72         ];

    73     },

    74 

    75     destructor: function () {

    76         (new Y.EventHandle(this._selectableEvents)).detach();

    77 

    78         this._selectableEvents = null;

    79         this._selectedMap      = null;

    80     },

    81 

    82     // -- Public Methods -------------------------------------------------------

    83 

    84     /**

    85     Returns an array of nodes that are currently selected.

    86 

    87     @method getSelectedNodes

    88     @return {Tree.Node.Selectable[]} Array of selected nodes.

    89     **/

    90     getSelectedNodes: function () {

    91         return Y.Object.values(this._selectedMap);

    92     },

    93 

    94     /**

    95     Selects the specified node.

    96 

    97     @method selectNode

    98     @param {Tree.Node.Selectable} node Node to select.

    99     @param {Object} [options] Options.

   100         @param {Boolean} [options.silent=false] If `true`, the `select` event

   101             will be suppressed.

   102         @param {String} [options.src] Source of the change, to be passed along

   103             to the event facade of the resulting event. This can be used to

   104             distinguish between changes triggered by a user and changes

   105             triggered programmatically, for example.

   106     @chainable

   107     **/

   108     selectNode: function (node, options) {

   109         // Instead of calling node.isSelected(), we look for the node in this

   110         // tree's selectedMap, which ensures that the `select` event will fire

   111         // in cases such as a node being added to this tree with its selected

   112         // state already set to true.

   113         if (!this._selectedMap[node.id]) {

   114             this._fireTreeEvent(EVT_SELECT, {

   115                 node: node,

   116                 src : options && options.src

   117             }, {

   118                 defaultFn: this._defSelectFn,

   119                 silent   : options && options.silent

   120             });

   121         }

   122 

   123         return this;

   124     },

   125 

   126     /**

   127     Unselects all selected nodes.

   128 

   129     @method unselect

   130     @param {Object} [options] Options.

   131         @param {Boolean} [options.silent=false] If `true`, the `unselect` event

   132             will be suppressed.

   133         @param {String} [options.src] Source of the change, to be passed along

   134             to the event facade of the resulting event. This can be used to

   135             distinguish between changes triggered by a user and changes

   136             triggered programmatically, for example.

   137     @chainable

   138     **/

   139     unselect: function (options) {

   140         for (var id in this._selectedMap) {

   141             if (this._selectedMap.hasOwnProperty(id)) {

   142                 this.unselectNode(this._selectedMap[id], options);

   143             }

   144         }

   145 

   146         return this;

   147     },

   148 

   149     /**

   150     Unselects the specified node.

   151 

   152     @method unselectNode

   153     @param {Tree.Node.Selectable} node Node to unselect.

   154     @param {Object} [options] Options.

   155         @param {Boolean} [options.silent=false] If `true`, the `unselect` event

   156             will be suppressed.

   157         @param {String} [options.src] Source of the change, to be passed along

   158             to the event facade of the resulting event. This can be used to

   159             distinguish between changes triggered by a user and changes

   160             triggered programmatically, for example.

   161     @chainable

   162     **/

   163     unselectNode: function (node, options) {

   164         if (node.isSelected() || this._selectedMap[node.id]) {

   165             this._fireTreeEvent(EVT_UNSELECT, {

   166                 node: node,

   167                 src : options && options.src

   168             }, {

   169                 defaultFn: this._defUnselectFn,

   170                 silent   : options && options.silent

   171             });

   172         }

   173 

   174         return this;

   175     },

   176 

   177     // -- Protected Methods ----------------------------------------------------

   178     _selectableAfterDefAddFn: function (e) {

   179         // If the node is marked as selected, we need go through the select

   180         // flow.

   181         if (e.node.isSelected()) {

   182             this.selectNode(e.node);

   183         }

   184     },

   185 

   186     _selectableAfterDefClearFn: function () {

   187         this._selectedMap = {};

   188     },

   189 

   190     _selectableAfterDefRemoveFn: function (e) {

   191         delete e.node.state.selected;

   192         delete this._selectedMap[e.node.id];

   193     },

   194 

   195     // -- Protected Event Handlers ---------------------------------------------

   196     _afterMultiSelectChange: function () {

   197         this.unselect();

   198     },

   199 

   200     _defSelectFn: function (e) {

   201         if (!this.get('multiSelect')) {

   202             this.unselect();

   203         }

   204 

   205         e.node.state.selected = true;

   206         this._selectedMap[e.node.id] = e.node;

   207     },

   208 

   209     _defUnselectFn: function (e) {

   210         delete e.node.state.selected;

   211         delete this._selectedMap[e.node.id];

   212     }

   213 };

   214 

   215 Selectable.ATTRS = {

   216     /**

   217     Whether or not to allow multiple nodes to be selected at once.

   218 

   219     @attribute {Boolean} multiSelect

   220     @default false

   221     **/

   222     multiSelect: {

   223         value: false

   224     }

   225 };

   226 

   227 Y.Tree.Selectable = Selectable;

   228 /**

   229 @module tree

   230 @submodule tree-selectable

   231 **/

   232 

   233 /**

   234 `Tree.Node` extension that adds methods useful for nodes in trees that use the

   235 `Tree.Selectable` extension.

   236 

   237 @class Tree.Node.Selectable

   238 @constructor

   239 @extensionfor Tree.Node

   240 **/

   241 

   242 function NodeSelectable() {}

   243 

   244 NodeSelectable.prototype = {

   245     /**

   246     Returns `true` if this node is currently selected.

   247 

   248     @method isSelected

   249     @return {Boolean} `true` if this node is currently selected, `false`

   250         otherwise.

   251     **/

   252     isSelected: function () {

   253         return !!this.state.selected;

   254     },

   255 

   256     /**

   257     Selects this node.

   258 

   259     @method select

   260     @param {Object} [options] Options.

   261         @param {Boolean} [options.silent=false] If `true`, the `select` event

   262             will be suppressed.

   263         @param {String} [options.src] Source of the change, to be passed along

   264             to the event facade of the resulting event. This can be used to

   265             distinguish between changes triggered by a user and changes

   266             triggered programmatically, for example.

   267     @chainable

   268     **/

   269     select: function (options) {

   270         this.tree.selectNode(this, options);

   271         return this;

   272     },

   273 

   274     /**

   275     Unselects this node.

   276 

   277     @method unselect

   278     @param {Object} [options] Options.

   279         @param {Boolean} [options.silent=false] If `true`, the `unselect` event

   280             will be suppressed.

   281         @param {String} [options.src] Source of the change, to be passed along

   282             to the event facade of the resulting event. This can be used to

   283             distinguish between changes triggered by a user and changes

   284             triggered programmatically, for example.

   285     @chainable

   286     **/

   287     unselect: function (options) {

   288         this.tree.unselectNode(this, options);

   289         return this;

   290     }

   291 };

   292 

   293 Y.Tree.Node.Selectable = NodeSelectable;

   294 

   295 

   296 }, '3.10.3', {"requires": ["tree"]});