Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

[Doc] Fix documentation related to <ReferenceField> and <SelectField> components. #4530

Merged
merged 3 commits into from
Mar 14, 2020
Merged

[Doc] Fix documentation related to <ReferenceField> and <SelectField> components. #4530

Changes from all commits
Commits
Show all changes
3 commits
Select commit Hold shift + click to select a range
eaf090c
Fix documentation related to <ReferenceField> and <SelectField> compo…
Mar 14, 2020
ee2ea45
Fix user id.
Mar 14, 2020
c2aaffc
More corrections.
Mar 14, 2020
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
37 changes: 19 additions & 18 deletions docs/Fields.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -472,13 +472,13 @@ However, in some cases (e.g. inside a `<ReferenceField>`), you may not want the
<SelectField source="gender" choices={choices} translateChoice={false}/>
```

**Tip**: `<ReferenceField>` sets `translateChoice` to `false` by default.
**Tip**: `<SelectField>` sets `translateChoice` to `true` by default.

## `<ReferenceField>`

This component fetches a single referenced record (using the `GET_MANY` REST method), and displays one field of this record. That's why a `<ReferenceField>` must always have a child `<Field>`.
This component fetches a single referenced record (using the `dataProvider.getMany()` REST method), and displays one field of this record. That's why a `<ReferenceField>` must always have a child `<Field>`.

For instance, here is how to fetch the `post` related to `comment` records, and display the `title` for each:
For instance, here is how to fetch the `user` related to `post` records, and display the `name` for each:

```jsx
import React from 'react';
Expand All @@ -488,9 +488,10 @@ export const PostList = (props) => (
<List {...props}>
<Datagrid>
<TextField source="id" />
<ReferenceField label="Author" source="user_id" reference="users">
<ReferenceField label="User" source="user_id" reference="users">
<TextField source="name" />
</ReferenceField>
<TextField source="title" />
</Datagrid>
</List>
);
Expand All @@ -506,23 +507,23 @@ With this configuration, `<ReferenceField>` wraps the user's name in a link to t

```jsx
<Admin dataProvider={myDataProvider}>
<Resource name="comments" list={CommentList} />
<Resource name="posts" />
<Resource name="posts" list={PostList} />
<Resource name="users" />
</Admin>
```

To change the link from the `<Edit>` page to the `<Show>` page, set the `link` prop to "show".

```jsx
<ReferenceField label="User" source="userId" reference="users" link="show">
<ReferenceField label="User" source="user_id" reference="users" link="show">
<TextField source="name" />
</ReferenceField>
```

By default, `<ReferenceField>` is sorted by its `source`. To specify another attribute to sort by, set the `sortBy` prop to the according attribute's name.

```jsx
<ReferenceField label="User" source="userId" reference="users" sortBy="user.name">
<ReferenceField label="User" source="user_id" reference="users" sortBy="user.name">
<TextField source="name" />
</ReferenceField>
```
Expand All @@ -531,7 +532,7 @@ You can also prevent `<ReferenceField>` from adding link to children by setting

```jsx
// No link
<ReferenceField label="User" source="userId" reference="users" link={false}>
<ReferenceField label="User" source="user_id" reference="users" link={false}>
<TextField source="name" />
</ReferenceField>
```
Expand All @@ -540,38 +541,38 @@ You can also use a custom `link` function to get a custom path for the children.

```jsx
// Custom path
<ReferenceField label="User" source="userId" reference="users" link={(record, reference) => `/my/path/to/${reference}/${record.id}`}>
<ReferenceField label="User" source="user_id" reference="users" link={(record, reference) => `/my/path/to/${reference}/${record.id}`}>
<TextField source="name" />
</ReferenceField>
```

**Tip**: React-admin accumulates and deduplicates the ids of the referenced records to make *one* `GET_MANY` call for the entire list, instead of n `GET_ONE` calls. So for instance, if the API returns the following list of comments:
**Tip**: 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:

```js
[
{
id: 123,
body: 'Totally agree',
post_id: 789,
title: 'Totally agree',
user_id: 789,
},
{
id: 124,
title: 'You are right my friend',
post_id: 789
user_id: 789
},
{
id: 125,
title: 'Not sure about this one',
post_id: 735
user_id: 735
}
]
```

Then react-admin renders the `<CommentList>` with a loader for the `<ReferenceField>`, fetches the API for the related posts in one call (`GET http://path.to.my.api/posts?ids=[789,735]`), and re-renders the list once the data arrives. This accelerates the rendering, and minimizes network load.
Then react-admin renders the `<PostList>` with a loader for the `<ReferenceField>`, fetches the API for the related users in one call (`GET http://path.to.my.api/users?ids=[789,735]`), and re-renders the list once the data arrives. This accelerates the rendering, and minimizes network load.

## `<ReferenceManyField>`

This component fetches a list of referenced records by reverse lookup of the current `record.id` in other resource (using the `GET_MANY_REFERENCE` REST method). You can specify the target field name, i.e. the field name of the current record's id in the other resource, using the required `target` field. The result is then passed to an iterator component (like `<SingleFieldList>` or `<Datagrid>`). The iterator component usually has one or more child `<Field>` components.
This component fetches a list of referenced records by reverse lookup of the current `record.id` in other resource (using the `dataProvider.getManyReference()` REST method). You can specify the target field name, i.e. the field name of the current record's id in the other resource, using the required `target` field. The result is then passed to an iterator component (like `<SingleFieldList>` or `<Datagrid>`). The iterator component usually has one or more child `<Field>` components.

For instance, here is how to fetch the `comments` related to a `post` record by matching `comment.post_id` to `post.id`, and then display the `author.name` for each, in a `<ChipField>`:

Expand Down Expand Up @@ -691,7 +692,7 @@ Where `[1, 23, 4]` refer to ids of `tag` resources.
http://myapi.com/tags?id=[1,23,4]
```

**Tip**: `<ReferenceArrayField>` fetches the related resources using the `GET_MANY` REST method, so the actual HTTP request depends on your REST client.
**Tip**: `<ReferenceArrayField>` fetches the related resources using the `dataProvider.getMany()` REST method, so the actual HTTP request depends on your REST client.

Once it receives the related resources, `<ReferenceArrayField>` passes them to its child component using the `ids` and `data` props, so the child must be an iterator component (like `<SingleFieldList>` or `<Datagrid>`). The iterator component usually has one or more child `<Field>` components.

Expand Down