The Spry.Data.DataSet class is the base class from which all other data sets derive from. The Spry.Data.DataSet class provides basic functionality for maintaining an array of row objects, destructive and non-destructive filtering, and sorting.
The Spry.Data.DataSet class derives from Spry.Utils.Notifier so it can also dispatch notifications.
Notifier --> DataSet
Spry.Data.DataSet is the constructor function for the Data Set. The constructor takes an optional single argument, which is an object that specifies the initial options for the Data Set.
Spry.Data.DataSet(options)
N/A
// An example of creating a data set with no options specified:
var ds1 = new Spry.Data.DataSet();
// An example of creating a data set with some options defined:
var ds2 = new Spry.Data.DataSet({ sortOnLoad: "firstname", sortOrderOnLoad: "descending" });
Only some methods can be called directly after the data set constructor. Some methods depend on the data being loaded to run. The list below can be called directly after the constructor:
All others should be used after the data is finished loading, via called functions or observers.
N/A
This function cancels the loading of the data set data. This is will interrupt any requests made by the loadData() function. This function is also called internally by loadData() before making another request for data.
cancelLoadData()
N/A
N/A
var ds = new Spry.Data.DataSet(); ... ds.loadData(); ... ds.cancelLoadData();
This function is used to remove duplicate rows from the data set. The distinct function will evaluate all the columns and if it finds 2 or more rows where every value is the same, it will throw away the duplicate rows and keep only one. This function can only be called *after* the data has been loaded into the data set.
Distinct can also be run automatically whenever new data is loaded into the data set. This is done by specifying the distinctOnLoad constructor option. In case the distinct functionality is need only for specific column(s) they may be defined through the additional parameter distinctFieldsOnLoad.
distinct(columnNames)
columnNames - String or Array. The column(s) of the data set to use when determining if a row is distinct. This parameter is optional. If ommited, all columns are used to determine if a row is distinct or not. If specified, must be a string that is the name of the column to use for the distinct process, or, must be an array of column names to used for the distinct process.
N/A
/* After a data set is defined and loaded with data, you can call
* distinct on it.
*/
var ds1 = Spry.Data.XMLDataSet("xml.xml","xpath");
...
ds1.distinct();
/* Run distinct automatically whenever data is loaded. */
var ds2 = Spry.Data.XMLDataSet("xml.xml","xpath", {distinctOnLoad: true, distinctFieldsOnLoad:['fld1', 'fld2']});
This function is used to non-destructively filter the data set based on a filter function provided by the caller. The filter function passed in must have the following interface:
function myFilterFunc(ds, row, rowIndex)
{
...
}
The arguments to this function are as follows:
The caller's filter function is called once for each row in the data set. If the caller's filter function wishes to add the row to the filtered view of the data set, then it must return the row object passed into the function. If it does not want the row to be in the filtered view of the data set, then it must return null.
As previously mentioned, this filtering is done non-destructively so internally, the data set is using the function to determine if it should add a row to a copy of the row array.
The caller's filter function remains active until it is removed. The filter function can be removed by calling filter with a null value instead of a function reference.
After filtering, a call to the getData function will return the filtered array of rows. To get the unfiltered array of rows, you must call getData, passing in a true for the unfiltered argument.
FilterData is the destructive filter, which actually throws out the filtered data from memory.
datasetname.filter(filterFunction);
filterFunction - Function Reference. The function to use to determine if a row should be filtered out or not.
N/A
var myFilterFunc = function(dataSet, row, rowNumber)
{
// Filter out all rows with paths that begin
// with the letter 's'.
if (row["@path"].search(/^s/) != -1)
return row; // Return the row to keep it in the data set.
return null; // Return null to remove the row from the data set.
}
// Filter the data.
dsPhotos.filter(myFilterFunc);
...
// Remove the filter.
dsPhotos.filter(null);
This function is used to filter the data set based on a filter function provided by the caller. filterData is a destructive method, which means that all rows that are discarded by the filtering is lost. The data can only be retrieved again by loading the data back into the data set again.
The filter function passed in must have the following interface:
function myFilterFunc(ds, row, rowIndex)
{
...
}
The arguments to this function are as follows:
The caller's filter function is called once for each row in the data set. If the caller's filter function wishes to keep the row, then it must return the row object passed into the function. If it does not want to keep the row, then it must return null.
As previously mentioned, this filtering is destructive so internally, the data set is modifying its only copy of the row array.
The caller's filter function remains active until it is removed, so if the data set is reloaded, the filtering will occur. The filter function can be removed by calling filter with a null value instead of a function reference.
filter is the non-destructive version of this function.
datasetname.filterData(filterFunction);
filterFunction - Function Reference. The function to use to determine if a row should be kept or discarded.
N/A
var myFilterFunc = function(dataSet, row, rowNumber)
{
// Filter out all rows with paths that begin
// with the letter 's'.
if (row["@path"].search(/^s/) != -1)
return row; // Return the row to keep it in the data set.
return null; // Return null to remove the row from the data set.
}
// Filter the data.
dsPhotos.filterData(myFilterFunc);
...
// Remove the filter.
dsPhotos.filterData(null);
N/A
Finds all rows within the data set that have the same column values contained in the specified object.
findRowsWithColumnValues(valueObj, firstMatchOnly, unfiltered)
valueObj - Object. Object containing the names of the columns and their values which each row must contain to be considered a match.
firstMatchOnly - Boolean. Optional argument. If true, causes the function to return the row object that first matched the values specified in valueObj. If not match was found, returns null.
unfiltered - Boolean. Optional argument. If true the function does its find through the unfiltered set of rows within the data set. If false or undefined, the find is done through the filtered set of rows.
The value returned by this function depends on the value of the firstMatchOnly argument. If firstMatchOnly is true, the function will return either the first row object that matches, or null. If firstMatchOnly is false or undefined, the function will return an array of all matches. This array may be empty (length == 0) if no matches were found.
var ds = new Spry.Data.DataSet();
..
// Look for all rows that have a column called "color" with a value of "red"
// and a column called "type" with a value of "sports".
var matchingRows = ds.findRowsWithColumnValues({ color: "red", type: "sports"
alert("Found " + matchingRows.length + "match(es).");
//Look for the first row that matches:
var firstMatchingRow = ds.findRowsWithColumnValues({ color: "red", type: "sports" }, true);
if (firstMatchingRow != null)
alert("Found a match!");
else
alert("Failed to find a match!");
This function returns the column type of the specified column.
getColumnType(columnName);
columnName - String. The name of the column.
The column type of the specified column, as a string:
var ds = new Spry.Data.DataSet();
...
var colType = ds.getColumnType("firstname");
This function returns the object that is the 'currentRow' in the data set. By default, the current row is the first row of the data set, but this can be changed by calling the function setCurrentRow() or setCurrentRowNumber().
getCurrentRow()
N/A
The row object or null.
Developers should note that the row object returned is the data set's internal row object. Any changes to the properties of this object results in a change to the data within the data set.
var row = ds1.getCurrentRow(); if (row["@title"] == "Me, Myself and I") ...
This function returns the row ID of the current row.
Developers should not confuse the ID of a row with the index of the row. The ID is a column that contains a unique identifier for the row. This identifier does not change if the rows of the data set are sorted, where as the row index for a given row will change if the rows are sorted.
getCurrentRowID()
N/A
Integer or String that represents the row ID.
The actual type of the row ID is left up to the implementor, but it must be an integer or string that can be used as a key into an associative array.
var rowID = ds.getCurrentRowID();
alert("Current row is: " + rowID);
This function returns the row index for the current row.
Developers should not confuse the row number for a row with its ID. The ID is a column that contains a unique identifier for the row. This identifier does not change if the rows of the data set are sorted, where as the row index for a given row may change if the rows are sorted.
getCurrentRowNumber()
N/A
Returns an integer index (row number) of the row within the data set.
var rowNumber = ds.getCurrentRowNumber();
alert("Current row number is: " + rowNumber);
This function returns an array of the internal row objects that store the data in the data set. Modifying any property of a row object results in a modification of the data in the data set. Users should keep in mind that some data sets load their data asynchronously, so they should check if it is ok to access the data, with a call to getDataWasLoaded(), before attempting to call getData().
getData(unfiltered)
unfiltered - Boolean. Optional argument. If true, getData() returns the unfiltered data array. If false or undefined, it returns the filtered version of the rows array.
Returns an array of row objects.
// Run through all of the rows in the data set. For each row,
// get the value in the "name" column and check to see if it
// is equal to the string "Spry". If it is, return the ID of
// the matching row.
var rows = ds.getData();
for (var i = 0; i < rows.length; i++)
{
if (rows[i]["name"] == "Spry")
return rows[i]["ds_RowID"];
}
This function returns 'true' if a data set successfully loaded its data. If this function returns true, it is safe to access and manipulate the data set. This function will return false if a load request is pending, or an error ocurred while trying to load the data.
getDataWasLoaded()
N/A
true/false
if (ds.getDataWasLoaded())
{
var rows = ds.getData();
for (var i = 0; i < rows.length; i++)
{
if (rows[i]["name"] == "Spry")
return rows[i]["ds_RowID"];
}
}
This method will return true if a request for data has been made and has not yet completed. Otherwise, it will return false.
getLoadDataRequestIsPending()
N/A
true/false
// Fire off a load request if the data set is not already // in the midst of loading its data: if (!ds.getLoadDataRequestIsPending()) ds.loadData();
This method returns the row object associated with the specified row ID.
getRowByID(rowID)
rowID - Integer or String. The ID of the row.
Returns the row object with the given rowID or null if it is not found.
// Get the row with the ID of 10. var row = ds.getRowByID(10); // If we have a match, extract out the value // of the firstname column. if (row) var firstname = row.firstname;
This method returns the row object at the specified row number within the data set.
getRowByRowNumber(rowNumber, unfiltered)
rowNumber - Integer. The row number of the row to fetch.
unfiltered - Boolean. If true, the data set will return the row object at the given row number in the internal unfiltered data array. Otherwise, it returns the row object at the given row number in the filtered data array.
Returns the row object at the given row number or null if it is not found.
// Get row 10 of the unfiltered data. var row = ds.getRowByRowNumber(10, true); // If we have a match, extract out the value // of the firstname column. if (row) var firstname = row.firstname;
This function returns the number of rows in the data set. If the data set has a non-destructive filter, this function returns the number of filtered rows. Users can pass an optional boolean argument to this function. If true, it will return the number of unfiltered rows. If false it will return the number of filtered rows.
getRowCount(unfiltered);
unfiltered - Boolean. Optional argument. If true, getRowCount the number of rows in the unfiltered data array. Otherwise, it returns the number of rows in the filtered data array.
An integer that is the number of rows in the data set.
var filteredRowCount = ds.getRowCount(); var unfilteredRowCount = ds.getRowCount(true);
This function returns the row number for the specified row object in the data set. If the data set has an active non-destructive filter, the row number returned is of the row within the filtered data array. An optional boolean argument can be passed to the function which tells the function to return the row number for the row within the unfiltered data array.
getRowNumber(rowObject, unfiltered)
rowObject - Object. The row to look for.
unfiltered - Boolean. Optional argument. If true the row number returned for the specified row is its row index within the unfiltered data array. Otherwise, it returns the index of the row within the filtered data array.
An integer that is the number of the specified row in the data set. Returns -1 if the row is not found within the data set.
This function returns the name of the column that was used when the data set was last sorted. This function will return an empty string if the data set was never sorted.
getSortColumn()
N/A
A string that is the name of the column last used for a primary sort. If the data set has never been sorted, an empty it returns an empty string.
var columnName = ds.getSortColumn();
This function returns the name of the sort order that was used when the data set was last sorted. This function will return an empty string if the data set was never sorted.
getSortOrder()
N/A
The current sort order of the data set:
var sortOrderName = ds1.getSortOrder();
datasetname.getUnfilteredData();
This function is *DEPRECATED*. Use getData(true) instead.
The default implementation for this function fires off asynchronous notifications for "onPostLoad" and "onDataChanged" events. Classes that derive from Spry.Data.DataSet are expected to override this function to trigger async loading of the data for the data set.
loadData()
N/A
NA
ds.setURL("newXML.xml");
ds.loadData();"
This function is used to set a column type for a data column. This is used to tell the data set the type of data it is dealing with. A common application is for setting numeric data as 'number'. This ensures that the column will sort numerically, and not alpha-numerically.
The valid column types are:
The 'html' column type results in the automatic entity decoding of values stored in a column of that type when the data is first loaded.
setColumnType(columnName, type)
columnName - String or Array of Strings. The name(s) of the column(s) to set.
type - String. One of the following values:
N/A
var ds1 = new Spry.Data.XMLDataSet("myxml.xml","races/standings");
// Example of setting the type of one column:
ds1.setColumnType("start", "date");
// Example of setting the type of multiple columns
// with one call:
ds1.setColumnType(["rank","place"],"number");
Sets the current row of the data set to the row with the specified row ID.
This method will cause an "onCurrentRowChanged" notification to be sent to all observers.
setCurrentRow(rowID)
rowID - Integer or String. The row ID of the row that is to become the current row.
N/A
// Set the current row of the data set // to the row with the integer ID of 13:
ds.setCurrentRow(13);
This function makes the row, at the specified row number (index), the current row of the data set. Spry uses a zero based counting system for row numbers.
Developers should not confuse the ID of a row with the index of the row. A row ID is a unique identifier that is stored within the row in a column called "ds_RowID". This identifier does not change even if the rows of the data set are sorted, where as the row index for a given row can change if the rows are sorted.
setCurrentRowNumber(rowNumber)
rowNumber - Integer. The row number of the row that will become the current row.
N/A
// Make the 3rd row of the data set the current row. Remember // that the row number is zero based. ds.setCurrentRowNumber(2);
Replaces the data inside the data set with the row data in the specified array. If the row data does not have a ds_RowID column defined, it will automatically create one and assign an ID that is the equivalent of the row's index within the array.
Developers should be aware that the data set takes ownership of the objects within the array that is passed in. That is, it uses those objects as its row object internally. It does not make a copy of the objects.
By default, this function will trigger a synchronous "onPreLoad" notification, followed by asynchronous "onPostLoad" and "onDataChanged" notifications that are made sometime *after* the function has exited. If developers want these notifications to happen synchronously before the function exits, they can pass a true for the optional 2nd argument to the function. Developers should be aware that synchronous notifications could cause potential notification cycles in complex situations where data sets and regions are used together, so use sync notifications with caution.
setDataFromDoc(arrayOfObjects, fireSyncLoad)
arrayOfObjects - Array of row objects.
fireSyncLoad - Boolean. Optional argument. If true forces synchronous notifications for "onPostLoad" and "onDataChanged" before the function exits.
// Create an array of data:
var arr = [ { color: "red", type: "sedan" }, { color: "blue", type: coupe" } ];
// Create a data set:
var ds = new Spry.Data.DataSet();
// Now set the data inside the data set:
ds.setDataFromArray(arr);
Sorts the data set using the specified column(s) and sort order.
Developers specify what columns to sort by passing in a single column name string, or an array of column name strings as the first argument to the function. By specifying more than one column name, developers are able to perform secondary, tertiary, etc, sorts on the data.
Valid sort orders are:
The "toggle" sort order will sort the data set in "ascending" order if it has not been previously sorted, otherwise, it causes the data set to sort in the opposite direction from the last sort.
sort(column, order)
column - String or Array of Strings. The column names to sort.
order - The sort order to be used during the sort. Values for order must be one of the following:
N/A
// An example of sorting a data set in ascending order // based on the values in a single column called "lastname":
ds.sort("lastname", "ascending"); // An example of toggling the sort of a data set based // on the values in multiple columns. Since 3 columns are // specified, the data set will perform a tertiary sort: ds.sort(["firstname", "lastname", "@id"], "toggle");
This function creates an interval timer that will continuously reload the data set at the interval specified.
Every time the interval timer fires, the loadData() method of the data set is called.
startLoadInterval(interval);
interval - Integer. The number of milliseconds that must elapse before the data is reloaded.
N/A
// Reload the data in the data set every 10 seconds: ds.startLoadInterval(10000);
This function kills the interval timer that was started with a call to startLoadInterval().
stopLoadInterval()
N/A
// Reload the data set every 10 seconds: ds.startLoadInterval(10000); ... // Stop the continuous loading of data: ds.stoptLoadInterval();
Copyright © 2007. Adobe Systems Incorporated.
All rights reserved.