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

## 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 component
| 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.
| bufferedListener(`String eventName`, `Function handler`, [`Object scope`], [`Number millis`]) : Function | Observable
Appends an event handler to this component that is buffered. If the event is triggered more than once in the specifie...
| delayedListener(`String eventName`, `Function handler`, [`Object scope`], [`Number delay`]) : Function | Observable
Appends an event handler to this component that is delayed the specified number of milliseconds. This is useful for e...
| 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 ...
| getSortState() : Object | AbstractDataModel
Interface method to supply info regarding the Grid's current sort state - if overridden, this should return an object...
| 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.
| on(`String eventName`, `Function handler`, [`Object scope`], [`boolean override`]) : void | Observable
Appends an event handler to this element (shorthand for addListener)
| 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.

## 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 component
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.

### bufferedListener

`public function bufferedListener(`String eventName`, `Function handler`, [`Object scope`], [`Number millis`])`
Appends an event handler to this component that is buffered. If the event is triggered more than once in the specified time-frame, only the last one actually fires.
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
- `millis` : Number
  (optional) The number of milliseconds to buffer (defaults to 250)

Returns:

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

This method is defined by Observable.

### delayedListener

`public function delayedListener(`String eventName`, `Function handler`, [`Object scope`], [`Number delay`])`
Appends an event handler to this component that is delayed the specified number of milliseconds. This is useful for events that modify the DOM and need to wait for the browser to catch up.
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 (defaults to 1 millisecond)

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.

### getSortState

`public function getSortState()`
Interface method to supply info regarding the Grid's current sort state - if overridden, this should return an object like this {column: this.sortColumn, direction: this.sortDir}.
Parameters:

- None.

Returns:

- `Object`

This method is defined by AbstractDataModel.

### 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, true for success, false for failure)
- `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.

### on

`public function on(`String eventName`, `Function handler`, [`Object scope`], [`boolean override`])`
Appends an event handler to this element (shorthand for addListener)
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.

### 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.

yui-ext - Copyright © 2006 Jack Slocum. | Yahoo! UI - Copyright © 2006 Yahoo! Inc.
All rights reserved.