lib/yuilib/3.13.0/datatable-mutable/datatable-mutable-debug.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         } 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.13.0', {"requires": ["datatable-base"]});