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	View
	jsonRoot : String	View
	The root property in the loaded json object that contains the data	View
	selectedClass : YAHOO.ext.DomHelper.Template	View
	The css class to add to selected nodes	View
	tpl : YAHOO.ext.DomHelper.Template	View
	The template used by this View	View

Public Methods

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

Public Events

Event		Defined By
	beforerender : (`YAHOO.ext.View this`, `Object data`)	JsonView
	Fires before rendering of the downloaded json data.	JsonView
	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.	View
	click : (`YAHOO.ext.View this`, `Number index`, `HTMLElement node`, `YAHOO.ext.EventObject e`)	View
	Fires when a template node is clicked.	View
	contextmenu : (`YAHOO.ext.View this`, `Number index`, `HTMLElement node`, `YAHOO.ext.EventObject e`)	View
	Fires when a template node is right clicked.	View
	dblclick : (`YAHOO.ext.View this`, `Number index`, `HTMLElement node`, `YAHOO.ext.EventObject e`)	View
	Fires when a template node is double clicked.	View
	load : (`YAHOO.ext.View this`, `Object data`, `Object response`)	JsonView
	Fires when data is loaded.	JsonView
	loadexception : (`YAHOO.ext.View this`, `Object response`)	JsonView
	Fires when loading fails.	JsonView
	selectionchange : (`YAHOO.ext.View this`, `Array selections`)	View
	Fires when the selected nodes change.	View

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.