You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
Copy file name to clipboardExpand all lines: docs/Fields.md
+3-5Lines changed: 3 additions & 5 deletions
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -368,17 +368,15 @@ const BookEdit = () => (
368
368
);
369
369
```
370
370
371
-
## Hiding A Field Label
371
+
## Hiding The Field Label
372
372
373
-
You can opt out of the label decoration by passing`false` to the `label` prop.
373
+
React-admin Field layout components like [`<Datagrid>`](./Datagrid.md) and [`<SimpleShowLayout>`](./SimpleShowLayout.md) inspect their children and use their `source` prop to set the table headers or the field labels. To opt out of this behavior, pass`false` to the `label` prop.
374
374
375
375
```jsx
376
-
// No label will be added
376
+
// No label will be added in SimpleShowLayout
377
377
<TextField source="author.name" label={false} />
378
378
```
379
379
380
-
**Note**: This prop has no effect when rendering a field outside a `<Datagrid>`, a `<SimpleShowLayout>`, a `<TabbedShowLayout>`, a `<SimpleForm>`, or a `<TabbedForm>`.
381
-
382
380
## Conditional Formatting
383
381
384
382
If you want to format a field depending on the value, create another component wrapping this field, and set the `sx` prop depending on the field value:
**Tip**: the `<Card sx>` prop in the `PostFilterSidebar` component above is here to put the sidebar on the left side of the screen, instead of the default right side.
234
234
235
-
## `children`: List Layout
235
+
## `children`
236
236
237
237
`<List>` itself doesn't render the list of records. It delegates this task to its children components. These children components grab the `data` from the `ListContext` and render them on screen.
238
238
@@ -397,7 +397,7 @@ const Dashboard = () => (
397
397
398
398
Please note that the selection state is not synced in the URL but in a global store using the resource as key. Thus, all lists in the page using the same resource will share the same selection state. This is a design choice because if row selection is not tied to a resource, then when a user deletes a record it may remain selected without any ability to unselect it. If you want the selection state to be local, you will have to implement your own `useListController` hook and pass a custom key to the `useRecordSelection` hook. You will then need to implement your own `DeleteButton` and `BulkDeleteButton` to manually unselect rows when deleting records.
399
399
400
-
## `empty`: Empty Page Component
400
+
## `empty`
401
401
402
402
When there is no result, and there is no active filter, and the resource has a create page, react-admin displays a special page inviting the user to create the first record.
Pass an object literal as the `sort` prop to determine the default `field` and `order` used for sorting:
807
807
@@ -821,13 +821,11 @@ For more details on list sort, see the [Sorting The List](./ListTutorial.md#sort
821
821
822
822
## `storeKey`
823
823
824
-
To display multiple lists of the same resource and keep distinct store states for each of them (filters, sorting and pagination), specify unique keys with the `storeKey` property.
824
+
By default, react-admin stores the list parameters (sort, pagination, filters) in localStorage so that users can come back to the list and find it in the same state as when they left it. React-admin uses the current resource as the identifier to store the list parameters (under the key `${resource}.listParams`).
825
825
826
-
In case no `storeKey`is provided, the states will be stored with the following key: `${resource}.listParams`.
826
+
If you want to display multiple lists of the same resource and keep distinct store states for each of them (filters, sorting and pagination), you must give each list a unique `storeKey`property. You can also disable the persistence of list parameters in the store by setting the `storeKey` prop to `false`.
827
827
828
-
**Note:** Please note that selection state will remain linked to a resource-based key as described [here](./List.md#disablesyncwithlocation).
829
-
830
-
In the example below, both lists `NewerBooks` and `OlderBooks` use the same resource ('books'), but their controller states are stored separately (under the store keys `'newerBooks'` and `'olderBooks'` respectively). This allows to use both components in the same app, each having its own state (filters, sorting and pagination).
828
+
In the example below, both lists `NewerBooks` and `OlderBooks` use the same resource ('books'), but their list parameters are stored separately (under the store keys `'newerBooks'` and `'olderBooks'` respectively). This allows to use both components in the same app, each having its own state (filters, sorting and pagination).
831
829
832
830
{% raw %}
833
831
```jsx
@@ -887,7 +885,7 @@ const Admin = () => {
887
885
888
886
**Tip:** The `storeKey` is actually passed to the underlying `useListController` hook, which you can use directly for more complex scenarios. See the [`useListController` doc](./useListController.md#storekey) for more info.
889
887
890
-
You can disable this feature by setting the `storeKey` prop to `false`. When disabled, parameters will not be persisted in the store.
888
+
**Note:***Selection state* will remain linked to a resource-based key regardless of the `storeKey`. This is a design choice because if row selection is not tied to a resource, then when a user deletes a record it may remain selected without any ability to unselect it. If you want the selection state to be local, you will have to implement your own `useListController` hook and pass a custom key to the `useRecordSelection` hook. You will then need to implement your own `DeleteButton` and `BulkDeleteButton` to manually unselect rows when deleting records.
891
889
892
890
## `title`
893
891
@@ -935,22 +933,6 @@ const PostList = () => (
935
933
936
934
**Tip**: The `List` component `classes` can also be customized for all instances of the component with its global css name `RaList` as [describe here](https://marmelab.com/blog/2019/12/18/react-admin-3-1.html#theme-overrides)
937
935
938
-
## Adding `meta` To The DataProvider Call
939
-
940
-
Use [the `queryOptions` prop](#queryoptions) to pass [a custom `meta`](./Actions.md#meta-parameter) to the `dataProvider.getList()` call.
941
-
942
-
{% raw %}
943
-
```jsx
944
-
import { List } from'react-admin';
945
-
946
-
constPostList= () => (
947
-
<List queryOptions={{ meta: { foo:'bar' } }}>
948
-
...
949
-
</List>
950
-
);
951
-
```
952
-
{% endraw %}
953
-
954
936
## Infinite Scroll Pagination
955
937
956
938
By default, the `<List>` component displays the first page of the list of records. To display the next page, the user must click on the "next" button. This is called "finite pagination". An alternative is to display the next page automatically when the user scrolls to the bottom of the list. This is called "infinite pagination".
@@ -1008,37 +990,43 @@ const PostList = () => (
1008
990
1009
991
The list will automatically update when a new record is created, or an existing record is updated or deleted.
1010
992
1011
-
## How to render an empty list
993
+
## Adding `meta` To The DataProvider Call
1012
994
1013
-
You can set the `empty` props value to `false` to bypass the empty page display and render an empty list instead.
995
+
Use [the `queryOptions` prop](#queryoptions)to pass [a custom `meta`](./Actions.md#meta-parameter) to the `dataProvider.getList()` call.
1014
996
1015
-
```tsx
997
+
{% raw %}
998
+
```jsx
1016
999
import { List } from'react-admin';
1017
1000
1018
-
constProductList= () => (
1019
-
<Listempty={false}>
1001
+
constPostList= () => (
1002
+
<List queryOptions={{ meta: { foo:'bar' } }}>
1020
1003
...
1021
1004
</List>
1022
-
)
1005
+
);
1023
1006
```
1007
+
{% endraw %}
1008
+
1009
+
## Rendering An Empty List
1024
1010
1025
-
## How to remove the `<ExportButton>`
1011
+
When there is no data, react-admin displays a special page inviting the user to create the first record. This page can be customized using [the `empty` prop](#empty-empty-page-component).
1026
1012
1027
-
You can remove the `<ExportButton>` by passing `false` to the `exporter` prop.
1013
+
You can set the `empty` props value to `false` to render an empty list instead.
1028
1014
1029
1015
```tsx
1030
1016
import { List } from'react-admin';
1031
1017
1032
1018
const ProductList = () => (
1033
-
<Listexporter={false}>
1019
+
<Listempty={false}>
1034
1020
...
1035
1021
</List>
1036
1022
)
1037
1023
```
1038
1024
1039
-
## How to disable storing the list parameters in the Store
1025
+
## Disabling Parameters Persistence
1026
+
1027
+
By default, react-admin stores the list parameters (sort, pagination, filters) in localStorage so that users can come back to the list and find it in the same state as when they left it. This also synchronizes the list parameters across tabs.
1040
1028
1041
-
You can disable the `storeKey`feature by setting the `storeKey` prop to `false`. When disabled, the list parameters will not be persisted in [the Store](./Store.md).
1029
+
You can disable this feature by setting [the `storeKey` prop](#storekey) to `false`:
These are a subset of the props accepted by `<List>` - only the props that change data fetching, and not the props related to the user interface.
67
67
68
-
In addition, `<ListBase>` renders its children components inside a `ListContext`. Check [the `<List children>` documentation](./List.md#children-list-layout) for usage examples.
68
+
In addition, `<ListBase>` renders its children components inside a `ListContext`. Check [the `<List children>` documentation](./List.md#children) for usage examples.
Copy file name to clipboardExpand all lines: docs/ReferenceField.md
+48-48Lines changed: 48 additions & 48 deletions
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -190,6 +190,53 @@ The `<ReferenceField>` component accepts the usual `className` prop. You can als
190
190
191
191
To override the style of all instances of `<ReferenceField>` using the [Material UI style overrides](https://mui.com/material-ui/customization/theme-components/#theme-style-overrides), use the `RaReferenceField` key.
192
192
193
+
## Performance
194
+
195
+
When used in a `<Datagrid>`, `<ReferenceField>` fetches the referenced record only once for the entire table.
React-admin accumulates and deduplicates the ids of the referenced records to make *one*`dataProvider.getMany()` call for the entire list, instead of n `dataProvider.getOne()` calls. So for instance, if the API returns the following list of posts:
217
+
218
+
```js
219
+
[
220
+
{
221
+
id:123,
222
+
title:'Totally agree',
223
+
user_id:789,
224
+
},
225
+
{
226
+
id:124,
227
+
title:'You are right my friend',
228
+
user_id:789
229
+
},
230
+
{
231
+
id:125,
232
+
title:'Not sure about this one',
233
+
user_id:735
234
+
}
235
+
]
236
+
```
237
+
238
+
Then react-admin renders the `<PostList>` with a loader for the `<ReferenceField>`, fetches the API for the related users in one call (`dataProvider.getMany('users', { ids: [789,735] }`), and re-renders the list once the data arrives. This accelerates the rendering and minimizes network load.
239
+
193
240
## Rendering More Than One Field
194
241
195
242
You often need to render more than one field of the reference table (e.g. if the `users` table has a `first_name` and a `last_name` field).
React-admin accumulates and deduplicates the ids of the referenced records to make *one*`dataProvider.getMany()` call for the entire list, instead of n `dataProvider.getOne()` calls. So for instance, if the API returns the following list of posts:
282
-
283
-
```js
284
-
[
285
-
{
286
-
id:123,
287
-
title:'Totally agree',
288
-
user_id:789,
289
-
},
290
-
{
291
-
id:124,
292
-
title:'You are right my friend',
293
-
user_id:789
294
-
},
295
-
{
296
-
id:125,
297
-
title:'Not sure about this one',
298
-
user_id:735
299
-
}
300
-
]
301
-
```
302
-
303
-
Then react-admin renders the `<PostList>` with a loader for the `<ReferenceField>`, fetches the API for the related users in one call (`dataProvider.getMany('users', { ids: [789,735] }`), and re-renders the list once the data arrives. This accelerates the rendering and minimizes network load.
304
-
305
-
## Removing the link
305
+
## Removing The Link
306
306
307
307
You can prevent `<ReferenceField>` from adding a link to its children by setting `link` to `false`.
Copy file name to clipboardExpand all lines: docs/ReferenceOneField.md
+1-1Lines changed: 1 addition & 1 deletion
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -224,7 +224,7 @@ const BookShow = () => (
224
224
```
225
225
{% endraw %}
226
226
227
-
## Removing the link
227
+
## Removing The Link
228
228
229
229
By default, `<ReferenceOneField>` links to the edition page of the related record. You can disable this behavior by setting the `link` prop to `false`.
0 commit comments