[Summary view] [Print] [Text view]

   1  /*
   2  YUI 3.17.2 (build 9c3c78e)
   3  Copyright 2014 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.17.2', {"requires": ["datatable-base"]});