Class: c3.Table

Defined in:	js/c3-table.coffee
Inherits:	c3.Base

Overview

A visualization of data using HTML tables.

Like other c3 visualizations, call redraw() to update the table when the data array is changed and call restyle() to update the table when styles or classes in the various options are changed. If the set of columns is changed, then please call render() to update the table; this flow has not been tested yet, but I can fix any issues that come up if this is needed.

Events

select - Triggered when a row is selected/unselected. The event is called with an argument that is an array of the selections. Items are references to selected data elements. single select tables are passed with their selection while multi select tables are passed with an array of the selections. Selections are references to items in the data array.
found - Triggered when a search is performed. The event is called with the search string, the datum for the row, and the row index. If there was no match, the datum and index will be null. The match event is deprecated.

Extensibility

The following members are created which represent c3.Selection's:

table - The HTML table
header - The HTML table thead header
headers - The individual th headers in the header row
body - The HTML table tbody body
rows - The HTML table tr rows
cells - The HTML table td cells

The following additional members are also created:

selections - [Array] The current table selections. Items point to entries in the table's data array.

Author:

Douglas Armstrong

Variables Summary

version =

0.1

type =

'table'

data =

[]

[Array] Array of data for the table to visualize. Each element that is defined would be a seperate row in the table.

key =

undefined

[Function] An optional callback to describe a unique key for each data element. These may be used to affect performance when updating the dataset and for animations.

filter =

undefined

[Function] A callback to define if data elements should be included in the table or not. For example, this could be set to a function that returns true for data elements with some non-zero value to cause elements with a zero value to not be included in the table.

columns =

[]

[Array<c3.Table.Column>] An array of column objects which describe how to construct the table. Column objects can contain the following members:

header [c3.Selection.Options] Options to describe the header contents, styles, events, etc. Use text or html to define the content for the header. Column headers are optional.
cells [c3.Selection.Options] Options to describe the cell contents, styles, events, etc. Use text or html to define the cell contents.
sortable [Boolean] - Boolean to define if the counter should be user-sortable by clicking on the header.
value [Function] - A callback to get the value of the cell for sorting or visualization.
sort [Function] - A callback to get the value for sorting, if different then value; also sets sortable to true.
sort_ascending [Boolean] - Sort the rows based on ascending value instead of descending.
vis [String] Optional type of visualization for the value of the cells in this column. Options include:
- bar - The value is represented as a horizontal bar across the cell underlying the content html. The bars may be styled using _vis_options.styles_.
total_value [Number, Function] - Some visualizations, such as bar, show their values relative to some total value. This number or callback provides for that value. If not set, the default is to use the sum of values for all the cells in the column.
vis_options [c3.Selection.Options] Options that may be used by value visualizations. Using the Table-level vis_options should perform better than column-specific options.

selectable =

false

[Boolean, String] Enable the table rows to be selectable based on the value:

true - Click to select a single row or ctrl-click on Windows and command-click on OSX to select multiple rows.
"single" - A single row can be selected.
"multi" - Multiple rows can be selected.

selections =

undefined

[Array] Specify any initial row selections as an array of rows.

sortable =

false

[Boolean] Enable the table rows to be user-sortable. Define the sortable property of the column object to enable sorting by that column. The value column property should then define a callback to specify the value to be used for sorting. If you would like a different value for sorting purposes then the sort property of the column object can be used. The table can still be sorted with sort_column even if the user is not allowed to change how it is sorted with sortable.

sort_column =

undefined

[{c3.Table.Column}, String] Specify the initial column to sort the table by. The column object should have the sort property set to define a value to sort on. The sort_column may be specified either as the column object directly or as a string to lookup the header text or html at render-time. This property will be updated to refer to the current column object being sorted on. sort_column can be set to sort the table even if the table and/or column is not sortable to allow user-configurable sorting.

limit_rows =

undefined

[Number] Limit the number of table rows to the top N

pagination =

false

[Boolean] Enable control for user paging between multiple pages when the table size is limited with limit_rows. The pagination footer will only render if there is more than one page.

page =

undefined

[Number] The curernt page of a paginated table

max_pages_in_paginator =

[Number] Maximum number of pages to show at a time in the footer pagination selection. Minimum value is 3.

searchable =

false

