@commercetools-uikit/data-table-manager

DataTableManager

Description

This component enhances the <DataTable> component and additionally provides a UI and state management to handle configuration of the table such as column manager.

• The disableDisplaySettings enables / disables the layout settings panel, allowing the user to select wrapping text and density display options.
• The disableColumnManager enables / disables the column manager panel, allowing the user to select which columns are visible.

Both panels delegate the handling of the settings change on the parent through function properties, allowing the settings to be persisted or just used as state props.

This component will render a triggering element (icon button) above the <DataTable> (top-right corner) which users can click to select the panel to open.

Installation

yarn add @commercetools-uikit/data-table-manager

npm --save install @commercetools-uikit/data-table-manager

Additionally install the peer dependencies (if not present)

yarn add react react-dom react-intl

npm --save install react react-dom react-intl

Usage

There are two ways this component can be used:

Attached

The basic usage is when it just wraps the DataTable component.

import DataTableManager from '@commercetools-uikit/data-table-manager';
import DataTable from '@commercetools-uikit/data-table';

const rows = [
  { id: 'parasite', title: 'Parasite', country: 'South Korea' },
  { id: 'portrait', title: 'Portrait of a Lady on Fire', country: 'France' },
  { id: 'wat', title: 'Woman at War', country: 'Iceland' },
];

const columns = [
  { key: 'title', label: 'Title' },
  { key: 'country', label: 'Country' },
];

const Example = () => (
  <DataTableManager columns={columns}>
    <DataTable rows={rows} />
  </DataTableManager>
);

export default Example;

Detached

As mentioned earlier, the default behavior places the triggering element above the <DataTable> component (top-right corner), but there may be use cases where the triggering element needs to be positioned differently on the page. This is also possible but requires the usage of one more component (DataTableManagerProvider) in order to share the manager state between the manager panels and the DataTable component.

In this mode, you should pass the manager props to the DataTableManagerProvider component and the DataTableManager does not need to receive any prop; it can be placed anywhere in the component's tree without requiring any prop.

import DataTableManager, {
  DataTableManagerProvider,
} from '@commercetools-uikit/data-table-manager';
import DataTable from '@commercetools-uikit/data-table';
import SearchTextInput from '@commercetools-uikit/search-text-input';

const rows = [
  { id: 'parasite', title: 'Parasite', country: 'South Korea' },
  { id: 'portrait', title: 'Portrait of a Lady on Fire', country: 'France' },
  { id: 'wat', title: 'Woman at War', country: 'Iceland' },
];

const columns = [
  { key: 'title', label: 'Title' },
  { key: 'country', label: 'Country' },
];

const SomeOtherComponent = () => {
  return <div>Some other component</div>;
};

const Example = () => (
  <DataTableManagerProvider columns={columns}>
    <header>
      <DataTableManager />
      <SearchTextInput />
    </header>
    <main>
      <SomeOtherComponent />
      <DataTable rows={rows} />
    </main>
  </DataTableManagerProvider>
);

export default Example;

With custom configuration settings

The DataTableManager provides a feature for users to add custom configurations to the data table settings.

To configure the data table manager, you can pass in your own jsx component and all the expected actions and states you want to control.

The ColumnSettingsManager component is also exposed for users to consume and pass in configuration of choice for custom column configurations, pass in your settings through the customColumnManager props.

import { ColumnSettingsManager } from '@commercetools-uikit/data-table-manager/column-settings-manager';

<DataTableManagerProvider
  columns={columns}
  onSettingsChange={() => tableSettingsChangeHandler}
  columnManager={columnManager}
  displaySettings={displaySettings}
  customSettings={customSettings}
  selectedColumns={selectedColumns}
  customColumnManager={customColumnManager}
  customColumns={visibleCustomColumns}
>
  <DataTable rows={rows} />
</DataTableManagerProvider>;

Properties

