Class RapidContext.Widget.Table

.Widget.Table(attrs, …childopt) → {Widget}

The table widget class. Used to provide a sortable and scrolling data table, using an outer <div> HTML element around a <table>. The Table widget can only have TableColumn child nodes, each providing a visible data column in the table.

Constructor Summary
	`new Table(attrs, …childopt) → {Widget}` Creates a new data table widget.

Method Summary
	`addAll(…child)` Adds one or more children to this widget.
	`addChildNode(child)` Adds a single child table column widget to this widget.
	`addClass(…cls)` Adds the specified CSS class names to this HTML DOM node.
	`addSelectedIds(…id) → {Array}` Adds the specified row id values to the selection.
	`animate(opts)` Performs a visual effect animation on this widget.
	`blurAll()` Blurs (unfocuses) this DOM node and all relevant child nodes.
	`clear()` Clears all the data in the table.
	`destroy()` Destroys this widget.
	`disable()` Disables this widget if it was previously enabled.
	`enable()` Enables this widget if it was previously disabled.
	`getCellElem(row, col) → {Node}` Returns a table cell element.
	`getChildNodes() → {Array}` Returns an array with all child DOM nodes.
	`getColumnIndex(field) → {number}` Returns the column index of a field.
	`getData() → {Array}` Returns an array with the data in the table.
	`getIdKey() → {string}` Returns the unique key identifier column field, or null if none was set.
	`getRowCount() → {number}` Returns the number of rows in the table.
	`getRowId(index) → {string}` Returns the row id for the specified row index.
	`getSelectedData() → {Object\|Array}` Returns the currently selected row data.
	`getSelectedIds() → {Array}` Returns the currently selected row ids.
	`getSortKey() → {string}` Returns the current sort key for the table.
	`hasClass(…cls) → {boolean}` Checks if this HTML DOM node has the specified CSS class names.
	`hide()` Hides this widget node if it was previously visible.
	`isDisabled() → {boolean}` Checks if this widget is disabled.
	`isHidden() → {boolean}` Checks if this widget node is hidden.
	`redraw()` Redraws the table from updated source data.
	`removeAll()` Removes all children to this widget.
	`removeChildNode(child)` Removes a single child table column widget from this widget.
	`removeClass(…cls)` Removes the specified CSS class names from this HTML DOM node.
	`removeSelectedIds(…id) → {Array}` Removes the specified row id values from the selection.
	`setAttrs(attrs)` Updates the widget or HTML DOM node attributes.
	`setData(data)` Sets the table data.
	`setIdKey(key)` Sets the unique key identifier column field.
	`setSelectedIds(…id) → {Array}` Sets the selection to the specified row id values.
	`setStyle(styles)` Updates the CSS styles of this HTML DOM node.
	`show()` Shows this widget node if it was previously hidden.
	`sortData(field, directionopt)` Sorts the table data by field and direction.
	`toggleClass(…cls) → {boolean}` Toggles adding and removing the specified CSS class names to and from this HTML DOM node.
	`uid() → {string}` Returns the unique identifier for this DOM node.

Event Summary
	`onclear` Emitted when the table data is cleared.
	`onselect` Emitted when the table selection changes.

Constructor

new Table(attrs, …childopt) → {Widget}

Creates a new data table widget.

Parameters:

Name Type Attributes Description

attrs

{Object}

the widget and node attributes

Properties

Name	Type	Attributes	Description
`select`	{string}	<optional>	the row selection mode ('none', 'one', 'multiple' or 'auto'), defaults to 'one'
`key`	{string}	<optional>	the unique key identifier column field, defaults to null
`hidden`	{boolean}	<optional>	the hidden widget flag, defaults to false

child {TableColumn} <optional>
<repeatable> the child table columns

Returns:

{Widget} the widget DOM node

Examples:

JavaScript

var attrs1 = { field: "id", title: "Identifier", key: true, type: "number" };
var attrs2 = { field: "name", title: "Name", maxLength: 50, sort: "asc" };
var attrs3 = { field: "modified", title: "Last Modified", type: "datetime" };
var col1 = RapidContext.Widget.TableColumn(attrs1);
var col2 = RapidContext.Widget.TableColumn(attrs2);
var col3 = RapidContext.Widget.TableColumn(attrs3);
var exampleTable = RapidContext.Widget.Table({}, col1, col2, col3);
RapidContext.Util.registerSizeConstraints(exampleTable, "50%", "100%");

