lib/yui/3.5.1/build/datatable-message/datatable-message.js

   1 /*
   2 YUI 3.5.1 (build 22)
   3 Copyright 2012 Yahoo! Inc. All rights reserved.
   4 Licensed under the BSD License.
   5 http://yuilibrary.com/license/
   6 */
   7 YUI.add('datatable-message', function(Y) {
   8
   9 /**
  10 Adds support for a message container to appear in the table.  This can be used
  11 to indicate loading progress, lack of records, or any other communication
  12 needed.
  13
  14 @module datatable
  15 @submodule datatable-message
  16 @since 3.5.0
  17 **/
  18 var Message;
  19
  20 /**
  21 _API docs for this extension are included in the DataTable class._
  22
  23 Adds support for a message container to appear in the table.  This can be used
  24 to indicate loading progress, lack of records, or any other communication
  25 needed.
  26
  27 Features added to `Y.DataTable`, and made available for custom classes at
  28 `Y.DataTable.Message`.
  29
  30 @class DataTable.Message
  31 @for DataTable
  32 @since 3.5.0
  33 **/
  34 Y.namespace('DataTable').Message = Message = function () {};
  35
  36 Message.ATTRS = {
  37     /**
  38     Enables the display of messages in the table.  Setting this to false will
  39     prevent the message Node from being created and `showMessage` from doing
  40     anything.
  41
  42     @attribute showMessages
  43     @type {Boolean}
  44     @default true
  45     @since 3.5.0
  46     **/
  47     showMessages: {
  48         value: true,
  49         validator: Y.Lang.isBoolean
  50     }
  51 };
  52
  53 Y.mix(Message.prototype, {
  54     /**
  55     Template used to generate the node that will be used to report messages.
  56
  57     @property MESSAGE_TEMPLATE
  58     @type {HTML}
  59     @default <tbody class="{className}"><td class="{contentClass}" colspan="{colspan}"></td></tbody>
  60     @since 3.5.0
  61     **/
  62     MESSAGE_TEMPLATE: '<tbody class="{className}"><tr><td class="{contentClass}" colspan="{colspan}"></td></tr></tbody>',
  63
  64     /**
  65     Hides the message node.
  66
  67     @method hideMessage
  68     @return {DataTable}
  69     @chainable
  70     @since 3.5.0
  71     **/
  72     hideMessage: function () {
  73         this.get('boundingBox').removeClass(
  74             this.getClassName('message', 'visible'));
  75
  76         return this;
  77     },
  78
  79     /**
  80     Display the message node and set its content to `message`.  If there is a
  81     localized `strings` entry for the value of `message`, that string will be
  82     used.
  83
  84     @method showMessage
  85     @param {String} message The message name or message itself to display
  86     @return {DataTable}
  87     @chainable
  88     @since 3.5.0
  89     **/
  90     showMessage: function (message) {
  91         var content = this.getString(message) || message;
  92
  93         if (!this._messageNode) {
  94             this._initMessageNode();
  95         }
  96
  97         if (this.get('showMessages')) {
  98             if (content) {
  99                 this._messageNode.one(
 100                     '.' + this.getClassName('message', 'content'))
 101                     .setContent(content);
 102
 103                 this.get('boundingBox').addClass(
 104                     this.getClassName('message','visible'));
 105             } else {
 106                 // TODO: is this right?
 107                 // If no message provided, remove the message node.
 108                 this.hideMessage();
 109             }
 110         }
 111
 112         return this;
 113     },
 114
 115     //--------------------------------------------------------------------------
 116     // Protected methods
 117     //--------------------------------------------------------------------------
 118     /**
 119     Updates the colspan of the `<td>` used to display the messages.
 120
 121     @method _afterMessageColumnsChange
 122     @param {EventFacade} e The columnsChange event
 123     @protected
 124     @since 3.5.0
 125     **/
 126     _afterMessageColumnsChange: function (e) {
 127         var contentNode;
 128
 129         if (this._messageNode) {
 130             contentNode = this._messageNode.one(
 131                 '.' + this.getClassName('message', 'content'));
 132
 133             if (contentNode) {
 134                 contentNode.set('colSpan', this._displayColumns.length);
 135             }
 136         }
 137     },
 138
 139     /**
 140     Relays to `_uiSetMessage` to hide or show the message node.
 141
 142     @method _afterMessageDataChange
 143     @param {EventFacade} e The dataChange event
 144     @protected
 145     @since 3.5.0
 146     **/
 147     _afterMessageDataChange: function (e) {
 148         this._uiSetMessage();
 149     },
 150
 151     /**
 152     Removes the message node if `showMessages` is `false`, or relays to
 153     `_uiSetMessage` if `true`.
 154
 155     @method _afterShowMessagesChange
 156     @param {EventFacade} e The showMessagesChange event
 157     @protected
 158     @since 3.5.0
 159     **/
 160     _afterShowMessagesChange: function (e) {
 161         if (e.newVal) {
 162             this._uiSetMessage(e);
 163         } else if (this._messageNode) {
 164             this.get('boundingBox').removeClass(
 165                 this.getClassName('message', 'visible'));
 166
 167             this._messageNode.remove().destroy(true);
 168             this._messageNode = null;
 169         }
 170     },
 171
 172     /**
 173     Binds the events necessary to keep the message node in sync with the current
 174     table and configuration state.
 175
 176     @method _bindMessageUI
 177     @protected
 178     @since 3.5.0
 179     **/
 180     _bindMessageUI: function () {
 181         this.after(['dataChange', '*:add', '*:remove', '*:reset'],
 182             Y.bind('_afterMessageDataChange', this));
 183
 184         this.after('columnsChange', Y.bind('_afterMessageColumnsChange', this));
 185
 186         this.after('showMessagesChange',
 187             Y.bind('_afterShowMessagesChange', this));
 188     },
 189
 190     /**
 191     Merges in the message related strings and hooks into the rendering cycle to
 192     also render and bind the message node.
 193
 194     @method initializer
 195     @protected
 196     @since 3.5.0
 197     **/
 198     initializer: function () {
 199         this._initMessageStrings();
 200
 201         if (this.get('showMessages')) {
 202             this.after('renderBody', Y.bind('_initMessageNode', this));
 203         }
 204
 205         this.after(Y.bind('_bindMessageUI', this), this, 'bindUI');
 206         this.after(Y.bind('_syncMessageUI', this), this, 'syncUI');
 207     },
 208
 209     /**
 210     Creates the `_messageNode` property from the configured `MESSAGE_TEMPLATE`
 211     and inserts it before the `<table>`'s `<tbody>` node.
 212
 213     @method _initMessageNode
 214     @protected
 215     @since 3.5.0
 216     **/
 217     _initMessageNode: function () {
 218         if (!this._messageNode) {
 219             this._messageNode = Y.Node.create(
 220                 Y.Lang.sub(this.MESSAGE_TEMPLATE, {
 221                     className: this.getClassName('message'),
 222                     contentClass: this.getClassName('message', 'content'),
 223                     colspan: this._displayColumns.length || 1
 224                 }));
 225
 226             this._tableNode.insertBefore(this._messageNode, this._tbodyNode);
 227         }
 228     },
 229
 230     /**
 231     Add the messaging related strings to the `strings` map.
 232
 233     @method _initMessageStrings
 234     @protected
 235     @since 3.5.0
 236     **/
 237     _initMessageStrings: function () {
 238         // Not a valueFn because other class extensions will want to add to it
 239         this.set('strings', Y.mix((this.get('strings') || {}),
 240             Y.Intl.get('datatable-message')));
 241     },
 242
 243     /**
 244     Node used to display messages from `showMessage`.
 245
 246     @property _messageNode
 247     @type {Node}
 248     @value `undefined` (not initially set)
 249     @since 3.5.0
 250     **/
 251     //_messageNode: null,
 252
 253     /**
 254     Synchronizes the message UI with the table state.
 255
 256     @method _syncMessageUI
 257     @protected
 258     @since 3.5.0
 259     **/
 260     _syncMessageUI: function () {
 261         this._uiSetMessage();
 262     },
 263
 264     /**
 265     Calls `hideMessage` or `showMessage` as appropriate based on the presence of
 266     records in the `data` ModelList.
 267
 268     This is called when `data` is reset or records are added or removed.  Also,
 269     if the `showMessages` attribute is updated.  In either case, if the
 270     triggering event has a `message` property on the EventFacade, it will be
 271     passed to `showMessage` (if appropriate).  If no such property is on the
 272     facade, the `emptyMessage` will be used (see the strings).
 273
 274     @method _uiSetMessage
 275     @param {EventFacade} e The columnsChange event
 276     @protected
 277     @since 3.5.0
 278     **/
 279     _uiSetMessage: function (e) {
 280         if (!this.data.size()) {
 281             this.showMessage((e && e.message) || 'emptyMessage');
 282         } else {
 283             this.hideMessage();
 284         }
 285     }
 286 });
 287
 288
 289 if (Y.Lang.isFunction(Y.DataTable)) {
 290     Y.Base.mix(Y.DataTable, [ Message ]);
 291 }
 292
 293
 294 }, '3.5.1' ,{requires:['datatable-base'], skinnable:true, lang:['en']});