Merge pull request #11119 from marmelab/exporterbutton-listcontext

Improve `<ExportButton>` with list-context getData

Author: fzaninotto

docs/ArrayField.md

@@ -6,7 +6,7 @@ storybook_path: ra-ui-materialui-fields-arrayfield--basic
 
 # `<ArrayField>`
 
-`<ArrayField>` renders an embedded array of objects. 
+`<ArrayField>` renders an embedded array of objects.
 
 ![ArrayField](./img/array-field.webp)
 
@@ -76,6 +76,7 @@ const PostShow = () => (
 |------------|----------|-------------------|---------|------------------------------------------|
 | `children` | Required | `ReactNode`       |         | The component to render the list.        |
 | `filter`   | Optional | `object`          |         | The filter to apply to the list.         |
+| `exporter` | Optional | `function`        | `default Exporter` | The function called by export buttons in the list context. |
 | `perPage`  | Optional | `number`          | 1000    | The number of items to display per page. |
 | `sort`     | Optional | `{ field, order}` |         | The sort to apply to the list.           |
 
@@ -158,6 +159,7 @@ const PostShow = () => (
 You can use the `filter` prop to display only a subset of the items in the array. For instance, to display only the backlinks for a particular day:
 
 {% raw %}
+
 ```jsx
 <ArrayField source="backlinks" filter={{ date: '2012-08-10T00:00:00.000Z' }}>
     <DataTable>
@@ -167,13 +169,14 @@ You can use the `filter` prop to display only a subset of the items in the array
     </DataTable>
 </ArrayField>
 ```
+
 {% endraw %}
 
 The filtering capabilities are very limited. For instance, there is no "greater than" or "less than" operator. You can only filter on the equality of a field.
 
 ## `perPage`
 
-If the value is a large array, and you don't need to display all the items, you can use the `perPage` prop to limit the number of items displayed. 
+If the value is a large array, and you don't need to display all the items, you can use the `perPage` prop to limit the number of items displayed.
 
 As `<ArrayField>` creates a [`ListContext`](./useListContext.md), you can use the `<Pagination>` component to navigate through the items.
 
@@ -209,13 +212,15 @@ const PostShow = () => (
 By default, `<ArrayField>` displays the items in the order they are stored in the field. You can use the `sort` prop to change the sort order.
 
 {% raw %}
+
 ```jsx
 <ArrayField source="tags" sort={{ field: 'name', order: 'ASC' }}>
     <SingleFieldList linkType={false}>
         <ChipField source="name" />
     </SingleFieldList>
 </ArrayField>
 ```
+
 {% endraw %}
 
 ## Using The List Context

docs/ReferenceArrayField.md

@@ -90,6 +90,7 @@ You can change how the list of related records is rendered by passing a custom c
 | `empty`        | Optional | `ReactNode`                                                                       | -                                | The component to render when the related records list is empty                                         |
 | `error`        | Optional | `ReactNode`                                                                       | -                                | The component to render when an error occurs while fetching the related records                        |
 | `filter`       | Optional | `Object`                                                                          | -                                | Filters to use when fetching the related records (the filtering is done client-side)                   |
+| `exporter`     | Optional | `function`                                                                        | `defaultExporter`                | The function called by export buttons in the list context                                                |
 | `loading`      | Optional | `ReactNode`                                                                       | `<LinearProgress>`             | The component to render while fetching the related records                                             |
 | `offline`      | Optional | `ReactNode`                                                              | `<Offline variant="inline" />` | The component to render when there is no connectivity and the record isn't in the cache |
 | `pagination`   | Optional | `ReactNode`                                                                         | -                                | Pagination element to display pagination controls. empty by default (no pagination)                    |

docs/ReferenceManyField.md

@@ -6,7 +6,7 @@ storybook_path: ra-ui-materialui-fields-referencemanyfield--basic
 
 # `<ReferenceManyField>`
 
-`<ReferenceManyField>` 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>` 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.
 
 <iframe src="https://www.youtube-nocookie.com/embed/UeM31-65Wc4" title="YouTube video player" frameborder="0" allow="accelerometer; autoplay; clipboard-write; encrypted-media; gyroscope; picture-in-picture; web-share" allowfullscreen style="aspect-ratio: 16 / 9;width:100%;margin-bottom:1em;" referrerpolicy="strict-origin-when-cross-origin"></iframe>
 
@@ -97,6 +97,7 @@ This example leverages [`<SingleFieldList>`](./SingleFieldList.md) to display an
 | `empty`        | Optional | `ReactNode`                                                                       | -                                | Element to display when there are no related records.                                |
 | `error`        | Optional | `ReactNode`                                                                       | -                                | The component to render when an error occurs while fetching the related records     |
 | `filter`       | Optional | `Object`                                                                          | -                                | Filters to use when fetching the related records, passed to `getManyReference()`    |
+| `exporter`     | Optional | `function`                                                                        | `default Exporter`                | The function called by export buttons in the list context                          |
 | `loading`      | Optional | `ReactNode`                                                                       | -                                | The component to render while fetching the related records                          |
 | `offline`      | Optional | `ReactNode`                                                                       | -                                | Element to display when there are no related records because of lack of network connectivity. |
 | `pagination`   | Optional | `Element`                                                                         | -                                | Pagination element to display pagination controls. empty by default (no pagination) |
@@ -120,7 +121,7 @@ This example leverages [`<SingleFieldList>`](./SingleFieldList.md) to display an
 - [`<SimpleList>`](./SimpleList.md)
 - [`<EditableDatagrid>`](./EditableDatagrid.md)
 - [`<Calendar>`](./Calendar.md)
-- Or a component of your own (check the [`<WithListContext>`](./WithListContext.md) and the [`useListContext`](./useListContext.md) chapters to learn how). 
+- Or a component of your own (check the [`<WithListContext>`](./WithListContext.md) and the [`useListContext`](./useListContext.md) chapters to learn how).
 
 For instance, use a `<DataTable>` to render the related records in a table:
 
@@ -451,9 +452,11 @@ Use the `queryOptions` prop to pass options to [the `dataProvider.getMany()` que
 For instance, to pass [a custom `meta`](./Actions.md#meta-parameter):
 
 {% raw %}
+
 ```jsx
 <ReferenceManyField queryOptions={{ meta: { foo: 'bar' } }} />
 ```
+
 {% endraw %}
 
 ## `reference`
@@ -505,6 +508,7 @@ This allows to inline the render logic for the list of related records.
 By default, it orders the possible values by id desc. You can change this order by setting the `sort` prop (an object with `field` and `order` properties).
 
 {% raw %}
+
 ```jsx
 <ReferenceManyField
   target="post_id"
@@ -514,6 +518,7 @@ By default, it orders the possible values by id desc. You can change this order
    ...
 </ReferenceManyField>
 ```
+
 {% endraw %}
 
 ## `source`
@@ -539,6 +544,7 @@ If you want to display multiple lists of the same reference and keep distinct se
 In the example below, both lists use the same reference ('books'), but their selection states are stored separately (under the store keys `'authors.1.books.selectedIds'` and `'custom.selectedIds'` respectively). This allows to use both components in the same page, each having its own state.
 
 {% raw %}
+
 ```jsx
 <Stack direction="row" spacing={2}>
     <ReferenceManyField
@@ -566,6 +572,7 @@ In the example below, both lists use the same reference ('books'), but their sel
     </ReferenceManyField>
 </Stack>
 ```
+
 {% endraw %}
 
 ## `target`
@@ -583,11 +590,12 @@ Name of the field carrying the relationship on the referenced resource. For inst
 
 ## Rendering Only One Record
 
-Although you are in a one-to-many relationship, you may want to render only one record. For instance, in a book with several reviews, you may want to display only the last. Or, for a product with many prices, you may want to display only the one in euros. 
+Although you are in a one-to-many relationship, you may want to render only one record. For instance, in a book with several reviews, you may want to display only the last. Or, for a product with many prices, you may want to display only the one in euros.
 
 In these cases, use [the `<ReferenceOneField>` component](./ReferenceOneField.md) instead of `<ReferenceManyField>`.
 
 {% raw %}
+
 ```jsx
 <ReferenceOneField
     label="Latest review"
@@ -599,9 +607,11 @@ In these cases, use [the `<ReferenceOneField>` component](./ReferenceOneField.md
     <TextField source="body" />
 </ReferenceOneField>
 ```
+
 {% endraw %}
 
 {% raw %}
+
 ```jsx
 <ReferenceOneField
     label="Price (€)"
@@ -612,6 +622,7 @@ In these cases, use [the `<ReferenceOneField>` component](./ReferenceOneField.md
     <NumberField source="price" />
 </ReferenceOneField>
 ```
+
 {% endraw %}
 
 ## Adding or editing a related record
@@ -624,6 +635,7 @@ To allow users to create or edit a record without leaving the current view, use
 </video>
 
 {% raw %}
+
 ```jsx
 import { Edit, SimpleForm, TextInput, ReferenceManyField, WithRecord, DataTable } from 'react-admin';
 import { CreateInDialogButton, EditInDialogButton } from "@react-admin/ra-form-layout";
@@ -667,4 +679,5 @@ const EmployerEdit = () => (
   </Edit>
 )
 ```
+
 {% endraw %}

docs/useList.md

@@ -66,6 +66,7 @@ const MyComponent = () => {
 `useList` expects an object with the following keys:
 
 * [`data`](#data)
+* [`exporter`](#exporter)
 * [`filter`](#filter)
 * [`filterCallback`](#filtercallback)
 * [`isFetching`](#isfetching)
@@ -88,6 +89,23 @@ const { data } = useList({
 });
 ```
 
+## `exporter`
+
+The function called by export buttons in this list context. Defaults to `defaultExporter`.
+
+```jsx
+import { downloadCSV } from 'react-admin';
+import jsonExport from 'jsonexport/dist';
+
+const exporter = records => {
+    jsonExport(records, (err, csv) => {
+        downloadCSV(csv, 'actors');
+    });
+};
+
+const listContext = useList({ data, exporter });
+```
+
 ## `filter`
 
 The initial filter to apply to the data.

docs/useListContext.md

@@ -92,6 +92,7 @@ const {
     defaultTitle, // Translated title based on the resource, e.g. 'Posts'
     resource, // Resource name, deduced from the location. e.g. 'posts'
     refetch, // Callback for fetching the list data again
+    getData, // Callback that returns the full list data (ignores pagination)
 } = useListContext();
 ```
 

docs/useListController.md

@@ -6,11 +6,11 @@ storybook_path: ra-core-controller-list-uselistcontroller--authenticated
 
 # `useListController`
 
-`useListController` contains the headless logic of the [`<List>`](./List.md) component. It's useful to create a custom List view. It's also the base hook when building a custom view with another UI kit than Material UI. 
+`useListController` contains the headless logic of the [`<List>`](./List.md) component. It's useful to create a custom List view. It's also the base hook when building a custom view with another UI kit than Material UI.
 
 ![List view built with Ant Design](./img/list_ant_design.png)
 
-`useListController` reads the list parameters from the URL, calls `dataProvider.getList()`, prepares callbacks for modifying the pagination, filters, sort and selection, and returns them together with the data. Its return value matches the [`ListContext`](./useListContext.md) shape. 
+`useListController` reads the list parameters from the URL, calls `dataProvider.getList()`, prepares callbacks for modifying the pagination, filters, sort and selection, and returns them together with the data. Its return value matches the [`ListContext`](./useListContext.md) shape.
 
 `useListController` is used internally by [`<List>`](./List.md) and [`<ListBase>`](./ListBase.md). If your list view uses react-admin components like [`<DataTable>`](./DataTable.md), prefer [`<ListBase>`](./ListBase.md) to `useListController` as it takes care of creating a `<ListContext>`.
 
@@ -21,6 +21,7 @@ storybook_path: ra-core-controller-list-uselistcontroller--authenticated
 Here the code for the post list view above, built with [Ant Design](https://ant.design/):
 
 {% raw %}
+
 ```jsx
 import { useListController } from 'react-admin'; 
 import { Card, Table, Button } from 'antd';
@@ -86,6 +87,7 @@ const columns = [
 
 export default PostList;
 ```
+
 {% endraw %}
 
 When using react-admin components, it's common to call `useListController()` without parameters, and to put the result in a `ListContext` to make it available to the rest of the component tree.
@@ -110,17 +112,21 @@ const MyList = () => {
 
 `useListController` expects an object as parameter. All keys are optional.
 
-* [`debounce`](./List.md#debounce): Debounce time in ms for the setFilters callbacks
-* [`disableAuthentication`](./List.md#disableauthentication): Set to true to allow anonymous access to the list
-* [`disableSyncWithLocation`](./List.md#disablesyncwithlocation): Set to true to have more than one list per page
-* [`exporter`](./List.md#exporter): Exporter function
-* [`filter`](./List.md#filter-permanent-filter): Permanent filter, forced over the user filter
-* [`filterDefaultValues`](./List.md#filterdefaultvalues): Default values for the filter form
-* [`perPage`](./List.md#perpage): Number of results per page
-* [`queryOptions`](./List.md#queryoptions): React-query options for the useQuery call
-* [`resource`](./List.md#resource): Resource name, e.g. 'posts' ; defaults to the current resource context
-* [`sort`](./List.md#sort): Current sort value, e.g. `{ field: 'published_at', order: 'DESC' }`
-* [`storeKey`](#storekey): Key used to differentiate the list from another sharing the same resource, in store managed states
+| Prop                      | Type                    | Default | Description                                                                                      |
+|---------------------------|-------------------------|---------|--------------------------------------------------------------------------------------------------|
+| `debounce`                | `number`                | `500`   | The debounce delay in milliseconds to apply when users change the sort or filter parameters.     |
+| `disableAuthentication`   | `boolean`               | `false` | Set to `true` to disable the authentication check.                                               |
+| `disableSyncWithLocation` | `boolean`               | `false` | Set to `true` to disable the synchronization of the list parameters with the URL.                |
+| `exporter`                | `function`              | -       | The function to call to export the list.                                                         |
+| `filter`                  | `object`                | -       | The permanent filter values, forced over the user filter                                         |
+| `filterDefaultValues`     | `object`                | -       | The default filter values.                                                                       |
+| `perPage`                 | `number`                | `10`    | The number of records to fetch per page.                                                         |
+| `queryOptions`            | `object`                | -       | The options to pass to the `useQuery` hook.                                                      |
+| `resource`                | `string`                | -       | The resource name, e.g. `posts`.                                                                 |
+| `sort`                    | `object`                | -       | The initial sort parameters, e.g. `{ field: 'published_at', order: 'DESC' }`.                     |
+| `storeKey`                | `string` &#124; `false` | -       | The key to use to store the current filter & sort. Pass `false` to disable store synchronization |
+
+Check [the `<List>` component documentation](./List.md) for more details about these parameters.
 
 Here are their default values:
 
@@ -178,6 +184,7 @@ If you want to disable the storage of list parameters altogether for a given lis
 In the example below, both lists `TopPosts` and `FlopPosts` use the same resource ('posts'), but their controller states are stored separately (under the store keys `'top'` and `'flop'` respectively).
 
 {% raw %}
+
 ```jsx
 import { useListController } from 'react-admin';
 
@@ -211,14 +218,14 @@ const FlopPosts = (
     <OrderedPostList storeKey="flop" sort={{ field: 'votes', order: 'ASC' }} />
 );
 ```
+
 {% endraw %}
 
 You can disable this feature by setting the `storeKey` prop to `false`. When disabled, parameters will not be persisted in the store.
 
-
 ## Return Value
 
-`useListController` returns an object with the following keys: 
+`useListController` returns an object with the following keys:
 
 ```jsx
 const {
@@ -253,16 +260,17 @@ const {
     defaultTitle, // Translated title based on the resource, e.g. 'Posts'
     resource, // Resource name, deduced from the location. e.g. 'posts'
     refetch, // Callback for fetching the list data again
+    getData, // Callback that returns the full list data (ignores pagination)
 } = useListController();
 ```
 
 ## Using `setFilters` to Update Filters
 
 The `setFilters` method is used to update the filters. It takes three arguments:
 
-- `filters`: an object containing the new filter values
-- `displayedFilters`: an object containing the new displayed filters
-- `debounced`: set to true to debounce the call to setFilters (false by default)
+* `filters`: an object containing the new filter values
+* `displayedFilters`: an object containing the new displayed filters
+* `debounced`: set to true to debounce the call to setFilters (false by default)
 
 You can use it to update the list filters: