Print Friendly

# Class YAHOO.ext.grid.LoadableDataModel

Package: | YAHOO.ext.grid
Class: | LoadableDataModel
Extends: | DefaultDataModel
Subclasses: | JSONDataModel, XMLDataModel
Defined In: | LoadableDataModel.js

This class extends DefaultDataModel and adds the core functionality to load data remotely. Generally you will want to use one of it's subclasses.

## Public Properties

Property | Defined By
--- | ---
| baseParams : Object | LoadableDataModel
An object of key/value pairs to be passed as parameters when loading pages/sorting
| loadedPage : Number | LoadableDataModel
The active page
| pageSize : Number | LoadableDataModel
The number of records per page
| pageUrl : String | LoadableDataModel
The script/page to call to provide paged/sorted data
| paramMap : Object | LoadableDataModel
Maps named params to url parameters - Override to specify your own param names
| remoteSort : Boolean | LoadableDataModel
True to use remote sorting, initPaging automatically sets this to true
| sortTypes<static> : Object | DefaultDataModel
<static> Alias to YAHOO.ext.grid.DefaultColumnModel.sortTypes

## Public Methods

Method | Defined By
--- | ---
| LoadableDataModel(`String dataType`) | LoadableDataModel
| addListener(`String eventName`, `Function handler`, [`Object scope`], [`boolean override`]) : void | Observable
Appends an event handler to this element
| addPostprocessor(`Number columnIndex`, `Function fn`) : void | LoadableDataModel
Adds a postprocessor function to format data before updating the underlying data source (ie. convert date to string b...
| addPreprocessor(`Number columnIndex`, `Function fn`) : void | LoadableDataModel
Adds a preprocessor function to parse data before it is added to the Model - ie. Date.parse to parse dates.
| addRow(`Array cellValues`) : Number | DefaultDataModel
Adds a row to the dataset.
| applySort() : void | DefaultDataModel
Applies the last used sort to the current data.
| delayedListener(`String eventName`, `Function handler`, [`Object scope`], [`Number delay`]) : Function | Observable
Appends an event handler to this element that is delayed the specified number of milliseconds.
| each(`Function fn`, [`Object scope`]) : void | DefaultDataModel
Calls passed function with each rows data - if the function returns false it stops.
| filter(`Object query`) : Number | DefaultDataModel
Filter the DataModel rows by the query defined in spec, see query for more details on the query spec.
| fireEvent(`String eventName`, `Object... args`) : Boolean | Observable
Fires the specified event with the passed parameters (minus the event name).
| getPageSize() : Number | LoadableDataModel
Returns the number of records per page
| getPostprocessor(`Number columnIndex`) : Function | LoadableDataModel
Gets the postprocessor function for the specified column.
| getPreprocessor(`Number columnIndex`) : Function | LoadableDataModel
Gets the preprocessor function for the specified column.
| getRow() : Array | DefaultDataModel
Returns the column data for the specified row.
| getRowCount() : Number | DefaultDataModel
Returns the number of rows in the dataset
| getRowId() : Number | DefaultDataModel
Returns the ID of the specified row. By default it return the value of the first column. Override to provide more ad...
| getRows(`Array indexes`) : Array | DefaultDataModel
Returns the column data for the specified rows as a multi-dimensional array: rows[3][0] would give you the value of ...
| getTotalPages() : Number | LoadableDataModel
Returns the total number of pages available
| getTotalRowCount() : Number | LoadableDataModel
Returns the total number of records available, override if needed
| getValueAt(`Number rowIndex`, `Number colIndex`) : Object | DefaultDataModel
Returns the value at the specified data position
| initPaging(`String url`, `Number pageSize`, [`Object baseParams`]) : void | LoadableDataModel
Initializes paging for this model.
| insertRow(`Number index`, `Array cellValues`) : Number | DefaultDataModel
Inserts a row a the specified location in the dataset.
| isPaged() : Boolean | LoadableDataModel
Returns true if this model uses paging
| load(`Object/String url`, [`String/Object params`], [`Function callback`], [`Number insertIndex`]) : void | LoadableDataModel
Initiates the loading of the data from the specified URL - Failed load attempts will fire the loadexception event.
| loadData() : void | LoadableDataModel
Empty interface method - Called to process the data returned by the XHR - Classes which extend LoadableDataModel shou...
| loadPage(`Number pageNum`, [`Function callback`], [`Boolean keepExisting`]) : void | LoadableDataModel
Loads a page of data.
| purgeListeners() : void | Observable
Removes all listeners for this object
| query(`Object spec`, `Boolean returnUnmatched`) : Array | DefaultDataModel
Query the DataModel rows by the filters defined in spec, for example... // column 1 starts with Jack, column 2 filte...
| removeListener(`String eventName`, `Function handler`, [`Object scope`]) : void | Observable
Removes a listener
| removePostprocessor(`Number columnIndex`) : void | LoadableDataModel
Removes a postprocessor function.
| removePreprocessor(`Number columnIndex`) : void | LoadableDataModel
Removes a preprocessor function.
| removeRow(`Number index`) : void | DefaultDataModel
Remove a row.
| setDefaultSort(`Function/Object sortInfo`, `Number columnIndex`, `String direction`) : void | DefaultDataModel
Sets the default sort info. Note: this function does not actually apply the sort.
| setValueAt(`Object value`, `Number rowIndex`, `Number colIndex`) : void | DefaultDataModel
Sets the specified value at the specified data position
| sort(`Function/Object sortInfo`, `Number columnIndex`, `String direction`) : void | DefaultDataModel
Sorts the data by the specified column - Uses the sortType specified for the column in the passed columnModel.

## Public Events

Event | Defined By
--- | ---
| beforeload : (`DataModel this`) | LoadableDataModel
Fires before a load takes place
| cellupdated : (`DataModel this`, `Number rowIndex`, `Number columnIndex`) | AbstractDataModel
Fires when a cell is updated
| datachanged : (`DataModel this`) | AbstractDataModel
Fires when the entire data structure has changed
| load : (`DataModel this`) | LoadableDataModel
Fires when new data has successfully been loaded
| loadexception : (`DataModel this`, `Exception e`, `Object response`) | LoadableDataModel
Fires when there's an error loading data
| rowsdeleted : (`DataModel this`, `Number firstRowIndex`, `Number lastRowIndex`) | AbstractDataModel
Fires when a range of rows have been deleted
| rowsinserted : (`DataModel this`, `Number firstRowIndex`, `Number lastRowIndex`) | AbstractDataModel
Fires when a range of rows have been inserted
| rowssorted : (`DataModel this`) | AbstractDataModel
Fires when the data has been sorted
| rowsupdated : (`DataModel this`, `Number firstRowIndex`, `Number lastRowIndex`) | AbstractDataModel
Fires when a range of rows have been updated

## Property Details

### baseParams

`public Object baseParams`
An object of key/value pairs to be passed as parameters when loading pages/sorting
This property is defined by LoadableDataModel.

### loadedPage

`public Number loadedPage`
The active page
This property is defined by LoadableDataModel.

### pageSize

`public Number pageSize`
The number of records per page
This property is defined by LoadableDataModel.

### pageUrl

`public String pageUrl`
The script/page to call to provide paged/sorted data
This property is defined by LoadableDataModel.

### paramMap

`public Object paramMap`
Maps named params to url parameters - Override to specify your own param names
This property is defined by LoadableDataModel.

### remoteSort

`public Boolean remoteSort`
True to use remote sorting, initPaging automatically sets this to true
This property is defined by LoadableDataModel.

### sortTypes<static>

`public Object sortTypes<static>`
<static> Alias to YAHOO.ext.grid.DefaultColumnModel.sortTypes
This property is defined by DefaultDataModel.

## Constructor Details

### LoadableDataModel

`public function LoadableDataModel(`String dataType`)`
Parameters:

- `dataType` : String
  YAHOO.ext.grid.LoadableDataModel.XML, YAHOO.ext.grid.LoadableDataModel.TEXT or YAHOO.ext.grid.JSON

## Method Details

### addListener

`public function addListener(`String eventName`, `Function handler`, [`Object scope`], [`boolean override`])`
Appends an event handler to this element
Parameters:

- `eventName` : String
  The type of event to listen for
- `handler` : Function
  The method the event invokes
- `scope` : Object
  (optional) The scope (this object) for the handler
- `override` : boolean
  (optional) If true, scope becomes the scope

Returns:

- `void`

This method is defined by Observable.

### addPostprocessor

`public function addPostprocessor(`Number columnIndex`, `Function fn`)`
Adds a postprocessor function to format data before updating the underlying data source (ie. convert date to string before updating XML document).
Parameters:

- `columnIndex` : Number
- `fn` : Function

Returns:

- `void`

This method is defined by LoadableDataModel.

### addPreprocessor

`public function addPreprocessor(`Number columnIndex`, `Function fn`)`
Adds a preprocessor function to parse data before it is added to the Model - ie. Date.parse to parse dates.
Parameters:

- `columnIndex` : Number
- `fn` : Function

Returns:

- `void`

This method is defined by LoadableDataModel.

### addRow

`public function addRow(`Array cellValues`)`
Adds a row to the dataset.
Parameters:

- `cellValues` : Array
  The array of values for the new row

Returns:

- `Number`
  The index of the added row

This method is defined by DefaultDataModel.

### applySort

`public function applySort()`
Applies the last used sort to the current data.
Parameters:

- None.

Returns:

- `void`

This method is defined by DefaultDataModel.

### delayedListener

`public function delayedListener(`String eventName`, `Function handler`, [`Object scope`], [`Number delay`])`
Appends an event handler to this element that is delayed the specified number of milliseconds.
Parameters:

- `eventName` : String
  The type of event to listen for
- `handler` : Function
  The method the event invokes
- `scope` : Object
  (optional) The scope (this object) for the handler
- `delay` : Number
  (optional) The number of milliseconds to delay

Returns:

- `Function`
  The wrapped function that was created (can be used to remove the listener)

This method is defined by Observable.

### each

`public function each(`Function fn`, [`Object scope`])`
Calls passed function with each rows data - if the function returns false it stops.
Parameters:

- `fn` : Function
- `scope` : Object
  (optional)

Returns:

- `void`

This method is defined by DefaultDataModel.

### filter

`public function filter(`Object query`)`
Filter the DataModel rows by the query defined in spec, see query for more details on the query spec.
Parameters:

- `query` : Object
  The query spec query

Returns:

- `Number`
  The number of rows removed

This method is defined by DefaultDataModel.

### fireEvent

`public function fireEvent(`String eventName`, `Object... args`)`
Fires the specified event with the passed parameters (minus the event name).
Parameters:

- `eventName` : String
- `args` : Object...
  Variable number of parameters are passed to handlers

Returns:

- `Boolean`
  returns false if any of the handlers return false otherwise it returns true

This method is defined by Observable.

### getPageSize

`public function getPageSize()`
Returns the number of records per page
Parameters:

- None.

Returns:

- `Number`

This method is defined by LoadableDataModel.

### getPostprocessor

`public function getPostprocessor(`Number columnIndex`)`
Gets the postprocessor function for the specified column.
Parameters:

- `columnIndex` : Number

Returns:

- `Function`

This method is defined by LoadableDataModel.

### getPreprocessor

`public function getPreprocessor(`Number columnIndex`)`
Gets the preprocessor function for the specified column.
Parameters:

- `columnIndex` : Number

Returns:

- `Function`

This method is defined by LoadableDataModel.

### getRow

`public function getRow()`
Returns the column data for the specified row.
Parameters:

- None.

Returns:

- `Array`

This method is defined by DefaultDataModel.

### getRowCount

`public function getRowCount()`
Returns the number of rows in the dataset
Parameters:

- None.

Returns:

- `Number`

This method is defined by DefaultDataModel.

### getRowId

`public function getRowId()`
Returns the ID of the specified row. By default it return the value of the first column. Override to provide more advanced ID handling.
Parameters:

- None.

Returns:

- `Number`

This method is defined by DefaultDataModel.

### getRows

`public function getRows(`Array indexes`)`
Returns the column data for the specified rows as a multi-dimensional array: rows[3][0] would give you the value of row 4, column 0.
Parameters:

- `indexes` : Array
  The row indexes to fetch

Returns:

- `Array`

This method is defined by DefaultDataModel.

### getTotalPages

`public function getTotalPages()`
Returns the total number of pages available
Parameters:

- None.

Returns:

- `Number`

This method is defined by LoadableDataModel.

### getTotalRowCount

`public function getTotalRowCount()`
Returns the total number of records available, override if needed
Parameters:

- None.

Returns:

- `Number`

This method is defined by LoadableDataModel.

### getValueAt

`public function getValueAt(`Number rowIndex`, `Number colIndex`)`
Returns the value at the specified data position
Parameters:

- `rowIndex` : Number
- `colIndex` : Number

Returns:

- `Object`

This method is defined by DefaultDataModel.

### initPaging

`public function initPaging(`String url`, `Number pageSize`, [`Object baseParams`])`
Initializes paging for this model.
Parameters:

- `url` : String
- `pageSize` : Number
- `baseParams` : Object
  (optional) Object containing key/value pairs to add to all requests

Returns:

- `void`

This method is defined by LoadableDataModel.

### insertRow

`public function insertRow(`Number index`, `Array cellValues`)`
Inserts a row a the specified location in the dataset.
Parameters:

- `index` : Number
  The index where the row should be inserted
- `cellValues` : Array
  The array of values for the new row

Returns:

- `Number`
  The index the row was inserted in

This method is defined by DefaultDataModel.

### isPaged

`public function isPaged()`
Returns true if this model uses paging
Parameters:

- None.

Returns:

- `Boolean`

This method is defined by LoadableDataModel.

### load

`public function load(`Object/String url`, [`String/Object params`], [`Function callback`], [`Number insertIndex`])`
Initiates the loading of the data from the specified URL - Failed load attempts will fire the loadexception event.
Parameters:

- `url` : Object/String
  The url from which the data can be loaded
- `params` : String/Object
  (optional) The parameters to pass as either a url encoded string "param1=1&param2=2" or as an object {param1: 1, param2: 2}
- `callback` : Function
  (optional) Callback when load is complete - called with signature (this, rowCountLoaded)
- `insertIndex` : Number
  (optional) if present, loaded data is inserted at the specified index instead of overwriting existing data

Returns:

- `void`

This method is defined by LoadableDataModel.

### loadData

`public function loadData()`
Empty interface method - Called to process the data returned by the XHR - Classes which extend LoadableDataModel should implement this method. See YAHOO.ext.XMLDataModel for an example implementation.
Parameters:

- None.

Returns:

- `void`

This method is defined by LoadableDataModel.

### loadPage

`public function loadPage(`Number pageNum`, [`Function callback`], [`Boolean keepExisting`])`
Loads a page of data.
Parameters:

- `pageNum` : Number
  Which page to load. The first page is 1.
- `callback` : Function
  (optional) Optional callback when loading is complete
- `keepExisting` : Boolean
  (optional) true to keep existing data and append the new data

Returns:

- `void`

This method is defined by LoadableDataModel.

### purgeListeners

`public function purgeListeners()`
Removes all listeners for this object
Parameters:

- None.

Returns:

- `void`

This method is defined by Observable.

### query

`public function query(`Object spec`, `Boolean returnUnmatched`)`
Query the DataModel rows by the filters defined in spec, for example...

    // column 1 starts with Jack, column 2 filtered by myFcn, column 3 equals 'Fred'
    dataModel.filter({1: /^Jack.+/i}, 2: myFcn, 3: 'Fred'});

Parameters:

- `spec` : Object
  The spec is generally an object literal consisting of column index and filter type. The filter type can be a string/number (exact match), a regular expression to test using String.search() or a function to call. If it's a function, it will be called with the value for the specified column and an array of the all column values for that row: yourFcn(value, columnData). If it returns anything other than true, the row is not a match. If you have modified Object.prototype this method may fail.
- `returnUnmatched` : Boolean
  True to return rows which don't match the query instead of rows that do match

Returns:

- `Array`
  An array of row indexes that match

This method is defined by DefaultDataModel.

### removeListener

`public function removeListener(`String eventName`, `Function handler`, [`Object scope`])`
Removes a listener
Parameters:

- `eventName` : String
  The type of event to listen for
- `handler` : Function
  The handler to remove
- `scope` : Object
  (optional) The scope (this object) for the handler

Returns:

- `void`

This method is defined by Observable.

### removePostprocessor

`public function removePostprocessor(`Number columnIndex`)`
Removes a postprocessor function.
Parameters:

- `columnIndex` : Number

Returns:

- `void`

This method is defined by LoadableDataModel.

### removePreprocessor

`public function removePreprocessor(`Number columnIndex`)`
Removes a preprocessor function.
Parameters:

- `columnIndex` : Number

Returns:

- `void`

This method is defined by LoadableDataModel.

### removeRow

`public function removeRow(`Number index`)`
Remove a row.
Parameters:

- `index` : Number

Returns:

- `void`

This method is defined by DefaultDataModel.

### setDefaultSort

`public function setDefaultSort(`Function/Object sortInfo`, `Number columnIndex`, `String direction`)`
Sets the default sort info. Note: this function does not actually apply the sort.
Parameters:

- `sortInfo` : Function/Object
  A sort comparison function or null to use the default or A object that has a method getSortType(index) that returns a function like a grid column model.
- `columnIndex` : Number
  The column index to sort by
- `direction` : String
  The direction of the sort ('DESC' or 'ASC')

Returns:

- `void`

This method is defined by DefaultDataModel.

### setValueAt

`public function setValueAt(`Object value`, `Number rowIndex`, `Number colIndex`)`
Sets the specified value at the specified data position
Parameters:

- `value` : Object
  The new value
- `rowIndex` : Number
- `colIndex` : Number

Returns:

- `void`

This method is defined by DefaultDataModel.

### sort

`public function sort(`Function/Object sortInfo`, `Number columnIndex`, `String direction`)`
Sorts the data by the specified column - Uses the sortType specified for the column in the passed columnModel.
Parameters:

- `sortInfo` : Function/Object
  A sort comparison function or null to use the default or A object that has a method getSortType(index) that returns a function like a grid column model.
- `columnIndex` : Number
  The column index to sort by
- `direction` : String
  The direction of the sort ('DESC' or 'ASC')

Returns:

- `void`

This method is defined by DefaultDataModel.

## Event Details

### beforeload

`public event beforeload`
Fires before a load takes place
Subscribers will be called with the following parameters:

- `this` : DataModel

This event is defined by LoadableDataModel.

### cellupdated

`public event cellupdated`
Fires when a cell is updated
Subscribers will be called with the following parameters:

- `this` : DataModel
- `rowIndex` : Number
- `columnIndex` : Number

This event is defined by AbstractDataModel.

### datachanged

`public event datachanged`
Fires when the entire data structure has changed
Subscribers will be called with the following parameters:

- `this` : DataModel

This event is defined by AbstractDataModel.

### load

`public event load`
Fires when new data has successfully been loaded
Subscribers will be called with the following parameters:

- `this` : DataModel

This event is defined by LoadableDataModel.

### loadexception

`public event loadexception`
Fires when there's an error loading data
Subscribers will be called with the following parameters:

- `this` : DataModel
- `e` : Exception
  The exception object or null
- `response` : Object
  The Connect response object

This event is defined by LoadableDataModel.

### rowsdeleted

`public event rowsdeleted`
Fires when a range of rows have been deleted
Subscribers will be called with the following parameters:

- `this` : DataModel
- `firstRowIndex` : Number
- `lastRowIndex` : Number

This event is defined by AbstractDataModel.

### rowsinserted

`public event rowsinserted`
Fires when a range of rows have been inserted
Subscribers will be called with the following parameters:

- `this` : DataModel
- `firstRowIndex` : Number
- `lastRowIndex` : Number

This event is defined by AbstractDataModel.

### rowssorted

`public event rowssorted`
Fires when the data has been sorted
Subscribers will be called with the following parameters:

- `this` : DataModel

This event is defined by AbstractDataModel.

### rowsupdated

`public event rowsupdated`
Fires when a range of rows have been updated
Subscribers will be called with the following parameters:

- `this` : DataModel
- `firstRowIndex` : Number
- `lastRowIndex` : Number

This event is defined by AbstractDataModel.

Copyright © 2006 Jack Slocum. All rights reserved.