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
- 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
orsorted
. - 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.
- 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.
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 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
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.
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 thegetDataForColumn
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, thengetDataForColumn
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, thengetDataForCustomColumn
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.
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:- 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.
- 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.