Print Friendly

# Class YAHOO.ext.grid.XMLDataModel

Package: | YAHOO.ext.grid
Class: | XMLDataModel
Extends: | LoadableDataModel
Defined In: | XMLDataModel.js

This is an implementation of a DataModel used by the Grid. It works with XML data.
Example schema from Amazon search:

    var schema = {
    tagName: 'Item',
    id: 'ASIN',
    fields: ['Author', 'Title', 'Manufacturer', 'ProductGroup']
    };

## 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
--- | ---
| XMLDataModel(`Object schema`, `XMLDocument xml`) | XMLDataModel
| 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(`String id`, `Array cellValues`) : Number | XMLDataModel
Adds a row to this DataModel and syncs the XML document
| applySort() : void | DefaultDataModel
Applies the last used sort to the current data.
| createNode(`XMLDocument xmlDoc`, `String/Number id`, `Array colData`) : XMLNode | XMLDataModel
Override this method to define your own node creation routine for when new rows are added. By default this method clo...
| 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 rowIndex`) : Number | XMLDataModel
Overrides getRowId in DefaultDataModel to return the ID value of the specified node.
| 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`, `String id`, `Array cellValues`) : Number | XMLDataModel
Inserts a row into this DataModel and syncs the XML document
| 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(`XMLDocument doc`, [`Function callback`], [`Boolean keepExisting`], [`Number insertIndex`]) : void | XMLDataModel
Overrides loadData in LoadableDataModel to process XML
| 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 | XMLDataModel
Removes the row from DataModel and syncs the XML document
| 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 | XMLDataModel
Overrides DefaultDataModel.setValueAt to update the underlying XML Document
| 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

### XMLDataModel

`public function XMLDataModel(`Object schema`, `XMLDocument xml`)`
Parameters:

- `schema` : Object
  The schema to use
- `xml` : XMLDocument
  An XML document to load immediately

## 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(`String id`, `Array cellValues`)`
Adds a row to this DataModel and syncs the XML document
Parameters:

- `id` : String
  The id of the row, if null the next row index is used
- `cellValues` : Array
  The cell values for this row

Returns:

- `Number`
  The index of the new row (if the model is sorted this index may not be accurate)

This method is defined by XMLDataModel.

### applySort

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

- None.

Returns:

- `void`

This method is defined by DefaultDataModel.

### createNode

`public function createNode(`XMLDocument xmlDoc`, `String/Number id`, `Array colData`)`
Override this method to define your own node creation routine for when new rows are added. By default this method clones the first node and sets the column values in the newly cloned node. In many instances this will not work and you will have to create the node manually.
Parameters:

- `xmlDoc` : XMLDocument
  The xml document being used by this model
- `id` : String/Number
  The row id
- `colData` : Array
  The column data for the new node

Returns:

- `XMLNode`
  The created node

This method is defined by XMLDataModel.

### 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(`Number rowIndex`)`
Overrides getRowId in DefaultDataModel to return the ID value of the specified node.
Parameters:

- `rowIndex` : Number

Returns:

- `Number`

This method is defined by XMLDataModel.

### 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`, `String id`, `Array cellValues`)`
Inserts a row into this DataModel and syncs the XML document
Parameters:

- `index` : Number
  The index to insert the row
- `id` : String
  The id of the row, if null the next row index is used
- `cellValues` : Array
  The cell values for this row

Returns:

- `Number`
  The index of the new row (if the model is sorted this index may not be accurate)

This method is defined by XMLDataModel.

### 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(`XMLDocument doc`, [`Function callback`], [`Boolean keepExisting`], [`Number insertIndex`])`
Overrides loadData in LoadableDataModel to process XML
Parameters:

- `doc` : XMLDocument
  The document to load
- `callback` : Function
  (optional) callback to call when loading is complete
- `keepExisting` : Boolean
  (optional) true to keep existing data
- `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 XMLDataModel.

### 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`)`
Removes the row from DataModel and syncs the XML document
Parameters:

- `index` : Number
  The index of the row to remove

Returns:

- `void`

This method is defined by XMLDataModel.

### 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`)`
Overrides DefaultDataModel.setValueAt to update the underlying XML Document
Parameters:

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

Returns:

- `void`

This method is defined by XMLDataModel.

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