SOURCE CODE: Uize.Widget.CollectionItem (view docs)

/*______________
|       ______  |   U I Z E    J A V A S C R I P T    F R A M E W O R K
|     /      /  |   ---------------------------------------------------
|    /    O /   |    MODULE : Uize.Widget.CollectionItem Class
|   /    / /    |
|  /    / /  /| |    ONLINE : http://www.uize.com
| /____/ /__/_| | COPYRIGHT : (c)2007-2016 UIZE
|          /___ |   LICENSE : Available under MIT License or GNU General Public License
|_______________|             http://www.uize.com/license.html
*/

/* Module Meta Data
  type: Class
  importance: 5
  codeCompleteness: 100
  docCompleteness: 100
*/

/*?
  Introduction
    The =Uize.Widget.CollectionItem= widget class manages state for an item that is intended to be one of many items owned by a collection widget instance.

    *DEVELOPERS:* `Chris van Rensburg`, `Jan Borgersen`

    In a Nutshell
      The =Uize.Widget.CollectionItem= class implements and manages the user interface for an item in a collection and is intended to be used in conjunction with the =Uize.Widget.Collection= class (or subclass).

      Some examples of collection items would be...

      - search results in a search results grid
      - movies in a queue of pending movie rentals
      - books in a list of book recommendations, in order of ratings score
*/

