JSDoc: o-table

new CellFormatter

Methods to format table cells for sorting.

Methods

• setFormatter(type, formatFunction)
• formatCell(...)

Links

• "CellFormatter" class on Github

new TableSorter

Provides methods to sort table instances.

Methods

• sortRowsByColumn(...) - (instance) Sort the given table.
• setCellFormatterForType(type, formatFunction) - (instance) Set a custom cell formatter for a given data type.

Links

• "TableSorter" class on Github

new BaseTable(...)

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

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

• "BaseTable" class on Github

new BasicTable(...)

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

Links

• "BasicTable" class on Github

new FlatTable(...)

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

Methods

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

Links

• "FlatTable" class on Github

new OverflowTable(...)

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

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

• "OverflowTable" class on Github

new ScrollTable(...)

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

Methods

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

Links

• "ScrollTable" class on Github

new Count(countEl, opts)

Class constructor.

Methods

• getCountLabel(count) - (static) Get the aria-label for the count element.

Links

• "Count" class on Github

new Message(messageElement, options)

Initialises an `o-message` component.

Methods

• render - (instance) Render the message.
• open - (instance) Open the message.
• close - (instance) Close the message.
• getDataAttributes(messageElement) - (static) Get the data attributes from the messageElement. If the message is being set up declaratively, this method is used to extract the data attributes from the DOM.
• init(rootElement, opts) - (static) Initialise message component.

Examples

Example #1

To construct all elements on the page with the `data-o-component="o-message"` attribute.
     Message.init();

Example #2

To construct a specifc o-message on the page.
			const myMessageElement = document.querySelector('.my-message');
     const myMessage = new Message(myMessageElement, {});

Example #3

To construct a message which does not already exist on the page.
     const errorAlert = new Message(null, {
			type: 'alert',
			state: 'error',
			content: {
				highlight: 'Something has gone wrong.',
				detail: 'The quick brown fox did not jump over the lazy dogs.'
			}
     });

Links

• "Message" class on Github

new OTable(rootEl, opts)

Constructs an o-table component.

Methods

• init(el, opts) - (static) Constructs all o-table components inside the element passed as the first parameter.
• setSortFormatterForType(type, formatFunction) - (static) Set a custom sort formatter for a given data type.

Links

• "OTable" class on Github

new Stream(streamEl, opts)

Class constructor.

Methods

• publishEvent(...) - (instance) Emits events that have a valid o-comment event name.

Links

• "Stream" class on Github

formatFunction(cell)

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

Returns

• string | object

Type

function

Links

• "formatFunction" typedef on Github

MessageOptions

An object of options to configure a message instance.

Properties

• type - (type: string) The o-message type e.g. 'action', 'alert' and 'notice'.
• state - (type: string) The o-message state e.g. `success`, `neutral`, `error`, `inform-inverse`.
• autoOpen - (type: boolean) [true] - Whether to show the message automatically.
• parentElement - (type: string) [null] - The element to append the message to. If none is declared it will leave any existing message elements in place or append to the body when creating a new message element.
• content - (type: object) Configuration for the message copy.
• content.detail - (type: string) Copy for of the message e.g "Thing saved to the place you requested.".
• content.highlight - (type: string) [null] - Highlighted copy to prepend the main message copy "Success!".
• content.additionalInfo - (type: string) [null] - More copy with additional information – only applies to a message with an `inner` layout.
• actions - (type: Object) Links to display on the message.
• actions.primary - (type: Object) Show a link in the style of a primary button within the message.
• actions.primary.text - (type: string) The copy for the link.
• actions.primary.url - (type: string) The url for the link.
• actions.primary.openInNewWindow - (type: boolean) [false] - Opens in a new tab/window when set to `true`.
• actions.secondary - (type: Object) Show a link with less emphasis that the primary action.
• actions.secondary.text - (type: string) The copy for the link.
• actions.secondary.url - (type: string) The url for the link.
• actions.secondary.openInNewWindow - (type: boolean) [false] - Opens in a new tab/window when set to `true`.
• close - (type: boolean) [true] - Whether or not to display a close button.

Type

object

Links

• "MessageOptions" typedef on Github

OTableOptions

Table options.

Properties

