recordset.js revision 7c27e5753536379eb04779844dfe64f0f3063248
0N/A * Provides a wrapper around a standard javascript object. Can be inserted into a Recordset instance. 0N/A * Retrieve a particular (or all) values from the object 1185N/A * @param field {string} (optional) The key to retrieve the value from. If not supplied, the entire object is returned. 1340N/A * @description Unique ID of the record instance 259N/A * @description The object stored within the record instance 1185N/A * The Recordset utility provides a standard way for dealing with 1185N/A * a collection of similar objects. 1340N/A * @submodule recordset-base 345N/A * The Recordset utility provides a standard way for dealing with 0N/A * a collection of similar objects. 0N/A * Provides the base Recordset implementation, which can be extended to add 0N/A * additional functionality, such as custom indexing. sorting, and filtering. 1190N/A * @param config {Object} Configuration object literal with initial attribute values 1185N/A * @description Publish default functions for events. Create the initial hash table. 1185N/A If this._items does not exist, then create it and set it to an empty array. 1185N/A The reason the conditional is needed is because of two scenarios: 1185N/A Instantiating new Y.Recordset() will not go into the setter of "records", and so 1205N/A it is necessary to create this._items in the initializer. 1205N/A Instantiating new Y.Recordset({records: [{...}]}) will call the setter of "records" and create 1185N/A this._items. In this case, we don't want that to be overwritten by []. 1190N/A //set up event listener to fire events when recordset is modified in anyway 1185N/A //Fires recordset changed event when any updates are made to the recordset 1185N/A //Fires appropriate hashTable methods on "add", "remove", "update" and "empty" events 92N/A * @description Helper method called upon by add() - it is used to create a new record(s) in the recordset 92N/A * @return {Y.Record} A Record instance. 990N/A //index = (Lang.isNumber(index) && (index > -1)) ? index : len; 990N/A //if records are to be added one at a time, push them in one at a time 583N/A * @description Helper method called upon by remove() - it is used to remove record(s) from the recordset 1185N/A * Helper method called upon by empty() - it is used to empty the recordset 1185N/A * @description Helper method called upon by update() - it is used to update the recordset 604N/A //--------------------------------------------- 1185N/A //--------------------------------------------- 1185N/A * @description Method called whenever "recordset:add" event is fired. It adds the new record(s) to the hashtable. 1185N/A * @description Method called whenever "recordset:remove" event is fired. It removes the record(s) from the recordset. 1185N/A * @description Method called whenever "recordset:update" event is fired. It updates the record(s) by adding the new ones and removing the overwritten ones. 1185N/A //deletes the object key that held on to an overwritten record and 1185N/A //creates an object key to hold on to the updated record 1185N/A * @description Method called whenever "recordset:empty" event is fired. It empties the hash table. 604N/A * @method _defEmptyHash 1185N/A * @description Sets up the hashtable with all the records currently in the recordset 1185N/A //If it is not an empty recordset - go through and set up the hash table. 1185N/A * @description Helper method - it takes an object bag and converts it to a Y.Record 0N/A * @param obj {Object || Y.Record} Any objet literal or Y.Record instance 1185N/A * @return {Y.Record} A Record instance. 1297N/A //--------------------------------------------- 1297N/A //--------------------------------------------- 1297N/A * @description Event that is fired whenever the recordset is changed. Note that multiple simultaneous changes still fires this event once. (ie: Adding multiple records via an array will only fire this event once at the completion of all the additions) 1297N/A * @method _recordSetUpdated 1297N/A this.
on([
'update',
'add',
'remove',
'empty'],
1185N/A * @description Syncs up the private hash methods with their appropriate triggering events. 1185N/A //--------------------------------------------- 605N/A //--------------------------------------------- 1185N/A * @description Returns the record with particular ID or index 604N/A * @param i {String, Number} The ID of the record if a string, or the index if a number. 1185N/A * @return {Y.Record} An Y.Record instance 0N/A * @description Returns the record at a particular index 1185N/A * @param i {Number} Index at which the required record resides 1185N/A * @return {Y.Record} An Y.Record instance 154N/A * @description Returns a range of records beginning at particular index 154N/A * @method getRecordsByIndex 1185N/A * @param index {Number} Index at which the required record resides 0N/A * @param range {Number} (Optional) Number of records to retrieve. The default is 1 1185N/A * @return {Array} An array of Y.Record instances 1185N/A //Range cannot take on negative values 972N/A * @description Returns the length of the recordset 972N/A * @return {Number} Number of records in the recordset 972N/A * @description Returns an array of values for a specified key in the recordset 972N/A * @method getValuesByKey 972N/A * @param index {Number} (optional) Index at which the required record resides 972N/A * @return {Array} An array of values for the given key 972N/A * @description Adds one or more Records to the RecordSet at the given index. If index is null, then adds the Records to the end of the RecordSet. 1190N/A * @param oData {Y.Record, Object Literal, Array} A Y.Record instance, An object literal of data or an array of object literals 1185N/A * @param index {Number} (optional) Index at which to add the record(s) 1190N/A * @return {Y.Recordset} The updated recordset instance 1185N/A //Passing in array of object literals for oData 1185N/A * @description Removes one or more Records to the RecordSet at the given index. If index is null, then removes a single Record from the end of the RecordSet. 850N/A * @param index {Number} (optional) Index at which to remove the record(s) from 168N/A * @param range {Number} (optional) Number of records to remove (including the one at the index) 1185N/A * @return {Y.Recordset} The updated recordset instance 168N/A //Default is to only remove the last record - the length is always 1 greater than the last index 1229N/A //this._recordRemoved(remRecords, index); 1229N/A //return ({data: remRecords, index:index}); 1185N/A * @description Empties the recordset 259N/A * @return {Y.Recordset} The updated recordset instance 259N/A * @description Updates the recordset with the new records passed in. Overwrites existing records when updating the index with the new records. 0N/A * @param data {Y.Record, Object Literal, Array} A Y.Record instance, An object literal of data or an array of object literals 154N/A * @param index {Number} (optional) The index to start updating from. 0N/A * @return {Y.Recordset} The updated recordset instance 0N/A //Whatever is passed in, we are changing it to an array so that it can be easily iterated in the _defUpdateFn method 849N/A * @description An array of records that the recordset is storing 0N/A // give them a copy, not the internal object 1185N/A //For allData passed in here, see if each instance is a Record. 1190N/A //If its not, change it to a record. 1185N/A //Then push it into the array. 1185N/A //This conditional statement handles creating empty recordsets 1340N/A //initialization of the attribute must be done before the first call to get('records') is made. 1340N/A //if lazyAdd were set to true, then instantiating using new Y.Recordset({records:[..]}) would 1340N/A * @description A hash table where the ID of the record is the key, and the record instance is the value. 1340N/A //Initially, create the hash table with all records currently in the recordset 1340N/A * @description The ID to use as the key in the hash table. 1340N/A //set to readonly true. If you want custom hash tables, you should use the recordset-indexer plugin. 1185N/A * Adds default and custom sorting functionality to the Recordset utility 58N/A * @module recordset 58N/A * @submodule recordset-sort 0N/A * Plugin that adds default and custom sorting functionality to the Recordset utility 0N/A * @class RecordsetSort 1185N/A * @description The last properties used to sort. Consists of an object literal with the keys "field", "desc", and "sorter" 1185N/A * @attribute lastSortProperties 1185N/A * @description Default sort function to use if none is specified by the user. 1185N/A * Takes two records, the key to sort by, and whether sorting direction is descending or not (boolean). 1185N/A * If two records have the same value for a given key, the ID is used as the tie-breaker. 1185N/A * @description A boolean telling if the recordset is in a sorted state. 1124N/A * @description Sets up the default function to use when the "sort" event is fired. 1124N/A //Toggle the isSorted ATTR based on events. 1190N/A * @description Method that all sort calls go through. 1185N/A * Sets up the lastSortProperties object with the details of the sort, and passes in parameters 1185N/A * to the "defaultSorter" or a custom specified sort function. 1185N/A //have to work directly with _items here - changing the recordset. 1185N/A * @description Sorts the recordset. 1190N/A * @param field {string} A key to sort by. 1185N/A * @param desc {boolean} True if you want sort order to be descending, false if you want sort order to be ascending 1185N/A * @description Resorts the recordset based on the last-used sort parameters (stored in 'lastSortProperties' ATTR) 1185N/A * @description Reverses the recordset calling the standard array.reverse() method. 1185N/A * @description Sorts the recordset based on the last-used sort parameters, but flips the order. (ie: Descending becomes ascending, and vice versa). 1185N/A //If a predefined field is not provided by which to sort by, throw an error 1124N/A},
'@VERSION@' ,{
requires:[
'recordset-base',
'arraysort',
'plugin']});
1124N/A * Plugin that provides the ability to filter through a recordset. 1185N/A * Uses the filter methods available on Y.Array (see arrayextras submodule) to filter the recordset. 1124N/A * @submodule recordset-filter 1124N/A * Plugin that provides the ability to filter through a recordset. 1124N/A * Uses the filter methods available on Y.Array (see arrayextras submodule) to filter the recordset. 1185N/A * @description Filter through the recordset with a custom filter function, or a key-value pair. 1145N/A * @param f {Function, String} A custom filter function or a string representing the key to filter by. 1145N/A * @param v {any} (optional) If a string is passed into f, this represents the value that key should take in order to be accepted by the filter. Do not pass in anything if 'f' is a custom function 1145N/A * @return recordset {Y.Recordset} A new filtered recordset instance 1145N/A //If a key-value pair is passed in, generate a custom function 0N/A //TODO: PARENT CHILD RELATIONSHIP //return new host.constructor({records:arr}); * @description The inverse of filter. Executes the supplied function on each item. Returns a new Recordset containing the items that the supplied function returned *false* for. * @param {Function} f is the function to execute on each item. * @return {Y.Recordset} A new Recordset instance containing the items on which the supplied function returned false. * @description Iterates over the Recordset, returning a new Recordset of all the elements that match the supplied regular expression * @param {pattern} pattern The regular expression to test against * @return {Y.Recordset} A Recordset instance containing all the items in the collection that produce a match against the supplied regular expression. If no items match, an empty Recordset instance is returned. //TODO: Add more pass-through methods to arrayextras },
'@VERSION@' ,{
requires:[
'recordset-base',
'plugin',
'array-extras']});
YUI.
add(
'recordset-indexer',
function(Y) {
* Provides the ability to store multiple custom hash tables referencing records in the recordset. * @submodule recordset-indexer * Plugin that provides the ability to store multiple custom hash tables referencing records in the recordset. * This utility does not support any collision handling. New hash table entries with a used key overwrite older ones. * @class RecordsetIndexer NAME:
"recordsetIndexer",
* @description Collection of all the hashTables created by the plugin. * The individual tables can be accessed by the key they are hashing against. //setup listeners on recordset events * @description Setup the hash table for a given key with all existing records in the recordset * @param key {string} A key to hash by. * @return obj {object} The created hash table //--------------------------------------------- //--------------------------------------------- * @description Updates all hash tables when a record is added to the recordset var tbl =
this.
get(
'hashTables');
//Go through every hashtable that is stored. //in each hashtable, look to see if the key is represented in the object being added. //if the object being added has a key which is being stored by hashtable v, add it into the table. * @description Updates all hash tables when a record is removed from the recordset var tbl =
this.
get(
'hashTables'),
//Go through every hashtable that is stored. //in each hashtable, look to see if the key is represented in the object being deleted. //if the hashtable has a key storing a record, and the key and the record both match the record being deleted, delete that row from the hashtable * @description Updates all hash tables when the recordset is updated (a combination of add and remove) //TODO: It will be more performant to create a new method rather than using _defAddHash, _defRemoveHash, due to the number of loops. See commented code. var tbl = this.get('hashTables'), reckey; Y.each(tbl, function(v, key) { Y.each(e.updated, function(o, i) { //delete record from hashtable if it has been overwritten reckey = o.getValue(key); //the undefined case is if more records are updated than currently exist in the recordset. if (e.overwritten[i] && (v[e.overwritten[i].getValue(key)] === e.overwritten[i])) { delete v[e.overwritten[i].getValue(key)]; // if (v[reckey] === o) { // //add the new updated record if it has a key that corresponds to a hash table // if (o.getValue(key)) { // v[o.getValue(key)] = o; //--------------------------------------------- //--------------------------------------------- * @description Creates a new hash table. * @param key {string} A key to hash by. * @return tbls[key] {object} The created hash table * @description Get a hash table that hashes records by a given key. * @param key {string} A key to hash by. * @return table {object} The created hash table return this.
get(
'hashTables')[
key];
},
'@VERSION@' ,{
requires:[
'recordset-base',
'plugin']});
YUI.
add(
'recordset',
function(Y){},
'@VERSION@' ,{
use:[
'recordset-base',
'recordset-sort',
'recordset-filter',
'recordset-indexer']});