User Interface XML

<Table id="exampleTable" w="50%" h="100%">
  <TableColumn field="id" title="Identifier" key="true" type="number" />
  <TableColumn field="name" title="Name" maxLength="50" sort="asc" />
  <TableColumn field="modified" title="Last Modified" type="datetime" />
</Table>

Source:

RapidContext_Widget_Table.js, line 58

Extends

RapidContext.Widget

Methods

addAll(…child)

Adds one or more children to this widget. This method will flatten any arrays among the arguments and ignores any null or undefined arguments. Any DOM nodes or widgets will be added to the end, and other objects will be converted to a text node first. Subclasses should normally override the addChildNode() method instead of this one, since that is the basis for DOM node insertion.

Parameters:

Name	Type	Attributes	Description
`child`	{string\|Node\|Array}	<repeatable>	the children to add

Inherited From:

RapidContext.Widget#addAll

Source:

RapidContext_Widget.js, line 570

addChildNode(child)

Adds a single child table column widget to this widget.

Parameters:

Name	Type	Description
`child`	{Widget}	the table column widget to add

Overrides:

RapidContext.Widget#addChildNode

Source:

RapidContext_Widget_Table.js, line 196

addClass(…cls)

Adds the specified CSS class names to this HTML DOM node.

Parameters:

Name	Type	Attributes	Description
`cls`	{string\|Array}	<repeatable>	the CSS class names to add

Inherited From:

RapidContext.Widget#addClass

Source:

RapidContext_Widget.js, line 333

addSelectedIds(…id) → {Array}

Adds the specified row id values to the selection. If the current selection is changed the select signal will be emitted.

Parameters:

Name	Type	Attributes	Description
`id`	{string\|Array}	<repeatable>	the row ids or array with ids to select

Returns:

{Array} an array with the new row ids actually selected

Source:

RapidContext_Widget_Table.js, line 535

animate(opts)

Performs a visual effect animation on this widget. This is implemented using the MochiKit.Visual effect package. All options sent to this function will be passed on to the appropriate MochiKit.Visual function.

Parameters:

Name Type Description

opts

{Object}

the visual effect options

Properties

Name	Type	Description
`effect`	{string}	the MochiKit.Visual effect name
`queue`	{string}	the MochiKit.Visual queue handling, defaults to "replace" and a unique scope for each widget (see `MochiKit.Visual` for full options)

Inherited From:

RapidContext.Widget#animate

Deprecated:

Use CSS animations instead.

Example:

widget.animate({ effect: "fade", duration: 0.5 });
widget.animate({ effect: "Move", transition: "spring", y: 300 });

Source:

RapidContext_Widget.js, line 492

blurAll()

Blurs (unfocuses) this DOM node and all relevant child nodes. This function will recursively blur all <a>, <button>, <input>, <textarea> and <select> child nodes found.

Inherited From:: RapidContext.Widget#blurAll
Source:: RapidContext_Widget.js, line 510

clear()

Clears all the data in the table. The column headers will not be affected by this method. Use removeAll() or removeChildNode() to also remove columns.

Source:: RapidContext_Widget_Table.js, line 310

destroy()

Destroys this widget.

Overrides:: RapidContext.Widget#destroy
Source:: RapidContext_Widget_Table.js, line 100

disable()

Disables this widget if it was previously enabled. This method is equivalent to calling setAttrs({ disabled: true }).

Inherited From:: RapidContext.Widget#disable
Source:: RapidContext_Widget.js, line 424

enable()

Enables this widget if it was previously disabled. This is equivalent to calling setAttrs({ disabled: false }).

Inherited From:: RapidContext.Widget#enable
Source:: RapidContext_Widget.js, line 416

getCellElem(row, col) → {Node}

Returns a table cell element.

Parameters:

Name	Type	Description
`row`	{number}	the row index
`col`	{number}	the column index

Returns:

{Node} the table cell element node, or null if not found

Source:

RapidContext_Widget_Table.js, line 295

getChildNodes() → {Array}

Returns an array with all child DOM nodes. Note that the array is a real JavaScript array, not a dynamic NodeList. This method is sometimes overridden by child widgets in order to hide intermediate DOM nodes required by the widget.

Returns:: {Array} the array of child DOM nodes
Inherited From:: RapidContext.Widget#getChildNodes
Source:: RapidContext_Widget.js, line 522

getColumnIndex(field) → {number}

