Skip to content

Commit 13b60f1

Browse files
djhidjhi
committed
Update the documentation for version 5.11.4
1 parent 447a934 commit 13b60f1

16 files changed

+426
-40
lines changed

‎Buttons.md‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1405,7 +1405,7 @@ export const PostList = () => (
14051405
<List>
14061406
<DataTable
14071407
bulkActionsToolbar={
1408-
<BulkActionsToolbar selectAllButton={PostSelectAllButton}>
1408+
<BulkActionsToolbar selectAllButton={<PostSelectAllButton />}>
14091409
<BulkDeleteButton />
14101410
</BulkActionsToolbar>
14111411
}

‎Features.md‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -257,7 +257,7 @@ Let's be realistic: Many developers focus on features first and don't have much
257257
React-admin provides **components that look pretty good out of the box**, so even if you don't spend time on the UI, it won't look bad (unless you try hard). React-admin uses [Material UI](https://mui.com/material-ui/getting-started/), which is a React implementation of the [Material Design](https://material.io/) guidelines, the most battle-tested design system.
258258

259259
<video controls autoplay playsinline muted loop width="100%">
260-
<source src="https://user-images.githubusercontent.com/99944/116970434-4a926480-acb8-11eb-8ce2-0602c680e45e.mp4" type="video/webm" />
260+
<source src="https://user-images.githubusercontent.com/99944/116970434-4a926480-acb8-11eb-8ce2-0602c680e45e.mp4" type="video/mp4" />
261261
Your browser does not support the video tag.
262262
</video>
263263

‎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>

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

‎ReferenceManyInput.md‎

Lines changed: 28 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -74,6 +74,8 @@ const ProductEdit = () => (
7474

7575
**Tip**: `<ReferenceManyInput>` cannot be used with `undoable` mutations. You have to set `mutationMode="optimistic"` or `mutationMode="pessimistic"` in the parent `<Edit>`, as in the example above.
7676

77+
**Tip**: `<SimpleFormIterator>` uses the `disableReordering` prop in this example because the `variants` resource doesn't support reordering. If your reference table does have a `rank` column, you can leave sorting controls on (see [the `rankSource` section](#ranksource) for details).
78+
7779
## Props
7880

7981
| Prop | Required | Type | Default | Description |
@@ -86,6 +88,7 @@ const ProductEdit = () => (
8688
| `source` | Optional | `string` | `id` | Name of the field that carries the identity of the current record, used as origin for the relationship |
8789
| `filter` | Optional | `Object` | - | Filters to use when fetching the related records, passed to `getManyReference()` |
8890
| `perPage` | Optional | `number` | 25 | Maximum number of referenced records to fetch |
91+
| `rankSource` | Optional | `string` | - | Name of the field used to store the rank of each item. When defined, it enables reordering of the items. |
8992
| `sort` | Optional | `{ field, order }` | `{ field: 'id', order: 'DESC' }` | Sort order to use when fetching the related records, passed to `getManyReference()` |
9093
| `defaultValue` | Optional | `array` | - | Default value of the input. |
9194
| `validate` | Optional | `Function` &#124; `array` | - | Validation rules for the array. See the [Validation Documentation](./Validation.md) for details. |
@@ -202,6 +205,31 @@ By default, react-admin restricts the possible values to 25 and displays no pagi
202205
</ReferenceManyInput>
203206
```
204207

208+
### `rankSource`
209+
210+
`<SimpleFormIterator>` provides controls to reorder the items in the list. If the related records have a numeric rank field, you can enable the reordering feature by setting the `rankSource` prop.
211+
212+
for example, if the variants have a `rank` field, you can set the `rankSource` prop like this:
213+
214+
```jsx
215+
<ReferenceManyInput
216+
reference="variants"
217+
target="product_id"
218+
rankSource="rank"
219+
>
220+
<SimpleFormIterator>
221+
<TextInput source="sku" />
222+
<SelectInput source="size" choices={sizes} />
223+
<SelectInput source="color" choices={colors} />
224+
<NumberInput source="stock" defaultValue={0} />
225+
</SimpleFormIterator>
226+
</ReferenceManyInput>
227+
```
228+
229+
Now the variants will be ordered by rank, and whenever the user changes the order of the items, `<ReferenceManyInput>` will update the `rank` field of each item accordingly.
230+
231+
Note that `<SimpleFormIterator>` doesn't have the `disableReordering` prop in that case, to display the up/down controls.
232+
205233
## `reference`
206234

207235
The name of the resource to fetch for the related records.

‎Scheduler.md‎

Lines changed: 5 additions & 5 deletions
Original file line numberDiff line numberDiff line change
@@ -125,27 +125,27 @@ export const EventList = () => (
125125
viewPreset="hourAndDay"
126126
startDate={startOfDay(new Date())}
127127
converters={{
128-
toBryntumEvent?: (record: RaRecord) => ({
128+
toBryntumEvent: (record) => ({
129129
id: record.id,
130130
name: record.name,
131131
resourceId: record.resource_id,
132132
eventColor: record.color,
133133
startDate: new Date(record.start_at),
134134
endDate: new Date(record.end_at),
135-
});
136-
toBryntumResource?: (record: RaRecord) => ({
135+
}),
136+
toBryntumResource: (record) => ({
137137
id: record.id,
138138
name: record.name,
139139
}),
140-
toEvent?: (model: EventModel) => ({
140+
toEvent: (model) => ({
141141
id: model.id,
142142
name: model.name,
143143
resource_id: model.resourceId,
144144
start_at: model.startDate,
145145
end_at: model.endDate,
146146
color: record.eventColor,
147147
}),
148-
toResource?: (model: ResourceModel) => ({
148+
toResource: (model) => ({
149149
id: model.id,
150150
name: model.name,
151151
}),

‎Theming.md‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -8,7 +8,7 @@ title: "Theming"
88
React-admin applications use a neutral style by default. You will probably want to customize the look and feel to match your branding, or your end users preferences. Don't worry! You can customize the look and feel of pretty much everything in react-admin.
99

1010
<video controls autoplay playsinline muted loop width="100%">
11-
<source src="https://user-images.githubusercontent.com/99944/116970434-4a926480-acb8-11eb-8ce2-0602c680e45e.mp4" type="video/webm" />
11+
<source src="https://user-images.githubusercontent.com/99944/116970434-4a926480-acb8-11eb-8ce2-0602c680e45e.mp4" type="video/mp4" />
1212
Your browser does not support the video tag.
1313
</video>
1414

‎_data/versions.yml‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1,4 +1,4 @@
1-
- latest (5.11.3)
1+
- latest (5.11.4)
22
- "5.10"
33
- "5.9"
44
- "5.8"

‎doc/5.11/Buttons.md‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1405,7 +1405,7 @@ export const PostList = () => (
14051405
<List>
14061406
<DataTable
14071407
bulkActionsToolbar={
1408-
<BulkActionsToolbar selectAllButton={PostSelectAllButton}>
1408+
<BulkActionsToolbar selectAllButton={<PostSelectAllButton />}>
14091409
<BulkDeleteButton />
14101410
</BulkActionsToolbar>
14111411
}

‎doc/5.11/Features.md‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -257,7 +257,7 @@ Let's be realistic: Many developers focus on features first and don't have much
257257
React-admin provides **components that look pretty good out of the box**, so even if you don't spend time on the UI, it won't look bad (unless you try hard). React-admin uses [Material UI](https://mui.com/material-ui/getting-started/), which is a React implementation of the [Material Design](https://material.io/) guidelines, the most battle-tested design system.
258258

259259
<video controls autoplay playsinline muted loop width="100%">
260-
<source src="https://user-images.githubusercontent.com/99944/116970434-4a926480-acb8-11eb-8ce2-0602c680e45e.mp4" type="video/webm" />
260+
<source src="https://user-images.githubusercontent.com/99944/116970434-4a926480-acb8-11eb-8ce2-0602c680e45e.mp4" type="video/mp4" />
261261
Your browser does not support the video tag.
262262
</video>
263263

0 commit comments

Comments
 (0)