Skip to content

Commit

Permalink
docs(Datagrid): add missing hook documentation
Browse files Browse the repository at this point in the history
  • Loading branch information
matthewgallo committed Apr 25, 2023
1 parent f3e81ba commit f692d10
Showing 1 changed file with 220 additions and 0 deletions.
220 changes: 220 additions & 0 deletions packages/cloud-cognitive/src/components/Datagrid/Datagrid.mdx
Original file line number Diff line number Diff line change
Expand Up @@ -221,6 +221,12 @@ for center and right aligned as well. See
[design guidance](https://pages.github.ibm.com/cdai-design/pal/components/data-table/column-alignment/usage)
for details around when to change default column alignment.

To utilize center or right aligned columns refer to the steps below:

1. Include `useColumnCenterAlign` or `useColumnRightAlign` hook/s.
2. Add `rightAlignedColumn` or `centerAlignedColumn` to the column object in
which you which to change the default column alignment.

```jsx
import {
Datagrid,
Expand Down Expand Up @@ -794,6 +800,220 @@ width will be set to the default column width (150px) or the value passed to the
...
```

## Actions column

This will add row actions (if more than two actions are provided an OverflowMenu
component will be used) to the cells on the column marked with `isAction: true`.
Each action button callback will include the actionId and the row object.

1. Include `useActionsColumn` hook
2. Add `isAction = true` to the column object in which you which to add the
overflow menu actions
3. Add `rowActions = []` array to the props

- `rowActions[].id` for callback to identify the action is called
- `rowActions[].onClick(actionId: string, row: Row, event: ClickEvent)` callback
on menuitem clicked.
[Row properties](https://react-table.tanstack.com/docs/api/useTable#row-properties)
- `rowActions[].shouldHideMenuItem(row: Row)` callback to hide this menuitem.
[Row properties](https://react-table.tanstack.com/docs/api/useTable#row-properties)
- `rowActions[].shouldDisableMenuItem(row: Row)` callback to disable this
menuitem.
[Row properties](https://react-table.tanstack.com/docs/api/useTable#row-properties)
- This will override `rowActions[].disabled` (from Carbon) because
`shouldDisableMenuItem` is more specific to the row.
- each action object can take all the props from `OverflowMenuItem` props, see
[carbon docs](https://react.carbondesignsystem.com/?path=/docs/components-overflowmenu--default#overflowmenu)

```jsx
const columns = [
// other columns
{
Header: '',
accessor: 'actions',
isAction: true,
},
];
const onActionClick = (actionId, row, event) => {};
const datagridState = useDatagrid(
{
columns,
data,
rowActions: [
{
id: 'edit',
itemText: 'Edit',
onClick: onActionClick,
},
{
id: 'hidden',
itemText: 'Hidden item',
onClick: onActionClick,
shouldHideMenuItem: () => true,
},
{
id: 'delete',
itemText: 'Delete',
hasDivider: true,
isDelete: true,
onClick: onActionClick,
},
],
},
useActionsColumn
);

return <Datagrid datagridState={datagridState} />;
```

## Customizing columns

Customizing columns allows user to reorder and hide certain columns of the
datagrid. Consuming component can use the provided callback to save/update
according to their persistent strategy.

1. Include `useCustomizeColumns` and `useColumnOrder` hooks (required)

- `useColumnOrder` comes from `react-table` but is exported by
`@carbon/ibm-products` to be used alongside `useCustomizeColumns`.

2. Implement `options.DatagridActions` component

- this component will have props: `datagridState`
- render `datagridState.CustomizeColumnsButton` component wherever makes sense.

3. Options available to set:

- `options.initialState.hiddenColumns: Array<ColumnId: String>`
- Array of column ids that will be hidden after initial render
- [react-table doc](https://react-table.tanstack.com/docs/api/useTable#table-options)
- `options.initialState.columnOrder: Array<ColumnId: String>`
- Order of the columns. Any column ids not in this array will be ordered by
their position in the `options.columns`
- [react-table doc](https://react-table.tanstack.com/docs/api/useColumnOrder#table-options)
- `options.customizeColumnsProps.onSaveColumnPrefs`
- type:
`Function(Columns: Array<{ColumnId: String, isVisible: Boolean}>) => void`
- Callback function when 'Save' button clicked on the narrow tearsheet. It
allows consumer to preserve the updated column preference. This output can
also be used to compute the `hiddenColumns` and `columnOrder`
- Reset to default (optional)
- There is a reset to default button on the modal. It will use the
`options.columns` as the default. If there are columns should be hidden by
default, denote them with property: `isVisible: false` (undefined will be
treated as `true`)

```jsx
const columns = React.useMemo(() => defaultHeader, []);
const [data] = useState(makeData(10));
const DatagridActions = (datagridState) => (
<TableToolbarContent>
<TableToolbarSearch ... />
<Button ... />
<datagridState.CustomizeColumnsButton />
</TableToolbarContent>
)
const datagridState = useDatagrid(
{
columns,
data,
initialState: {
hiddenColumns: ['age'],
columnOrder: [],
},
customizeColumnsProps: {
onSaveColumnPrefs: (newColDefs) => {
console.log(newColDefs);
},
},
DatagridActions,
},
useCustomizeColumns,
useColumnOrder,
);

return (
<Datagrid datagridState={datagridState} />
);
```

## Disabling select rows

Disabling select rows allows you to choose which rows will be disabled in the
table.

1. Include the `useDisableSelectRows` hook in the `endPlugins` property of
`useDatagrid`.
2. Add the `shouldDisableSelectRow` to the `useDatagrid` hook, this will be a
function that returns the row indexes that will be disabled.

```jsx
const [data] = useState(makeData(10));
const columns = React.useMemo(() => getColumns(data), []);
const datagridState = useDatagrid(
{
columns,
data,
DatagridActions,
DatagridBatchActions,
endPlugins: [useDisableSelectRows],
shouldDisableSelectRow: (row) => row.id % 2 === 0,
disableSelectAll: true,
},
useSelectRows
);

return <Datagrid datagridState={datagridState} />;
```

## Infinite scroll

Infinite scroll is supported via the `useInfiniteScroll` hook. This hook will
allow you to fetch more data to display to the user after a certain scroll
threshold. The `useInfiniteScroll` hook can also be used to support virtualized
data, this is required when working with large amounts of data, only rendering
the rows that need to be visible in the component at a point in time.

Infinite scroll:

1. Include `useInfiniteScroll` hook
2. Add `fetchMoreData` property to `useDatagrid`, this will be a function that
is called when the scroll threshold is met. Optionally change the height of
the grid with the `virtualHeight` property.

```jsx
const datagridState = useDatagrid(
{
columns,
data,
isFetching,
fetchMoreData: fetchData,
virtualHeight: 540,
emptyStateTitle: 'Empty state title',
emptyStateDescription: 'Description explaining why the table is empty',
},
useInfiniteScroll
);
```

Virtualized data:

1. Include `useInfiniteScroll` hook
2. The Datagrid will know to use virtualized data just by providing the
`useInfiniteScroll` hook

```jsx
const [data] = useState(makeData(10000));
const columns = React.useMemo(() => getColumns(data), []);
const datagridState = useDatagrid(
{
columns,
data,
},
useInfiniteScroll
);
```

## Code sample

<CodesandboxLink exampleDirectory="Datagrid" />
Expand Down

0 comments on commit f692d10

Please sign in to comment.