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

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 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(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.
  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...
  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 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 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 ...
  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, 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.
  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 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.

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

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.

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

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, 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, 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(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.

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)
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.
yui-ext - Copyright © 2006 Jack Slocum. | Yahoo! UI - Copyright © 2006 Yahoo! Inc.
All rights reserved.