Uize.module ({
  name:'Uize.Widget.CollectionItem',
  required:[
    'Uize.Widget.Button',
    'Uize.Dom.Classes'
  ],
  builder:function (_superclass) {
    'use strict';

    var
      /*** Variables for Scruncher Optimization ***/
        _true = true,
        _false = false,
        _undefined
    ;

    /*** Private Instance Methods ***/
      function _updateUiTitle (m) {
        if (m.isWired) {
          var _title = m._title;
          _title != _undefined && m.setNodeInnerHtml ('title',_title);
          /*?
            DOM Nodes
              title DOM Node
                An optional node whose contents will be replaced with the value of the =title= state property, if this property's value is not =null= or =undefined=.

                The =innerHTML= value of the =title DOM Node= will be updated to reflect the value of the =title= state property whenever the value of this property is changed, is not =null= or =undefined=, and the instance is wired up.

                NOTES
                - this DOM node is optional
          */
        }
      }

      function _updateUiState (m) {
        if (m.isWired) {
          /*** set CSS class for root node ***/
            Uize.Dom.Classes.setState(
              m.getNode(),
              ['', m._cssClassOver, m._cssClassActive],
              (m._selected ? 2 : m._over && 1) || 0
              /*?
                DOM Nodes
                  Root Node
                    The root node is the DOM node with the name =''= (empty string), and is required for this widget class.

                    The =className= property of this node is updated to reflect the state of the instance's =selected= and =over= state properties. If the instance is selected (i.e. =selected= is =true=, then the =className= property of the node is updated to contain =cssClassActive=. If the instance is not selected, but the user is hovering over it (i.e. =over= is set to =true=), then the =className= property of the node is updated to contain =cssClassOver=. If both =selected= and =over= are both set to =false=, then the node's =className= property will not be updated.

                    NOTES
                    - this DOM node is required
              */
            );

          /*** set CSS class for preview node ***/
            var
              _cssClassImage = m._cssClassImage,
              _cssClassImageOver = m._cssClassImageOver
            ;
            typeof _cssClassImage == 'string' && typeof _cssClassImageOver == 'string' &&
              Uize.Dom.Classes.setState(
                m.getNode('preview'),
                [_cssClassImage, _cssClassImageOver],
                m._over
                /*?
                  DOM Nodes
                    preview
                      An optional node that should provide a preview for the item that is represented by the instance, and whose =className= property is updated to reflect the state of the instance's =over= state property.

                      When =over= is set to =true=, the value of this node's =className= property will be set to the value of the =cssClassImageOver= state property. When =over= is set to =false=, the value of this node's =className= property will be set to the value of the =cssClassImage= state property. When either of the =cssClassImage= or =cssClassImageOver= state properties are set to =null= or are left =undefined=, then the =className= property of this node will not be updated.

                      NOTES
                      - this DOM node is optional
                      - in a typical implementation this DOM node will be an IMG tag, but it does not have to be
                */
              )
            ;
        }
      }

      function _onChangeUpdateUiState () {
        _updateUiState (this);
      }

      function _selectItem (m,_domEvent,_forceToggle) {
        m.fire ({name:'Click Selected',domEvent:_domEvent,forceToggle:_forceToggle});
        /*?
          Instance Events
            Click Selected
              An instance event that is fired when the user clicks on the optional =select= button, or when the user clicks on the =previewShell= DOM node and the value of the =previewClickAction= state property is set to either ='Select'= or ='Toggle Selected'=.

              When this event is fired because the user clicks on the =previewShell= DOM node and =previewClickAction= is set to ='Toggle Selected'=, then the event object will contain a =forceToggle= property that is set to =true=.
        */
      }

      function _setSelectorState (m) {
        var _selectButton = m.children.select;
        _selectButton.get ('state') != 'over' && _selectButton.set ({selected:m._selected});
      }

    return _superclass.subclass ({
      alphastructor: function () {
        this._properties = {};
      },

      omegastructor:function () {
        var m = this;

        /*** add select button ***/
          m.addChildButton (
            'select',function (_event) {_selectItem (m,_event.domEvent,_true)}
            /*?
              Child Widgets
                select
                  An instance of the =Uize.Widget.Button= class, that lets the user toggle the =selected= state for the instance.

                  NOTES
                  - the markup for this child widget is optional, and a given implementation of this widget in HTML does not need to offer a =select= button
            */
          ).set ({
            clickToSelect:_true,
            clickToDeselect:_true
          });
          _setSelectorState (m);

        /*** add remove button ***/
          m.addChildButton (
            'remove',
            function () {m.fire ({name:'Remove',byUser:_true})}
            /*?
              Child Widgets
                remove
                  An instance of the =Uize.Widget.Button= class, that lets the user remove the item represented by the instance, or the current selection of items.

                  Clicking on this button fires the =Remove= instance event, with a =byUser= property in the event object that is set to the value =true=.

                  NOTES
                  - the markup for this child widget is optional, and a given implementation of this widget in HTML does not need to offer a =remove= button
                  - see the related =Remove= instance event

              Instance Events
                Remove
                  An instance event that is fired when the user clicks on the =remove= button of an instance.

                  The =Uize.Widget.CollectionItem= class (or subclass) is not responsible for removing the item represented by an instance. Instead, the =Remove= event is fired and handled by an instance of the =Uize.Widget.Collection= class (or subclass) that owns the collection items as child widgets. The =Uize.Widget.Collection= class then performs the operations necessary to update the data set for the collection of items. Also, the =Uize.Widget.Collection= class is responsible for deciding if just the item whose =remove= button was clicked should be removed, or if all currently selected items should be removed.

                  NOTES
                  - see the related =remove= child widget
            */
          );
      },

      instanceMethods:{
        addChildButton:Uize.Widget.Button.addChildButton,

        updateUi:function () {
          _updateUiState (this);
          _updateUiTitle (this);
        },

        wireUi:function () {
          var m = this;
          if (!m.isWired) {
            // NOTE: Ideally want to get rid of cssClassBase because we're using Uize.Dom.Classes, but for backwards compatibility, need to still
            // minimally support it.  If there was a case that an application was passing in cssClassBase in order to get the item to have a certain
            // class (and it wasn't already in the markup), we need to set it here, so that would still operate correctly.
            var _rootNode = m.getNode();
            if (m._cssClassBase && _rootNode)
              _rootNode.className = m._cssClassBase
            ;

            /*** wire up the preview shell node ***/
              var
                _previewShellNode = m.getNode ('previewShell') || 'imageLink',
                  /*?
                    DOM Nodes
                      previewShell
                        A node that serves as a shell around the =preview= DOM node.

                        Mouseover, mouseout, and click events are wired for this node in order to manage =over= and =selected= state for the instance, and in order to fire instance events, such as the ='Click Preview'=, ='Click Selected'=, and ='Item Mouse Down'= events.

                        NOTES
                        - this DOM node is required, even if the optional =preview= DOM node is omitted

                      imageLink -- DEPRECATED 2009-07-28
                        The deprecated =imageLink= DOM node is an alternate / legacy name for the =previewShell= DOM node.

                        If the =imageLink= DOM node is used, it will behave in exactly the same way as the =previewShell= node. If you're writing new code, you should *not* use this DOM node in your HTML markup.

                        NOTES
                        - this DOM node is deprecated
                  */
                _fireItemMouseDownEvent = function (_event) {
                  m.fire ({name:'Item Mouse Down',domEvent:_event,bubble:_true});
                  /*?
                    Instance Events
                      Item Mouse Down
                        A bubbling instance event that is fired when the user mouses down on the =previewShell= DOM node.

                        As a bubbling event, a handler for this event can be wired by an instance of the =Uize.Widget.Collection= class (or subclass) - that owns the collection items as child widgets - on itself. This is the case with the =Uize.Widget.Collection.Dynamic= class, which manages drag-and-drop for reordering of items in a collection.

                        When this event is fired, the event object contains a =domEvent= property that is a reference to the mousedown DOM event, and a =bubble= property that is set to =true=.
                  */
                }
              ;
              m.wireNode (
                _previewShellNode,
                {
                  mouseover:function () {m.set ({_over:_true})},
                  mouseout:function () {m.set ({_over:_false})},
                  touchend:_fireItemMouseDownEvent,
                  mousedown:_fireItemMouseDownEvent
                }
              );

              if (m._previewClickAction)
                m.wireNode (
                  _previewShellNode,
                  'click',
                  function (_event) {
                    var _forceToggle = m._previewClickAction == 'Toggle Selected';
                    _forceToggle || m._previewClickAction == 'Select'
                      ? _selectItem (m,_event,_forceToggle)
                      : m.fire ({name:'Click Preview',bubble:_true});
                        /*?
                          Instance Events
                            Click Preview
                              An instance event that is fired when the user clicks on the =previewShell= DOM node and the =previewClickAction= state property is set to ='Preview'= or =null=, or left =undefined=.

                              As a bubbling event, a handler for this event can be wired by an instance of the =Uize.Widget.Collection= class (or subclass) - that owns the collection items as child widgets - on itself. When this event is fired, the event object contains a =bubble= property that is set to =true=.
                        */
                  }
                )
              ;

            _superclass.doMy (m,'wireUi');
          }
        }
      },

      instanceProperties:{
        isCollectionItem: _true
        /*?
          Instance Properties
            isCollectionItem
              A boolean specifying whether or not this class supports the collection item interface (not yet formally defined)

              NOTES
              - for now, this is only used to determine if this class is indeed a =CollectionItem=
              - see the =isCollectionItem= method =Uize.Widget.Collection=
        */
      },

      stateProperties:{
        _cssClassActive:'cssClassActive',
          /*?
            State Properties
              cssClassActive
                A string, specifying the CSS class name that should be added to the =className= property of the `root node` when the instance is selected (i.e. the =selected= state property is set to =true=).

                For a more in-depth discussion of the interaction between this property and the companion =cssClassOver= property, consult the reference for the `root node`.

                NOTES
                - see the companion =cssClassOver= state property
                - see the related =cssClassImage= and =cssClassImageOver= state properties
                - the initial value is =undefined=
          */
        _cssClassBase:'cssClassBase',
          /*?
            State Properties
              cssClassBase -- DEPRECATED 2011-02-03
                A string, specifying the base CSS class string that should be set as the =className= property of the `root node` when wiring the instance.

                This state property, now deprecated, was originally used to aid in constructing the =className= property for the `root node` to reflect the =selected= and =over= states of the instance.

                NOTES
                - This state property is deprecated
                - the initial value is =undefined=
          */
        _cssClassImage:'cssClassImage',
          /*?
            State Properties
              cssClassImage
                A string, specifying the value that should be set for the =className= property of the =preview= DOM node when the user is not moused over the instance (i.e. the =over= state property is set to =false=).

                For a more in-depth discussion of the interaction between this property and the companion =cssClassImageOver= property, consult the reference for the =preview= DOM node.

                NOTES
                - see the companion =cssClassImageOver= state property
                - see the related =cssClassActive=, =cssClassBase=, and =cssClassOver= state properties
                - the initial value is =undefined=
          */
        _cssClassImageOver:'cssClassImageOver',
          /*?
            State Properties
              cssClassImageOver
                A string, specifying the value that should be set for the =className= property of the =preview= DOM node when the user mouses over the instance (i.e. the =over= state property is set to =true=).

                For a more in-depth discussion of the interaction between this property and the companion =cssClassImage= property, consult the reference for the =preview= DOM node.

                NOTES
                - see the companion =cssClassImage= state property
                - see the related =cssClassActive=, =cssClassBase=, and =cssClassOver= state properties
                - the initial value is =undefined=
          */
        _cssClassOver:'cssClassOver',
          /*?
            State Properties
              cssClassOver
                A string, specifying the CSS class name that should be added to the =className= property of the root node when the user is mousing over the instance and it is not already selected (i.e. the =over= state property is set to =true= and the =selected= state property is set to =false=).

                For a more in-depth discussion of the interaction between this property and the companion =cssClassActive= property, consult the reference for the `root node`.

                NOTES
                - see the companion =cssClassActive= state properties
                - see the related =cssClassImage= and =cssClassImageOver= state properties
                - the initial value is =undefined=
          */
        _locked:{
          name:'locked',
          value:_false
          /*?
            State Properties
              locked
                A boolean, indicating whether or not the instance is locked.

                NOTES
                - the initial value is =false=
          */
        },
        _over:{
          name:'over',
          onChange:[
            function () {
              var m = this;
              m.isWired && m._previewTooltip && Uize.Tooltip &&
                Uize.Tooltip.showTooltip (m._previewTooltip,m._over)
              ;
            },
            _onChangeUpdateUiState
          ],
          value:_false
          /*?
            State Properties
              over
                A boolean, indicating whether or not the user is mousing over the =previewShell= DOM node of the instance.

                The value of this property is set to =true= when the user mouses over the instance's =previewShell= DOM node, and is set to =false= when the user mouses out.

                NOTES
                - the initial value is =false=
          */
        },
        _previewClickAction:'previewClickAction',
          /*?
            State Properties
              previewClickAction
                A string, specifying the desired action that should be performed when the =previewShell= DOM node is clicked.

                VALUES

                - ='Preview'= - Clicking will fire a bubbling ='Click Preview'= instance event.
                - ='Select'= - Clicking will select the item, clearing any existing selection.
                - ='Toggle Selected'= - Clicking will toggle the selected state of the item, not affecting any other currently selected items.
                - =not defined= - When this property is not defined or is set to the value =null=, =false=, or =''= (empty string), then a bubbling ='Click Preview'= instance event will be fired (i.e. defaulting to the behavior for the value ='Preview'=).

                NOTES
                - the initial value is =undefined=
          */
        _previewTooltip:'previewTooltip',
          /*?
            State Properties
              previewTooltip
                An object reference to a DOM node, or a string whose value is the =id= for a DOM node, that should be displayed as a tooltip for the instance when the value of the =over= state property changes to =true= and the instance is wired.

                Essentially, the =previewTooltip= state property can be used to specify a tooltip that should appear when the user mouses over the =previewShell= DOM node.

                NOTES
                - the initial value is =undefined=
                - in order for the value of this property to be honored, the =Uize.Tooltip= module must already be loaded, but the =Uize.Widget.CollectionItem= module does not explicitly require the =Uize.Tooltip= module
          */
        _properties:{
          name:'properties',
          onChange:function () {
            var
              _properties = this._properties
            ;
            _properties && 'title' in _properties && this.set ({_title:_properties.title});
          }
          /*?
            State Properties
              properties
                An object, acting as a "bucket" for additional data that may be associated to an instance.

                The data in the =properties= state property is used by the =getPropertyForItems= and =getPropertyForSelected= instance methods of the =Uize.Widget.Collection= class. When the value of the =properties= state property is changed, the value of the =title= state property is set from the "title" property of the =properties= object, if it exists.

                NOTES
                - the initial value is =undefined=
          */
        },
        _selected:{
          name:'selected',
          onChange:[
            function () {this.children.select && _setSelectorState (this)},
            _onChangeUpdateUiState
          ],
          value:_false
          /*?
            State Properties
              selected
                A boolean, indicating whether or not the instance is selected.

                When the value of the =selected= state property changes, the selected state of the =select= child widget will be updated, and the CSS class of the =Root Node= will be updated to reflect the instance's selected state.

                NOTES
                - the initial value is =false=
          */
        },
        _title:{
          name:'title',
          onChange:function () {
            var
              m = this,
              _properties = m._properties
            ;
            if (_properties) {
              _properties.title = m._title;
              _updateUiTitle (m);
              m.fire({ name: 'Title Changed', bubble: _true, value: m._title });
            }
          }
          /*?
            State Properties
              title
                A string, whose value will be used to set the value of the =innerHTML= property of the =title DOM Node=.

                The =innerHTML= value of the =title DOM Node= will be updated to reflect the value of the =title= state property whenever the value of this property is changed, is not =null= or =undefined=, and the instance is wired up. When the value of the =properties= state property is changed, the value of the =title= state property is set from the "title" property of the =properties= object.

                NOTES
                - the initial value is =undefined=
          */
        }
      }
    });
  }
});