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

Update <SimpleList> to fallback to recordRepresentation when not given primaryText #9172

Merged
merged 3 commits into from
Aug 11, 2023
Merged

Update <SimpleList> to fallback to recordRepresentation when not given primaryText #9172

Show file tree
Hide file tree
Changes from 1 commit
Commits
Show all changes
3 commits
Select commit Hold shift + click to select a range
43c1d90
Add ability to use SimpleList without `primaryText`
fzaninotto Aug 10, 2023
8f4af81
Apply suggestions from code review
fzaninotto Aug 11, 2023
d3dfe79
Review
fzaninotto Aug 11, 2023
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
188 changes: 95 additions & 93 deletions docs/Datagrid.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -38,24 +38,24 @@ The `<Datagrid>` is an **iterator** component: it gets an array of records from

## Props

Here are all the props accepted by the component:

* [`body`](#body)
* [`bulkActionButtons`](#bulkactionbuttons)
* [`children`](#children)
* [`empty`](#empty)
* [`expand`](#expand)
* [`expandSingle`](#expandsingle)
* [`header`](#header)
* [`hover`](#hover)
* [`isRowExpandable`](#isrowexpandable)
* [`isRowSelectable`](#isrowselectable)
* [`optimized`](#optimized-better-performance-for-large-tables)
* [`rowStyle`](#rowstyle)
* [`rowSx`](#rowsx)
* [`rowClick`](#rowclick)
* [`size`](#size)
* [`sx`](#sx-css-api)
| 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 @@ -107,39 +107,6 @@ const PostList = () => (
export default PostList;
```

## `children`

`<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.

You can even create your own field components.

```jsx
// in src/posts.js
import * as React from 'react';
import { useRecordContext, List, Datagrid, TextField, DateField } from 'react-admin';

const FullNameField = () => {
const record = useRecordContext();
return <span>{record.firstName} {record.lastName}</span>;
}

export const UserList = () => (
<List>
<Datagrid rowclick="edit">
<FullNameField source="last_name" label="Name" />
<DateField source="dob" />
<TextField source="city" />
</Datagrid>
</List>
);
```

`<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.

## `bulkActionButtons`

<video controls autoplay playsinline muted loop>
Expand Down Expand Up @@ -377,6 +344,39 @@ const CustomResetViewsButton = () => {
};
```

## `children`

`<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.

You can even create your own field components.

```jsx
// in src/posts.js
fzaninotto marked this conversation as resolved.
Show resolved Hide resolved
import * as React from 'react';
import { useRecordContext, List, Datagrid, TextField, DateField } from 'react-admin';

const FullNameField = () => {
const record = useRecordContext();
return <span>{record.firstName} {record.lastName}</span>;
}

export const UserList = () => (
<List>
<Datagrid rowclick="edit">
<FullNameField source="last_name" label="Name" />
<DateField source="dob" />
<TextField source="city" />
</Datagrid>
</List>
);
```

`<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.

## `empty`

It's possible that a Datagrid will have no records to display. If the Datagrid's parent component does not handle the empty state, the Datagrid will display a message indicating there are no results. This message is translatable and its key is `ra.navigation.no_results`.
Expand Down Expand Up @@ -606,7 +606,7 @@ export const PostList = () => (
```
{% endraw %}

## `optimized`: Better Performance For Large Tables
## `optimized`

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.
Expand All @@ -628,90 +628,92 @@ const PostList = () => (
);
```

## `rowStyle`

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.
## `rowClick`

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.
You can catch clicks on rows to redirect to the show or edit view by setting the `rowClick` prop:

```jsx
import { List, Datagrid } from 'react-admin';

const postRowStyle = (record, index) => ({
backgroundColor: record.nb_views >= 500 ? '#efe' : 'white',
});
export const PostList = () => (
<List>
<Datagrid rowStyle={postRowStyle}>
<Datagrid rowClick="edit">
...
</Datagrid>
</List>
);
```

## `rowSx`
`rowClick` accepts the following values:

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.
* "edit" to redirect to the edition vue
fzaninotto marked this conversation as resolved.
Show resolved Hide resolved
* "show" to redirect to the show vue
fzaninotto marked this conversation as resolved.
Show resolved Hide resolved
* "expand" to open the `expand` panel
* "toggleSelection" to trigger the `onToggleItem` function
* `false` to do nothing
* a function `(id, resource, record) => path` that may return any of the above values or a custom path

**Tip**: If you pass a function, it can return `'edit'`, `'show'`, `false` or a router path. This allows to redirect to either the Edit or Show view after checking a condition on the record. For example:

```js
const postRowClick = (id, resource, record) => record.editable ? 'edit' : 'show';
```

**Tip**: If you pass a function, it can also return a promise allowing you to check an external API before returning a path. For example:

```js
import fetchUserRights from './fetchUserRights';

const getPermissions = useGetPermissions();
const postRowClick = (id, resource, record) =>
useGetPermissions()
.then(permissions => permissions === 'admin' ? 'edit' : 'show');
```

## `rowStyle`

*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.

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.

```jsx
import { List, Datagrid } from 'react-admin';

const postRowSx = (record, index) => ({
const postRowStyle = (record, index) => ({
backgroundColor: record.nb_views >= 500 ? '#efe' : 'white',
});
export const PostList = () => (
<List>
<Datagrid rowSx={postRowSx}>
<Datagrid rowStyle={postRowStyle}>
...
</Datagrid>
</List>
);
```

## `rowClick`
## `rowSx`

You can catch clicks on rows to redirect to the show or edit view by setting the `rowClick` 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.

```jsx
import { List, Datagrid } from 'react-admin';

const postRowSx = (record, index) => ({
backgroundColor: record.nb_views >= 500 ? '#efe' : 'white',
});
export const PostList = () => (
<List>
<Datagrid rowClick="edit">
<Datagrid rowSx={postRowSx}>
...
</Datagrid>
</List>
);
```

`rowClick` accepts the following values:

* "edit" to redirect to the edition vue
* "show" to redirect to the show vue
* "expand" to open the `expand` panel
* "toggleSelection" to trigger the `onToggleItem` function
* `false` to do nothing
* a function `(id, resource, record) => path` that may return any of the above values or a custom path

**Tip**: If you pass a function, it can return `'edit'`, `'show'`, `false` or a router path. This allows to redirect to either the Edit or Show view after checking a condition on the record. For example:

```js
const postRowClick = (id, resource, record) => record.editable ? 'edit' : 'show';
```

**Tip**: If you pass a function, it can also return a promise allowing you to check an external API before returning a path. For example:

```js
import fetchUserRights from './fetchUserRights';

const getPermissions = useGetPermissions();
const postRowClick = (id, resource, record) =>
useGetPermissions()
.then(permissions => permissions === 'admin' ? 'edit' : 'show');
```

## `size`

The `<Datagrid>` is designed for a high density of content, so the row padding is low. If you want to add more margin to each cell, set the `size` prop to `medium`.
Expand Down
85 changes: 50 additions & 35 deletions docs/SimpleList.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -37,19 +37,40 @@ export const PostList = () => (

`<SimpleList>` executes the functions passed as `primaryText`, `secondaryText`, and `tertiaryText` on render, passing the current `record` as parameter. It uses the result to render each List item.

It accepts the following props:

* [`primaryText`](#primarytext) (required)
* [`secondaryText`](#secondarytext)
* [`tertiaryText`](#tertiarytext)
* [`linkType`](#linktype)
* [`leftAvatar`](#leftavatar)
* [`leftIcon`](#lefticon)
* [`rightAvatar`](#rightavatar)
* [`rightIcon`](#righticon)
* [`rowStyle`](#rowstyle)
* [`rowSx`](#rowsx)
* [`empty`](#empty)
## Props

| Prop | Required | Type | Default | Description |
| --- | --- | --- | --- | --- |
| `primaryText` | Optional | mixed | record representation | The primary text to display. |
fzaninotto marked this conversation as resolved.
Show resolved Hide resolved
| `secondaryText` | Optional | mixed | | The secondary text to display. |
| `tertiaryText` | Optional | mixed | | The tertiary text to display. |
| `linkType` | Optional |mixed | `"edit"` | The target of each item click |
fzaninotto marked this conversation as resolved.
Show resolved Hide resolved
| `leftAvatar` | Optional | function | | A function returning an `<Avatar>` component to display before the primary text. |
| `leftIcon` | Optional | function | | A function returning an `<Icon>` component to display before the primary text. |
| `rightAvatar` | Optional | function | | A function returning an `<Avatar>` component to display after the primary text. |
| `rightIcon` | Optional | function | | A function returning an `<Icon>` component to display after the primary text. |
| `rowStyle` | Optional | function | | A function returning a style object to apply to each row. |
| `rowSx` | Optional | function | | A function returning a sx object to apply to each row. |
| `empty` | Optional | ReactElement | | A ReactElement to display instead of the list when the data is empty. |

## `empty`

It's possible that a SimpleList will have no records to display. If the SimpleList's parent component does not handle the empty state, the SimpleList will display a message indicating there are no results. This message is translatable and its key is `ra.navigation.no_results`.
fzaninotto marked this conversation as resolved.
Show resolved Hide resolved

You can customize the empty state by passing a component to the `empty` prop:

```jsx
const CustomEmpty = () => <div>No books found</div>;

const PostList = () => (
<List>
<SimpleList
primaryText={record => record.title}
empty={<CustomEmpty />}
/>
</List>
);
```

## `leftAvatar`

Expand Down Expand Up @@ -78,22 +99,20 @@ export const PostList = () => (
);
```


`linkType` accepts the following values:

* `linkType="edit"`: links to the edit page. This is the default behavior.
* `linkType="show"`: links to the show page.
* `linkType={false}`: does not create any link.



## `primaryText`

The `primaryText`, `secondaryText` and `tertiaryText` props can accept 3 types of values:
The `primaryText`, `secondaryText` and `tertiaryText` props can accept 4 types of values:

1. a function returning a string,
2. a string,
3. a React element.
4. `undefined` (the default)

If it's a **function**, react-admin passes the current record as parameter:

Expand Down Expand Up @@ -151,6 +170,18 @@ export const PostList = () => (

`<SimpleList>` creates a `RecordContext` for each list item. This allows Field components to grab the current record using [`useRecordContext`](./useRecordContext.md).

If it's **undefined**, react-admin uses the [`recordRepresentation`](./Resource.md#recordrepresentation) for the current Resource. This is the default value.

```jsx
import { List, SimpleList } from 'react-admin';

export const PostList = () => (
<List>
<SimpleList />
</List>
);
```

## `rightAvatar`

This prop should be a function returning an `<Avatar>` component. When present, the `<ListItem>` renders a `<ListItemAvatar>` after the `<ListItemText>`
Expand All @@ -161,6 +192,8 @@ This prop should be a function returning an `<Icon>` component. When present, th

## `rowStyle`

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

This optional prop should be a function, which gets called for each row. It receives the current record and index as arguments, and should return a style object. The style object is applied to the `<ListItem>` styles prop.

```jsx
Expand Down Expand Up @@ -203,24 +236,6 @@ See [`primaryText`](#primarytext)

See [`primaryText`](#primarytext)

## `empty`

It's possible that a SimpleList will have no records to display. If the SimpleList's parent component does not handle the empty state, the SimpleList will display a message indicating there are no results. This message is translatable and its key is `ra.navigation.no_results`.

You can customize the empty state by passing a component to the `empty` prop:

```jsx
const CustomEmpty = () => <div>No books found</div>;

const PostList = () => (
<List>
<SimpleList
primaryText={record => record.title}
empty={<CustomEmpty />}
/>
</List>
);
```

## Using `<SimpleList>` On Small Screens

Expand Down
Loading
Loading