Print Friendly

# Class YAHOO.ext.JsonView

Package: | YAHOO.ext
Class: | JsonView
Extends: | View
Defined In: | TemplateView.js

Shortcut class to create a JSON + UpdateManager template view. Usage:

    var view = new YAHOO.ext.JsonView('my-element',
               '<div id="{id}">{foo} - {bar}</div>', // auto create template
               { multiSelect: true, jsonRoot: 'data' });

    // listen for node click?
    view.on('click', function(vw, index, node, e){
        alert('Node "' + node.id + '" at index: ' + index + ' was clicked.');
    });

    // direct load of JSON data
    view.load('foobar.php');

    // Example from my blog list
    var tpl = new YAHOO.ext.Template(
        '<div class="entry">' +
           '<a class="entry-title" href="{link}">{title}</a>' +
           '<h4>{date} by {author} | {comments} Comments</h4>{description}' +
        '</div><hr />'
    );

    var moreView = new YAHOO.ext.JsonView('entry-list', tpl, {
       jsonRoot: 'posts'
    });
    moreView.on('beforerender', this.sortEntries, this, true);
    moreView.load({
        url:'/blog/get-posts.php',
        params: 'allposts=true',
        text:'Loading Blog Entries...'
    });

## Public Properties

Property | Defined By
--- | ---
| jsonData : Object | View
The current json data or null
| jsonRoot : String | View
The root property in the loaded json object that contains the data
| selectedClass : YAHOO.ext.DomHelper.Template | View
The css class to add to selected nodes
| tpl : YAHOO.ext.DomHelper.Template | View
The template used by this View

## Public Methods

Method | Defined By
--- | ---
| JsonView(`String/HTMLElement/Element container`, `DomHelper.Template tpl`, `Object config`) | JsonView
Create a new JsonView
| addListener(`String eventName`, `Function handler`, [`Object scope`], [`boolean override`]) : void | Observable
Appends an event handler to this component
| 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...
| clearFilter() : void | JsonView
Clears the current filter.
| clearSelections([`Boolean suppressEvent`]) : void | View
Clear all selections
| 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...
| filter(`String property`, `String/RegExp value`) : void | JsonView
Filter the data by a specific property.
| filterBy(`Function fn`, [`Object scope`]) : void | JsonView
Filter by a function. The passed function will be called with each object in the current dataset. If the function re...
| findItemFromChild(`HTMLElement node`) : HTMLElement | View
Returns the template node the passed child belongs to or null if it doesn't belong to one.
| fireEvent(`String eventName`, `Object... args`) : Boolean | Observable
Fires the specified event with the passed parameters (minus the event name).
| getCount() : Number | JsonView
Get the number of records in the current JSON dataset
| getEl() : YAHOO.ext.Element | View
Returns the element this view is bound to.
| getNode(`HTMLElement/String/Number nodeInfo`) : HTMLElement | View
Gets a template node.
| getNodes(`Number startIndex`, `Number endIndex`) : Array | View
Gets a range template nodes.
| getSelectedIndexes() : Array | View
Get the indexes of the selected nodes.
| getSelectedNodes() : Array | View
Get the currently selected nodes.
| getSelectionCount() : Number | View
Get the number of selected nodes.
| indexOf(`HTMLElement/String/Number nodeInfo`) : Number | View
Finds the index of the passed node
| load(`Object/String/Function url`, [`String/Object params`], [`Function callback`], [`Boolean discardUrl`]) : void | JsonView
Performs an async request, loading the JSON from the response. If params are specified it uses POST, otherwise it use...
| on(`String eventName`, `Function handler`, [`Object scope`], [`boolean override`]) : void | Observable
Appends an event handler to this element (shorthand for addListener)
| prepareData(`Array/Object data`, `Number index`) : void | View
Function to override to reformat the data that is sent to the template for each node.
| purgeListeners() : void | Observable
Removes all listeners for this object
| refresh() : void | View
Refreshes the view.
| refreshNode(`Number index`) : void | View
Refresh an individual node.
| removeListener(`String eventName`, `Function handler`, [`Object scope`]) : void | Observable
Removes a listener
| select(`Array/HTMLElement/String/Number nodeInfo`, [`Boolean keepExisting`], [`Boolean suppressEvent`]) : void | View
Selects nodes.
| setDataModel(`DataModel dataModel`) : void | View
Changes the data model this view uses and refresh the view.
| sort(`String property`, [`String direction`], [`Function sortType`]) : void | JsonView
Sorts the data for this view and refreshes it.
| unplugDataModel(`DataModel dataModel`) : void | View
Unplug the data model and stop updates.

## Public Events

