Class jabberwerx.ui.RosterView

View over an EntitySet (oftimes referred to as a "roster").

This class provides the following events:

Class Summary
Constructor Attributes	Constructor Name and Description
	jabberwerx.ui.RosterView(cache, mode) Creates a new RosterView with the given cache and mode.

Field Summary
Field Attributes	Field Name and Description
	cache The `EntitySet` cache this `RosterView` is a view for.
<static>	jabberwerx.ui.RosterView.groupmode_collapsed Mode for a collapsed grouping.
<static>	jabberwerx.ui.RosterView.groupmode_expanded Mode for an expanded grouping.
<static>	jabberwerx.ui.RosterView.groupmode_single Mode for a "single-mode" grouping.

Fields borrowed from class jabberwerx.ui.JWView:: jq

Method Summary
Method Attributes	Method Name and Description
	addFilter(filter) Adds a filter for the contents of the RosterView.
	clearFilters() Removes all of the filters.
	createDOM(doc) Creates the DOM for this `RosterView`.
	destroy() Destroys this `RosterView`.
	destroyDOM(doc) Destroys the DOM for this `RosterView`.
	filterByActive(entity) Function that can be used to filter entities that aren't online.
	filterByContacts(entity) Function that can be used to filter entities that aren't contacts (i.e.
	getDefaultGroupingName() Retrieves the default grouping display name.
	graphUnserialized()
	groupByGroups(entity) Retrieves the groups for this Entity
	grouping(name) Retrieves the grouping for the given name.
	removeFilter(filter) Removes a filter from the RosterView.
	setDefaultGroupingName(name) Changes the default grouping display name.
	setSort(sort) Sets the sort function for the entities.
	sortByDisplayName(a, b) Compare two entities by display Name
	sortEntityByDisplayName(a, b) Function that can be used for sorting to compare two entites by display name.
	update() Updates this `RosterView`'s display.

Methods borrowed from class jabberwerx.ui.JWView:: dimensions, height, hide, parent, persistOptions, remove, render, restoreDOM, restoreRender, restoreUpdate, shouldBeSavedWithGraph, show, wasUnserialized, width, willBeSerialized
Methods borrowed from class jabberwerx.JWModel:: applyEvent, event
Methods borrowed from class jabberwerx.JWBase:: getClassName, init, invocation, shouldBeSerializedInline, toString

Class Detail

jabberwerx.ui.RosterView(cache, mode)

Creates a new RosterView with the given cache and mode. If {mode} is .groupmode_single, then the display is effectively a flat list of all entities. Otherewise, the display consists of zero or more groupings that contain entities.

Parameters:
{jabberwerx.EntitySet} cache: The cache
{Number} mode Optional: The default group mode (one of jabberwerx.ui.RosterView.groupmode_collapsed, jabberwerx.ui.RosterView.groupmode_expanded, or jabberwerx.ui.RosterView.groupmode_single)

Throws:
{TypeError}: If {cache} is not an instance of EntitySet; or if {mode} is not an accepted value

Field Detail

{jabberwerx.EntitySet} cache

The EntitySet cache this RosterView is a view for.

<static> jabberwerx.ui.RosterView.groupmode_collapsed

Mode for a collapsed grouping.

<static> jabberwerx.ui.RosterView.groupmode_expanded

Mode for an expanded grouping.

<static> jabberwerx.ui.RosterView.groupmode_single

Mode for a "single-mode" grouping.

Method Detail

addFilter(filter)

Adds a filter for the contents of the RosterView. Multiple filters can be applied. If one filter says an entry should be hidden, the entry becomes hidden. Another filter cannot override that.

Parameters:
{function} filter: A function that takes an Entity and returns false if the entry should be hidden.

Throws:
{TypeError}: If {filter} is not a function

clearFilters()

Removes all of the filters.

{Element} createDOM(doc)

Creates the DOM for this RosterView. This method creates the following basic structure:

<div class='jabberwerx roster'></div>

If #cache contains any groupings, each is rendered and appended to the container <div/>.

Parameters:
{Document} doc: The owning document

Returns:: {Element} The DOM for this RosterView

destroy()

Destroys this RosterView. This method unbinds all callbacks before calling the superclass' implementation.

destroyDOM(doc)

Destroys the DOM for this RosterView. This implementation iterates through all the groupings, calling jabberwerx.ui.RosterView.Grouping#destroy.

Parameters:
doc

{Boolean} filterByActive(entity)

Function that can be used to filter entities that aren't online.

Parameters:
{jabberwerx.Entity} entity: The contact/roster

Returns:: {Boolean} true if {entity} is active

{Boolean} filterByContacts(entity)

Function that can be used to filter entities that aren't contacts (i.e. local user and the server).

Parameters:
{jabberwerx.Entity} entity: The contact/roster

Returns:: {Boolean} true if {entity} is an instance of jabberwerx.Contact

{String} getDefaultGroupingName()

Retrieves the default grouping display name. This is the value displayed in the DOM for the "" grouping.

This is not linked to jabberwerx.RosterController.defaultGroup.

Returns:: {String} The default grouping name

graphUnserialized()

{String[]} groupByGroups(entity)

Retrieves the groups for this Entity

Parameters:
{jabberwerx.Entity} entity: The Entity

Returns:: {String[]} The array of groups

{jabberwerx.ui.RosterView.Grouping} grouping(name)

Retrieves the grouping for the given name.

Parameters:
{String} name: The grouping name (or "" for the default grouping name).

Returns:: {jabberwerx.ui.RosterView.Grouping} The grouping for the given name, or {null} if not found

removeFilter(filter)

Removes a filter from the RosterView.

Parameters:
{function} filter: The function that was passed into jabberwerx.ui.RosterView#addFilter that should be removed.

setDefaultGroupingName(name)

Changes the default grouping display name. If {name} is not equal to the current value, it is changed to {name} and the default grouping (if any) is updated.

Parameters:
{String} name: The new default grouping name

Throws:
{TypeError}: If {name} is not a valid non-empty string.

setSort(sort)

Sets the sort function for the entities. Pass in nothing if you want to clear the sort function.

Parameters:
{function} sort: The function called to compare two entities. The function takes two parameters, both entities, and returns -1 if the first one is less than the second one, 1 if the first one is greater than the second one and 0 if they are equal.

Throws:
{TypeError}: If {sort} is not a function or null

{Number} sortByDisplayName(a, b)

Compare two entities by display Name

Parameters:
{jabberwerx.Entity} a: The contact/roster
{jabberwerx.Entity} b: The contact/roster

Returns:: {Number} Returns 0 if {a}={b}; 1 if {a}>{b}; otherwise returns -1

{Number} sortEntityByDisplayName(a, b)

Function that can be used for sorting to compare two entites by display name.

Parameters:
{jabberwerx.Entity} a: The contact/roster
{jabberwerx.Entity} b: The contact/roster

Returns:: {Number} Returns 0 if equals; 1 if greater; -1 if less

{Boolean} update()

Updates this RosterView's display. This implementation walks the current groupings, inserting any missing into this RosterView's DOM, then calling jabberwerx.ui.RosterView.Grouping#update.

Returns:: {Boolean} true if this RosterView is updatable

Classes

Class jabberwerx.ui.RosterView