Returns the column index of a field.

Parameters:

Name	Type	Description
`field`	{string}	the field name

Returns:

{number} the column index, or -1 if not found

Source:

RapidContext_Widget_Table.js, line 223

getData() → {Array}

Returns an array with the data in the table. The array returned should correspond exactly to the one previously set, i.e. it has not been sorted or modified in other ways.

Returns:: {Array} an array with the data in the table
Source:: RapidContext_Widget_Table.js, line 321

getIdKey() → {string}

Returns the unique key identifier column field, or null if none was set.

Returns:: {string} the key column field name, or null for none
Source:: RapidContext_Widget_Table.js, line 240

getRowCount() → {number}

Returns the number of rows in the table. This is a convenience method for getData().length.

Returns:: {number} the number of table rows
Source:: RapidContext_Widget_Table.js, line 451

getRowId(index) → {string}

Returns the row id for the specified row index. If the row index is out of bounds, null will be returned. The row ids are the data values from the key column, or automatically generated internal values if no key column is set. Note that the row index uses the current table sort order.

Parameters:

Name	Type	Description
`index`	{number}	the row index, 0 <= index < row count

Returns:

{string} the unique row id, or null if not found

Source:

RapidContext_Widget_Table.js, line 466

getSelectedData() → {Object|Array}

Returns the currently selected row data.

Returns:: {Object|Array} the data row selected, or an array of selected data rows if multiple selection is enabled
Source:: RapidContext_Widget_Table.js, line 489

getSelectedIds() → {Array}

Returns the currently selected row ids. If no rows are selected, an empty array will be returned. The row ids are the data values from the key column, or automatically generated internal values if no key column is set.

Returns:: {Array} an array with the selected row ids
Source:: RapidContext_Widget_Table.js, line 479

getSortKey() → {string}

Returns the current sort key for the table.

Returns:: {string} the current sort field, or null for none
Source:: RapidContext_Widget_Table.js, line 276

hasClass(…cls) → {boolean}

Checks if this HTML DOM node has the specified CSS class names. Note that more than one CSS class name may be checked, in which case all must be present.

Parameters:

Name	Type	Attributes	Description
`cls`	{string\|Array}	<repeatable>	the CSS class names to check

Returns:

{boolean} true if all CSS classes were present, or false otherwise

Inherited From:

RapidContext.Widget#hasClass

Source:

RapidContext_Widget.js, line 315

hide()

Hides this widget node if it was previously visible. This method is equivalent to calling setAttrs({ hidden: true }). It is safe for all types of widgets, since it only adds the widgetHidden CSS class instead of setting the display style property.

Inherited From:: RapidContext.Widget#hide
Source:: RapidContext_Widget.js, line 470

isDisabled() → {boolean}

Checks if this widget is disabled. This method checks both the "widgetDisabled" CSS class and the disabled property. Changes to the disabled status can be made with enable(), disable() or setAttrs().

Returns:: {boolean} true if the widget is disabled, or false otherwise
Inherited From:: RapidContext.Widget#isDisabled
Source:: RapidContext_Widget.js, line 395

isHidden() → {boolean}

Checks if this widget node is hidden. This method checks for the existence of the widgetHidden CSS class. It does NOT check the actual widget visibility (the display style property set by animations for example).

Returns:: {boolean} true if the widget is hidden, or false otherwise
Inherited From:: RapidContext.Widget#isHidden
Source:: RapidContext_Widget.js, line 437

redraw()

Redraws the table from updated source data. Note that this method will not add or remove rows and keeps the current row order intact. For a more complete redraw of the table, use setData().

Source:: RapidContext_Widget_Table.js, line 413

removeAll()

Removes all children to this widget. This method will also destroy and child widgets and disconnect all signal listeners. This method uses the getChildNodes() and removeChildNode() methods to find and remove the individual child nodes.

Inherited From:: RapidContext.Widget#removeAll
Source:: RapidContext_Widget.js, line 582

removeChildNode(child)

Removes a single child table column widget from this widget. This will also clear all the data in the table.

Parameters:

Name	Type	Description
`child`	{Widget}	the table column widget to remove

Overrides:

RapidContext.Widget#removeChildNode

Source:

RapidContext_Widget_Table.js, line 210

removeClass(…cls)

Removes the specified CSS class names from this HTML DOM node. Note that this method will not remove any class starting with "widget".

Parameters:

