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.