Event | Defined By
--- | ---
| beforerender : (`YAHOO.ext.View this`, `Object data`) | JsonView
Fires before rendering of the downloaded json data.
| beforeselect : (`YAHOO.ext.View this`, `HTMLElement node`, `Array selections`) | View
Fires before a selection is made. If any handlers return false, the selection is cancelled.
| click : (`YAHOO.ext.View this`, `Number index`, `HTMLElement node`, `YAHOO.ext.EventObject e`) | View
Fires when a template node is clicked.
| contextmenu : (`YAHOO.ext.View this`, `Number index`, `HTMLElement node`, `YAHOO.ext.EventObject e`) | View
Fires when a template node is right clicked.
| dblclick : (`YAHOO.ext.View this`, `Number index`, `HTMLElement node`, `YAHOO.ext.EventObject e`) | View
Fires when a template node is double clicked.
| load : (`YAHOO.ext.View this`, `Object data`, `Object response`) | JsonView
Fires when data is loaded.
| loadexception : (`YAHOO.ext.View this`, `Object response`) | JsonView
Fires when loading fails.
| selectionchange : (`YAHOO.ext.View this`, `Array selections`) | View
Fires when the selected nodes change.

## Property Details

### jsonData

`public Object jsonData`
The current json data or null
This property is defined by View.

### jsonRoot

`public String jsonRoot`
The root property in the loaded json object that contains the data
This property is defined by View.

### selectedClass

`public YAHOO.ext.DomHelper.Template selectedClass`
The css class to add to selected nodes
This property is defined by View.

### tpl

`public YAHOO.ext.DomHelper.Template tpl`
The template used by this View
This property is defined by View.

## Constructor Details

### JsonView

`public function JsonView(`String/HTMLElement/Element container`, `DomHelper.Template tpl`, `Object config`)`
Create a new JsonView
Parameters:

- `container` : String/HTMLElement/Element
  The container element where the view is to be rendered.
- `tpl` : DomHelper.Template
  The rendering template
- `config` : Object
  The config object

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

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

### clearFilter

`public function clearFilter()`
Clears the current filter.
Parameters:

- None.

Returns:

- `void`

This method is defined by JsonView.

### clearSelections

`public function clearSelections([`Boolean suppressEvent`])`
Clear all selections
Parameters:

- `suppressEvent` : Boolean
  (optional) true to skip firing of the selectionchange event

Returns:

- `void`

This method is defined by View.

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

### filter

`public function filter(`String property`, `String/RegExp value`)`
Filter the data by a specific property.
Parameters:

- `property` : String
  A property on your JSON objects
- `value` : String/RegExp
  Either string that the property values should start with or a RegExp to test against the property

Returns:

- `void`

This method is defined by JsonView.

### filterBy

`public function filterBy(`Function fn`, [`Object scope`])`
Filter by a function. The passed function will be called with each object in the current dataset. If the function returns true, the value is kept otherwise it is filtered.
Parameters:

- `fn` : Function
  The
- `scope` : Object
  (optional) The scope of the function (defaults to this JsonView)

Returns:

- `void`

This method is defined by JsonView.

### findItemFromChild

`public function findItemFromChild(`HTMLElement node`)`
Returns the template node the passed child belongs to or null if it doesn't belong to one.
Parameters:

- `node` : HTMLElement

Returns:

- `HTMLElement`
  The template node

This method is defined by View.

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

### getCount

`public function getCount()`
Get the number of records in the current JSON dataset
Parameters:

- None.

Returns:

- `Number`

This method is defined by JsonView.

### getEl

`public function getEl()`
Returns the element this view is bound to.
Parameters:

- None.

Returns:

- `YAHOO.ext.Element`

This method is defined by View.

### getNode

`public function getNode(`HTMLElement/String/Number nodeInfo`)`
Gets a template node.
Parameters:

- `nodeInfo` : HTMLElement/String/Number
  An HTMLElement template node, index of a template node or the id of a template node

Returns:

- `HTMLElement`
  The node or null if it wasn't found

This method is defined by View.

### getNodes

`public function getNodes(`Number startIndex`, `Number endIndex`)`
Gets a range template nodes.
Parameters:

- `startIndex` : Number
- `endIndex` : Number

Returns:

- `Array`
  An array of nodes

This method is defined by View.

### getSelectedIndexes

`public function getSelectedIndexes()`
Get the indexes of the selected nodes.
Parameters:

- None.

Returns:

- `Array`

This method is defined by View.

### getSelectedNodes

`public function getSelectedNodes()`
Get the currently selected nodes.
Parameters:

- None.

Returns:

- `Array`
  An array of HTMLElements

This method is defined by View.

### getSelectionCount

`public function getSelectionCount()`
Get the number of selected nodes.
Parameters:

- None.

Returns:

- `Number`

This method is defined by View.

### indexOf

`public function indexOf(`HTMLElement/String/Number nodeInfo`)`
Finds the index of the passed node
Parameters:

- `nodeInfo` : HTMLElement/String/Number
  An HTMLElement template node, index of a template node or the id of a template node

Returns:

- `Number`
  The index of the node or -1

This method is defined by View.

### load

`public function load(`Object/String/Function url`, [`String/Object params`], [`Function callback`], [`Boolean discardUrl`])`
Performs an async request, loading the JSON from the response. If params are specified it uses POST, otherwise it uses GET.
Parameters:

