Understanding a table component lifecycle

The developer toolkit provides Angular schematics that can create table components for you to use in your application. Learn about the component framework to understand how tables are implemented and configured.

Table component overview

A typical table definition involves the following characteristics:

Table header: The table header is either a string literal (translated) or a template reference (in cases where the header involves custom styling).
Table column headers: The table column header strings along with other properties such as sortable or sorted.
Table toolbar actions: The actions to show on the table toolbar. Each action is typically associated with a callback to invoke when selected.
Table toolbar contents: The content to show on the table toolbar. Each content is typically associated with a template reference (icon) and a callback to invoke when selected.
Overflow menu actions: The overflow menu is displayed in the last column of every row.

A typical application component that defines a table completes the following actions:

Defines the table component in a configuration file (buc-table-config.json).
Translates headers and action literals.
Optionally, enables or disables columns based on Tenant administrator configurations.
Optionally, enables or disables toolbar actions, content, or overflow menu actions based on the rows that are selected.
Allows users to configure the table columns.
Calls one or more APIs to populate the table. The data that is returned by the API is matched by using the column name.

The framework manages the table's lifecycle and simplifies the implementation of the application component. The framework separates the table definition from table implementation. The table definition is managed as a configuration and loaded from a JSON (buc-table-config.json). The framework loads the table configuration and initializes the table. The application component implements the business logic, such as fetching the table data and implementing actions.

The framework loads the table configuration from three files:

The custom JSON file for a specific route: <module>/packages/<route>/src-custom/assets/custom/buc-table-config.json
The default application-specific table configurations from <module>/packages/<module-short-name>-shared/assets/<module>/buc-table-config.json
Common components specific table configuration from <module>/node_modules/@buc/common-components/assets/common-components/buc-table-config.json

During compilation, the three files are merged; giving precedence to the custom JSON file. For more information about the JSON configuration file, see JSON syntax.

Table implementation

The framework provides a base class BaseTableComponent for all components that contain a table. This class initializes the table's configuration BucTableConfiguration based on the table name that is specified by the component.

The BaseTableComponent class includes the following key methods:

initializeTable(tableName, templateMapping)

Initializes the table configuration based on the defined buc-table-config.json files. After initialization, the subclass (component) can remove any column headers based on tenant level overrides. Tenant level overrides refer to the Settings > Display settings > Data fields that administrators can modify.

disableTableFieldConfiguration

By default, the BaseTableComponent enables table configuration. You can disable table configuration by calling this method so that users cannot change the columns from within the UI.

applyUserPreference

After the table is initialized, the subcomponent calls this method to load the user's column preferences. By default this method triggers the table to load. If you want to delay the table load, pass false as a parameter to this method.

loadTable

Loads the table with data. This method delegates to the fetchTableData method to allow subclasses to implement the business logic to fetch the data. Then, this method calls the getDataForColumn method to allow subclasses to prepare the data for each column in the table header.

fetchTableData

This abstract method must be implemented by subclasses to fetch an array of data to populate the table.

getDataForColumn

Depending on your scenario, you will need to use either getDataForColumn or getDataForCustomColumn.

This abstract method must be implemented by subclasses to create the data for the column.

If you are adding a new table or adding columns to a table in the default buc-table-config.json file: If a column does not include the dataBinding property, then getDataForColumn is called.

getDataForCustomColumn

Depending on your scenario, you will need to use either getDataForCustomColumn or getDataForColumn.

This abstract method must be implemented by subclasses to create the data for the column.

If you are adding a new table or adding columns to an existing table using the custom buc-table-config.json file: If a column does not include the dataBinding property, then getDataForCustomColumn is called.

updateSortCriteria

This method is called on the subclass to handle the sort criteria for the table. All headers that include the sorted property is provided to the subclass to decide the final sort preference. By default, multi-column sorting is unavailable. The first column that has sorted set to true is used for sorting.

setActionResourceIds

This method sets the resource IDs for actions that include a resourceId property.

onToolbarActionClicked

This method is called on the subclass to allow the subclass to handle a toolbar action click event.

onToolbarContentClicked

This method is called on the subclass to allow the subclass to handle a toolbar content click event.

onOverflowMenuActionSelected

This method is called on the subclass to allow the subclass to handle an overflow menu action click event.

onTableLoadComplete

This method allows the subcomponent to finalize after the table's data is ready.

The BucTableConfiguration class encapsulates the table's configuration. It allows subclasses to dynamically enable or disable headers, actions, and content. The class maintains two versions of the data:

The static configuration that is obtained from merging the base table configuration and custom configuration JSON files. The static configuration is influenced by various factors that depend on the type of configuration.
- Tenant level overrides on table columns: A component might decide to disable (remove) certain columns based on Tenant level overrides. For example, UOM or Product class. These overrides must be made by the application component before user preferences are applied.
- Resource IDs for toolbar actions: If a component supports multiple tables based on the same configuration (for example, inbound orders vs outbound orders), the action resource IDs might differ based on the type of table. These overrides can be applied by calling the setActionResourceIds method.
- Overflow menu actions: The component can choose to remove certain overflow menu actions based on tenant level overrides.
The active configuration, which the application component changes dynamically if required. The active configuration is managed by methods that have Active in their name. Based on the type of configuration, the active configuration is influenced by various factors:
1. User preference: When applyUserPreference is called, the base component applies the stored user preference (if any) to the headers and only chooses the headers that are currently available.
2. Actions from the toolbar menu or overflow menu: The component might need to dynamically control these actions based on the row that is selected. In such cases, the component can choose to set the active actions based on the row select event. The component can also override the action's resource ID based on the selected row. However, if the actions are not based on row selection, the active actions are equal to the static configuration.

Table sort preferences

By default, multi-column sorting is unavailable for the table and a single default column as sorted. Developers can introduce new sorted columns by updating the buc-table-config.json file and setting the column parameter "sorted": true as well. In cases where multiple columns include the "sorted": true parameter, the first column in the sequence with the parameter is used as the sort column.