mutable.js revision 53c97f474022b2633bdeccab063f518c4015f27a
/**
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,
arrayIndex = Y.Array.indexOf,
/**
_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
**/
/**
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,
}
};
/**
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
**/
}
if (config) {
}
this.fire('addColumn', {
});
}
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
**/
}
this.fire('modifyColumn', {
});
}
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
**/
this.fire('moveColumn', {
});
}
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) {
this.fire('removeColumn', {
});
}
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
**/
// Allow autoSync: true + addRow({ data }, { sync: false })
this.get('autoSync'),
if (sync) {
}
}
}
}
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
**/
// Allow autoSync: true + addRow({ data }, { sync: false })
this.get('autoSync'),
// TODO: support removing via DOM element. This should be relayed to View
}
if (model) {
if (sync) {
}
}
}
}
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
**/
// Allow autoSync: true + addRow({ data }, { sync: false })
this.get('autoSync'),
}
}
}
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) {
i, len;
}
if (cols) {
}
},
/**
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) {
if (column) {
}
},
/**
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) {
if (column) {
if (fromIndex > -1) {
}
if (toCols) {
// spliced off the same array, so adjust destination
// index if necessary
toIndex--;
}
}
} else { Y.log('Column [' + e.column + '] could not be moved. Destination index invalid 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) {
if (column) {
if (index > -1) {
}
}
},
/**
Publishes the events used by the mutation methods:
* addColumn
* removeColumn
* modifyColumn
* moveColumn
@method initializer
@protected
@since 3.5.0
**/
initializer: function () {
this.publish({
});
}
});
/**
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
**/
// Add feature APIs to public Y.DataTable class
}
/**
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
**/