Skip to content

Commit 8384ca3

Browse files
committed
Improve documentation
1 parent a55d5ef commit 8384ca3

File tree

6 files changed

+112
-13
lines changed

6 files changed

+112
-13
lines changed

docs/DataTable.md

Lines changed: 3 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -757,7 +757,9 @@ export const PostList = () => (
757757

758758
## `offline`
759759

760-
It's possible that a `<DataTable>` will have no records to display because of connectivity issues. In that case, `<DataTable>` will display a message indicating data couldn't be fetched.
760+
It's possible that a `<DataTable>` will have no records to display because of connectivity issues. In that case, `<DataTable>` will display the following message:
761+
762+
> No connectivity. Could not fetch data.
761763
762764
You can customize this message via react-admin's [translation system](./Translation.md), by setting a custom translation for the `ra.notification.offline` key.
763765

docs/Datagrid.md

Lines changed: 16 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -643,9 +643,23 @@ export const PostList = () => (
643643

644644
## `offline`
645645

646-
It's possible that a Datagrid will have no records to display because of connectivity issues. In that case, the Datagrid will display a message indicating data couldn't be fetched. This message is translatable and its key is `ra.notification.offline`.
646+
It's possible that a `<Datagrid>` will have no records to display because of connectivity issues. In that case, `<Datagrid>` will display the following message:
647647

648-
You can customize the content to display by passing a component to the `offline` prop:
648+
> No connectivity. Could not fetch data.
649+
650+
You can customize this message via react-admin's [translation system](./Translation.md), by setting a custom translation for the `ra.notification.offline` key.
651+
652+
```tsx
653+
const messages = {
654+
ra: {
655+
notification: {
656+
offline: "No network. Data couldn't be fetched.",
657+
}
658+
}
659+
}
660+
```
661+
662+
If you need to go beyond text, pass a custom element as the `<Datagrid offline>` prop:
649663

650664
```tsx
651665
const CustomOffline = () => <div>No network. Data couldn't be fetched.</div>;

docs/Edit.md

Lines changed: 4 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -72,7 +72,7 @@ You can customize the `<Edit>` component using the following props:
7272
| `id` | | `string | number` | | the id of the record to edit |
7373
| `mutationMode` | | `pessimistic | optimistic | undoable` | | switch to optimistic or pessimistic mutations (undoable by default) |
7474
| `mutationOptions` | | `object` | | options for the `dataProvider.update()` call |
75-
| `offline` | | `ReactNode` | | The content rendered to render when data could not be fetched because of connectivity issues |
75+
| `offline` | | `ReactNode` | `<Offline>` | The content rendered to render when data could not be fetched because of connectivity issues |
7676
| `queryOptions` | | `object` | | options for the `dataProvider.getOne()` call |
7777
| `redirect` | | `string | Function | false` | | change the redirect location after successful creation |
7878
| `resource` | | `string` | | override the name of the resource to create |
@@ -493,7 +493,9 @@ The default `onError` function is:
493493

494494
## `offline`
495495

496-
It's possible that an `<Edit>` will have no record to display because of connectivity issues. In that case, `<Edit>` will display a message indicating data couldn't be fetched.
496+
It's possible that a `<Edit>` will have no records to display because of connectivity issues. In that case, `<Edit>` will display the following message:
497+
498+
> No connectivity. Could not fetch data.
497499
498500
You can customize this message via react-admin's [translation system](./Translation.md), by setting a custom translation for the `ra.notification.offline` key.
499501

docs/Show.md

Lines changed: 4 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -68,7 +68,7 @@ That's enough to display the post show view above.
6868
| `disable Authentication` | Optional | `boolean` | | Set to `true` to disable the authentication check
6969
| `empty WhileLoading` | Optional | `boolean` | | Set to `true` to return `null` while the show is loading
7070
| `id` | Optional | `string | number` | | The record id. If not provided, it will be deduced from the URL
71-
| `offline` | Optional | `ReactNode` | | The content rendered to render when data could not be fetched because of connectivity issues
71+
| `offline` | | `ReactNode` | `<Offline>` | The content rendered to render when data could not be fetched because of connectivity issues |
7272
| `queryOptions` | Optional | `object` | | The options to pass to the `useQuery` hook
7373
| `resource` | Optional | `string` | | The resource name, e.g. `posts`
7474
| `sx` | Optional | `object` | | Override or extend the styles applied to the component
@@ -279,7 +279,9 @@ export const PostShow = () => (
279279

280280
## `offline`
281281

282-
It's possible that a `<Show>` will have no record to display because of connectivity issues. In that case, `<Show>` will display a message indicating data couldn't be fetched.
282+
It's possible that a `<Show>` will have no records to display because of connectivity issues. In that case, `<Show>` will display the following message:
283+
284+
> No connectivity. Could not fetch data.
283285
284286
You can customize this message via react-admin's [translation system](./Translation.md), by setting a custom translation for the `ra.notification.offline` key.
285287

docs/SimpleList.md

Lines changed: 33 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -47,6 +47,7 @@ export const PostList = () => (
4747
| `rowClick` | Optional |mixed | `"edit"` | The action to trigger when the user clicks on a row. |
4848
| `leftAvatar` | Optional | function | | A function returning an `<Avatar>` component to display before the primary text. |
4949
| `leftIcon` | Optional | function | | A function returning an `<Icon>` component to display before the primary text. |
50+
| `offline` | Optional | Element | `<Offline>` | The content rendered to render when data could not be fetched because of connectivity issues. |
5051
| `rightAvatar` | Optional | function | | A function returning an `<Avatar>` component to display after the primary text. |
5152
| `rightIcon` | Optional | function | | A function returning an `<Icon>` component to display after the primary text. |
5253
| `rowStyle` | Optional | function | | A function returning a style object to apply to each row. |
@@ -80,6 +81,38 @@ This prop should be a function returning an `<Avatar>` component. When present,
8081

8182
This prop should be a function returning an `<Icon>` component. When present, the `<ListItem>` renders a `<ListIcon>` before the `<ListItemText>`
8283

84+
## `offline`
85+
86+
It's possible that a `<SimpleList>` will have no records to display because of connectivity issues. In that case, `<SimpleList>` will display the following message:
87+
88+
> No connectivity. Could not fetch data.
89+
90+
You can customize this message via react-admin's [translation system](./Translation.md), by setting a custom translation for the `ra.notification.offline` key.
91+
92+
```tsx
93+
const messages = {
94+
ra: {
95+
notification: {
96+
offline: "No network. Data couldn't be fetched.",
97+
}
98+
}
99+
}
100+
```
101+
102+
If you need to go beyond text, pass a custom element as the `<SimpleList offline>` prop:
103+
104+
```tsx
105+
const Offline = () => (
106+
<p>No network. Data couldn't be fetched.</p>
107+
);
108+
109+
const BookList = () => (
110+
<List>
111+
<SimpleList offline={<Offline />} />
112+
</List>
113+
);
114+
```
115+
83116
## `primaryText`
84117

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

docs/SingleFieldList.md

Lines changed: 52 additions & 6 deletions
Original file line numberDiff line numberDiff line change
@@ -83,12 +83,13 @@ You can customize how each record is displayed by passing a Field component as c
8383

8484
`<SingleFieldList>` accepts the following props:
8585

86-
| Prop | Required | Type | Default | Description |
87-
| ----------- | -------- | ------------------------- | ------- | ----------------------------------------------- |
88-
| `children` | Optional | `ReactNode` | | React element to render for each record |
89-
| `empty` | Optional | `ReactNode` | | React element to display when the list is empty |
90-
| `linkType` | Optional | `'edit' | 'show' | false` | `edit` | The target of the link on each item |
91-
| `sx` | Optional | `object` | | The sx props of the Material UI Box component |
86+
| Prop | Required | Type | Default | Description |
87+
| ----------- | -------- | ------------------------- | ------------------------------ | ----------------------------------------------- |
88+
| `children` | Optional | `ReactNode` | | React element to render for each record |
89+
| `empty` | Optional | `ReactNode` | | React element to display when the list is empty |
90+
| `linkType` | Optional | `'edit' | 'show' | false` | `edit` | The target of the link on each item |
91+
| `offline` | Optional | Element | `<Offline variant="inline" />` | The content rendered to render when data could not be fetched because of connectivity issues. |
92+
| `sx` | Optional | `object` | | The sx props of the Material UI Box component |
9293

9394
Additional props are passed down to the underlying [Material UI `<Stack>` component](https://mui.com/material-ui/react-stack/).
9495

@@ -133,6 +134,51 @@ The `<SingleFieldList>` items link to the edition page by default. You can set t
133134
* `linkType="show"`: links to the show page.
134135
* `linkType={false}`: does not create any link.
135136

137+
## `offline`
138+
139+
It's possible that a `<SingleFieldList>` will have no records to display because of connectivity issues. In that case, `<SingleFieldList>` will display the following message:
140+
141+
> No connectivity. Could not fetch data.
142+
143+
You can customize this message via react-admin's [translation system](./Translation.md), by setting a custom translation for the `ra.notification.offline` key.
144+
145+
```tsx
146+
const messages = {
147+
ra: {
148+
notification: {
149+
offline: "No network. Data couldn't be fetched.",
150+
}
151+
}
152+
}
153+
```
154+
155+
If you need to go beyond text, pass a custom element as the `<SingleFieldList offline>` prop:
156+
157+
```tsx
158+
import {
159+
Show,
160+
SimpleShowLayout,
161+
TextField,
162+
ReferenceArrayField,
163+
SingleFieldList
164+
} from 'react-admin';
165+
166+
const Offline = () => (
167+
<p>No network. Data couldn't be fetched.</p>
168+
);
169+
170+
const PostShow = () => (
171+
<Show>
172+
<SimpleShowLayout>
173+
<TextField source="title" />
174+
<ReferenceArrayField label="Tags" reference="tags" source="tags">
175+
<SingleFieldList offline={<Offline />} />
176+
</ReferenceArrayField>
177+
</SimpleShowLayout>
178+
</Show>
179+
);
180+
```
181+
136182
## `sx`: CSS API
137183

138184
The `<SingleFieldList>` component accepts the usual `className` prop. You can also override the styles of the inner components thanks to the `sx` property. This property accepts the following subclasses:

0 commit comments

Comments
 (0)