Skip to content

Commit

Permalink
Merge pull request #4530 from WiXSL/fix-reference-field-docs
Browse files Browse the repository at this point in the history 
[Doc] Fix documentation related to <ReferenceField> and <SelectField> components.
  • Loading branch information
@fzaninotto
fzaninotto authored Mar 14, 2020
2 parents e868735 + c2aaffc commit 0215051
Showing 1 changed file with 19 additions and 18 deletions.
37 changes: 19 additions & 18 deletions docs/Fields.md
View file
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

0 comments on commit 0215051

Please sign in to comment.