Name	Type	Attributes	Description
`cls`	{string\|Array}	<repeatable>	the CSS class names to remove

Inherited From:

RapidContext.Widget#removeClass

Source:

RapidContext_Widget.js, line 353

removeSelectedIds(…id) → {Array}

Removes the specified row id values from the selection. If the current selection is changed the select signal will be emitted.

Parameters:

Name	Type	Attributes	Description
`id`	{string\|Array}	<repeatable>	the row ids or array with ids to unselect

Returns:

{Array} an array with the row ids actually unselected

Source:

RapidContext_Widget_Table.js, line 573

setAttrs(attrs)

Updates the widget or HTML DOM node attributes.

Parameters:

Name Type Description

attrs

{Object}

the widget and node attributes to set

Properties

Name	Type	Attributes	Description
`select`	{string}	<optional>	the row selection mode ('none', 'one' or 'multiple')
`key`	{string}	<optional>	the unique key identifier column field
`hidden`	{boolean}	<optional>	the hidden widget flag

Overrides:

RapidContext.Widget#setAttrs

Source:

RapidContext_Widget_Table.js, line 179

setData(data)

Sets the table data. The table data is an array of objects, each having properties corresponding to the table column fields. Any object property not mapped to a table column will be ignored (i.e. a hidden column). See the TableColumn class for data mapping details. Note that automatically generated row ids will be reset by this method and any selection on such tables is lost.

Parameters:

Name	Type	Description
`data`	{Array}	an array with data objects

Example:

var data = [
    { id: 1, name: "John Doe", modified: "@1300000000000" },
    { id: 2, name: "First Last", modified: new Date() },
    { id: 3, name: "Another Name", modified: "2004-11-30 13:33:20" }
];
table.setData(data);

Source:

RapidContext_Widget_Table.js, line 343

setIdKey(key)

Sets the unique key identifier column field. Note that this method will regenerate all row identifiers if the table already contains data.

Parameters:

Name	Type	Description
`key`	{string}	the new key column field name

Source:

RapidContext_Widget_Table.js, line 260

setSelectedIds(…id) → {Array}

Sets the selection to the specified row id values. If the current selection is changed the select signal will be emitted.

Parameters:

Name	Type	Attributes	Description
`id`	{string\|Array}	<repeatable>	the row ids or array with ids to select

Returns:

{Array} an array with the row ids actually modified

Source:

RapidContext_Widget_Table.js, line 502

setStyle(styles)

Updates the CSS styles of this HTML DOM node. This method is identical to MochiKit.Style.setStyle, but uses "this" as the first argument.

Parameters:

Name	Type	Description
`styles`	{Object}	an object with the styles to set

Inherited From:

RapidContext.Widget#setStyle

Example:

widget.setStyle({ "font-size": "bold", "color": "red" });

Source:

RapidContext_Widget.js, line 294

show()

Shows this widget node if it was previously hidden. This method is equivalent to calling setAttrs({ hidden: false }). It is safe for all types of widgets, since it only removes the widgetHidden CSS class instead of setting the display style property.

Inherited From:: RapidContext.Widget#show
Source:: RapidContext_Widget.js, line 460

sortData(field, directionopt)

Sorts the table data by field and direction.

Parameters:

Name	Type	Attributes	Description
`field`	{string}		the sort field
`direction`	{string}	<optional>	the sort direction, either "asc" or "desc"

Source:

RapidContext_Widget_Table.js, line 383

toggleClass(…cls) → {boolean}

Toggles adding and removing the specified CSS class names to and from this HTML DOM node. If all the CSS classes are already set, they will be removed. Otherwise they will be added.

Parameters:

Name	Type	Attributes	Description
`cls`	{string\|Array}	<repeatable>	the CSS class names to remove

Returns:

{boolean} true if the CSS classes were added, or false otherwise

Inherited From:

RapidContext.Widget#toggleClass

Source:

RapidContext_Widget.js, line 376

uid() → {string}

Returns the unique identifier for this DOM node. If a node id has already been set, that id will be returned. Otherwise a new id will be generated and assigned to the widget DOM node.

Returns:: {string} the the unique DOM node identifier
Inherited From:: RapidContext.Widget#uid
Source:: RapidContext_Widget.js, line 182

Events

onclear

Emitted when the table data is cleared.

Source:: RapidContext_Widget_Table.js, line 83

onselect

Emitted when the table selection changes.

Source:: RapidContext_Widget_Table.js, line 90