• sortable - (type: boolean) [true] - Disable the table's sort feature.
• expanded - (types: undefined | types: boolean) [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

• "OTableOptions" typedef on Github

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.

Type

function

Links

• "formatFunction" typedef on Github

CellFormatter#setFormatter(type, formatFunction)

Instance Method

Example

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

Links

• "setFormatter" function on Github

CellFormatter#formatCell(...)

Instance Method

Returns

• string | number - A representation of cell which can be used for sorting.

Links

• "formatCell" function on Github

TableSorter#sortRowsByColumn(...)

Instance Method

Sort the given table.

Returns

• void

Links

• "sortRowsByColumn" function on Github

TableSorter#setCellFormatterForType(type, formatFunction)

Instance Method

Set a custom cell formatter for a given data type.

Links

• "setCellFormatterForType" function on Github

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

• void

Links

• "updateRows" function on Github

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

• void

Links

• "renderRowUpdates" function on Github

BaseTable#filter(headerIndex, filter)

Instance Method

Filter the table and render the result.

Returns

• undefined

Links

• "filter" function on Github

BaseTable#getTableHeader(columnIndex)

Instance Method

Gets a table header for a given column index.

Returns

• HTMLElement - the table header

Links

• "getTableHeader" function on Github

BaseTable#sortRowsByColumn(columnIndex, sortOrder)

Instance Method

Sort the table.

Returns

• undefined

Links

• "sortRowsByColumn" function on Github

<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

• "defaultSort" constant on Github

BaseTable#addSortButtons

Instance Method

Add sort buttons to the DOM within the table header.

Returns

• undefined

Links

• "addSortButtons" function on Github

BaseTable#sorted(...)

Instance Method

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

Links

• "sorted" function on Github

BaseTable#destroy

Instance Method

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

Returns

• undefined

Links

• "destroy" function on Github

FlatTable#updateRows

Instance Method

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

Returns

• void

Links

• "updateRows" function on Github

OverflowTable#filter(headerIndex, filter)

Instance Method

Filter the table.

Returns

• undefined

Links

• "filter" function on Github

OverflowTable#isExpanded

Instance Method

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

Returns

• boolean - is the table expanded?

Links

• "isExpanded" function on Github

OverflowTable#isContracted

Instance Method

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

Returns

• boolean - is the table contracted?

Links

• "isContracted" function on Github

OverflowTable#canExpand

Instance Method

Check if the table supports the expand/contract feature.

Returns

• boolean - can the table expand and contract?

Links

• "canExpand" function on Github

OverflowTable#renderRowUpdates

Instance Method

Updates the dom to account for row updates.

Returns

• undefined

Links

• "renderRowUpdates" function on Github

OverflowTable#contractTable

Instance Method

Hides table rows if the table can be expanded.

Returns

• void

Links

• "contractTable" function on Github

OverflowTable#expandTable

Instance Method

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

Returns

• void

Links

• "expandTable" function on Github

ScrollTable#filter(headerIndex, filter)

Instance Method

Filter the table.

Returns

• undefined

Links

• "filter" function on Github

ScrollTable#updateRows

Instance Method

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

Returns

• undefined

Links

• "updateRows" function on Github

Comments.getDataAttributes(rootEl)

Static Method

Get the data attributes from the element. If the component is being set up declaratively, this method is used to extract the data attributes from the DOM.

Returns

• object - - Data attributes as an object

Links

• "getDataAttributes" function on Github

Comments.init(rootEl, opts)

Static Method

Initialise the component.

Returns

• Comments | Array.<Comments> - - Comments instance(s)

Links

• "init" function on Github

module.exports.message()

Static Method

Build a full message element. Used when there is no message element in the DOM.

Returns

• HTMLElement - Returns the new message element

Links

• "message" function on Github

module.exports.closeButton

Static Method

Build a close button

Returns

• HTMLElement - Returns a new element to close the message

Links

• "closeButton" function on Github

CookieMessage#updateConsent

Instance Method

Enables cookie setting behaviour from the FT consent service https://github.com/Financial-Times/next-consent-proxy/tree/master/src

Returns

• void

Links

• "updateConsent" function on Github

CookieMessage#shouldShowCookieMessage

Instance Method

Checks whether cookie is set

Returns

• boolean - - should the cookie message be shown

Links

• "shouldShowCookieMessage" function on Github

CookieMessage#showCookieMessage

Instance Method

Displays cookie message banner, based on existing cookies.

Returns

• void

Links

• "showCookieMessage" function on Github

CookieMessage#removeCookieMessage

Instance Method

Removes cookie message banner.

Returns

• void

Links

• "removeCookieMessage" function on Github

CookieMessage#destroy

Instance Method

Undo theme and event listeners set on init.

Returns

• void

Links

• "destroy" function on Github

CookieMessage.getOptionsFromDom(cookieMessageElement)

Static Method

Get the data attributes from the cookieMessageElement. If the cookie message is being set up declaratively, this method is used to extract the data attributes from the DOM.

Returns

• Object.<string, any> - - The options

Links

• "getOptionsFromDom" function on Github

CookieMessage.init(rootElement, options)

Static Method

Initialise cookie message components.

Returns

• CookieMessage | Array.<CookieMessage> - - The newly instantiated CookieMessage (or CookieMessages, if rootElement was not a banner)

Links

• "init" function on Github

Count.getCountLabel(count)

Static Method

Get the aria-label for the count element.

Returns

• string - The string that should be used as the aria-label

Links

• "getCountLabel" function on Github

Message#render

Instance Method

Render the message.

Returns

• void

Links

• "render" function on Github

Message#open

Instance Method

Open the message.

Returns

• void

Links

• "open" function on Github

Message#close

Instance Method

Close the message.

Returns

• void

Links

• "close" function on Github

Message.getDataAttributes(messageElement)

Static Method

Get the data attributes from the messageElement. If the message is being set up declaratively, this method is used to extract the data attributes from the DOM.

Returns

• object - - An object of options defined via data attributes on the message element

Links

• "getDataAttributes" function on Github

Message.init(rootElement, opts)

Static Method

Initialise message component.

Returns

• Message | Array.<Message> - The newly constructed message component or components

Links

• "init" function on Github

OTable.init(el, opts)

Static Method

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

Returns

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

Links

• "init" function on Github

OTable.setSortFormatterForType(type, formatFunction)

Static Method

Set a custom sort formatter for a given data type.

Example

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

	import OTable from '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

• "setSortFormatterForType" function on Github

Stream#publishEvent(...)

Instance Method

Emits events that have a valid o-comment event name.

Returns

• void

Links

• "publishEvent" function on Github