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

     9 

    10 /**

    11 Adds mutation convenience methods such as `table.addRow(data)` to `Y.DataTable`. (or other built class).

    12 

    13 @module datatable

    14 @submodule datatable-mutable

    15 @since 3.5.0

    16 **/

    17 var toArray = Y.Array,

    18     YLang   = Y.Lang,

    19     isString = YLang.isString,

    20     isArray  = YLang.isArray,

    21     isObject = YLang.isObject,

    22     isNumber = YLang.isNumber,

    23     arrayIndex = Y.Array.indexOf,

    24     Mutable;

    25 

    26 /**

    27 _API docs for this extension are included in the DataTable class._

    28 

    29 Class extension to add mutation convenience methods to `Y.DataTable` (or other

    30 built class).

    31 

    32 Column mutation methods are paired with new custom events:

    33 

    34  * addColumn

    35  * removeColumn

    36  * modifyColumn

    37  * moveColumn

    38 

    39 Row mutation events are bubbled from the DataTable's `data` ModelList through

    40 the DataTable instance.

    41 

    42 @class DataTable.Mutable

    43 @for DataTable

    44 @since 3.5.0

    45 **/

    46 Y.namespace('DataTable').Mutable = Mutable = function () {};

    47 

    48 Mutable.ATTRS = {

    49     /**

    50     Controls whether `addRow`, `removeRow`, and `modifyRow` should trigger the

    51     underlying Model's sync layer by default.

    52 

    53     When `true`, it is unnecessary to pass the "sync" configuration property to

    54     those methods to trigger per-operation sync.

    55 

    56 

    57     @attribute autoSync

    58     @type {Boolean}

    59     @default `false`

    60     @since 3.5.0

    61     **/

    62     autoSync: {

    63         value: false,

    64         validator: YLang.isBoolean

    65     }

    66 };

    67 

    68 Y.mix(Mutable.prototype, {

    69     /**

    70     Adds the column configuration to the DataTable's `columns` configuration.

    71     If the `index` parameter is supplied, it is injected at that index.  If the

    72     table has nested headers, inject a subcolumn by passing an array of indexes

    73     to identify the new column's final location.

    74 

    75     The `index` parameter is required if adding a nested column.

    76 

    77     This method is a convienience method for fetching the DataTable's `columns`

    78     attribute, updating it, and calling

    79     `table.set('columns', _updatedColumnsDefs_)`

    80 

    81     For example:

    82 

    83     <pre><code>// Becomes last column

    84     table.addColumn('name');

    85 

    86     // Inserted after the current second column, moving the current third column

    87     // to index 4

    88     table.addColumn({ key: 'price', formatter: currencyFormatter }, 2 );

    89 

    90     // Insert a new column in a set of headers three rows deep.  The index array

    91     // translates to

    92     // [ 2, --  in the third column's children

    93     //   1, --  in the second child's children

    94     //   3 ] -- as the fourth child column

    95     table.addColumn({ key: 'age', sortable: true }, [ 2, 1, 3 ]);

    96     </code></pre>

    97 

    98     @method addColumn

    99     @param {Object|String} config The new column configuration object

   100     @param {Number|Number[]} [index] the insertion index

   101     @return {DataTable}

   102     @chainable

   103     @since 3.5.0

   104     **/

   105     addColumn: function (config, index) {

   106         if (isString(config)) {

   107             config = { key: config };

   108         }

   109 

   110         if (config) {

   111             if (arguments.length < 2 || (!isNumber(index) && !isArray(index))) {

   112                 index = this.get('columns').length;

   113             }

   114 

   115             this.fire('addColumn', {

   116                 column: config,

   117                 index: index

   118             });

   119         }

   120         return this;

   121     },

   122 

   123     /**

   124     Updates an existing column definition. Fires the `modifyColumn` event.

   125 

   126     For example:

   127 

   128     <pre><code>// Add a formatter to the existing 'price' column definition

   129     table.modifyColumn('price', { formatter: currencyFormatter });

   130 

   131     // Change the label on a header cell in a set of nested headers three rows

   132     // deep.  The index array translates to

   133     // [ 2,  -- in the third column's children

   134     //   1,  -- the second child

   135     //   3 ] -- the fourth child column

   136     table.modifyColumn([2, 1, 3], { label: 'Experience' });

   137     </code></pre>

   138 

   139     @method modifyColumn

   140     @param {String|Number|Number[]|Object} name The column key, name, index, or

   141                 current configuration object

   142     @param {Object} config The new column configuration properties

   143     @return {DataTable}

   144     @chainable

   145     @since 3.5.0

   146     **/

   147     modifyColumn: function (name, config) {

   148         if (isString(config)) {

   149             config = { key: config };

   150         }

   151 

   152         if (isObject(config)) {

   153             this.fire('modifyColumn', {

   154                 column: name,

   155                 newColumnDef: config

   156             });

   157         }

   158 

   159         return this;

   160     },

   161 

   162     /**

   163     Moves an existing column to a new location. Fires the `moveColumn` event.

   164 

   165     The destination index can be a number or array of numbers to place a column

   166     header in a nested header row.

   167 

   168     @method moveColumn

   169     @param {String|Number|Number[]|Object} name The column key, name, index, or

   170                 current configuration object

   171     @param {Number|Number[]} index The destination index of the column

   172     @return {DataTable}

   173     @chainable

   174     @since 3.5.0

   175     **/

   176     moveColumn: function (name, index) {

   177         if (name !== undefined && (isNumber(index) || isArray(index))) {

   178             this.fire('moveColumn', {

   179                 column: name,

   180                 index: index

   181             });

   182         }

   183 

   184         return this;

   185     },

   186 

   187     /**

   188     Removes an existing column. Fires the `removeColumn` event.

   189 

   190     @method removeColumn

   191     @param {String|Number|Number[]|Object} name The column key, name, index, or

   192                 current configuration object

   193     @return {DataTable}

   194     @chainable

   195     @since 3.5.0

   196     **/

   197     removeColumn: function (name) {

   198         if (name !== undefined) {

   199             this.fire('removeColumn', {

   200                 column: name

   201             });

   202         }

   203 

   204         return this;

   205     },

   206 

   207     /**

   208     Adds a new record to the DataTable's `data` ModelList.  Record data can be

   209     an object of field values or an instance of the DataTable's configured

   210     `recordType` class.

   211 

   212     This relays all parameters to the `data` ModelList's `add` method.

   213 

   214     If a configuration object is passed as a second argument, and that object

   215     has `sync: true` set, the underlying Model will be `save()`d.

   216 

   217     If the DataTable's `autoSync` attribute is set to `true`, the additional

   218     argument is not needed.

   219 

   220     If syncing and the last argument is a function, that function will be used

   221     as a callback to the Model's `save()` method.

   222 

   223     @method addRow

   224     @param {Object} data The data or Model instance for the new record

   225     @param {Object} [config] Configuration to pass along

   226     @param {Function} [callback] Callback function for Model's `save()`

   227       @param {Error|null} callback.err If an error occurred or validation

   228         failed, this parameter will contain the error. If the sync operation

   229         succeeded, _err_ will be `null`.

   230       @param {Any} callback.response The server's response. This value will

   231         be passed to the `parse()` method, which is expected to parse it and

   232         return an attribute hash.

   233     @return {DataTable}

   234     @chainable

   235     @since 3.5.0

   236     **/

   237     addRow: function (data, config) {

   238         // Allow autoSync: true + addRow({ data }, { sync: false })

   239         var sync = (config && ('sync' in config)) ?

   240                 config.sync :

   241                 this.get('autoSync'),

   242             models, model, i, len, args;

   243 

   244         if (data && this.data) {

   245             models = this.data.add.apply(this.data, arguments);

   246 

   247             if (sync) {

   248                 models = toArray(models);

   249                 args   = toArray(arguments, 1, true);

   250 

   251                 for (i = 0, len = models.length; i < len; ++i) {

   252                     model = models[i];

   253 

   254                     if (model.isNew()) {

   255                         models[i].save.apply(models[i], args);

   256                     }

   257                 }

   258             }

   259         }

   260 

   261         return this;

   262     },

   263 

   264     /**

   265     Removes a record from the DataTable's `data` ModelList.  The record can be

   266     provided explicitly or targeted by it's `id` (see ModelList's `getById`

   267     method), `clientId`, or index in the ModelList.

   268 

   269     After locating the target Model, this relays the Model and all other passed

   270     arguments to the `data` ModelList's `remove` method.

   271 

   272     If a configuration object is passed as a second argument, and that object

   273     has `sync: true` set, the underlying Model will be destroyed, passing

   274     `{ delete: true }` to trigger calling the Model's sync layer.

   275 

   276     If the DataTable's `autoSync` attribute is set to `true`, the additional

   277     argument is not needed.

   278 

   279     If syncing and the last argument is a function, that function will be used

   280     as a callback to the Model's `destroy()` method.

   281 

   282     @method removeRow

   283     @param {Object|String|Number} id The Model instance or identifier

   284     @param {Object} [config] Configuration to pass along

   285     @param {Function} [callback] Callback function for Model's `save()`

   286       @param {Error|null} callback.err If an error occurred or validation

   287         failed, this parameter will contain the error. If the sync operation

   288         succeeded, _err_ will be `null`.

   289       @param {Any} callback.response The server's response. This value will

   290         be passed to the `parse()` method, which is expected to parse it and

   291         return an attribute hash.

   292     @return {DataTable}

   293     @chainable

   294     @since 3.5.0

   295     **/

   296     removeRow: function (id, config) {

   297         var modelList = this.data,

   298             // Allow autoSync: true + addRow({ data }, { sync: false })

   299             sync      = (config && ('sync' in config)) ?

   300                             config.sync :

   301                             this.get('autoSync'),

   302             models, model, i, len, args;

   303 

   304         // TODO: support removing via DOM element. This should be relayed to View

   305         if (isObject(id) && id instanceof this.get('recordType')) {

   306             model = id;

   307         } else if (modelList && id !== undefined) {

   308             model = modelList.getById(id) ||

   309                     modelList.getByClientId(id) ||

   310                     modelList.item(id);

   311         }

   312 

   313         if (model) {

   314             args = toArray(arguments, 1, true);

   315 

   316             models = modelList.remove.apply(modelList,

   317                 [model].concat(args));

   318 

   319             if (sync) {

   320                 if (!isObject(args[0])) {

   321                     args.unshift({});

   322                 }

   323 

   324                 args[0]['delete'] = true;

   325 

   326                 models = toArray(models);

   327 

   328                 for (i = 0, len = models.length; i < len; ++i) {

   329                     model = models[i];

   330                     model.destroy.apply(model, args);

   331                 }

   332             }

   333         }

   334 

   335         return this;

   336     },

   337 

   338     /**

   339     Updates an existing record in the DataTable's `data` ModelList.  The record

   340     can be provided explicitly or targeted by it's `id` (see ModelList's

   341     `getById` method), `clientId`, or index in the ModelList.

   342 

   343     After locating the target Model, this relays the all other passed

   344     arguments to the Model's `setAttrs` method.

   345 

   346     If a configuration object is passed as a second argument, and that object

   347     has `sync: true` set, the underlying Model will be `save()`d.

   348 

   349     If the DataTable's `autoSync` attribute is set to `true`, the additional

   350     argument is not needed.

   351 

   352     If syncing and the last argument is a function, that function will be used

   353     as a callback to the Model's `save()` method.

   354 

   355     @method modifyRow

   356     @param {Object|String|Number} id The Model instance or identifier

   357     @param {Object} data New data values for the Model

   358     @param {Object} [config] Configuration to pass along to `setAttrs()`

   359     @param {Function} [callback] Callback function for Model's `save()`

   360       @param {Error|null} callback.err If an error occurred or validation

   361         failed, this parameter will contain the error. If the sync operation

   362         succeeded, _err_ will be `null`.

   363       @param {Any} callback.response The server's response. This value will

   364         be passed to the `parse()` method, which is expected to parse it and

   365         return an attribute hash.

   366     @return {DataTable}

   367     @chainable

   368     @since 3.5.0

   369     **/

   370     modifyRow: function (id, data, config) {

   371         var modelList = this.data,

   372             // Allow autoSync: true + addRow({ data }, { sync: false })

   373             sync      = (config && ('sync' in config)) ?

   374                             config.sync :

   375                             this.get('autoSync'),

   376             model, args;

   377 

   378         if (isObject(id) && id instanceof this.get('recordType')) {

   379             model = id;

   380         } else if (modelList && id !== undefined) {

   381             model = modelList.getById(id) ||

   382                     modelList.getByClientId(id) ||

   383                     modelList.item(id);

   384         }

   385 

   386         if (model && isObject(data)) {

   387             args = toArray(arguments, 1, true);

   388 

   389             model.setAttrs.apply(model, args);

   390 

   391             if (sync && !model.isNew()) {

   392                 model.save.apply(model, args);

   393             }

   394         }

   395 

   396         return this;

   397     },

   398 

   399     // --------------------------------------------------------------------------

   400     // Protected properties and methods

   401     // --------------------------------------------------------------------------

   402 

   403     /**

   404     Default function for the `addColumn` event.

   405 

   406     Inserts the specified column at the provided index.

   407 

   408     @method _defAddColumnFn

   409     @param {EventFacade} e The `addColumn` event

   410         @param {Object} e.column The new column definition object

   411         @param {Number|Number[]} e.index The array index to insert the new column

   412     @protected

   413     @since 3.5.0

   414     **/

   415     _defAddColumnFn: function (e) {

   416         var index   = toArray(e.index),

   417             columns = this.get('columns'),

   418             cols    = columns,

   419             i, len;

   420 

   421         for (i = 0, len = index.length - 1; cols && i < len; ++i) {

   422             cols = cols[index[i]] && cols[index[i]].children;

   423         }

   424 

   425         if (cols) {

   426             cols.splice(index[i], 0, e.column);

   427 

   428             this.set('columns', columns, { originEvent: e });

   429         } else { Y.log('addColumn index not findable', 'warn', 'datatable');

   430         }

   431     },

   432 

   433     /**

   434     Default function for the `modifyColumn` event.

   435 

   436     Mixes the new column properties into the specified column definition.

   437 

   438     @method _defModifyColumnFn

   439     @param {EventFacade} e The `modifyColumn` event

   440         @param {Object|String|Number|Number[]} e.column The column definition object or identifier

   441         @param {Object} e.newColumnDef The properties to assign to the column

   442     @protected

   443     @since 3.5.0

   444     **/

   445     _defModifyColumnFn: function (e) {

   446         var columns = this.get('columns'),

   447             column  = this.getColumn(e.column);

   448 

   449         if (column) {

   450             Y.mix(column, e.newColumnDef, true);

   451 

   452             this.set('columns', columns, { originEvent: e });

   453         } else { Y.log('Could not locate column index to modify column', 'warn', 'datatable');

   454         }

   455     },

   456 

   457     /**

   458     Default function for the `moveColumn` event.

   459 

   460     Removes the specified column from its current location and inserts it at the

   461     specified array index (may be an array of indexes for nested headers).

   462 

   463     @method _defMoveColumnFn

   464     @param {EventFacade} e The `moveColumn` event

   465         @param {Object|String|Number|Number[]} e.column The column definition object or identifier

   466         @param {Object} e.index The destination index to move to

   467     @protected

   468     @since 3.5.0

   469     **/

   470     _defMoveColumnFn: function (e) {

   471         var columns = this.get('columns'),

   472             column  = this.getColumn(e.column),

   473             toIndex = toArray(e.index),

   474             fromCols, fromIndex, toCols, i, len;

   475 

   476         if (column) {

   477             fromCols  = column._parent ? column._parent.children : columns;

   478             fromIndex = arrayIndex(fromCols, column);

   479 

   480             if (fromIndex > -1) {

   481                 toCols = columns;

   482 

   483                 for (i = 0, len = toIndex.length - 1; toCols && i < len; ++i) {

   484                     toCols = toCols[toIndex[i]] && toCols[toIndex[i]].children;

   485                 }

   486 

   487                 if (toCols) {

   488                     len = toCols.length;

   489                     fromCols.splice(fromIndex, 1);

   490                     toIndex = toIndex[i];

   491 

   492                     if (len > toCols.lenth) {

   493                         // spliced off the same array, so adjust destination

   494                         // index if necessary

   495                         if (fromIndex < toIndex) {

   496                             toIndex--;

   497                         }

   498                     }

   499 

   500                     toCols.splice(toIndex, 0, column);

   501 

   502                     this.set('columns', columns, { originEvent: e });

   503                 } else { Y.log('Column [' + e.column + '] could not be moved. Destination index invalid for moveColumn', 'warn', 'datatable');

   504                 }

   505             }

   506         } else { Y.log('Column [' + e.column + '] not found for moveColumn', 'warn', 'datatable');

   507         }

   508     },

   509 

   510     /**

   511     Default function for the `removeColumn` event.

   512 

   513     Splices the specified column from its containing columns array.

   514 

   515     @method _defRemoveColumnFn

   516     @param {EventFacade} e The `removeColumn` event

   517         @param {Object|String|Number|Number[]} e.column The column definition object or identifier

   518     @protected

   519     @since 3.5.0

   520     **/

   521     _defRemoveColumnFn: function (e) {

   522         var columns = this.get('columns'),

   523             column  = this.getColumn(e.column),

   524             cols, index;

   525 

   526         if (column) {

   527             cols = column._parent ? column._parent.children : columns;

   528             index = Y.Array.indexOf(cols, column);

   529 

   530             if (index > -1) {

   531                 cols.splice(index, 1);

   532 

   533                 this.set('columns', columns, { originEvent: e });

   534             }

   535         } else { Y.log('Could not locate column [' + e.column + '] for removeColumn', 'warn', 'datatable');

   536         }

   537     },

   538 

   539     /**

   540     Publishes the events used by the mutation methods:

   541 

   542      * addColumn

   543      * removeColumn

   544      * modifyColumn

   545      * moveColumn

   546 

   547     @method initializer

   548     @protected

   549     @since 3.5.0

   550     **/

   551     initializer: function () {

   552         this.publish({

   553             addColumn:    { defaultFn: Y.bind('_defAddColumnFn', this) },

   554             removeColumn: { defaultFn: Y.bind('_defRemoveColumnFn', this) },

   555             moveColumn:   { defaultFn: Y.bind('_defMoveColumnFn', this) },

   556             modifyColumn: { defaultFn: Y.bind('_defModifyColumnFn', this) }

   557         });

   558     }

   559 });

   560 

   561 /**

   562 Adds an array of new records to the DataTable's `data` ModelList.  Record data

   563 can be an array of objects containing field values or an array of instance of

   564 the DataTable's configured `recordType` class.

   565 

   566 This relays all parameters to the `data` ModelList's `add` method.

   567 

   568 Technically, this is an alias to `addRow`, but please use the appropriately

   569 named method for readability.

   570 

   571 If a configuration object is passed as a second argument, and that object

   572 has `sync: true` set, the underlying Models will be `save()`d.

   573 

   574 If the DataTable's `autoSync` attribute is set to `true`, the additional

   575 argument is not needed.

   576 

   577 If syncing and the last argument is a function, that function will be used

   578 as a callback to each Model's `save()` method.

   579 

   580 @method addRows

   581 @param {Object[]} data The data or Model instances to add

   582 @param {Object} [config] Configuration to pass along

   583 @param {Function} [callback] Callback function for each Model's `save()`

   584   @param {Error|null} callback.err If an error occurred or validation

   585     failed, this parameter will contain the error. If the sync operation

   586     succeeded, _err_ will be `null`.

   587   @param {Any} callback.response The server's response. This value will

   588     be passed to the `parse()` method, which is expected to parse it and

   589     return an attribute hash.

   590 @return {DataTable}

   591 @chainable

   592 @since 3.5.0

   593 **/

   594 Mutable.prototype.addRows = Mutable.prototype.addRow;

   595 

   596 // Add feature APIs to public Y.DataTable class

   597 if (YLang.isFunction(Y.DataTable)) {

   598     Y.Base.mix(Y.DataTable, [Mutable]);

   599 }

   600 

   601 /**

   602 Fired by the `addColumn` method.

   603 

   604 @event addColumn

   605 @preventable _defAddColumnFn

   606 @param {Object} column The new column definition object

   607 @param {Number|Number[]} index The array index to insert the new column

   608 @since 3.5.0

   609 **/

   610 

   611 /**

   612 Fired by the `removeColumn` method.

   613 

   614 @event removeColumn

   615 @preventable _defRemoveColumnFn

   616 @param {Object|String|Number|Number[]} column The column definition object or identifier

   617 @since 3.5.0

   618 **/

   619 

   620 /**

   621 Fired by the `modifyColumn` method.

   622 

   623 @event modifyColumn

   624 @preventable _defModifyColumnFn

   625 @param {Object|String|Number|Number[]} column The column definition object or identifier

   626 @param {Object} newColumnDef The properties to assign to the column

   627 @since 3.5.0

   628 **/

   629 

   630 /**

   631 Fired by the `moveColumn` method.

   632 

   633 @event moveColumn

   634 @preventable _defMoveColumnFn

   635 @param {Object|String|Number|Number[]} column The column definition object or identifier

   636 @param {Object} index The destination index to move to

   637 @since 3.5.0

   638 **/

   639 

   640 

   641 

   642 }, '3.10.3', {"requires": ["datatable-base"]});