Origami Frontend Components & Services

JSDoc: o-table

new CellFormatter

Methods to format table cells for sorting.

Methods

Links

new TableSorter

Provides methods to sort table instances.

Methods

Links

new BaseTable(...)

The shared functionality of all `o-table` variants.

parameter type default description
rootEl HTMLElement The `o-table` element.
sorter TableSorter
opts Object [{}]
opts.sortable Bool [true]

Methods

  • updateRows - (instance) Update the o-table instance with rows added or removed dynamically from the table. Applies any existing sort and filter to new rows.
  • renderRowUpdates - (instance) Updates the dom to account for row updates, including when their sort order changes, or any filter is applied. E.g. changes the dom order, applies aria-labels to hidden rows, updates the table height to efficiently hide them. Note this does not calculate which rows should be sorted or filtered, and does not look for new rows added to the dom. See `updateRows`.
  • filter(headerIndex, filter) - (instance) Filter the table and render the result.
  • getTableHeader(columnIndex) - (instance) Gets a table header for a given column index.
  • sortRowsByColumn(columnIndex, sortOrder) - (instance) Sort the table.
  • addSortButtons - (instance) Add sort buttons to the DOM within the table header.
  • sorted(...) - (instance) Indicate that the table has been sorted after intercepting the sorting event.
  • destroy - (instance) Gets the instance ready for deletion. Removes event listeners that were added during instatiation of the component.

Links

new BasicTable(...)

Initialises an `o-table` component without responsive behaviour.

parameter type default description
rootEl HTMLElement The `o-table` element.
sorter TableSorter
opts Object [{}]
opts.sortable Bool [true]

Links

new FlatTable(...)

Initialises an `o-table` component with "flat" responsive behaviour.

parameter type default description
rootEl HTMLElement The `o-table` element.
sorter TableSorter
opts Object [{}]
opts.sortable Bool [true]

Methods

  • updateRows - (instance) Update the o-table instance with rows added dynamically to the table.

Links

new OverflowTable(...)

Initialises an `o-table` component with "overflow" responsive behaviour.

parameter type default description
rootEl HTMLElement The `o-table` element.
sorter TableSorter
opts Object [{}]
opts.sortable Bool [true]
opts.expanded Undefined | Bool
opts.minimumRowCount Number [20]

Methods

  • filter(headerIndex, filter) - (instance) Filter the table.
  • isExpanded - (instance) Check if the table is expanded (true) or collapsed (false).
  • isContracted - (instance) Check if the table is collapsed (true) or expanded (false).
  • canExpand - (instance) Check if the table supports the expand/contract feature.
  • renderRowUpdates - (instance) Updates the dom to account for row updates.
  • contractTable - (instance) Hides table rows if the table can be expanded.
  • expandTable - (instance) Expands the table, revealing hidden table rows, if it can be expanded and has been contracted.

Links

new ScrollTable(...)

Initialises an `o-table` component with "scroll" responsive behaviour.

parameter type default description
rootEl HTMLElement The `o-table` element.
sorter TableSorter
opts Object [{}]
opts.sortable Bool [true]

Methods

Links

new OTable(rootEl, opts)

Constructs an o-table component.

parameter type default description
rootEl HTMLElement An o-table element.
opts OTable~opts A table options object.

Methods

Links

formatFunction(cell)

The `formatFunction` take the table cell HTMLElement, and converts it to a String or Number of sorting.

parameter type default description
cell HTMLElement

Returns

  • String | Object

Type

function

Links

formatFunction(cell)

The custom formatter accepts a table cell and returns a sort value for that cell. This could be used to define a custom sort order for an unsupported format, such as emoji's, or a new date format.

parameter type default description
cell HTMLElement

Type

function

Links

CellFormatter#setFormatter(type, formatFunction)

Instance Method

parameter type default description
type String The data type of the cell to apply the filter function to.
formatFunction formatFunction The function to take the cell and return a sortable value (string/number).

Example

mySortFormatter.setFormatter('emoji-time', (cell) => {
 	const text = cell.textContent.trim();
 	if (text === '🌑') {
 		return 1;
 	}
 	if (text === '🌤️️') {
 		return 2;
 	}
 	return 0;
 });

Links

CellFormatter#formatCell(cell, type)

Instance Method

parameter type default description
cell HTMLElement
type String The data type of the cell, e.g. date, number, currency. Custom types are supported.

Returns

  • String | Number - A representation of cell which can be used for sorting.

Links

TableSorter#sortRowsByColumn(...)

Instance Method

Sort the given table.

parameter type default description
table BaseTable The table instance to sort.
columnIndex Number The index of the table column to sort.
sortOrder String How to sort the column, "ascending" or "descending"
batch Number [100] - Deprecated. No longer used. How many rows to render at once when sorting.

Returns

  • undefined

Links

TableSorter#setCellFormatterForType(type, formatFunction)

Instance Method

Set a custom cell formatter for a given data type.

parameter type default description
type String The data type to apply the filter function to.
formatFunction formatFunction Callback to format a table cell to a sort value.

Links

BaseTable#updateRows

Instance Method

Update the o-table instance with rows added or removed dynamically from the table. Applies any existing sort and filter to new rows.

Returns

  • undefined

Links

BaseTable#renderRowUpdates

Instance Method

Updates the dom to account for row updates, including when their sort order changes, or any filter is applied. E.g. changes the dom order, applies aria-labels to hidden rows, updates the table height to efficiently hide them.

