Skip to content

Commit 11e2c04

Browse files
djhidjhi
authored
Merge pull request #10956 from marmelab/doc-RAFB-RMFB-missing-props
[Doc] Add missing props to `<ReferenceArrayFieldBase>` and `<ReferenceManyFieldBase>` documentation
2 parents 8df4f87 + 5fc4255 commit 11e2c04

File tree

4 files changed

+337
-7
lines changed

4 files changed

+337
-7
lines changed

‎docs/ReferenceArrayFieldBase.md‎

Lines changed: 101 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -91,7 +91,10 @@ You can change how the list of related records is rendered by passing a custom c
9191
| `reference` | Required | `string` | - | The name of the resource for the referenced records, e.g. 'tags' |
9292
| `children` | Optional\* | `Element` | | One or several elements that render a list of records based on a `ListContext` |
9393
| `render` | Optional\* | `(ListContext) => Element` | | A function that takes a list context and renders a list of records |
94+
| `empty` | Optional | `ReactNode` | - | The component to render when the related records list is empty |
95+
| `error` | Optional | `ReactNode` | - | The component to render when an error occurs while fetching the related records |
9496
| `filter` | Optional | `Object` | - | Filters to use when fetching the related records (the filtering is done client-side) |
97+
| `loading` | Optional | `ReactNode` | - | The component to render while fetching the related records |
9598
| `offline` | Optional | `ReactNode` | | The component to render when there is no connectivity and the record isn't in the cache |
9699
| `perPage` | Optional | `number` | 1000 | Maximum number of results to display |
97100
| `queryOptions` | Optional | [`UseQuery Options`](https://tanstack.com/query/v5/docs/react/reference/useQuery) | `{}` | `react-query` options for the `getMany` query |
@@ -129,6 +132,70 @@ const TagList = (props: { children: React.ReactNode }) => {
129132
};
130133
```
131134
135+
## `empty`
136+
137+
By default, `<ReferenceArrayFieldBase>` renders its children even when the related records list is empty. You can customize what is rendered by providing your own component via the `empty` prop:
138+
139+
```jsx
140+
import { ReferenceArrayFieldBase, ShowBase } from 'react-admin';
141+
142+
export const PostShow = () => (
143+
<ShowBase>
144+
<ReferenceArrayFieldBase
145+
source="tag_ids"
146+
reference="tags"
147+
empty={<p>No tags found.</p>}
148+
>
149+
...
150+
</ReferenceArrayFieldBase>
151+
</ShowBase>
152+
);
153+
```
154+
155+
You can also have `<ReferenceArrayFieldBase>` render nothing in that case by setting the prop to `null`:
156+
157+
```jsx
158+
<ReferenceArrayFieldBase
159+
source="tag_ids"
160+
reference="tags"
161+
empty={null}
162+
>
163+
...
164+
</ReferenceArrayFieldBase>
165+
```
166+
167+
## `error`
168+
169+
By default, `<ReferenceArrayFieldBase>` renders its children even when an error occurs while fetching the related records. You can customize what is rendered by providing your own component via the `error` prop:
170+
171+
```jsx
172+
import { ReferenceArrayFieldBase, ShowBase } from 'react-admin';
173+
174+
export const PostShow = () => (
175+
<ShowBase>
176+
<ReferenceArrayFieldBase
177+
source="tag_ids"
178+
reference="tags"
179+
error={<p>Error loading tags. Please try again.</p>}
180+
>
181+
...
182+
</ReferenceArrayFieldBase>
183+
</ShowBase>
184+
);
185+
```
186+
187+
You can also have `<ReferenceArrayFieldBase>` render nothing in that case by setting the prop to `null`:
188+
189+
```jsx
190+
<ReferenceArrayFieldBase
191+
source="tag_ids"
192+
reference="tags"
193+
error={null}
194+
>
195+
...
196+
</ReferenceArrayFieldBase>
197+
```
198+
132199
## `render`
133200
134201
Alternatively to `children`, you can pass a `render` function prop to `<ReferenceArrayFieldBase>`. The `render` prop will receive the `ListContext` as its argument, allowing to inline the rendering logic.
@@ -176,12 +243,44 @@ For instance, to render only tags that are 'published', you can use the followin
176243
```
177244
{% endraw %}
178245
246+
## `loading`
247+
248+
By default, `<ReferenceArrayFieldBase>` renders its children even while fetching the related records. You can customize what is rendered by providing your own component via the `loading` prop:
249+
250+
```jsx
251+
import { ReferenceArrayFieldBase, ShowBase } from 'react-admin';
252+
253+
export const PostShow = () => (
254+
<ShowBase>
255+
<ReferenceArrayFieldBase
256+
source="tag_ids"
257+
reference="tags"
258+
loading={<p>Loading tags...</p>}
259+
>
260+
...
261+
</ReferenceArrayFieldBase>
262+
</ShowBase>
263+
);
264+
```
265+
266+
You can also have `<ReferenceArrayFieldBase>` render nothing in that case by setting the prop to `null`:
267+
268+
```jsx
269+
<ReferenceArrayFieldBase
270+
source="tag_ids"
271+
reference="tags"
272+
loading={null}
273+
>
274+
...
275+
</ReferenceArrayFieldBase>
276+
```
277+
179278
## `offline`
180279
181280
By default, `<ReferenceArrayFieldBase>` renders nothing when there is no connectivity and the records haven't been cached yet. You can provide your own component via the `offline` prop:
182281
183282
```jsx
184-
import { ReferenceArrayFieldBase, ShowBase } from 'ra-core';
283+
import { ReferenceArrayFieldBase, ShowBase } from 'react-admin';
185284

186285
export const PostShow = () => (
187286
<ShowBase>
@@ -199,7 +298,7 @@ export const PostShow = () => (
199298
**Tip**: If the records are in the Tanstack Query cache but you want to warn the user that they may see an outdated version, you can use the `<IsOffline>` component:
200299
201300
```jsx
202-
import { IsOffline, ReferenceArrayFieldBase, ShowBase } from 'ra-core';
301+
import { IsOffline, ReferenceArrayFieldBase, ShowBase } from 'react-admin';
203302

204303
export const PostShow = () => (
205304
<ShowBase>

‎docs/ReferenceManyFieldBase.md‎

Lines changed: 68 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -89,11 +89,13 @@ export const PostList = () => (
8989
9090
| Prop | Required | Type | Default | Description |
9191
| -------------- | -------- | --------------------------------------------------------------------------------- | -------------------------------- | ----------------------------------------------------------------------------------- |
92-
| `children` | Optional | `Element` | - | One or several elements that render a list of records based on a `ListContext` |
92+
| `children` | Optional\* | `Element` | - | One or several elements that render a list of records based on a `ListContext` |
9393
| `render` | Optional\* | `(ListContext) => Element` | - | Function that receives a `ListContext` and returns an element |
94-
| `debounce` | Optional\* | `number` | 500 | debounce time in ms for the `setFilters` callbacks |
94+
| `debounce` | Optional | `number` | 500 | debounce time in ms for the `setFilters` callbacks |
9595
| `empty` | Optional | `ReactNode` | - | Element to display when there are no related records. |
96+
| `error` | Optional | `ReactNode` | - | The component to render when an error occurs while fetching the related records |
9697
| `filter` | Optional | `Object` | - | Filters to use when fetching the related records, passed to `getManyReference()` |
98+
| `loading` | Optional | `ReactNode` | - | The component to render while fetching the related records |
9799
| `offline` | Optional | `ReactNode` | - | Element to display when there are no related records because of lack of network connectivity. |
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 |
@@ -177,6 +179,38 @@ Use `empty` to customize the text displayed when there are no related records.
177179
</ReferenceManyFieldBase>
178180
```
179181
182+
## `error`
183+
184+
By default, `<ReferenceManyFieldBase>` renders its children when an error occurs while fetching the related records. You can customize what is rendered by providing your own component via the `error` prop:
185+
186+
```jsx
187+
import { ReferenceManyFieldBase, ShowBase } from 'react-admin';
188+
189+
export const AuthorShow = () => (
190+
<ShowBase>
191+
<ReferenceManyFieldBase
192+
reference="books"
193+
target="author_id"
194+
error={<p>Error loading books. Please try again.</p>}
195+
>
196+
...
197+
</ReferenceManyFieldBase>
198+
</ShowBase>
199+
);
200+
```
201+
202+
You can also have `<ReferenceManyFieldBase>` render nothing in that case by setting the prop to `null`:
203+
204+
```jsx
205+
<ReferenceManyFieldBase
206+
reference="books"
207+
target="author_id"
208+
error={null}
209+
>
210+
...
211+
</ReferenceManyFieldBase>
212+
```
213+
180214
## `filter`: Permanent Filter
181215
182216
You can filter the query used to populate the possible values. Use the `filter` prop for that.
@@ -195,6 +229,38 @@ You can filter the query used to populate the possible values. Use the `filter`
195229
196230
{% endraw %}
197231
232+
## `loading`
233+
234+
By default, `<ReferenceManyFieldBase>` renders its children while fetching the related records. You can customize what is rendered by providing your own component via the `loading` prop:
235+
236+
```jsx
237+
import { ReferenceManyFieldBase, ShowBase } from 'react-admin';
238+
239+
export const AuthorShow = () => (
240+
<ShowBase>
241+
<ReferenceManyFieldBase
242+
reference="books"
243+
target="author_id"
244+
loading={<p>Loading books...</p>}
245+
>
246+
...
247+
</ReferenceManyFieldBase>
248+
</ShowBase>
249+
);
250+
```
251+
252+
You can also have `<ReferenceManyFieldBase>` render nothing in that case by setting the prop to `null`:
253+
254+
```jsx
255+
<ReferenceManyFieldBase
256+
reference="books"
257+
target="author_id"
258+
loading={null}
259+
>
260+
...
261+
</ReferenceManyFieldBase>
262+
```
263+
198264
## `offline`
199265
200266
Use `offline` to customize the text displayed when there are no related records because of lack of network connectivity.

‎docs_headless/src/content/docs/ReferenceArrayFieldBase.md‎

Lines changed: 100 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -87,11 +87,14 @@ You can change how the list of related records is rendered by passing a custom c
8787
| `reference` | Required | `string` | - | The name of the resource for the referenced records, e.g. 'tags' |
8888
| `children` | Optional\* | `Element` | | One or several elements that render a list of records based on a `ListContext` |
8989
| `render` | Optional\* | `(ListContext) => Element` | | A function that takes a list context and renders a list of records |
90+
| `empty` | Optional | `ReactNode` | - | The component to render when the related records list is empty |
91+
| `error` | Optional | `ReactNode` | - | The component to render when an error occurs while fetching the related records |
9092
| `filter` | Optional | `Object` | - | Filters to use when fetching the related records (the filtering is done client-side) |
93+
| `loading` | Optional | `ReactNode` | - | The component to render while fetching the related records |
9194
| `perPage` | Optional | `number` | 1000 | Maximum number of results to display |
9295
| `queryOptions` | Optional | [`UseQuery Options`](https://tanstack.com/query/v5/docs/react/reference/useQuery) | `{}` | `react-query` options for the `getMany` query |
9396
| `sort` | Optional | `{ field, order }` | `{ field: 'id', order: 'DESC' }` | Sort order to use when displaying the related records (the sort is done client-side) |
94-
| `sortBy` | Optional | `string | Function` | `source` | When used in a `List`, name of the field to use for sorting when the user clicks on the column header. |
97+
| `sortBy` | Optional | `string \| Function` | `source` | When used in a `List`, name of the field to use for sorting when the user clicks on the column header. |
9598
9699
\* Either one of children or render is required.
97100
@@ -124,6 +127,70 @@ const TagList = (props: { children: React.ReactNode }) => {
124127
};
125128
```
126129
130+
## `empty`
131+
132+
By default, `<ReferenceArrayFieldBase>` renders its children when the related records list is empty. You can customize what is rendered by providing your own component via the `empty` prop:
133+
134+
```jsx
135+
import { ReferenceArrayFieldBase, ShowBase } from 'ra-core';
136+
137+
export const PostShow = () => (
138+
<ShowBase>
139+
<ReferenceArrayFieldBase
140+
source="tag_ids"
141+
reference="tags"
142+
empty={<p>No tags found.</p>}
143+
>
144+
...
145+
</ReferenceArrayFieldBase>
146+
</ShowBase>
147+
);
148+
```
149+
150+
You can also have `<ReferenceArrayFieldBase>` render nothing in that case by setting the prop to `null`:
151+
152+
```jsx
153+
<ReferenceArrayFieldBase
154+
source="tag_ids"
155+
reference="tags"
156+
empty={null}
157+
>
158+
...
159+
</ReferenceArrayFieldBase>
160+
```
161+
162+
## `error`
163+
164+
By default, `<ReferenceArrayFieldBase>` renders its children when an error occurs while fetching the related records. You can customize what is rendered by providing your own component via the `error` prop:
165+
166+
```jsx
167+
import { ReferenceArrayFieldBase, ShowBase } from 'ra-core';
168+
169+
export const PostShow = () => (
170+
<ShowBase>
171+
<ReferenceArrayFieldBase
172+
source="tag_ids"
173+
reference="tags"
174+
error={<p>Error loading tags. Please try again.</p>}
175+
>
176+
...
177+
</ReferenceArrayFieldBase>
178+
</ShowBase>
179+
);
180+
```
181+
182+
You can also have `<ReferenceArrayFieldBase>` render nothing in that case by setting the prop to `null`:
183+
184+
```jsx
185+
<ReferenceArrayFieldBase
186+
source="tag_ids"
187+
reference="tags"
188+
error={null}
189+
>
190+
...
191+
</ReferenceArrayFieldBase>
192+
```
193+
127194
## `render`
128195
129196
Alternatively to `children`, you can pass a `render` function prop to `<ReferenceArrayFieldBase>`. The `render` prop will receive the `ListContext` as its argument, allowing to inline the rendering logic.
@@ -169,6 +236,38 @@ For instance, to render only tags that are 'published', you can use the followin
169236
/>
170237
```
171238
239+
## `loading`
240+
241+
By default, `<ReferenceArrayFieldBase>` renders its children while fetching the related records. You can customize what is rendered by providing your own component via the `loading` prop:
242+
243+
```jsx
244+
import { ReferenceArrayFieldBase, ShowBase } from 'ra-core';
245+
246+
export const PostShow = () => (
247+
<ShowBase>
248+
<ReferenceArrayFieldBase
249+
source="tag_ids"
250+
reference="tags"
251+
loading={<p>Loading tags...</p>}
252+
>
253+
...
254+
</ReferenceArrayFieldBase>
255+
</ShowBase>
256+
);
257+
```
258+
259+
You can also have `<ReferenceArrayFieldBase>` render nothing in that case by setting the prop to `null`:
260+
261+
```jsx
262+
<ReferenceArrayFieldBase
263+
source="tag_ids"
264+
reference="tags"
265+
loading={null}
266+
>
267+
...
268+
</ReferenceArrayFieldBase>
269+
```
270+
172271
## `perPage`
173272
174273
`<ReferenceArrayFieldBase>` fetches *all* the related fields, and puts them all in a `ListContext`. If a record has a large number of related records, it may be a good idea to limit the number of displayed records. The `perPage` prop allows to create a client-side pagination for the related records.

0 commit comments

Comments
 (0)