Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Jump to bottom

[Doc] Update Datagrid documentation regarding preferenceKey #9649

Merged
merged 5 commits into from
Feb 12, 2024
Merged

[Doc] Update Datagrid documentation regarding preferenceKey #9649

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
5 commits
Select commit Hold shift + click to select a range
466b07c
update doc
erwanMarmelab Feb 7, 2024
3b568c7
add an example
erwanMarmelab Feb 7, 2024
c8d0103
add specifications
erwanMarmelab Feb 7, 2024
6a0ad09
add links and use SelectColumnsButton in TopToolbar
erwanMarmelab Feb 9, 2024
8b5701e
rename preference key
erwanMarmelab Feb 12, 2024
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
91 changes: 56 additions & 35 deletions docs/Datagrid.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -35,37 +35,37 @@ export const PostList = () => (

![The `<Datagrid>` component](./img/tutorial_post_list_less_columns.png)

You can find more advanced examples of `<Datagrid>` usage in the [demos](./Demos.md).
You can find more advanced examples of `<Datagrid>` usage in the [demos](./Demos.md).

The `<Datagrid>` is an **iterator** component: it gets an array of records from the `ListContext`, and iterates to display each record in a row. Other examples of iterator component are [`<SimpleList>`](./SimpleList.md) and [`<SingleFieldList>`](./SingleFieldList.md).

**Tip**: If you need more Datagrid features, check out these two alternative components:

- [`<EditableDatagrid>`](./EditableDatagrid.md)<img class="icon" src="./img/premium.svg" /> lets users edit the content right in the datagrid
- [`<DatagridAG>`](./DatagridAG.md)<img class="icon" src="./img/premium.svg" /> adds suport for column reordering, aggregation, pivoting, row grouping, infinite scroll, etc.
- [`<DatagridAG>`](./DatagridAG.md)<img class="icon" src="./img/premium.svg" /> adds suport for column reordering, aggregation, pivoting, row grouping, infinite scroll, etc.

Both are [Enterprise Edition](https://marmelab.com/ra-enterprise) components.

## Props

| Prop | Required | Type | Default | Description |
| --- | --- | --- | --- | --- |
| `children` | Required | Element | n/a | The list of `<Field>` components to render as columns. |
| `body` | Optional | Element | `<Datagrid Body>` | The component used to render the body of the table. |
| `bulkActionButtons` | Optional | Element | `<BulkDelete Button>` | The component used to render the bulk action buttons. |
| `empty` | Optional | Element | `<Empty>` | The component used to render the empty table. |
| `expand` | Optional | Element | | The component used to render the expand panel for each row. |
| `expandSingle` | Optional | Boolean | `false` | Whether to allow only one expanded row at a time. |
| `header` | Optional | Element | `<Datagrid Header>` | The component used to render the table header. |
| `hover` | Optional | Boolean | `true` | Whether to highlight the row under the mouse. |
| `isRowExpandable` | Optional | Function | `() => true` | A function that returns whether a row is expandable. |
| `isRowSelectable` | Optional | Function | `() => true` | A function that returns whether a row is selectable. |
| `optimized` | Optional | Boolean | `false` | Whether to optimize the rendering of the table. |
| `rowClick` | Optional | mixed | | The action to trigger when the user clicks on a row. |
| `rowStyle` | Optional | Function | | A function that returns the style to apply to a row. |
| `rowSx` | Optional | Function | | A function that returns the sx prop to apply to a row. |
| `size` | Optional | `'small'` or `'medium'` | `'small'` | The size of the table. |
| `sx` | Optional | Object | | The sx prop passed down to the Material UI `<Table>` element. |
| Prop | Required | Type | Default | Description |
| ------------------- | -------- | ----------------------- | --------------------- | ------------------------------------------------------------- |
| `children` | Required | Element | n/a | The list of `<Field>` components to render as columns. |
| `body` | Optional | Element | `<Datagrid Body>` | The component used to render the body of the table. |
| `bulkActionButtons` | Optional | Element | `<BulkDelete Button>` | The component used to render the bulk action buttons. |
| `empty` | Optional | Element | `<Empty>` | The component used to render the empty table. |
| `expand` | Optional | Element | | The component used to render the expand panel for each row. |
| `expandSingle` | Optional | Boolean | `false` | Whether to allow only one expanded row at a time. |
| `header` | Optional | Element | `<Datagrid Header>` | The component used to render the table header. |
| `hover` | Optional | Boolean | `true` | Whether to highlight the row under the mouse. |
| `isRowExpandable` | Optional | Function | `() => true` | A function that returns whether a row is expandable. |
| `isRowSelectable` | Optional | Function | `() => true` | A function that returns whether a row is selectable. |
| `optimized` | Optional | Boolean | `false` | Whether to optimize the rendering of the table. |
| `rowClick` | Optional | mixed | | The action to trigger when the user clicks on a row. |
| `rowStyle` | Optional | Function | | A function that returns the style to apply to a row. |
| `rowSx` | Optional | Function | | A function that returns the sx prop to apply to a row. |
| `size` | Optional | `'small'` or `'medium'` | `'small'` | The size of the table. |
| `sx` | Optional | Object | | The sx prop passed down to the Material UI `<Table>` element. |

Additional props are passed down to [the Material UI `<Table>` element](https://mui.com/material-ui/api/table/).

Expand Down Expand Up @@ -379,7 +379,7 @@ const CustomResetViewsButton = () => {

`<Datagrid>` accepts a list of Field components as children. It inspects each child's `source` and/or `label` props to determine the name of the column.

What's a Field component? Simply a component that reads the record (via `useRecordContext`) and renders a value. React-admin includes many Field components that you can use as children of `<Datagrid>` (`<TextField>`, `<NumberField>`, `<DateField>`, `<ReferenceField>`, and many more). Check [the Fields documentation](./Fields.md) for more information.
What's a Field component? Simply a component that reads the record (via `useRecordContext`) and renders a value. React-admin includes many Field components that you can use as children of `<Datagrid>` (`<TextField>`, `<NumberField>`, `<DateField>`, `<ReferenceField>`, and many more). Check [the Fields documentation](./Fields.md) for more information.

You can even create your own field components.

Expand All @@ -404,7 +404,7 @@ export const UserList = () => (
);
```

`<Datagrid>` also inspects its children for `headerClassName` and `cellClassName` props, and gives the class names to the headers and the cells of that column.
`<Datagrid>` also inspects its children for `headerClassName` and `cellClassName` props, and gives the class names to the headers and the cells of that column.

Finally, `<Datagrid>` inspects children for props that indicate how it should be sorted (see [the Customizing The Sort Order For Columns section](#customizing-column-sort)) below.

Expand Down Expand Up @@ -437,7 +437,7 @@ const PostList = () => (
</video>


To show more data from the resource without adding too many columns, you can show data in an expandable panel below the row on demand, using the `expand` prop.
To show more data from the resource without adding too many columns, you can show data in an expandable panel below the row on demand, using the `expand` prop.

For instance, this code shows the `body` of a post in an expandable panel:

Expand Down Expand Up @@ -605,9 +605,9 @@ const PostPanel = () => {

const PostList = () => (
<List>
<Datagrid
<Datagrid
expand={<PostPanel />}
isRowExpandable={row => row.has_detail}
isRowExpandable={row => row.has_detail}
>
<TextField source="id" />
<TextField source="title" />
Expand Down Expand Up @@ -643,7 +643,7 @@ export const PostList = () => (
When displaying large pages of data, you might experience some performance issues.
This is mostly due to the fact that we iterate over the `<Datagrid>` children and clone them.

In such cases, you can opt-in for an optimized version of the `<Datagrid>` by setting its `optimized` prop to `true`.
In such cases, you can opt-in for an optimized version of the `<Datagrid>` by setting its `optimized` prop to `true`.
Be aware that you can't have dynamic children, such as those displayed or hidden by checking permissions, when using this mode.

```tsx
Expand Down Expand Up @@ -699,7 +699,7 @@ import { Identifier, RaRecord } from 'react-admin';
import fetchUserRights from './fetchUserRights';

const getPermissions = useGetPermissions();
const postRowClick = (id: Identifier, resource: string, record: RaRecord) =>
const postRowClick = (id: Identifier, resource: string, record: RaRecord) =>
useGetPermissions()
.then(permissions => permissions === 'admin' ? 'edit' : 'show');
```
Expand All @@ -708,7 +708,7 @@ const postRowClick = (id: Identifier, resource: string, record: RaRecord) =>

*Deprecated - use [`rowSx`](#rowsx) instead.*

You can customize the `<Datagrid>` row style (applied to the `<tr>` element) based on the record, thanks to the `rowStyle` prop, which expects a function. React-admin calls this function for each row, passing the current record and index as arguments. The function should return a style object, which react-admin uses as a `<tr style>` prop.
You can customize the `<Datagrid>` row style (applied to the `<tr>` element) based on the record, thanks to the `rowStyle` prop, which expects a function. React-admin calls this function for each row, passing the current record and index as arguments. The function should return a style object, which react-admin uses as a `<tr style>` prop.

For instance, this allows to apply a custom background to the entire row if one value of the record - like its number of views - passes a certain threshold.

Expand All @@ -729,7 +729,7 @@ export const PostList = () => (

## `rowSx`

You can customize the styles of rows and cells in `<Datagrid>` (applied to the `<DatagridRow>` element) based on the record, thanks to the `rowSx` prop, which expects a function. React-admin calls this function for each row, passing the current record and index as arguments. The function should return a Material UI [`sx`](https://mui.com/system/getting-started/the-sx-prop/), which react-admin uses as a `<TableRow sx>` prop.
You can customize the styles of rows and cells in `<Datagrid>` (applied to the `<DatagridRow>` element) based on the record, thanks to the `rowSx` prop, which expects a function. React-admin calls this function for each row, passing the current record and index as arguments. The function should return a Material UI [`sx`](https://mui.com/system/getting-started/the-sx-prop/), which react-admin uses as a `<TableRow sx>` prop.

For instance, this allows to apply a custom background to the entire row if one value of the record - like its number of views - passes a certain threshold.

Expand Down Expand Up @@ -762,7 +762,7 @@ export const PostList = () => (
);
```

**Tip**: `size` is actually a prop of the Material UI `<Table>` component. Just like all additional `<Datagrid>` props, it is passed down to the `<Table>` component.
**Tip**: `size` is actually a prop of the Material UI `<Table>` component. Just like all additional `<Datagrid>` props, it is passed down to the `<Table>` component.

## `sx`: CSS API

Expand Down Expand Up @@ -827,7 +827,7 @@ const PostList = () => (
Your browser does not support the video tag.
</video>

You don't need to do anything for this to work, as it's enabled by default.
You don't need to do anything for this to work, as it's enabled by default.

## Configurable

Expand Down Expand Up @@ -896,6 +896,27 @@ const PostList = () => (
);
```

If you include a [`<SelectColumnsButton>`](./SelectColumnsButton.md) in a page that has more than one `<DatagridConfigurable>`, you have to link the two components by giving them the same preferenceKey:

```tsx
const PostListActions = () => (
<TopToolbar>
<SelectColumnsButton preferenceKey="posts.datagrid" />
</TopToolbar>
);

const PostList = () => (
<List actions={<PostListActions />}>
<DatagridConfigurable preferenceKey="posts.datagrid">
<TextField source="id" />
<TextField source="title" />
<TextField source="author" />
<TextField source="year" />
</DatagridConfigurable>
</List>
);
```

The inspector uses the field `source` (or `label` when it's a string) to display the column name. If you use non-field children (e.g. action buttons), then it's your responsibility to wrap them in a component with a `label` prop, that will be used by the inspector. You can use a [`<WrapperField>`](./WrapperField.md) for that purpose:

```tsx
Expand Down Expand Up @@ -940,7 +961,7 @@ The separation between list pages and edit pages is not always relevant. Sometim
Your browser does not support the video tag.
</video>

`<EditableDatagrid>` is a drop-in replacement for `<Datagrid>`. It expects 2 additional props: `createForm` and `editForm`, the components to be displayed when a user creates or edits a row. The `<RowForm>` component allows to create such forms using react-admin Input components.
`<EditableDatagrid>` is a drop-in replacement for `<Datagrid>`. It expects 2 additional props: `createForm` and `editForm`, the components to be displayed when a user creates or edits a row. The `<RowForm>` component allows to create such forms using react-admin Input components.

```tsx
import {
Expand Down Expand Up @@ -1075,7 +1096,7 @@ Note how the `permissions` prop is passed down to the custom `filters` component

It's up to your `authProvider` to return whatever you need to check roles and permissions inside your component. Check [the authProvider documentation](./Authentication.md) for more information.

**Tip**: The [ra-rbac module](./AuthRBAC.md#datagrid) provides a wrapper for the `<Datagrid>` with built-in permission check for columns.
**Tip**: The [ra-rbac module](./AuthRBAC.md#datagrid) provides a wrapper for the `<Datagrid>` with built-in permission check for columns.

## Standalone Usage

Expand Down Expand Up @@ -1195,7 +1216,7 @@ const PostList = () => (

## Showing / Hiding Columns

The [`<SelectColumnsButton>`](./SelectColumnsButton.md) component lets users hide, show, and reorder datagrid columns.
The [`<SelectColumnsButton>`](./SelectColumnsButton.md) component lets users hide, show, and reorder datagrid columns.

<video controls autoplay playsinline muted loop>
<source src="./img/SelectColumnsButton.webm" type="video/webm"/>
Expand Down Expand Up @@ -1237,7 +1258,7 @@ const PostList = () => (
);
```

`<SelectColumnsButton>` must be used in conjunction with `<DatagridConfigurable>`, the configurable version of `<Datagrid>`, described in the next section.
[`<SelectColumnsButton>`](./SelectColumnsButton.md) must be used in conjunction with `<DatagridConfigurable>`, the configurable version of `<Datagrid>`, described in the next section.

**Tip**: For even more column customization (resizable columns, column grouping, etc.), check out the [`<DatagridAG>`](./DatagridAG.md) component.

Expand Down
46 changes: 19 additions & 27 deletions docs/SelectColumnsButton.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -14,10 +14,10 @@ This button lets users show or hide columns in a Datagrid. It must be used in co
</video>


## Usage
## Usage

Add the `<SelectColumnsButton>` component to the `<List actions>` prop:

```jsx
import {
DatagridConfigurable,
Expand Down Expand Up @@ -65,30 +65,22 @@ const ListActions = () => (
If you include `<SelectColumnsButton>` in a page that has more than one `<DatagridConfigurable>` (e.g. in a dasboard), you have to link the two components by giving them the same `preferenceKey`:

```jsx
const BookList = () => {
const { data, total, isLoading } = useGetList('books', {
pagination: { page: 1, perPage: 10 },
sort,
});
return (
<div>
<SelectColumnsButton preferenceKey="postList1" />
<DatagridConfigurable
preferenceKey="postList1"
data={data}
total={total}
isLoading={isLoading}
sort={sort}
bulkActionButtons={false}
>
<TextField source="id" />
<TextField source="title" />
<TextField source="author" />
<TextField source="year" />
</DatagridConfigurable>
</div>
);
};
const BookListActions = () => (
<TopToolbar>
<SelectColumnsButton preferenceKey="books.datagrid" />
</TopToolbar>
);

const BookList = () => (
<List actions={<BookListActions />}>
<DatagridConfigurable preferenceKey="books.datagrid">
<TextField source="id" />
<TextField source="title" />
<TextField source="author" />
<TextField source="year" />
</DatagridConfigurable>
</List>
);
```

## Adding a label to unlabeled columns
Expand All @@ -111,4 +103,4 @@ const PostList = () => (
);
```

**Tip:** You may need to clear your local storage to reflect the changes, as react-admin saves the computed column names in the Store. For the same reason, your users may need to log out and in again to see the changes. Alternatively, you can leverage [Store Invalidation](./Store.md#store-invalidation) to do it automatically.
**Tip:** You may need to clear your local storage to reflect the changes, as react-admin saves the computed column names in the Store. For the same reason, your users may need to log out and in again to see the changes. Alternatively, you can leverage [Store Invalidation](./Store.md#store-invalidation) to do it automatically.
Loading