Note this does not calculate which rows should be sorted or filtered, and does not look for new rows added to the dom. See updateRows.

Returns

  • undefined

Links

BaseTable#filter(headerIndex, filter)

Instance Method

Filter the table and render the result.

parameter type default description
headerIndex Number The index of the table column to filter.
filter String | function How to filter the column (either a string to match or a callback function).

Returns

  • undefined

Links

BaseTable#getTableHeader(columnIndex)

Instance Method

Gets a table header for a given column index.

parameter type default description
columnIndex Number The index of the table column to get the header for.

Returns

  • HTMLElement

Links

BaseTable#sortRowsByColumn(columnIndex, sortOrder)

Instance Method

Sort the table.

parameter type default description
columnIndex Number The index of the table column to sort.
sortOrder Number How to sort the column, "ascending" or "descending"

Returns

  • undefined

Links

<anonymous>~defaultSort

Inner Property

Fires an "oTable.sorting" event. The sorting event can be cancelled to provide a totally custom method of sorting the table. https://developer.mozilla.org/en-US/docs/Web/API/EventTarget/dispatchEvent

Links

BaseTable#addSortButtons

Instance Method

Add sort buttons to the DOM within the table header.

Returns

  • undefined

Links

BaseTable#sorted(...)

Instance Method

Indicate that the table has been sorted after intercepting the sorting event.

parameter type default description
sortDetails Object Details of the current sort state.
sortDetails.columnIndex Number | Null The index of the currently sorted column.
sortDetails.sortOrder String | Null The type of sort, "ascending" or "descending"

Links

BaseTable#destroy

Instance Method

Gets the instance ready for deletion. Removes event listeners that were added during instatiation of the component.

Returns

  • undefined

Links

FlatTable#updateRows

Instance Method

Update the o-table instance with rows added dynamically to the table.

Returns

  • undefined

Links

OverflowTable#filter(headerIndex, filter)

Instance Method

Filter the table.

parameter type default description
headerIndex Number The index of the table column to filter.
filter String | function How to filter the column (either a string to match or a callback function).

Returns

  • undefined

Links

OverflowTable#isExpanded

Instance Method

Check if the table is expanded (true) or collapsed (false).

Returns

  • Bool

Links

OverflowTable#isContracted

Instance Method

Check if the table is collapsed (true) or expanded (false).

Returns

  • Bool

Links

OverflowTable#canExpand

Instance Method

Check if the table supports the expand/contract feature.

Returns

  • Bool

Links

OverflowTable#renderRowUpdates

Instance Method

Updates the dom to account for row updates.

Returns

  • undefined

Links

OverflowTable#contractTable

Instance Method

Hides table rows if the table can be expanded.

Returns

  • - undefined

Links

OverflowTable#expandTable

Instance Method

Expands the table, revealing hidden table rows, if it can be expanded and has been contracted.

Returns

  • - undefined

Links

ScrollTable#filter(headerIndex, filter)

Instance Method

Filter the table.

parameter type default description
headerIndex Number The index of the table column to filter.
filter String | function How to filter the column (either a string to match or a callback function).

Returns

  • undefined

Links

ScrollTable#updateRows

Instance Method

Update the o-table instance with rows added dynamically to the table.

Returns

  • undefined

Links

OTable~opts

Table options.

Properties

  • sortable - (type: Bool) [true] - Disable the table's sort feature.
  • expanded - (types: Undefined | types: Bool) [Undefined] - Allow the "OverflowTable" to hide results behind a "show more" button. The table is expanded by default when "true", contracted when "false", or not expandable if not set.
  • minimumRowCount - (type: Number) [20] - When the `expanded` option is set, the number of rows to show when the table is not expanded.

Type

Object

Links

OTable.init(el, opts)

Static Method

Constructs all o-table components inside the element passed as the first parameter.

parameter type default description
el (optional) HTMLElement | string document.body Element where to search for o-table components. You can pass an HTMLElement or a selector string.
opts OTable~opts A table options object.

Returns

  • Array.<(FlatTable|ScrollTable|OverflowTable|BasicTable)> | FlatTable | ScrollTable | OverflowTable | BasicTable - - A table instance or array of table instances.

Links

OTable.setSortFormatterForType(type, formatFunction)

Static Method

Set a custom sort formatter for a given data type.

parameter type default description
type String The data type to apply the filter function to.
formatFunction formatFunction

Example

Mapping table cells which contain emojis to a numerical sort value.

	const OTable = require('o-table');
	// Set a filter for custom data type "emoji-time".
	// The return value may be a string or number.
	OTable.setSortFormatterForType('emoji-time', (cell) => {
		const text = cell.textContent.trim();
		if (text === '🌑') {
			return 1;
		}
		if (text === '🌤️️') {
			return 2;
		}
		return 0;
	});
	OTable.init();

Links

new OTable(rootEl, opts)

Constructs an o-table component.

parameter type default description
rootEl HTMLElement An o-table element.
opts OTable~opts A table options object.

Methods

Links

Switch component view

GitHub Repository

Install o-table

If using the Build Service, add o-table@^7.4.0 to your script and link tags.

If running a Manual Build, run bower install --save "o-table@^7.4.0".

Help & Support

o-table is maintained directly by the Origami team. If you have any questions about o-table or Origami in general, we are happy to help. 😊

Slack: #ft-origami
Email: origami.support@ft.com

Feedback / Issues

To report a bug or request features please create an issue on Github. For support or general feedback please get in touch 😊

Slack: #ft-origami
Email: origami.support@ft.com