Element: <oj-c-table-display>

CORE PACK

Oracle® JavaScript Extension Toolkit (JET)
21.0.0
G39657-01

Since:
  • 21.0.0
Module:
  • table-display

QuickNav

Slots

Attributes

Methods

Type Definitions

Exported Types

Documentation-only Types

Other Topics


JET TableDisplay Component

Description: The TableDisplay component presents data in a tabular format for display-focused use cases.

Data

The JET TableDisplay gets its data from a DataProvider.

Example of data provider content

<oj-c-table-display data="[[dataProvider]]"></oj-c-table-display>

Keyboard End User Information

Target Key Action
table-display Tab Move browser focus to next tab stop on the page.
Shift + Tab Move browser focus to previous tab stop on the page.
Up Arrow Scroll the table display up.
Down Arrow Scroll the table display down.
Left Arrow Scroll the table display to the left.
Right Arrow Scroll the table display to the right.
sort control Enter Toggle the sort order of the column if the column is sortable.
Space Toggle the sort order of the column if the column is sortable.

Touch End User Information

table-display follows standard browser touch interactions for scrolling and focus behavior.

Accessibility

The table-display component implements the table role for accessibility. This enables compatibility with assistive technologies that provide table reading commands in addition to the keyboard interactions described above.

An application is required to include contextual information to make table-display accessible for assistive technologies by providing one or more the following properties as appropriate:

  • aria-labelledby
  • aria-label

Additionally, an application should specify at least one accessible row header for each row by providing a value for the row.accessible-row-header attribute. The information in the cell(s) specified will be used by assistive technologies to convey basic contextual information for the focused row. For example, if a user is arrowing up or down in an 'Amount Due' column, having something like '$500' read out does not provide any helpful information as to who or what that amount corresponds to. If an 'Account Holder' column is specified as an accessible row header, then something like 'Larry Ellison, $500' would be read out instead. Providing this additional row context is essential for creating an accessible table-display experience.

Custom Colors

Using colors, including background and text colors, is not accessible if it is the only way information is conveyed. Low vision users may not be able to see the different colors, and in high contrast mode the colors are removed. The Redwood approved way to show status is to use a badge.

Background Color

The table-display background color is managed via the --oj-current-bg-color CSS variable. If a different background color is desired, one can be set by adding a background color class on table-display. Table-display does not support background colors with transparencies. See the 'Background Color' cookbook demo for examples.

Custom Data Attributes

The table-display component supports the following custom data attributes.

Name Description
data-oj-as

Provides an alias for a specific template instance and has the same subproperties as the $current variable.

<oj-c-table-display id="tableDisplay">
  <template slot="cellTemplate" data-oj-as="cell">
  </template>
</oj-c-table-display>


Usage

Signature:

interface CTableDisplayElement<K extends string | number,D,C extends string>

Typescript Import Format
//To typecheck the element APIs, import as below.
import { CTableDisplayElement } from "oj-c/table-display";

//For the transpiled javascript to load the element's module, import as below
import "oj-c/table-display";

For additional information visit:

Note: Application logic should not interact with the component's properties or invoke its methods until the BusyContext indicates that the component is ready for interaction.


Slots

JET components that allow child content support slots. Please see the slots section of the JET component overview doc for more information on allowed slot content and slot types.

cellTemplate

Note: When the template is executed for each item, it will have access to the binding context containing the following properties: oj-c.TableDisplay.CellTemplateContext

The template for rendering each data cell in table-display. When a column.template is specified that will take precedence over this template. The slot content must be a template element. The content of the template should not include the td element, only its contents. The template has access to the context CellTemplateContext via $current or the aliased name for $current set via data-oj-as.
Properties of $current:
Name Type Argument Description
columnKey C Column key
data D[keyof D] <optional>
 Data for the cell, derived from the column.field property
item Item.<K, D> Row item containing data and metadata

footerTemplate

Note: When the template is executed for each item, it will have access to the binding context containing the following properties: oj-c.TableDisplay.FooterTemplateContext