[Boolean, Function] Set to enable searching in the footer. If set to true, then the content of all columns will be searched. Otherwise, it can be set to an accessor function that will be called with the row data and index. This function should return the string content of the row to be used for searching. If a match is found the current page is changed so the found row is visible. The found event will be triggered with the search string used. If a match was found the second and third arguments will be the row data and index of the match, otherwise they will be null. If a table is both searchable and selectable the event found event handler will default to selecting the row; this may be overriden. The user may use regular expressions in their search string.

searchable_if_not_paginated =

true

[Boolean] Allow table to be searchable even if it isn't paginated

table_options =

undefined

[c3.Selection.Options] Options for the table node.

table_header_options =

undefined

[c3.Selection.Options] Options for the table thead header.

header_options =

undefined

[c3.Selection.Options] Options for the table th headers. Callbacks are called with two arguments: The first is the column object and the second is the column index.

footer_options =

undefined

[c3.Selection.Options] Options for the table caption footer used for pagination.

table_body_options =

undefined

[c3.Selection.Options] Options for the table tbody.

row_options =

undefined

[c3.Selection.Options] Options for the table tr rows. Callbacks are called with two arguments. The first is the data element, the second is the row index.

A column_options options could be created using col to specify options for each column instead of manually specifying in each column object in columns. If this is needed, just let me know.

cell_options =

undefined

[c3.Selection.Options] Options for the table td cells. Callbacks are called with three arguments. The first is the data element, the second is the column index, and the third is the row index.

vis_options =

undefined

[c3.Selection.Options] Options for any vis visualizations, such as inline bar charts. Callbacks are called with the first argument as the data element, the second as the column index, and the third as the row index.

Variable inherited from c3.Base

_next_uid anchor height width anchor_styles handlers

Class Method Summary

. (Array) set_select(set, item, multi_select) Helper logic for selecting an item in a multiple-select list with a click or ctrl-click

Instance Method Summary

# (void) _init() Bound
# (void) _update_headers() Bound
# (void) _update(origin) Bound
# (void) _style(style_new) Bound
# (void) sort(column, ascending) Bound Sort the table
# (void) highlight(selections = @selections) Bound Update the visual selection in the table without triggering selection event
# (void) select(selections = @selections) Bound Select items in the table and trigger the selection event
# (?) search(value) Bound Find will find the specified string value in the table and set the current page for it to be visible This method will not trigger any events, unlike find().
# (?) find(value) Bound Search will find a string in the table, same as search() except that it will also trigger the found event

Inherited Method Summary

Methods inherited from c3.Base

#render #resize #redraw #restyle #init #_prep #_init #size #_size #update #_update #draw #_draw #style #_style

Class Method Details

. (Array) set_select(set, item, multi_select)

Helper logic for selecting an item in a multiple-select list with a click or ctrl-click

Parameters:

set ( Array ) — An array of items that represents the current selection
item ( Object ) — A new item to add or remove from the current selection
multi_select ( Boolean ) — Indicate if multiple selections are allowed

Returns:

( Array ) — This returns the new set, but also modifys the set passed in, so old references are still valid

Constructor Details

# (void) constructor()

Instance Method Details

# (void) _init() Bound

# (void) _update_headers() Bound

# (void) _update(origin) Bound

# (void) _style(style_new) Bound

# (void) sort(column, ascending) Bound

Sort the table

Parameters:

column ( column ) — A reference to the column object to sort on
ascending ( Boolean ) — True to sort top to bottom based on ascending values, otherwise alternate on subsequent calls to sorting on the same column.

# (void) highlight(selections = @selections) Bound

Update the visual selection in the table without triggering selection event

Parameters:

selections ( Array ) — An array of items to select referencing items in the data array

# (void) select(selections = @selections) Bound

Select items in the table and trigger the selection event

Parameters:

selections ( Array ) — An array of items to select referencing items in the data array

# (?) search(value) Bound

Find will find the specified string value in the table and set the current page for it to be visible This method will not trigger any events, unlike find().

Parameters:

value ( String ) — string to search for

Returns:

( ? ) — An array of the data element found and its index in the data array or null if not found

# (?) find(value) Bound

Search will find a string in the table, same as search() except that it will also trigger the found event

Parameters:

value ( String ) — string to search for

Returns:

( ? ) — An array of the data element found and its index in the data array