text: /**
  Adds mutation convenience methods such as `table.addRow(data)` to `Y.DataTable`. (or other built class).
  
  @module datatable
  @submodule datatable-mutable
  @since 3.5.0
  **/
  var toArray = Y.Array,
      YLang   = Y.Lang,
      isString = YLang.isString,
      isArray  = YLang.isArray,
      isObject = YLang.isObject,
      isNumber = YLang.isNumber,
      arrayIndex = Y.Array.indexOf,
      Mutable;
  
  /**
  _API docs for this extension are included in the DataTable class._
  
  Class extension to add mutation convenience methods to `Y.DataTable` (or other
  built class).
  
  Column mutation methods are paired with new custom events:
  
   * addColumn
   * removeColumn
   * modifyColumn
   * moveColumn
  
  Row mutation events are bubbled from the DataTable's `data` ModelList through
  the DataTable instance.
  
  @class DataTable.Mutable
  @for DataTable
  @since 3.5.0
  **/
  Y.namespace('DataTable').Mutable = Mutable = function () {};
  
  Mutable.ATTRS = {
      /**
      Controls whether `addRow`, `removeRow`, and `modifyRow` should trigger the
      underlying Model's sync layer by default.
  
      When `true`, it is unnecessary to pass the "sync" configuration property to
      those methods to trigger per-operation sync.
  
  
      @attribute autoSync
      @type {Boolean}
      @default `false`
      @since 3.5.0
      **/
      autoSync: {
          value: false,
          validator: YLang.isBoolean
      }
  };
  
  Y.mix(Mutable.prototype, {
      /**
      Adds the column configuration to the DataTable's `columns` configuration.
      If the `index` parameter is supplied, it is injected at that index.  If the
      table has nested headers, inject a subcolumn by passing an array of indexes
      to identify the new column's final location.
  
      The `index` parameter is required if adding a nested column.
  
      This method is a convienience method for fetching the DataTable's `columns`
      attribute, updating it, and calling
      `table.set('columns', _updatedColumnsDefs_)`
  
      For example:
  
      <pre><code>// Becomes last column
      table.addColumn('name');
  
      // Inserted after the current second column, moving the current third column
      // to index 4
      table.addColumn({ key: 'price', formatter: currencyFormatter }, 2 );
  
      // Insert a new column in a set of headers three rows deep.  The index array
      // translates to
      // [ 2, --  in the third column's children
      //   1, --  in the second child's children
      //   3 ] -- as the fourth child column
      table.addColumn({ key: 'age', sortable: true }, [ 2, 1, 3 ]);
      </code></pre>
  
      @method addColumn
      @param {Object|String} config The new column configuration object
      @param {Number|Number[]} [index] the insertion index
      @return {DataTable}
      @chainable
      @since 3.5.0
      **/
      addColumn: function (config, index) {
          if (isString(config)) {
              config = { key: config };
          }
  
          if (config) {
              if (arguments.length < 2 || (!isNumber(index) && !isArray(index))) {
                  index = this.get('columns').length;
              }
  
              this.fire('addColumn', {
                  column: config,
                  index: index
              });
          }
          return this;
      },
  
      /**
      Updates an existing column definition. Fires the `modifyColumn` event.
  
      For example:
  
      <pre><code>// Add a formatter to the existing 'price' column definition
      table.modifyColumn('price', { formatter: currencyFormatter });
  
      // Change the label on a header cell in a set of nested headers three rows
      // deep.  The index array translates to
      // [ 2,  -- in the third column's children
      //   1,  -- the second child
      //   3 ] -- the fourth child column
      table.modifyColumn([2, 1, 3], { label: 'Experience' });
      </code></pre>
  
      @method modifyColumn
      @param {String|Number|Number[]|Object} name The column key, name, index, or
                  current configuration object
      @param {Object} config The new column configuration properties
      @return {DataTable}
      @chainable
      @since 3.5.0
      **/
      modifyColumn: function (name, config) {
          if (isString(config)) {
              config = { key: config };
          }
  
          if (isObject(config)) {
              this.fire('modifyColumn', {
                  column: name,
                  newColumnDef: config
              });
          }
  
          return this;
      },
  
      /**
      Moves an existing column to a new location. Fires the `moveColumn` event.
  
      The destination index can be a number or array of numbers to place a column
      header in a nested header row.
  
      @method moveColumn
      @param {String|Number|Number[]|Object} name The column key, name, index, or
                  current configuration object
      @param {Number|Number[]} index The destination index of the column
      @return {DataTable}
      @chainable
      @since 3.5.0
      **/
      moveColumn: function (name, index) {
          if (name !== undefined && (isNumber(index) || isArray(index))) {
              this.fire('moveColumn', {
                  column: name,
                  index: index
              });
          }
  
          return this;
      },
  
      /**
      Removes an existing column. Fires the `removeColumn` event.
  
      @method removeColumn
      @param {String|Number|Number[]|Object} name The column key, name, index, or
                  current configuration object
      @return {DataTable}
      @chainable
      @since 3.5.0
      **/
      removeColumn: function (name) {
          if (name !== undefined) {
              this.fire('removeColumn', {
                  column: name
              });
          }
  
          return this;
      },
  
      /**
      Adds a new record to the DataTable's `data` ModelList.  Record data can be
      an object of field values or an instance of the DataTable's configured
      `recordType` class.
  
      This relays all parameters to the `data` ModelList's `add` method.
  
      If a configuration object is passed as a second argument, and that object
      has `sync: true` set, the underlying Model will be `save()`d.
  
      If the DataTable's `autoSync` attribute is set to `true`, the additional
      argument is not needed.
  
      If syncing and the last argument is a function, that function will be used
      as a callback to the Model's `save()` method.
  
      @method addRow
      @param {Object} data The data or Model instance for the new record
      @param {Object} [config] Configuration to pass along
      @param {Function} [callback] Callback function for Model's `save()`
        @param {Error|null} callback.err If an error occurred or validation
          failed, this parameter will contain the error. If the sync operation
          succeeded, _err_ will be `null`.
        @param {Any} callback.response The server's response. This value will
          be passed to the `parse()` method, which is expected to parse it and
          return an attribute hash.
      @return {DataTable}
      @chainable
      @since 3.5.0
      **/
      addRow: function (data, config) {
          // Allow autoSync: true + addRow({ data }, { sync: false })
          var sync = (config && ('sync' in config)) ?
                  config.sync :
                  this.get('autoSync'),
              models, model, i, len, args;
  
          if (data && this.data) {
              models = this.data.add.apply(this.data, arguments);
  
              if (sync) {
                  models = toArray(models);
                  args   = toArray(arguments, 1, true);
  
                  for (i = 0, len = models.length; i < len; ++i) {
                      model = models[i];
  
                      if (model.isNew()) {
                          models[i].save.apply(models[i], args);
                      }
                  }
              }
          }
  
          return this;
      },
  
      /**
      Removes a record from the DataTable's `data` ModelList.  The record can be
      provided explicitly or targeted by it's `id` (see ModelList's `getById`
      method), `clientId`, or index in the ModelList.
  
      After locating the target Model, this relays the Model and all other passed
      arguments to the `data` ModelList's `remove` method.
  
      If a configuration object is passed as a second argument, and that object
      has `sync: true` set, the underlying Model will be destroyed, passing
      `{ delete: true }` to trigger calling the Model's sync layer.
  
      If the DataTable's `autoSync` attribute is set to `true`, the additional
      argument is not needed.
  
      If syncing and the last argument is a function, that function will be used
      as a callback to the Model's `destroy()` method.
  
      @method removeRow
      @param {Object|String|Number} id The Model instance or identifier
      @param {Object} [config] Configuration to pass along
      @param {Function} [callback] Callback function for Model's `save()`
        @param {Error|null} callback.err If an error occurred or validation
          failed, this parameter will contain the error. If the sync operation
          succeeded, _err_ will be `null`.
        @param {Any} callback.response The server's response. This value will
          be passed to the `parse()` method, which is expected to parse it and
          return an attribute hash.
      @return {DataTable}
      @chainable
      @since 3.5.0
      **/
      removeRow: function (id, config) {
          var modelList = this.data,
              // Allow autoSync: true + addRow({ data }, { sync: false })
              sync      = (config && ('sync' in config)) ?
                              config.sync :
                              this.get('autoSync'),
              models, model, i, len, args;
  
          // TODO: support removing via DOM element. This should be relayed to View
          if (isObject(id) && id instanceof this.get('recordType')) {
              model = id;
          } else if (modelList && id !== undefined) {
              model = modelList.getById(id) ||
                      modelList.getByClientId(id) ||
                      modelList.item(id);
          }
  
          if (model) {
              args = toArray(arguments, 1, true);
  
              models = modelList.remove.apply(modelList,
                  [model].concat(args));
  
              if (sync) {
                  if (!isObject(args[0])) {
                      args.unshift({});
                  }
  
                  args[0]['delete'] = true;
  
                  models = toArray(models);
  
                  for (i = 0, len = models.length; i < len; ++i) {
                      model = models[i];
                      model.destroy.apply(model, args);
                  }
              }
          }
  
          return this;
      },
  
      /**
      Updates an existing record in the DataTable's `data` ModelList.  The record
      can be provided explicitly or targeted by it's `id` (see ModelList's
      `getById` method), `clientId`, or index in the ModelList.
  
      After locating the target Model, this relays the all other passed
      arguments to the Model's `setAttrs` method.
  
      If a configuration object is passed as a second argument, and that object
      has `sync: true` set, the underlying Model will be `save()`d.
  
      If the DataTable's `autoSync` attribute is set to `true`, the additional
      argument is not needed.
  
      If syncing and the last argument is a function, that function will be used
      as a callback to the Model's `save()` method.
  
      @method modifyRow
      @param {Object|String|Number} id The Model instance or identifier
      @param {Object} data New data values for the Model
      @param {Object} [config] Configuration to pass along to `setAttrs()`
      @param {Function} [callback] Callback function for Model's `save()`
        @param {Error|null} callback.err If an error occurred or validation
          failed, this parameter will contain the error. If the sync operation
          succeeded, _err_ will be `null`.
        @param {Any} callback.response The server's response. This value will
          be passed to the `parse()` method, which is expected to parse it and
          return an attribute hash.
      @return {DataTable}
      @chainable
      @since 3.5.0
      **/
      modifyRow: function (id, data, config) {
          var modelList = this.data,
              // Allow autoSync: true + addRow({ data }, { sync: false })
              sync      = (config && ('sync' in config)) ?
                              config.sync :
                              this.get('autoSync'),
              model, args;
  
          if (isObject(id) && id instanceof this.get('recordType')) {
              model = id;
          } else if (modelList && id !== undefined) {
              model = modelList.getById(id) ||
                      modelList.getByClientId(id) ||
                      modelList.item(id);
          }
  
          if (model && isObject(data)) {
              args = toArray(arguments, 1, true);
  
              model.setAttrs.apply(model, args);
  
              if (sync && !model.isNew()) {
                  model.save.apply(model, args);
              }
          }
  
          return this;
      },
  
      // --------------------------------------------------------------------------
      // Protected properties and methods
      // --------------------------------------------------------------------------
  
      /**
      Default function for the `addColumn` event.
  
      Inserts the specified column at the provided index.
  
      @method _defAddColumnFn
      @param {EventFacade} e The `addColumn` event
          @param {Object} e.column The new column definition object
          @param {Number|Number[]} e.index The array index to insert the new column
      @protected
      @since 3.5.0
      **/
      _defAddColumnFn: function (e) {
          var index   = toArray(e.index),
              columns = this.get('columns'),
              cols    = columns,
              i, len;
  
          for (i = 0, len = index.length - 1; cols && i < len; ++i) {
              cols = cols[index[i]] && cols[index[i]].children;
          }
  
          if (cols) {
              cols.splice(index[i], 0, e.column);
  
              this.set('columns', columns, { originEvent: e });
          } else { Y.log('addColumn index not findable', 'warn', 'datatable');
          }
      },
  
      /**
      Default function for the `modifyColumn` event.
  
      Mixes the new column properties into the specified column definition.
  
      @method _defModifyColumnFn
      @param {EventFacade} e The `modifyColumn` event
          @param {Object|String|Number|Number[]} e.column The column definition object or identifier
          @param {Object} e.newColumnDef The properties to assign to the column
      @protected
      @since 3.5.0
      **/
      _defModifyColumnFn: function (e) {
          var columns = this.get('columns'),
              column  = this.getColumn(e.column);
  
          if (column) {
              Y.mix(column, e.newColumnDef, true);
  
              this.set('columns', columns, { originEvent: e });
          } else { Y.log('Could not locate column index to modify column', 'warn', 'datatable');
          }
      },
  
      /**
      Default function for the `moveColumn` event.
  
      Removes the specified column from its current location and inserts it at the
      specified array index (may be an array of indexes for nested headers).
  
      @method _defMoveColumnFn
      @param {EventFacade} e The `moveColumn` event
          @param {Object|String|Number|Number[]} e.column The column definition object or identifier
          @param {Object} e.index The destination index to move to
      @protected
      @since 3.5.0
      **/
      _defMoveColumnFn: function (e) {
          var columns = this.get('columns'),
              column  = this.getColumn(e.column),
              toIndex = toArray(e.index),
              fromCols, fromIndex, toCols, i, len;
  
          if (column) {
              fromCols  = column._parent ? column._parent.children : columns;
              fromIndex = arrayIndex(fromCols, column);
  
              if (fromIndex > -1) {
                  toCols = columns;
  
                  for (i = 0, len = toIndex.length - 1; toCols && i < len; ++i) {
                      toCols = toCols[toIndex[i]] && toCols[toIndex[i]].children;
                  }
  
                  if (toCols) {
                      len = toCols.length;
                      fromCols.splice(fromIndex, 1);
                      toIndex = toIndex[i];
  
                      if (len > toCols.lenth) {
                          // spliced off the same array, so adjust destination
                          // index if necessary
                          if (fromIndex < toIndex) {
                              toIndex--;
                          }
                      }
  
                      toCols.splice(toIndex, 0, column);
  
                      this.set('columns', columns, { originEvent: e });
                  } else { Y.log('Column [' + e.column + '] could not be moved. Destination index invalid for moveColumn', 'warn', 'datatable');
                  }
              }
          } else { Y.log('Column [' + e.column + '] not found for moveColumn', 'warn', 'datatable');
          }
      },
  
      /**
      Default function for the `removeColumn` event.
  
      Splices the specified column from its containing columns array.
  
      @method _defRemoveColumnFn
      @param {EventFacade} e The `removeColumn` event
          @param {Object|String|Number|Number[]} e.column The column definition object or identifier
      @protected
      @since 3.5.0
      **/
      _defRemoveColumnFn: function (e) {
          var columns = this.get('columns'),
              column  = this.getColumn(e.column),
              cols, index;
  
          if (column) {
              cols = column._parent ? column._parent.children : columns;
              index = Y.Array.indexOf(cols, column);
  
              if (index > -1) {
                  cols.splice(index, 1);
  
                  this.set('columns', columns, { originEvent: e });
              }
          } else { Y.log('Could not locate column [' + e.column + '] for removeColumn', 'warn', 'datatable');
          }
      },
  
      /**
      Publishes the events used by the mutation methods:
  
       * addColumn
       * removeColumn
       * modifyColumn
       * moveColumn
  
      @method initializer
      @protected
      @since 3.5.0
      **/
      initializer: function () {
          this.publish({
              addColumn:    { defaultFn: Y.bind('_defAddColumnFn', this) },
              removeColumn: { defaultFn: Y.bind('_defRemoveColumnFn', this) },
              moveColumn:   { defaultFn: Y.bind('_defMoveColumnFn', this) },
              modifyColumn: { defaultFn: Y.bind('_defModifyColumnFn', this) }
          });
      }
  });
  
  /**
  Adds an array of new records to the DataTable's `data` ModelList.  Record data
  can be an array of objects containing field values or an array of instance of
  the DataTable's configured `recordType` class.
  
  This relays all parameters to the `data` ModelList's `add` method.
  
  Technically, this is an alias to `addRow`, but please use the appropriately
  named method for readability.
  
  If a configuration object is passed as a second argument, and that object
  has `sync: true` set, the underlying Models will be `save()`d.
  
  If the DataTable's `autoSync` attribute is set to `true`, the additional
  argument is not needed.
  
  If syncing and the last argument is a function, that function will be used
  as a callback to each Model's `save()` method.
  
  @method addRows
  @param {Object[]} data The data or Model instances to add
  @param {Object} [config] Configuration to pass along
  @param {Function} [callback] Callback function for each Model's `save()`
    @param {Error|null} callback.err If an error occurred or validation
      failed, this parameter will contain the error. If the sync operation
      succeeded, _err_ will be `null`.
    @param {Any} callback.response The server's response. This value will
      be passed to the `parse()` method, which is expected to parse it and
      return an attribute hash.
  @return {DataTable}
  @chainable
  @since 3.5.0
  **/
  Mutable.prototype.addRows = Mutable.prototype.addRow;
  
  // Add feature APIs to public Y.DataTable class
  if (YLang.isFunction(Y.DataTable)) {
      Y.Base.mix(Y.DataTable, [Mutable]);
  }
  
  /**
  Fired by the `addColumn` method.
  
  @event addColumn
  @preventable _defAddColumnFn
  @param {Object} column The new column definition object
  @param {Number|Number[]} index The array index to insert the new column
  @since 3.5.0
  **/
  
  /**
  Fired by the `removeColumn` method.
  
  @event removeColumn
  @preventable _defRemoveColumnFn
  @param {Object|String|Number|Number[]} column The column definition object or identifier
  @since 3.5.0
  **/
  
  /**
  Fired by the `modifyColumn` method.
  
  @event modifyColumn
  @preventable _defModifyColumnFn
  @param {Object|String|Number|Number[]} column The column definition object or identifier
  @param {Object} newColumnDef The properties to assign to the column
  @since 3.5.0
  **/
  
  /**
  Fired by the `moveColumn` method.
  
  @event moveColumn
  @preventable _defMoveColumnFn
  @param {Object|String|Number|Number[]} column The column definition object or identifier
  @param {Object} index The destination index to move to
  @since 3.5.0
  **/
  
  