From e9577c0407545d979b63cc55ffd1f6417403961c Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Fran=C3=A7ois=20Zaninotto?= Date: Thu, 25 Jan 2024 12:19:18 +0100 Subject: [PATCH 1/2] [Doc] Improve FunctionField documentation - add video - reorganize content - add more examples - add TS tip --- docs/FunctionField.md | 112 +++++++++++++++++++++++++++++++++++++++--- docs/WrapperField.md | 7 ++- 2 files changed, 112 insertions(+), 7 deletions(-) diff --git a/docs/FunctionField.md b/docs/FunctionField.md index a941fc5d895..34d9d5af4f3 100644 --- a/docs/FunctionField.md +++ b/docs/FunctionField.md @@ -5,15 +5,37 @@ title: "The FunctionField Component" # `` -If you need a special function to render a field, `` is the perfect match. It passes the `record` to a `render` function supplied by the developer. For instance, to display the full name of a `user` record based on `first_name` and `last_name` properties: +If you need a special function to render a field, `` is the perfect match. It executes a `render` function using the current record as parameter. + + + +## Usage + +`` requires a `render` prop, which is a function that takes the current record as argument and returns a string or an element. + +For instance, to display the full name of a `user` record based on `first_name` and `last_name` properties: ```jsx -import { FunctionField } from 'react-admin'; +import { List, Datagrid, FunctionField } from 'react-admin'; - `${record.first_name} ${record.last_name}`} /> +const UserList = () => ( + + + `${record.first_name} ${record.last_name}`} + /> + ... + + +); ``` -## Properties +Theoretically, you can omit the `source` for the `` since you provide the render function. However, when used inside a ``, providing the `source` prop (or the `sortBy` prop) is required to make the column sortable. When a user clicks on a column, `` uses these properties to sort the data. + +`` is based on [the `useRecordContext` hook](./useRecordContext.md). + +## Props | Prop | Required | Type | Default | Description | | -------- | -------- | -------- | ------- | -------------------------------------------------------------------------- | @@ -21,6 +43,84 @@ import { FunctionField } from 'react-admin'; `` also accepts the [common field props](./Fields.md#common-field-props). -**Tip**: Technically, you can omit the `source` and `sortBy` properties for the `` since you provide the render function. However, providing a `source` or a `sortBy` will allow the `Datagrid` to make the column sortable, since when a user clicks on a column, the `Datagrid` uses these properties to sort. Should you provide both, `sortBy` will override `source` for sorting the column. +## `render` + +The `render` prop accepts a function that takes the current record as argument and returns a string or an element. + +```tsx +// return a string +const render = (record: any) => `${record.first_name} ${record.last_name}`; + +// return an element +const render = (record: any) => ( + <>{record.first_name} {record.last_name} +); +``` + +React-admin wraps the result of the `render` function in a `` component. + +Since this function executes in a [RecordContext](./useRecordContext.md), you can even use other Field components to compute the value: + +```tsx +import { List, Datagrid, FunctionField, TextField } from 'react-admin'; + +const render = () => ( + + {' '} + + +); +const UserList = () => ( + + + + ... + + +); +``` + +However, if you only need to combine Field components, prefer [the `` component](./WrapperField.md) for a simpler syntax: + +```tsx +import { List, Datagrid, WrapperField, TextField } from 'react-admin'; + +const UserList = () => ( + + + + + + + ... + + +); +``` + +## TypeScript + +To type the `record` argument of the `render` function, provide the record's type as a generic parameter to the component: + +```tsx +import { List, Datagrid, FunctionField } from 'react-admin'; + +interface User { + id: number; + first_name: string; + last_name: string; +} -**Tip**: If you want to combine two existing Field components, check [the `` component](./WrapperField.md) instead. +const UserList = () => ( + + + + source="last_name" + label="Name" + render={record => `${record.first_name} ${record.last_name}`} + /> + ... + + +); +``` \ No newline at end of file diff --git a/docs/WrapperField.md b/docs/WrapperField.md index f63d6e1e2fd..3bc054b437a 100644 --- a/docs/WrapperField.md +++ b/docs/WrapperField.md @@ -7,6 +7,8 @@ title: "The WrapperField Component" This component simply renders its children. Why would you want to use such a dumb component? To combine several fields in a single cell (in a ``), in a single row (in a ``) or in a group of inputs (in a ``) . +## Usage + `` allows to define the `label` and sort field for a combination of fields: ```jsx @@ -44,5 +46,8 @@ const PostEdit = () => ( ); ``` +**Tip**: If you just want to combine two fields in a string, check [the `` component](./FunctionField.md) instead. + +## Props -**Tip**: If you just want to combine two fields in a string, check [the `` component](./FunctionField.md) instead. \ No newline at end of file +`` accepts the [common field props](./Fields.md#common-field-props). \ No newline at end of file From c548d7fdb922319445e874512b47a75c63f4e6f7 Mon Sep 17 00:00:00 2001 From: Francois Zaninotto Date: Fri, 26 Jan 2024 09:37:50 +0100 Subject: [PATCH 2/2] Update docs/WrapperField.md Co-authored-by: Jean-Baptiste Kaiser --- docs/WrapperField.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/WrapperField.md b/docs/WrapperField.md index 3bc054b437a..eeaef356b89 100644 --- a/docs/WrapperField.md +++ b/docs/WrapperField.md @@ -50,4 +50,4 @@ const PostEdit = () => ( ## Props -`` accepts the [common field props](./Fields.md#common-field-props). \ No newline at end of file +`` accepts the [common field props](./Fields.md#common-field-props). \ No newline at end of file