Skip to content

Commit e887aec

Browse files
MadeorskMadeorsk
committed
Update docs for API changes and apply reviews.
1 parent 3797ecc commit e887aec

File tree

11 files changed

+208
-258
lines changed

11 files changed

+208
-258
lines changed

‎docs/RecordsIterator.md‎

Lines changed: 22 additions & 49 deletions
Original file line numberDiff line numberDiff line change
@@ -21,12 +21,15 @@ const MostVisitedPosts = () => (
2121
resource="posts"
2222
sort={{ field: 'views', order: 'DESC' }}
2323
perPage={20}
24+
emptyWhileLoading
2425
>
2526
<ul>
2627
<RecordsIterator
2728
render={record => <li>{record.title} - {record.views}</li>}
2829
/>
2930
</ul>
31+
32+
<WithListContext error={<div>Error loading list</div>} />
3033
</ListBase>
3134
);
3235
```
@@ -40,48 +43,42 @@ You can use `<RecordsIterator>` as a child of any component that provides a [`Li
4043
- [`<ReferenceArrayField>`](./ReferenceArrayField.md),
4144
- [`<ReferenceManyField>`](./ReferenceManyField.md)
4245

43-
`<RecordsIterator>` expects that data is properly loaded, without error. If you want to handle loading, error, offline and empty states, use properties on the component providing you the list context (like [`<List>`](./List.md), [`<ReferenceArrayField>`](./ReferenceArrayField.md), [`<ReferenceManyField>`](./ReferenceManyField.md)). You can also make use of [`<WithListContext>`](./WithListContext.md) [`loading`](./WithListContext.md#loading), [`errorElement`](./WithListContext.md#errorelement), [`offline`](./WithListContext.md#offline) and [`empty`](./WithListContext.md#empty) props.
46+
`<RecordsIterator>` expects that data is properly loaded, without error. If you want to handle loading, error, offline and empty states, use related props on the component providing you the list context (like [`<List loading>`](./List.md), [`<ReferenceArrayField loading>`](./ReferenceArrayField.md), [`<ReferenceManyField loading>`](./ReferenceManyField.md)). You can also make use of [`<WithListContext>`](./WithListContext.md) [`loading`](./WithListContext.md#loading), [`error`](./WithListContext.md#error), [`offline`](./WithListContext.md#offline) and [`empty`](./WithListContext.md#empty) props.
4447

4548
{% raw %}
4649
```jsx
47-
import { ListBase, RecordsIterator, WithListContext } from 'react-admin';
50+
import { ListBase, RecordsIterator } from 'react-admin';
4851

4952
const MostVisitedPosts = () => (
5053
<ListBase
5154
resource="posts"
5255
sort={{ field: 'views', order: 'DESC' }}
5356
perPage={20}
57+
loading={<p>Loading...</p>}
58+
error={<p>Something went wrong</p>}
59+
offline={<p>You are offline</p>}
5460
>
55-
<WithListContext
56-
loading={<p>Loading...</p>}
57-
errorElement={<p>Something went wrong</p>}
58-
empty={<p>No posts found</p>}
59-
offline={<p>You are offline</p>}
60-
>
61-
<ul>
62-
<RecordsIterator
63-
render={record => <li>{record.title} - {record.views}</li>}
64-
/>
65-
</ul>
66-
</WithListContext>
61+
<ul>
62+
<RecordsIterator
63+
render={record => <li>{record.title} - {record.views}</li>}
64+
/>
65+
</ul>
6766
</ListBase>
6867
);
6968
```
7069
{% endraw %}
7170

7271
## Props
7372

74-
`<RecordsIterator>` exposes the following important props:
73+
| Prop | Required | Type | Default | Description |
74+
| ----------- |-------------|-----------------------------------| ------- | ---------------------------------------------------------------------------------------------------- |
75+
| `children` | Optional`*` | `ReactNode` | - | The content to render for each record |
76+
| `data` | Optional`*` | `RaRecord[]` | - | The records. Defaults to the `data` from the [`ListContext`](./useListContext.md) |
77+
| `isPending` | Optional | `boolean` | - | A boolean indicating whether the data is pending. Defaults to the `isPending` from the [`ListContext`](./useListContext.md) |
78+
| `render` | Optional | `(record: RaRecord) => ReactNode` | - | A function that returns the content to render for each record |
79+
| `total` | Optional | `number` | - | The total number of records. Defaults to the `total` from the [`ListContext`](./useListContext.md) |
7580

76-
| Prop | Required | Type | Default | Description |
77-
| ----------- | -------- |-----------------------------------| ------- | ---------------------------------------------------------------------------------------------------- |
78-
| `children` | Optional | `ReactNode` | - | The content to render for each record |
79-
| `data` | Optional | `RaRecord[]` | - | The records. Defaults to the `data` from the [`ListContext`](./useListContext.md) |
80-
| `isPending` | Optional | `boolean` | - | A boolean indicating whether the data is pending. Defaults to the `isPending` from the [`ListContext`](./useListContext.md) |
81-
| `render` | Optional | `(record: RaRecord) => ReactNode` | - | A function that returns the content to render for each record |
82-
| `total` | Optional | `number` | - | The total number of records. Defaults to the `total` from the [`ListContext`](./useListContext.md) |
83-
84-
Either `children` or `render` is required.
81+
`*` Either `children` or `render` is required.
8582

8683
## `children`
8784

@@ -166,7 +163,7 @@ const DashboardMostVisitedPosts = () => {
166163

167164
## `render`
168165

169-
If provided, `RecordsIterator` will call the `render` prop for each record. This is useful when the components you render need the record data to render themselves, or when you want to pass additional props to the rendered component.
166+
If provided, `RecordsIterator` will call the `render` prop for each record. This is useful to customize the rendered component using the record data.
170167

171168
{% raw %}
172169
```tsx
@@ -185,27 +182,3 @@ const PostList = () => (
185182
{% endraw %}
186183

187184
**Note**: You can't provide both the `children` and the `render` props. If both are provided, `<RecordsIterator>` will use the `render` prop.
188-
189-
## `total`
190-
191-
Although `<RecordsIterator>` reads the total from the closest [`<ListContext>`](./useListContext), you may provide it yourself when no such context is available:
192-
193-
{% raw %}
194-
```jsx
195-
import { RecordsIterator, TextField } from 'react-admin';
196-
import { customerSegments } from './customerSegments.json';
197-
198-
const PostList = () => (
199-
<ul>
200-
<RecordsIterator
201-
data={customerSegments}
202-
total={customerSegments.length}
203-
>
204-
<li>
205-
<TextField source="name" />
206-
</li>
207-
</RecordsIterator>
208-
</ul>
209-
);
210-
```
211-
{% endraw %}

‎docs/ReferenceArrayFieldBase.md‎

Lines changed: 9 additions & 13 deletions
Original file line numberDiff line numberDiff line change
@@ -44,19 +44,15 @@ A typical `post` record therefore looks like this:
4444

4545
In that case, use `<ReferenceArrayFieldBase>` to display the post tag names as a list of chips, as follows:
4646

47-
```jsx
48-
import { ListBase, RecordsIterator, ReferenceArrayFieldBase, WithListContext } from 'react-admin';
49-
50-
export const PostList = () => (
51-
<ListBase>
52-
<WithListContext loading={null} errorElement={null} offline={null} empty={null}>
53-
<RecordsIterator>
54-
<ReferenceArrayFieldBase reference="tags" source="tag_ids">
55-
<TagList />
56-
</ReferenceArrayFieldBase>
57-
</RecordsIterator>
58-
</WithListContext>
59-
</ListBase>
47+
```tsx
48+
import { ShowBase, ReferenceArrayFieldBase } from 'ra-core';
49+
50+
export const PostShow = () => (
51+
<ShowBase>
52+
<ReferenceArrayFieldBase reference="tags" source="tag_ids">
53+
<TagList />
54+
</ReferenceArrayFieldBase>
55+
</ShowBase>
6056
);
6157

6258
const TagList = (props: { children: React.ReactNode }) => {

‎docs/ReferenceFieldBase.md‎

Lines changed: 25 additions & 23 deletions
Original file line numberDiff line numberDiff line change
@@ -218,22 +218,25 @@ By default, when used in a `<Datagrid>`, and when the user clicks on the column
218218

219219
<iframe src="https://www.youtube-nocookie.com/embed/egBhWqF3sWc" title="YouTube video player" frameborder="0" allow="accelerometer; autoplay; clipboard-write; encrypted-media; gyroscope; picture-in-picture; web-share" allowfullscreen style="aspect-ratio: 16 / 9;width:100%;margin-bottom:1em;"></iframe>
220220

221-
When used in a `<DataTable>`, `<ReferenceFieldBase>` fetches the referenced record only once for the entire table.
221+
When used in a [list context](./useListContext.md), `<ReferenceFieldBase>` fetches the referenced record only once for the entire table.
222222

223223
For instance, with this code:
224224

225225
```jsx
226-
import { ListBase, RecordsIterator, ReferenceFieldBase, WithListContext } from 'react-admin';
226+
import { ListBase, RecordsIterator, ReferenceFieldBase } from 'react-admin';
227227

228228
export const PostList = () => (
229-
<ListBase>
230-
<WithListContext loading={null} errorElement={null} offline={null} empty={null}>
231-
<RecordsIterator>
232-
<ReferenceFieldBase source="user_id" reference="users">
233-
<AuthorView />
234-
</ReferenceFieldBase>
235-
</RecordsIterator>
236-
</WithListContext>
229+
<ListBase
230+
loading={null}
231+
error={null}
232+
offline={null}
233+
emptyWhileLoading
234+
>
235+
<RecordsIterator>
236+
<ReferenceFieldBase source="user_id" reference="users">
237+
<AuthorView />
238+
</ReferenceFieldBase>
239+
</RecordsIterator>
237240
</ListBase>
238241
);
239242
```
@@ -270,19 +273,18 @@ For example, the following code prefetches the authors referenced by the posts:
270273

271274
{% raw %}
272275
```jsx
273-
const PostList = () => (
274-
<ListBase queryOptions={{ meta: { prefetch: ['author'] } }}>
275-
<WithListContext loading={null} errorElement={null} offline={null} empty={null}>
276-
<RecordsIterator render={(author) => (
277-
<div>
278-
<h3>{author.title}</h3>
279-
<ReferenceFieldBase source="author_id" reference="authors">
280-
<AuthorView />
281-
</ReferenceFieldBase>
282-
</div>
283-
)} />
284-
</WithListContext>
285-
</ListBase>
276+
const PostShow = () => (
277+
<ShowBase
278+
queryOptions={{ meta: { prefetch: ['author'] } }}
279+
render={author => (
280+
<div>
281+
<h3>{author.title}</h3>
282+
<ReferenceFieldBase source="author_id" reference="authors">
283+
<AuthorView />
284+
</ReferenceFieldBase>
285+
</div>
286+
)}
287+
/>
286288
);
287289
```
288290
{% endraw %}

‎docs/ReferenceManyFieldBase.md‎

Lines changed: 12 additions & 9 deletions
Original file line numberDiff line numberDiff line change
@@ -72,17 +72,20 @@ const BookList = ({
7272
You can also use `<ReferenceManyFieldBase>` in a list, e.g. to display the authors of the comments related to each post in a list by matching `post.id` to `comment.post_id`:
7373
7474
```jsx
75-
import { ListBase, RecordsIterator, ReferenceManyFieldBase, WithListContext } from 'react-admin';
75+
import { ListBase, RecordsIterator, ReferenceManyFieldBase } from 'react-admin';
7676

7777
export const PostList = () => (
78-
<ListBase>
79-
<WithListContext loading={null} errorElement={null} offline={null} empty={null}>
80-
<RecordsIterator>
81-
<ReferenceManyFieldBase reference="comments" target="post_id">
82-
<CustomAuthorView source="name"/>
83-
</ReferenceManyFieldBase>
84-
</RecordsIterator>
85-
</WithListContext>
78+
<ListBase
79+
loading={null}
80+
error={null}
81+
offline={null}
82+
emptyWhileLoading
83+
>
84+
<RecordsIterator>
85+
<ReferenceManyFieldBase reference="comments" target="post_id">
86+
<CustomAuthorView source="name"/>
87+
</ReferenceManyFieldBase>
88+
</RecordsIterator>
8689
</ListBase>
8790
);
8891
```

‎docs/WithListContext.md‎

Lines changed: 33 additions & 33 deletions
Original file line numberDiff line numberDiff line change
@@ -29,9 +29,9 @@ const BookList = () => (
2929
<ReferenceArrayField reference="tags" source="tag_ids">
3030
<WithListContext
3131
loading={<Typography>Loading tags...</Typography>}
32-
errorElement={<Typography>Error while loading tags</Typography>}
33-
empty={<Typography>No associated tags</Typography>}
34-
render={({ data }) => (
32+
error={<Typography>Error while loading tags</Typography>}
33+
empty={<Typography>No associated tags</Typography>}
34+
render={({data}) => (
3535
<Stack direction="row" spacing={1}>
3636
{data.map(tag => (
3737
<Chip key={tag.id} label={tag.name} />
@@ -70,23 +70,23 @@ const BookList = () => (
7070

7171
const TagList = () => {
7272
const { isPending, error, data, total } = useListContext();
73-
73+
7474
if (isPending) {
75-
return <Typography>Loading tags...</Typography>;
76-
}
77-
75+
return <Typography>Loading tags...</Typography>;
76+
}
77+
7878
if (error) {
79-
return <Typography>Error while loading tags</Typography>;
80-
}
81-
79+
return <Typography>Error while loading tags</Typography>;
80+
}
81+
8282
if (data == null || data.length === 0 || total === 0) {
83-
return <Typography>No associated tags</Typography>;
84-
}
85-
83+
return <Typography>No associated tags</Typography>;
84+
}
85+
8686
return (
8787
<Stack direction="row" spacing={1}>
8888
{data.map(tag => (
89-
<Chip key={tag.id} label={tag.name} />
89+
<Chip key={tag.id} label={tag.name}/>
9090
))}
9191
</Stack>
9292
);
@@ -97,13 +97,13 @@ Whether you use `<WithListContext>` or `useListContext` is a matter of coding st
9797

9898
## Standalone usage
9999

100-
You can also use `<WithListContext>` outside of a `ListContext` by filling `data`, `total`, `error`, and `isPending` properties manually.
100+
You can also use `<WithListContext>` outside of a `ListContext` by filling `data`, `total`, `errorState`, and `isPending` properties manually.
101101

102102
```jsx
103103
import { WithListContext } from 'react-admin';
104104
import { Chip, Stack, Typography } from '@mui/material';
105105

106-
const TagList = ({data, isPending}) => (
106+
const TagList = ({ data, isPending }) => (
107107
<WithListContext
108108
data={data}
109109
isPending={isPending}
@@ -124,18 +124,18 @@ const TagList = ({data, isPending}) => (
124124

125125
`<WithListContext>` accepts a single `render` prop, which should be a function.
126126

127-
| Prop | Required | Type | Default | Description |
128-
|----------------|----------|----------------|---------|-------------------------------------------------------------------------------------------|
129-
| `children` | Optional | `ReactNode` | | The components rendered in the list context. |
130-
| `data` | Optional | `RecordType[]` | | The list data in standalone usage. |
131-
| `empty` | Optional | `ReactNode` | | The component to display when the data is empty. |
132-
| `error` | Optional | `Error` | | The error in standalone usage. |
133-
| `errorElement` | Optional | `ReactNode` | | The component to display in case of error. |
134-
| `isPending` | Optional | `boolean` | | Determine if the list is loading in standalone usage. |
135-
| `loading` | Optional | `ReactNode` | | The component to display while checking authorizations. |
136-
| `offline` | Optional | `ReactNode` | | The component to display when there is no connectivity to load data and no data in cache. |
137-
| `render` | Required | `function` | | The function to render the data |
138-
| `total` | Optional | `number` | | The total number of data in the list in standalone usage. |
127+
| Prop | Required | Type | Default | Description |
128+
|--------------|----------|----------------|---------|-------------------------------------------------------------------------------------------|
129+
| `children` | Optional | `ReactNode` | | The components rendered in the list context. |
130+
| `data` | Optional | `RecordType[]` | | The list data in standalone usage. |
131+
| `empty` | Optional | `ReactNode` | | The component to display when the data is empty. |
132+
| `errorState` | Optional | `Error` | | The error in standalone usage. |
133+
| `error` | Optional | `ReactNode` | | The component to display in case of error. |
134+
| `isPending` | Optional | `boolean` | | Determine if the list is loading in standalone usage. |
135+
| `loading` | Optional | `ReactNode` | | The component to display while checking authorizations. |
136+
| `offline` | Optional | `ReactNode` | | The component to display when there is no connectivity to load data and no data in cache. |
137+
| `render` | Required | `function` | | The function to render the data |
138+
| `total` | Optional | `number` | | The total number of data in the list in standalone usage. |
139139

140140
## `empty`
141141

@@ -160,15 +160,15 @@ If `empty` is not provided, the render function will be called with empty data.
160160
/>
161161
```
162162

163-
## `errorElement`
163+
## `error`
164164

165-
Use `errorElement` to display a message when an error is thrown.
165+
Use `error` to display a message when an error is thrown.
166166

167-
If `errorElement` is not provided, the render function will be called with the error.
167+
If `error` is not provided, the render function will be called with the error.
168168

169169
```jsx
170170
<WithListContext
171-
errorElement={<p>Error while loading books...</p>}
171+
error={<p>Error while loading books...</p>}
172172
render={({ data }) => (
173173
<ul>
174174
{data.map(book => (
@@ -366,7 +366,7 @@ const LineChart = ({ data }) => {
366366
Another use case is to create a button that refreshes the current list. As the [`ListContext`](./useListContext.md) exposes the `refetch` function, it's as simple as:
367367

368368
```jsx
369-
import { WithListContext } from 'react-admin';
369+
import { WithListContext } from 'react-admin';
370370

371371
const RefreshListButton = () => (
372372
<WithListContext render={({ refetch }) => (

0 commit comments

Comments
 (0)