From 207331b63ce6f428375419607fbd05c4658cd2b0 Mon Sep 17 00:00:00 2001 From: Jean-Baptiste Kaiser Date: Mon, 9 Dec 2024 17:36:35 +0100 Subject: [PATCH] update docs for 5.4.2 --- DateRangeInput.md | 12 ++++-- ReferenceManyToManyField.md | 42 +++++++++++++++++---- ReferenceManyToManyInput.md | 74 ++++++++++++++++++++++++++++++++----- TreeWithDetails.md | 46 +++++++++++++++-------- _data/versions.yml | 2 +- 5 files changed, 139 insertions(+), 37 deletions(-) diff --git a/DateRangeInput.md b/DateRangeInput.md index 354ab924cc0..3e17687dc1a 100644 --- a/DateRangeInput.md +++ b/DateRangeInput.md @@ -9,14 +9,20 @@ This [Enterprise Edition](https://react-admin-ee.marmelab.com)` is a wrapper around the [Material UI X Date Range Picker](https://mui.com/x/react-date-pickers/date-range-picker/), which is a MUI X Pro package. This means that you need to own a [MUI X Pro license](https://mui.com/x/introduction/licensing/#pro-plan) to use it. +**Note**: `` is a wrapper around the [Material UI X Date Range Picker](https://mui.com/x/react-date-pickers/date-range-picker/), which is a MUI X Pro package. This means that you need to own a [MUI X Pro license](https://mui.com/x/introduction/licensing/#pro-plan) to use it and install the package: + +```sh +npm install --save @mui/x-date-pickers-pro +# or +yarn add @mui/x-date-pickers-pro +``` ## Usage Use `` inside a form component (``, ``, ``, etc.) to allow users to pick a start and an end date. ```tsx -import { DateRangeInput } from '@react-admin/ra-form-layout'; +import { DateRangeInput } from '@react-admin/ra-form-layout/DateRangeInput'; import { Edit, SimpleForm } from 'react-admin'; export const EventEdit = () => ( @@ -106,7 +112,7 @@ import { SimpleForm, TextInput, } from "react-admin"; -import { DateRangeInput } from '@react-admin/ra-form-layout'; +import { DateRangeInput } from '@react-admin/ra-form-layout/DateRangeInput'; const requiredValues = dates => !dates || isEmpty(dates[0]) || isEmpty(dates[1]) diff --git a/ReferenceManyToManyField.md b/ReferenceManyToManyField.md index 87c7ada4fbc..daabd6b2bae 100644 --- a/ReferenceManyToManyField.md +++ b/ReferenceManyToManyField.md @@ -5,7 +5,7 @@ title: "The ReferenceManyToManyField Component" # `` -This [Enterprise Edition](https://react-admin-ee.marmelab.com) component fetches a list of referenced records by lookup in an associative table, and passes the records down to its child component, which must be an iterator component (e.g. ``). +This [Enterprise Edition](https://react-admin-ee.marmelab.com)React Admin Enterprise Edition icon component fetches a list of referenced records by lookup in an associative table, and passes the records down to its child component, which must be an iterator component (e.g. ``). !["ReferenceManyToManyField example showing band's venues"](./img/reference-many-to-many-field.png) @@ -15,7 +15,7 @@ Note: The `` cannot currently display multiple records Let's imagine that you're writing an app managing concerts for artists. The data model features a many-to-many relationship between the `bands` and `venues` tables through a `performances` associative table. -``` +```txt ┌─────────┐ ┌──────────────┐ ┌───────────────┐ │ bands │ │ performances │ │ venues │ │---------│ │--------------│ │---------------│ @@ -28,7 +28,7 @@ Let's imagine that you're writing an app managing concerts for artists. The data In this example, `bands.id` matches `performances.band_id`, and `performances.venue_id` matches `venues.id`. -To allow users see the `venues` for a given `band` in ``, wrap that component in `` where you define the relationship via the `reference`, `through` and `using` props: +To allow users see the `venues` for a given `band` in ``, wrap that component in `` where you define the relationship via the `reference`, `through` and `using` props: ```tsx import React from 'react'; @@ -61,17 +61,18 @@ export const BandShow = () => ( | ----------- | -------- | ------------------------------------------- | -------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `children` | Required | `element` | - | An iterator element (e.g. `` or ``). The iterator element usually has one or more child `` components. | | `reference` | Required | `string` | - | Name of the reference resource, e.g. 'venues' | -| `through` | Required | `string` | - | Name of the resource for the associative table, e.g. 'performances' +| `through` | Required | `string` | - | Name of the resource for the associative table, e.g. 'performances' | | `filter` | Optional | `object` | `{}` | Filter for the associative table (passed to the `getManyReference()` call) | | `joinLimit` | Optional | `number` | 100 | Limit for the number of results fetched from the associative table. Should be **greater than `perPage`** | | `perPage` | Optional | `number` | 25 | Limit the number of displayed result after `getManyReference` is called. Useful when using a pagination component. Should be **smaller than `joinLimit`** | +| `queryOptions` | Optional | `UseQueryOptions` | - | Query options for the `getMany` and `getManyReference` calls | | `sort` | Optional | `{ field: string, order: 'ASC' or 'DESC' }` | `{ field: 'id', order: 'DESC' }` | Sort for the associative table (passed to the `getManyReference()` call) | | `source` | Optional | `string` | `'id'` | Name of the field containing the identity of the main resource. Used determine the value to look for in the associative table. | | `using` | Optional | `string` | `'[resource]_id,[reference]_id'` | Tuple (comma separated) of the two field names used as foreign keys, e.g 'band_id,venue_id'. The tuple should start with the field pointing to the resource, and finish with the field pointing to the reference | ## `children` -`` expects an _iterator_ component as child, i.e. a component working inside a `ListContext`. +`` expects an _iterator_ component as child, i.e. a component working inside a `ListContext`. This means you can use a `` instead of a ``, which is useful if you want to display more details about related records. For instance, to display the venue `name` and `location`: @@ -105,6 +106,7 @@ export const BandShow = () => ( You can filter the records of the associative table (e.g. `performances`) using the `filter` prop. This `filter` is passed to the `getManyReference()` call. {% raw %} + ```tsx ``` + {% endraw %} ## `joinLimit` @@ -165,6 +168,27 @@ import { Pagination } from 'react-admin'; ``` +## `queryOptions` + +Use the `queryOptions` prop to customize the queries for `getMany` and `getManyReference`. + +You can for instance use it to pass [a custom meta](./Actions.md#meta-parameter) to the dataProvider. + +{% raw %} + +```tsx + + {/* ... */} + +``` + +{% endraw %} + ## `reference` The name of the target resource to fetch. @@ -187,6 +211,7 @@ For instance, if you want to display the `venues` of a given `bands`, through `p By default, react-admin orders the possible values by `id` desc for the associative table (e.g. `performances`). You can change this order by setting the `sort` prop (an object with `field` and `order` properties) to be applied to the associative resource. {% raw %} + ```tsx ``` + {% endraw %} ## `source` @@ -242,8 +268,8 @@ You can specify the columns to use in the associative `using` the using prop. `` fetches the `dataProvider` twice in a row: -- once to get the records of the associative resource (`performances` in this case), using a `getManyReference()` call -- once to get the records of the reference resource (`venues` in this case), using a `getMany()` call. +- once to get the records of the associative resource (`performances` in this case), using a `getManyReference()` call +- once to get the records of the reference resource (`venues` in this case), using a `getMany()` call. For instance, if the user displays the band of id `123`, `` first issues the following query to the `dataProvider`: @@ -286,4 +312,4 @@ And receives the reference venues: ], "total": 3 } -``` \ No newline at end of file +``` diff --git a/ReferenceManyToManyInput.md b/ReferenceManyToManyInput.md index bb1a571404d..76ef74a105f 100644 --- a/ReferenceManyToManyInput.md +++ b/ReferenceManyToManyInput.md @@ -5,7 +5,7 @@ title: "The ReferenceManyToManyInput Component" # `` -This [Enterprise Edition](https://react-admin-ee.marmelab.com) component allows to create, edit or remove relationships between two resources sharing an associative table. The changes in the associative table are sent to the dataProvider _when the user submits the form_, so that they can cancel the changes before submission. +This [Enterprise Edition](https://react-admin-ee.marmelab.com)React Admin Enterprise Edition icon component allows to create, edit or remove relationships between two resources sharing an associative table. The changes in the associative table are sent to the dataProvider _when the user submits the form_, so that they can cancel the changes before submission.