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