Props	Type	Required	Default	Description
columns	array	✅		Each object requires a unique key which should correspond to property key of the items of rows that you want to render under this column, and a label which defines the name shown on the header. The list of columns to be rendered. Each column can be customized (see properties below).
columns[].key	string	✅		The unique key of the column that is used to identify your data type. You can use this value to determine which value from a row item should be rendered. For example, if the data is a list of users, where each user has a firstName property, the column key should be firstName, which renders the correct value by default. The key can also be some custom or computed value, in which case you need to provide an explicit mapping of the value by implementing either the itemRendered function or the column-specific renderItem function.
columns[].label	node	✅		The label of the column that will be shown on the column header.
columns[].width	string		auto	Sets a width for this column. Accepts the same values as the ones specified for individual grid-template-columns. For example, using minmax pairs (e.g. minmax(200px, 400px)), a combinations of fraction values (1fr/2fr/etc), or fixed values such as 200px. By default, the column grows according to the content and respecting the total table available width.
columns[].align	enum Possible values: 'left', 'center', 'right'			Use this to override the table's own horizontalCellAlignment prop for this specific column.
columns[].onClick	func			A callback function, called when the header cell is clicked. Signature: (event) => void
columns[].renderItem	func			A callback function to render the content of cells under this column, overriding the default itemRenderer prop of the table. Signature: (row: object, isRowCollapsed: boolean) => React.Node
columns[].headerIcon	node			Use this prop to place an Icon or IconButton on the left of the column label. It is advised to place these types of components through this prop instead of label, in order to properly position and align the elements. This is particularly useful for medium-sized icons which require more vertical space than the typography.
columns[].isTruncated	bool		false	Set this to true to allow text content of this cell to be truncated with an ellipsis, instead of breaking into multiple lines. NOTE: when using this option, it is recommended to specify a width for the column, because if the table doesn't have enough space for all columns, it will start clipping the columns with truncated content, and if no width is set (or the value is set auto -- the default) it can shrink until the column disappears completely. By enforcing a minimum width for these columns, the table will respect them and grow horizontally, adding scrollbars if needed.
columns[].isSortable	bool		false	Set this to true to show a sorting button, which calls onSortChange upon being clicked. You should enable this flag for every column you want to be able to sort. When at least one column is sortable, the table props sortBy, sortDirection and onSortChange should be provided.
columns[].disableResizing	bool		false	Set this to true to prevent this column from being manually resized by dragging the edge of the header with a mouse.
columns[].shouldIgnoreRowClick	bool		false	Set this to true to prevent click event propagation for this cell. You might want this if you need the column to have its own call-to-action or input while the row also has a defined onRowClick.
children	node	✅		Any React node. Usually you want to render the <DataTable> component. Note that the child component will implicitly receive the props columns and isCondensed from the <DataTableManager>.
displaySettings	object			The managed display settings of the table.
displaySettings.disableDisplaySettings	bool		true	Set this flag to false to show the display settings panel option.
displaySettings.isCondensed	bool		false	Set this to true to reduce the paddings of all cells, allowing the table to display more data in less space.
displaySettings.isWrappingText	bool		false	Set this to true to allow text in a cell to wrap. This is required if disableDisplaySettings is set to false.
displaySettings.primaryButton	element			A React element to be rendered as the primary button, useful when the display settings work as a form.
displaySettings.secondaryButton	element			A React element to be rendered as the secondary button, useful when the display settings work as a form.
columnManager	object			The managed column settings of the table.
columnManager.disableColumnManager	bool		true	Set this to false to show the column settings panel option.
columnManager.visibleColumnKeys	Array of string			The keys of the visible columns.
columnManager.hideableColumns	array			The keys of the visible columns.
columnManager.hideableColumns[].key	string	✅
columnManager.hideableColumns[].label	<string, node>	✅
columnManager.areHiddenColumnsSearchable	bool			Set this to true to show a search input for the hidden columns panel.
columnManager.searchHiddenColumns	func			A callback function, called when the search input for the hidden columns panel changes. Signature: (searchTerm: string) => Promise<void>
columnManager.searchHiddenColumnsPlaceholder	string			Placeholder value of the search input for the hidden columns panel.
columnManager.primaryButton	element			A React element to be rendered as the primary button, useful when the column settings work as a form.
columnManager.secondaryButton	element			A React element to be rendered as the secondary button, useful when the column settings work as a form.
columnManager.columnManagerLabel	node			This value overrides the default label that will be shown on the column header and dropdown.
onSettingsChange	func			A callback function, called when any of the properties of either display settings or column settings is modified. Signature: (action: string, nextValue: object) => void
topBar	node			A React node for rendering additional information within the table manager.
managerTheme	enum Possible values: 'light', 'dark'			Sets the background theme of the Card that contains the settings
customSettings	JSON			A JSON object carrying all the settings for each custom panel. When using the customSettings, each item in the custom setting can be designed to serve as an interface for data table configuration, It should at least have a key, customPanelTitle, and customComponent as property.
customSettings['key']	string	✅		The key of the custom component. Every panel is identifiable by it's unique key provided in the JSON object.
customSettings['key'].customPanelTitle	string	✅		The title of the custom component setting
customSettings['key'].customComponent	ReactNode			A component added to the settings interface to provide additional configuration for the data table setting
customColumnManager.disableCustomColumnManager	bool		true	Set this to false to show the column settings panel option.
customColumnManager.visibleColumnKeys	Array of string			The keys of the visible columns.
customColumnManager.hideableColumns	array			The keys of the hideable columns.
customColumnManager.hideableColumns[].key	string	✅		The uniqque key of each hideable column.
customColumnManager.hideableColumns[].label	<string, node>	✅		The label of each hideable column.
customColumnManager.areHiddenCustomColumnsSearchable	bool			Set this to true to show a search input for the hidden columns panel.
customColumnManager.searchHiddenColumns	func			A callback function, called when the search input for the hidden custom columns panel changes. Signature: (searchTerm: string) => Promise<void>
customColumnManager.searchHiddenColumnsPlaceholder	string			Placeholder value of the search input for the hidden custom columns panel.
customColumnManager.primaryButton	element			A React element to be rendered as the primary button, useful when the custom column settings work as a form.
customColumnManager.secondaryButton	element			A React element to be rendered as the secondary button, useful when the custom column settings work as a form.

*: DataTableManagerProvider component accepts the same properties as the DataTableManager