#

API Docs for: 3.10.3
Show: Inherited Protected Private Deprecated

# File: datatable/js/mutable.js

    /**
    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
    **/