The template for rendering each footer cell in table-display. When a column.footerTemplate is specified that will take precedence over this template. The slot content must be a template element. The content of the template should not include the td element, only its contents. The template has access to the context FooterTemplateContext via $current or the aliased name for $current set via data-oj-as.
Properties of $current:
Name Type Argument Description
footerText string <optional>
 Column footer text
key C Column key

headerTemplate

Note: When the template is executed for each item, it will have access to the binding context containing the following properties: oj-c.TableDisplay.HeaderTemplateContext

The template for rendering each header cell in table-display. When a column.headerTemplate is specified that will take precedence over this template. The slot content must be a template element. The content of the template should not include the th element, only its contents. The template has access to the context HeaderTemplateContext via $current or the aliased name for $current set via data-oj-as. Use oj-c-sort-control to provide sorting in a header.
Properties of $current:
Name Type Argument Description
headerText string <optional>
 Column header text
key C Column key

noData

The template for rendering content when table-display has an empty data set. The slot content must be a template element. If not specified then a default no data message will be displayed.

DynamicSlots.CellTemplateContext (Dynamic)

Context passed into the cell template specified in the column.template property.

Note: For additional information see .

Properties of $current:
Name Type Argument Description
columnKey C Column key
data D[keyof D] <optional>
 Data for the cell, derived from the column.field property
item Item.<K, D> Row item containing data and metadata

DynamicSlots.FooterTemplateContext (Dynamic)

Context passed into the footer template specified in the column.footerTemplate property.

Note: For additional information see .

Properties of $current:
Name Type Argument Description
footerText string <optional>
 Column footer text
key C Column key

DynamicSlots.HeaderTemplateContext (Dynamic)

Context passed into the header template specified in the column.headerTemplate property.

Note: For additional information see .

Properties of $current:
Name Type Argument Description
headerText string <optional>
 Column header text
key C Column key

Attributes

column-order :Array<C>

Controls the displayed columns and their order. An array of column keys that represents the displayed columns and the order to display them in. If not set, all columns will be displayed in the order returned by Object.keys(columns).
Names
Item Name
Property columnOrder
Property change event columnOrderChanged
Property change listener attribute (must be of type function, see Events and Listeners for additional information.) on-column-order-changed

column-widths :Record<C, number>

The desired widths of the specified table-display columns. A record mapping columns keys to numbers representing pixel widths for each column. Values should only be provided when a specific width is desired for a column as values provided will override table-display's normal column sizing calculations. Applications should avoid setting widths for every column in most cases as doing so will likely result in a non-responsive layout.
Names
Item Name
Property columnWidths
Property change event columnWidthsChanged
Property change listener attribute (must be of type function, see Events and Listeners for additional information.) on-column-widths-changed

columns :Record.<C, oj-c.TableDisplay.Column.<K, D>>

The set of columns that can be displayed in table-display. If no columns-order is specified, all columns specified will be displayed in the order returned by Object.keys(columns). Otherwise only the columns specified in the columns-order value will be displayed.
Names
Item Name
Property columns
Property change event columnsChanged
Property change listener attribute (must be of type function, see Events and Listeners for additional information.) on-columns-changed

data :DataProvider.<K, D>

The data provider for table-display.
Names
Item Name
Property data
Property change event dataChanged
Property change listener attribute (must be of type function, see Events and Listeners for additional information.) on-data-changed

horizontal-grid-visible :"enabled"|"disabled"

Controls the display of table-display horizontal gridlines.
Supported Values:
Value Description
enabled Display horizontal gridlines
disabled Do not display horizontal gridlines
Default Value:
  • 'enabled'
Names
Item Name
Property horizontalGridVisible
Property change event horizontalGridVisibleChanged
Property change listener attribute (must be of type function, see Events and Listeners for additional information.) on-horizontal-grid-visible-changed

layout :"contents"|"fixed"