- `url` : Object/String/Function
  The url for this request or a function to call to get the url or a config object containing any of the following options:

       view.load({ url: 'your-url.php',
       params: {param1: 'foo', param2: 'bar'}, // or a URL encoded string
       callback: yourFunction,
       scope: yourObject, //(optional scope)
       discardUrl: false,
       nocache: false,
       text: 'Loading...',
       timeout: 30,
       scripts: false
       });

  The only required property is url. The optional properties nocache, text and scripts are shorthand for disableCaching, indicatorText and loadScripts and are used to set their associated property on this UpdateManager instance.
- `params` : String/Object
  (optional) The parameters to pass as either a url encoded string "param1=1&param2=2" or an object {param1: 1, param2: 2}
- `callback` : Function
  (optional) Callback when transaction is complete - called with signature (oElement, bSuccess)
- `discardUrl` : Boolean
  (optional) By default when you execute an update the defaultUrl is changed to the last used url. If true, it will not store the url.

Returns:

- `void`

This method is defined by JsonView.

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

### prepareData

`public function prepareData(`Array/Object data`, `Number index`)`
Function to override to reformat the data that is sent to the template for each node.
Parameters:

- `data` : Array/Object
  The raw data (array of colData for a data model bound view or a JSON object for an UpdateManager bound view).
- `index` : Number
  The index of the data within the data model

Returns:

- `void`

This method is defined by View.

### purgeListeners

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

- None.

Returns:

- `void`

This method is defined by Observable.

### refresh

`public function refresh()`
Refreshes the view.
Parameters:

- None.

Returns:

- `void`

This method is defined by View.

### refreshNode

`public function refreshNode(`Number index`)`
Refresh an individual node.
Parameters:

- `index` : Number

Returns:

- `void`

This method is defined by View.

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

### select

`public function select(`Array/HTMLElement/String/Number nodeInfo`, [`Boolean keepExisting`], [`Boolean suppressEvent`])`
Selects nodes.
Parameters:

- `nodeInfo` : Array/HTMLElement/String/Number
  An HTMLElement template node, index of a template node, id of a template node or an array of any of those to select
- `keepExisting` : Boolean
  (optional) true to keep existing selections
- `suppressEvent` : Boolean
  (optional) true to skip firing of the selectionchange vent

Returns:

- `void`

This method is defined by View.

### setDataModel

`public function setDataModel(`DataModel dataModel`)`
Changes the data model this view uses and refresh the view.
Parameters:

- `dataModel` : DataModel

Returns:

- `void`

This method is defined by View.

### sort

`public function sort(`String property`, [`String direction`], [`Function sortType`])`
Sorts the data for this view and refreshes it.
Parameters:

- `property` : String
  A property on your JSON objects to sort on
- `direction` : String
  (optional) desc or asc (defaults to asc)
- `sortType` : Function
  (optional) A function to call to convert the data to a sortable value.

Returns:

- `void`

This method is defined by JsonView.

### unplugDataModel

`public function unplugDataModel(`DataModel dataModel`)`
Unplug the data model and stop updates.
Parameters:

- `dataModel` : DataModel

Returns:

- `void`

This method is defined by View.

## Event Details

### beforerender

`public event beforerender`
Fires before rendering of the downloaded json data.
Subscribers will be called with the following parameters:

- `this` : YAHOO.ext.View
- `data` : Object
  The json data loaded

This event is defined by JsonView.

### beforeselect

`public event beforeselect`
Fires before a selection is made. If any handlers return false, the selection is cancelled.
Subscribers will be called with the following parameters:

- `this` : YAHOO.ext.View
- `node` : HTMLElement
  The node to be selected
- `selections` : Array
  Array of currently selected nodes

This event is defined by View.

### click

`public event click`
Fires when a template node is clicked.
Subscribers will be called with the following parameters:

- `this` : YAHOO.ext.View
- `index` : Number
  The index of the target node
- `node` : HTMLElement
  The target node
- `e` : YAHOO.ext.EventObject
  The raw event object

This event is defined by View.

### contextmenu

`public event contextmenu`
Fires when a template node is right clicked.
Subscribers will be called with the following parameters:

- `this` : YAHOO.ext.View
- `index` : Number
  The index of the target node
- `node` : HTMLElement
  The target node
- `e` : YAHOO.ext.EventObject
  The raw event object

This event is defined by View.

### dblclick

`public event dblclick`
Fires when a template node is double clicked.
Subscribers will be called with the following parameters:

- `this` : YAHOO.ext.View
- `index` : Number
  The index of the target node
- `node` : HTMLElement
  The target node
- `e` : YAHOO.ext.EventObject
  The raw event object

This event is defined by View.

### load

`public event load`
Fires when data is loaded.
Subscribers will be called with the following parameters:

- `this` : YAHOO.ext.View
- `data` : Object
  The json data loaded
- `response` : Object
  The raw Connect response object

This event is defined by JsonView.

### loadexception

`public event loadexception`
Fires when loading fails.
Subscribers will be called with the following parameters:

- `this` : YAHOO.ext.View
- `response` : Object
  The raw Connect response object

This event is defined by JsonView.

### selectionchange

`public event selectionchange`
Fires when the selected nodes change.
Subscribers will be called with the following parameters:

- `this` : YAHOO.ext.View
- `selections` : Array
  Array of the selected nodes

This event is defined by View.

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