diff --git a/docs/FieldsForRelationships.md b/docs/FieldsForRelationships.md index a0ae4bbb9e4..6664c534bf7 100644 --- a/docs/FieldsForRelationships.md +++ b/docs/FieldsForRelationships.md @@ -16,6 +16,8 @@ React-admin handles relationships *regardless of the capacity of the API to mana React-admin provides helpers to fetch related records, depending on the type of relationship, and how the API implements it. + + ## One-To-Many When one record has many related records, this is called a one-to-many relationship. For instance, if an author has written several books, `authors` has a one-to-many relationship with `books`. diff --git a/docs/ReferenceArrayField.md b/docs/ReferenceArrayField.md index 7c28b929399..df5804a09d0 100644 --- a/docs/ReferenceArrayField.md +++ b/docs/ReferenceArrayField.md @@ -7,7 +7,15 @@ title: "The ReferenceArrayField Component" Use `` to display a list of related records, via a one-to-many relationship materialized by an array of foreign keys. -![ReferenceArrayField](./img/reference-array-field.png) + + +`` fetches a list of referenced records (using the `dataProvider.getMany()` method), and puts them in a [`ListContext`](./useListContext.md). It then renders each related record, using its [`recordRepresentation`](./Resource.md#recordrepresentation), in a [``](./ChipField.md). + +**Tip**: If the relationship is materialized by a foreign key on the referenced resource, use [the `` component](./ReferenceManyField.md) instead. + +**Tip**: To edit the records of a one-to-many relationship, use [the `` component](./ReferenceArrayInput.md). + +## Usage For instance, let's consider a model where a `post` has many `tags`, materialized to a `tags_ids` field containing an array of ids: @@ -35,24 +43,9 @@ A typical `post` record therefore looks like this: } ``` -In that case, use `` to display the post tags names as follows: +In that case, use `` to display the post tag names as Chips as follows: ```jsx - -``` - -`` fetches a list of referenced records (using the `dataProvider.getMany()` method), and puts them in a [`ListContext`](./useListContext.md). It then renders each related record, using its [`recordRepresentation`](./Resource.md#recordrepresentation), in a [``](./ChipField.md). - -**Tip**: If the relationship is materialized by a foreign key on the referenced resource, use [the `` component](./ReferenceManyField.md) instead. - -## Usage - -`` expects a `reference` attribute, which specifies the resource to fetch for the related records. It also expects a `source` attribute, which defines the field containing the list of ids to look for in the referenced resource. - -For instance, if each post contains a list of tag ids (e.g. `{ id: 1234, title: 'Lorem Ipsum', tag_ids: [1, 23, 4] }`), here is how to fetch the list of tags for each post in a list, and display the `name` for each `tag` in a ``: - -```jsx -import * as React from "react"; import { List, Datagrid, ReferenceArrayField, TextField } from 'react-admin'; export const PostList = () => ( @@ -60,16 +53,20 @@ export const PostList = () => ( - + ); ``` +![ReferenceArrayField](./img/reference-array-field.png) + +`` expects a `reference` attribute, which specifies the resource to fetch for the related records. It also expects a `source` attribute, which defines the field containing the list of ids to look for in the referenced resource. + `` fetches the `tag` resources related to each `post` resource by matching `post.tag_ids` to `tag.id`. By default, it renders one string by related record, via a [``](./SingleFieldList.md) with a [``](./ChipField.md) child using the resource [`recordRepresentation`](./Resource.md#recordrepresentation) as source -Configure the `` to render related records in a meaningul way. For instance, for the `tags` resource, if you want the `` to display the tag `name`: +Configure the `` to render related records in a meaningful way. For instance, for the `tags` resource, if you want the `` to display the tag `name`: ```jsx diff --git a/docs/ReferenceField.md b/docs/ReferenceField.md index da727062c10..ed82bd81f5d 100644 --- a/docs/ReferenceField.md +++ b/docs/ReferenceField.md @@ -7,7 +7,9 @@ title: "The ReferenceField Component" `` is useful for displaying many-to-one and one-to-one relationships, e.g. the details of a user when rendering a post authored by that user. -![ReferenceField](./img/reference_field_show.png) + + +## Usage For instance, let's consider a model where a `post` has one author from the `users` resource, referenced by a `user_id` field. @@ -22,18 +24,35 @@ For instance, let's consider a model where a `post` has one author from the `use └──────────────┘ ``` -In that case, use `` to display the post author's id as follows: +In that case, use `` to display the post author's as follows: ```jsx - +import { Show, SimpleShowLayout, ReferenceField, TextField, DateField } from 'react-admin'; + +export const PostShow = () => ( + + + + + + + + +); ``` -`` fetches the data, puts it in a [`RecordContext`](./useRecordContext.md), and renders the [`recordRepresentation`](./Resource.md#recordrepresentation) (the record `id` field by default). +`` fetches the data, puts it in a [`RecordContext`](./useRecordContext.md), and renders the [`recordRepresentation`](./Resource.md#recordrepresentation) (the record `id` field by default) wrapped in a link to the related user `` page. + +![ReferenceField](./img/reference_field_show.png) So it's a good idea to configure the `` to render related records in a meaningul way. For instance, for the `users` resource, if you want the `` to display the full name of the author: ```jsx - `${record.first_name} ${record.last_name}`} /> + `${record.first_name} ${record.last_name}`} +/> ``` Alternately, if you pass a child component, `` will render it instead of the `recordRepresentation`. Usual child components for `` are other `` components (e.g. [``](./TextField.md)). @@ -48,27 +67,6 @@ This component fetches a referenced record (`users` in this example) using the ` It uses `dataProvider.getMany()` instead of `dataProvider.getOne()` [for performance reasons](#performance). When using several `` in the same page (e.g. in a ``), this allows to call the `dataProvider` once instead of once per row. -## Usage - -Here is how to render both a post and the author name in a show view: - -```jsx -import { Show, SimpleShowLayout, ReferenceField, TextField, DateField } from 'react-admin'; - -export const PostShow = () => ( - - - - - - - - -); -``` - -With this configuration, `` wraps the user's name in a link to the related user `` page. - ## Props | Prop | Required | Type | Default | Description | diff --git a/docs/ReferenceManyField.md b/docs/ReferenceManyField.md index 0ea09616b8a..832edb923d6 100644 --- a/docs/ReferenceManyField.md +++ b/docs/ReferenceManyField.md @@ -7,7 +7,15 @@ title: "The ReferenceManyField Component" `` is useful for displaying a list of related records via a one-to-many relationship, when the foreign key is carried by the referenced resource. -![referenceManyField](./img/reference_many_field.png) + + +This component fetches a list of referenced records by a reverse lookup of the current `record.id` in the `target` field of another resource (using the `dataProvider.getManyReference()` REST method), and puts them in a [`ListContext`](./useListContext.md). Its children can then use the data from this context. The most common case is to use [``](./SingleFieldList.md) or [``](./Datagrid.md) as child. + +**Tip**: If the relationship is materialized by an array of ids in the initial record, use [the `` component](./ReferenceArrayField.md) instead. + +**Tip**: To edit the records of a one-to-many relationship, use [the `` component](./ReferenceManyInput.md). + +## Usage For instance, if an `author` has many `books`, and each book resource exposes an `author_id` field: @@ -25,12 +33,14 @@ For instance, if an `author` has many `books`, and each book resource exposes an `` can render the titles of all the books by a given author. ```jsx +import { Show, SimpleShowLayout, ReferenceManyField, Datagrid, TextField, DateField } from 'react-admin'; + const AuthorShow = () => ( - + @@ -41,42 +51,13 @@ const AuthorShow = () => ( ); ``` -This component fetches a list of referenced records by a reverse lookup of the current `record.id` in the `target` field of another resource (using the `dataProvider.getManyReference()` REST method), and puts them in a [`ListContext`](./useListContext.md). Its children can then use the data from this context. The most common case is to use [``](./SingleFieldList.md) or [``](./Datagrid.md) as child. - -**Tip**: If the relationship is materialized by an array of ids in the initial record, use [the `` component](./ReferenceArrayField.md) instead. - -**Tip**: To edit the records of a one-to-many relationship, use [the `` component](./ReferenceManyInput.md). - -## Usage - -For instance, here is how to show the title of the books written by a particular author in a show view. - -```jsx -import { Show, SimpleShowLayout, TextField, ReferenceManyField, Datagrid, DateField } from 'react-admin'; - -export const AuthorShow = () => ( - - - - - - - - - - - - - -); -``` +![referenceManyField](./img/reference_many_field.png) `` accepts a `reference` attribute, which specifies the resource to fetch for the related record. It also accepts a `source` attribute which defines the field containing the value to look for in the `target` field of the referenced resource. By default, this is the `id` of the resource (`authors.id` in the previous example). You can also use `` in a list, e.g. to display the authors of the comments related to each post in a list by matching `post.id` to `comment.post_id`: ```jsx -import * as React from "react"; import { List, Datagrid, ChipField, ReferenceManyField, SingleFieldList, TextField } from 'react-admin'; export const PostList = () => (