Skip to content

Commit c7e11af

Browse files
fzaninottofzaninotto
committed
[Doc] Update ReferenceManyField doc
1 parent b7a21fd commit c7e11af

File tree

1 file changed

+44
-75
lines changed

1 file changed

+44
-75
lines changed

‎docs/ReferenceManyField.md‎

Lines changed: 44 additions & 75 deletions
Original file line numberDiff line numberDiff line change
@@ -89,19 +89,21 @@ This example leverages [`<SingleFieldList>`](./SingleFieldList.md) to display an
8989

9090
| Prop | Required | Type | Default | Description |
9191
| -------------- | -------- | --------------------------------------------------------------------------------- | -------------------------------- | ----------------------------------------------------------------------------------- |
92-
| `children` | Required if no render | `Element` | - | One or several elements that render a list of records based on a `ListContext` |
93-
| `render` | Required if no children | `(listContext) => Element` | - | Function that receives a `ListContext` and render elements |
92+
| `reference` | Required | `string` | - | The name of the resource for the referenced records, e.g. 'books' |
93+
| `target` | Required | `string` | - | Target field carrying the relationship on the referenced resource, e.g. 'user_id' |
94+
| `children` | Optional&nbsp;* | `Element` | - | One or several elements that render a list of records based on a `ListContext` |
95+
| `render` | Optional&nbsp;* | `(listContext) => Element` | - | Function that receives a `ListContext` and render elements |
9496
| `debounce` | Optional | `number` | 500 | debounce time in ms for the `setFilters` callbacks |
9597
| `empty` | Optional | `ReactNode` | - | Element to display when there are no related records. |
9698
| `filter` | Optional | `Object` | - | Filters to use when fetching the related records, passed to `getManyReference()` |
9799
| `pagination` | Optional | `Element` | - | Pagination element to display pagination controls. empty by default (no pagination) |
98100
| `perPage` | Optional | `number` | 25 | Maximum number of referenced records to fetch |
99101
| `queryOptions` | Optional | [`UseQuery Options`](https://tanstack.com/query/v3/docs/react/reference/useQuery) | `{}` | `react-query` options for the `getMany` query |
100-
| `reference` | Required | `string` | - | The name of the resource for the referenced records, e.g. 'books' |
101102
| `sort` | Optional | `{ field, order }` | `{ field: 'id', order: 'DESC' }` | Sort order to use when fetching the related records, passed to `getManyReference()` |
102103
| `source` | Optional | `string` | `id` | Target field carrying the relationship on the source record (usually 'id') |
103104
| `storeKey` | Optional | `string` | - | The key to use to store the records selection state |
104-
| `target` | Required | `string` | - | Target field carrying the relationship on the referenced resource, e.g. 'user_id' |
105+
106+
`*` You must provide either `children` or `render`.
105107

106108
`<ReferenceManyField>` also accepts the [common field props](./Fields.md#common-field-props), except `emptyText` (use the child `empty` prop instead).
107109

@@ -139,96 +141,34 @@ export const AuthorShow = () => (
139141
);
140142
```
141143

142-
Or [`<WithListContext>`](./WithListContext.md) to render the related records in a custom way:
144+
Alternatively, you can use [the `render` prop](#render) to render the related records in a custom way:
143145

144146
```jsx
145-
import { Show, SimpleShowLayout, TextField, ReferenceManyField, WithListContext, DateField } from 'react-admin';
147+
import { Show, SimpleShowLayout, TextField, ReferenceManyField, DateField } from 'react-admin';
146148

147149
export const AuthorShow = () => (
148150
<Show>
149151
<SimpleShowLayout>
150152
<TextField source="first_name" />
151153
<TextField source="last_name" />
152154
<DateField label="Born" source="dob" />
153-
<ReferenceManyField label="Books" reference="books" target="author_id">
154-
<WithListContext render={({ data }) => (
155+
<ReferenceManyField
156+
label="Books"
157+
reference="books"
158+
target="author_id"
159+
render={({ data }) => (
155160
<ul>
156161
{data.map(book => (
157162
<li key={book.id}>{book.title}</li>
158163
))}
159164
</ul>
160-
)} />
161-
</ReferenceManyField>
165+
)}
166+
/>
162167
</SimpleShowLayout>
163168
</Show>
164169
);
165170
```
166171

167-
## `render`
168-
169-
Alternatively to children you can pass a render prop to `<ReferenceManyField>`. The render prop will receive the list context as its argument, allowing to inline the render logic for both the list and the pagination.
170-
When receiving a render prop the `<ReferenceManyField>` component will ignore the children and the pagination property.
171-
172-
```jsx
173-
import { Show, SimpleShowLayout, ReferenceManyField, DataTable, TextField, DateField } from 'react-admin';
174-
175-
const CustomAuthorView = ({
176-
source,
177-
children,
178-
}: {
179-
source: string;
180-
}) => {
181-
const context = useListController();
182-
183-
if (context.isPending) {
184-
return <p>Loading...</p>;
185-
}
186-
187-
if (context.error) {
188-
return <p className="error">{context.error.toString()}</p>;
189-
}
190-
return (
191-
<p>
192-
{listContext.data?.map((datum, index) => (
193-
<li key={index}>{datum[source]}</li>
194-
))}
195-
</p>
196-
);
197-
};
198-
199-
const AuthorShow = () => (
200-
<Show>
201-
<SimpleShowLayout>
202-
<TextField source="first_name" />
203-
<TextField source="last_name" />
204-
<ReferenceManyField
205-
reference="books"
206-
target="author_id"
207-
render={
208-
(context) => {
209-
210-
if (context.isPending) {
211-
return <p>Loading...</p>;
212-
}
213-
214-
if (context.error) {
215-
return <p className="error">{context.error.toString()}</p>;
216-
}
217-
return (
218-
<p>
219-
{listContext.data?.map((author, index) => (
220-
<li key={index}>{author.name}</li>
221-
))}
222-
</p>
223-
);
224-
}
225-
}
226-
/>
227-
</SimpleShowLayout>
228-
</Show>
229-
);
230-
```
231-
232172
## `debounce`
233173

234174
By default, `<ReferenceManyField>` does not refresh the data as soon as the user enters data in the filter form. Instead, it waits for half a second of user inactivity (via `lodash.debounce`) before calling the `dataProvider` on filter change. This is to prevent repeated (and useless) calls to the API.
@@ -416,6 +356,35 @@ For instance, if you want to display the `books` of a given `author`, the `refer
416356
</ReferenceManyField>
417357
```
418358

359+
## `render`
360+
361+
Alternatively to `children`, you can pass a `render` prop to `<ReferenceManyField>`. It will receive the [`ListContext`](./useListContext.md#return-value) as its argument, and should return a React node.
362+
363+
This allows to inline the render logic for the list of related records.
364+
365+
```jsx
366+
<ReferenceManyField
367+
reference="books"
368+
target="author_id"
369+
render={({ isPending, error, data }) => {
370+
if (isPending) {
371+
return <p>Loading...</p>;
372+
}
373+
374+
if (error) {
375+
return <p className="error">{error.toString()}</p>;
376+
}
377+
return (
378+
<p>
379+
{data.map((author, index) => (
380+
<li key={index}>{author.name}</li>
381+
))}
382+
</p>
383+
);
384+
}}
385+
/>
386+
```
387+
419388
## `sort`
420389

421390
By default, it orders the possible values by id desc. You can change this order by setting the `sort` prop (an object with `field` and `order` properties).

0 commit comments

Comments
 (0)