The column sizing method used for table-display columns.
Supported Values:
Value Description
contents When specified, the initial column sizes are determined by the contents of the data. Does not require an overall width set on table-display. Can have performance issues when large numbers of columns and/or rows are initially rendered.
fixed When specified, the initial column sizes are determined by column weights. Requires an overall width set on table-display (width='100%', width='200rem', etc.) Very performant when rendering large numbers of columns and/or rows.
Default Value:
  • 'contents'
Names
Item Name
Property layout
Property change event layoutChanged
Property change listener attribute (must be of type function, see Events and Listeners for additional information.) on-layout-changed

row :{ accessibleRowHeader?: C | Array<C> | ((context: oj-c.TableDisplay.RowContext<K, D>) => C | Array<C>); }

A subset of attributes for controlling certain behaviors on a per row basis.
Names
Item Name
Property row
Property change event rowChanged
Property change listener attribute (must be of type function, see Events and Listeners for additional information.) on-row-changed

sort-criteria :Array<{ attribute: keyof D; sortDirection: 'ascending' | 'descending'; }>

Set of sort criteria representing the sort state of this Table's columns.
Supports writeback:
  • true
Names
Item Name
Property sortCriteria
Property change event sortCriteriaChanged
Property change listener attribute (must be of type function, see Events and Listeners for additional information.) on-sort-criteria-changed

vertical-grid-visible :"enabled"|"disabled"

Controls the display of table-display vertical gridlines.
Supported Values:
Value Description
enabled Display vertical gridlines
disabled Do not display vertical gridlines
Default Value:
  • 'disabled'
Names
Item Name
Property verticalGridVisible
Property change event verticalGridVisibleChanged
Property change listener attribute (must be of type function, see Events and Listeners for additional information.) on-vertical-grid-visible-changed

Methods

getProperty(property) : {any}

Retrieves the value of a property or a subproperty.
Parameters:
Name Type Description
property string The property name to get. Supports dot notation for subproperty access.
Returns:
Type
any

setProperties(properties) : {void}

Performs a batch set of properties.
Parameters:
Name Type Description
properties object An object containing the property and value pairs to set.
Returns:
Type
void

setProperty(property, value) : {void}

Sets a property or a single subproperty for complex properties and notifies the component of the change, triggering a corresponding event.
Parameters:
Name Type Description
property string The property name to set. Supports dot notation for subproperty access.
value any The new value to set the property to.
Returns:
Type
void

Type Definitions

Exported Types

Note: Type definitions in this section are exported by the module, and so can be imported for use in application code.

RowContext<K,D>

Context used to specify a row in table-display.
Typescript Import Format
//To import this type, use the format below.
import { RowContext } from "oj-c/table-display";
Properties:
Name Type Description
item Item.<K, D> Row item containing data and metadata

Documentation-only Types

Note: Type definitions in this section have been provided for documentation purposes and cannot be imported into application code.

CellAlignment

Properties:
Name Type Argument
horizontal "center" | "end" | "start" | "left" | "right" <optional>
vertical "center" | "top" | "bottom" <optional>

CellPadding

Specifies whether padding is enabled or disabled on specific sides of a cell.
Properties:
Name Type Argument Description
bottom "disabled" | "enabled" <optional>
 Specifies whether bottom padding is enabled or disabled.
end "disabled" | "enabled" <optional>
 Specifies whether end padding (right in ltr locales, left in rtl locales) is enabled or disabled.
start "disabled" | "enabled" <optional>
 Specifies whether start padding (left in ltr locales, right in rtl locales) is enabled or disabled.
top "disabled" | "enabled" <optional>
 Specifies whether top padding is enabled or disabled.

CellTemplateContext<K,D,C>

Context passed into the cell template specified in the column.template property.
Properties:
Name Type Argument Description
columnKey C Column key
data D[keyof D] <optional>
 Data for the cell, derived from the column.field property
item Item.<K, D> Row item containing data and metadata

Column<K,D>

