lib/yuilib/3.13.0/datatable-mutable/datatable-mutable.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-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         }
 430     },
 431
 432     /**
 433     Default function for the `modifyColumn` event.
 434
 435     Mixes the new column properties into the specified column definition.
 436
 437     @method _defModifyColumnFn
 438     @param {EventFacade} e The `modifyColumn` event
 439         @param {Object|String|Number|Number[]} e.column The column definition object or identifier
 440         @param {Object} e.newColumnDef The properties to assign to the column
 441     @protected
 442     @since 3.5.0
 443     **/
 444     _defModifyColumnFn: function (e) {
 445         var columns = this.get('columns'),
 446             column  = this.getColumn(e.column);
 447
 448         if (column) {
 449             Y.mix(column, e.newColumnDef, true);
 450
 451             this.set('columns', columns, { originEvent: e });
 452         }
 453     },
 454
 455     /**
 456     Default function for the `moveColumn` event.
 457
 458     Removes the specified column from its current location and inserts it at the
 459     specified array index (may be an array of indexes for nested headers).
 460
 461     @method _defMoveColumnFn
 462     @param {EventFacade} e The `moveColumn` event
 463         @param {Object|String|Number|Number[]} e.column The column definition object or identifier
 464         @param {Object} e.index The destination index to move to
 465     @protected
 466     @since 3.5.0
 467     **/
 468     _defMoveColumnFn: function (e) {
 469         var columns = this.get('columns'),
 470             column  = this.getColumn(e.column),
 471             toIndex = toArray(e.index),
 472             fromCols, fromIndex, toCols, i, len;
 473
 474         if (column) {
 475             fromCols  = column._parent ? column._parent.children : columns;
 476             fromIndex = arrayIndex(fromCols, column);
 477
 478             if (fromIndex > -1) {
 479                 toCols = columns;
 480
 481                 for (i = 0, len = toIndex.length - 1; toCols && i < len; ++i) {
 482                     toCols = toCols[toIndex[i]] && toCols[toIndex[i]].children;
 483                 }
 484
 485                 if (toCols) {
 486                     len = toCols.length;
 487                     fromCols.splice(fromIndex, 1);
 488                     toIndex = toIndex[i];
 489
 490                     if (len > toCols.lenth) {
 491                         // spliced off the same array, so adjust destination
 492                         // index if necessary
 493                         if (fromIndex < toIndex) {
 494                             toIndex--;
 495                         }
 496                     }
 497
 498                     toCols.splice(toIndex, 0, column);
 499
 500                     this.set('columns', columns, { originEvent: e });
 501                 }
 502             }
 503         }
 504     },
 505
 506     /**
 507     Default function for the `removeColumn` event.
 508
 509     Splices the specified column from its containing columns array.
 510
 511     @method _defRemoveColumnFn
 512     @param {EventFacade} e The `removeColumn` event
 513         @param {Object|String|Number|Number[]} e.column The column definition object or identifier
 514     @protected
 515     @since 3.5.0
 516     **/
 517     _defRemoveColumnFn: function (e) {
 518         var columns = this.get('columns'),
 519             column  = this.getColumn(e.column),
 520             cols, index;
 521
 522         if (column) {
 523             cols = column._parent ? column._parent.children : columns;
 524             index = Y.Array.indexOf(cols, column);
 525
 526             if (index > -1) {
 527                 cols.splice(index, 1);
 528
 529                 this.set('columns', columns, { originEvent: e });
 530             }
 531         }
 532     },
 533
 534     /**
 535     Publishes the events used by the mutation methods:
 536
 537      * addColumn
 538      * removeColumn
 539      * modifyColumn
 540      * moveColumn
 541
 542     @method initializer
 543     @protected
 544     @since 3.5.0
 545     **/
 546     initializer: function () {
 547         this.publish({
 548             addColumn:    { defaultFn: Y.bind('_defAddColumnFn', this) },
 549             removeColumn: { defaultFn: Y.bind('_defRemoveColumnFn', this) },
 550             moveColumn:   { defaultFn: Y.bind('_defMoveColumnFn', this) },
 551             modifyColumn: { defaultFn: Y.bind('_defModifyColumnFn', this) }
 552         });
 553     }
 554 });
 555
 556 /**
 557 Adds an array of new records to the DataTable's `data` ModelList.  Record data
 558 can be an array of objects containing field values or an array of instance of
 559 the DataTable's configured `recordType` class.
 560
 561 This relays all parameters to the `data` ModelList's `add` method.
 562
 563 Technically, this is an alias to `addRow`, but please use the appropriately
 564 named method for readability.
 565
 566 If a configuration object is passed as a second argument, and that object
 567 has `sync: true` set, the underlying Models will be `save()`d.
 568
 569 If the DataTable's `autoSync` attribute is set to `true`, the additional
 570 argument is not needed.
 571
 572 If syncing and the last argument is a function, that function will be used
 573 as a callback to each Model's `save()` method.
 574
 575 @method addRows
 576 @param {Object[]} data The data or Model instances to add
 577 @param {Object} [config] Configuration to pass along
 578 @param {Function} [callback] Callback function for each Model's `save()`
 579   @param {Error|null} callback.err If an error occurred or validation
 580     failed, this parameter will contain the error. If the sync operation
 581     succeeded, _err_ will be `null`.
 582   @param {Any} callback.response The server's response. This value will
 583     be passed to the `parse()` method, which is expected to parse it and
 584     return an attribute hash.
 585 @return {DataTable}
 586 @chainable
 587 @since 3.5.0
 588 **/
 589 Mutable.prototype.addRows = Mutable.prototype.addRow;
 590
 591 // Add feature APIs to public Y.DataTable class
 592 if (YLang.isFunction(Y.DataTable)) {
 593     Y.Base.mix(Y.DataTable, [Mutable]);
 594 }
 595
 596 /**
 597 Fired by the `addColumn` method.
 598
 599 @event addColumn
 600 @preventable _defAddColumnFn
 601 @param {Object} column The new column definition object
 602 @param {Number|Number[]} index The array index to insert the new column
 603 @since 3.5.0
 604 **/
 605
 606 /**
 607 Fired by the `removeColumn` method.
 608
 609 @event removeColumn
 610 @preventable _defRemoveColumnFn
 611 @param {Object|String|Number|Number[]} column The column definition object or identifier
 612 @since 3.5.0
 613 **/
 614
 615 /**
 616 Fired by the `modifyColumn` method.
 617
 618 @event modifyColumn
 619 @preventable _defModifyColumnFn
 620 @param {Object|String|Number|Number[]} column The column definition object or identifier
 621 @param {Object} newColumnDef The properties to assign to the column
 622 @since 3.5.0
 623 **/
 624
 625 /**
 626 Fired by the `moveColumn` method.
 627
 628 @event moveColumn
 629 @preventable _defMoveColumnFn
 630 @param {Object|String|Number|Number[]} column The column definition object or identifier
 631 @param {Object} index The destination index to move to
 632 @since 3.5.0
 633 **/
 634
 635
 636
 637 }, '3.13.0', {"requires": ["datatable-base"]});