Specifies the properties of a column.
Properties:
Name Type Argument Description
alignment oj-c.TableDisplay.CellAlignment <optional>
 The alignment specified for data cells in this column.
field keyof D <optional>
 Specifies the field attribute of the row item data that is mapped to the column.
footerAlignment oj-c.TableDisplay.CellAlignment <optional>
 The alignment specified for the footer cell in this column.
footerPadding "disabled" | "enabled" | oj-c.TableDisplay.CellPadding <optional>
 Specifies padding for the footer cell in this column. Valid string values include 'enabled' and 'disabled'. Setting either 'enabled' or 'disabled' will apply to all sides of the footer cell, while providing an instance of CellPadding will only apply to the specified sides of the footer cell.
footerTemplate string <optional>
 The name of the slot used to specify the template for rendering the footer cell in the column. The slot content must be a template element. The content of the template should not include the td element, only its contents. The template has access to the following context via $current or the aliased name for $current set via data-oj-as.
footerText string <optional>
 Text to display in the footer cell of the column
headerAlignment oj-c.TableDisplay.CellAlignment <optional>
 The alignment specified for the header cell in this column.
headerPadding "disabled" | "enabled" | oj-c.TableDisplay.CellPadding <optional>
 Specifies padding for the header cell in this column. Valid string values include 'enabled' and 'disabled'. Setting either 'enabled' or 'disabled' will apply to all sides of the header cell, while providing an instance of CellPadding will only apply to the specified sides of the header cell.
headerTemplate string <optional>
 The name of the slot used to specify the template for rendering the header cell in the column. The slot content must be a template element. The content of the template should not include the th element, only its contents. The template has access to the following context via $current or the aliased name for $current set via data-oj-as.
headerText string <optional>
 Text to display in the header cell of the column.
horizontalAlignment "center" | "end" | "start" | "left" | "right" <optional>
 The horizontal alignment of this column.
maxWidth number <optional>
 The maximum width in pixels of the column. This value is used during initial render, and does not affect the ability to resize the column. This value is applicable when either, layout='fixed' or layout='contents'.
minWidth number <optional>
 The minimum width in pixels of the column. This value is used during initial render, and does not affect the ability to resize the column. This value is applicable when either, layout='fixed' or layout='contents'. If not set and layout='fixed' a default minimum width will be determined by the theme.
padding "disabled" | "enabled" | oj-c.TableDisplay.CellPadding | (context: oj-c.TableDisplay.RowContext<K, D>) => "disabled" | "enabled" | oj-c.TableDisplay.CellPadding <optional>
 Specifies padding for the data cells in this column. Valid string values include 'enabled' and 'disabled'. Setting either 'enabled' or 'disabled' will apply to all sides of the data cells, while providing an instance of CellPadding will only apply to the specified sides of the data cells.
sortable "disabled" | "enabled" <optional>
 Enable or disable sorting along the column headers.
sticky "disabled" | "enabled" <optional>
 Whether this column should be prevented from scrolling out of view.
template string <optional>
 The name of the slot used to specify the template for rendering data cells in the column. The slot content must be a template element. The content of the template should not include the td element, only its contents. The template has access to the following context via $current or the aliased name for $current set via data-oj-as.
weight number <optional>
 Specifies the relative sizing weight of the column. If not set a default of 1 is assumed. This must be a positive number greater than or equal to 1. Its value does not affect the ability to resize the column. When table-display's layout attribute is set to fixed, this value is used to determine the relative width of the column compared to the other columns. For example, a column with a weight of 2 will have twice as much space allocated to it as a column with a weight of 1. This value has no effect when table-display's layout attribute is set to contents.

FooterTemplateContext<C>

Context passed into the footer template specified in the column.footerTemplate property.
Properties:
Name Type Argument Description
footerText string <optional>
 Column footer text
key C Column key

HeaderTemplateContext<C>

Context passed into the header template specified in the column.headerTemplate property.
Properties:
Name Type Argument Description
headerText string <optional>
 Column header text
key C Column key