diff --git a/docs/CreateBase.md b/docs/CreateBase.md index c5c40d01bdf..fac12211b9b 100644 --- a/docs/CreateBase.md +++ b/docs/CreateBase.md @@ -40,6 +40,8 @@ export const BookCreate = () => ( ); ``` +## Props + You can customize the `` component using the following props, documented in the `` component: * `children`: the components that renders the form diff --git a/docs/CreateDialog.md b/docs/CreateDialog.md index 1355c8b9eaa..17093456885 100644 --- a/docs/CreateDialog.md +++ b/docs/CreateDialog.md @@ -68,7 +68,6 @@ In the related ``, you don't need to declare a `create` component as t **Note**: You can't use the `` and have a standard `` specified on your ``, because the `` declarations would conflict. If you need this, use the [``](./CreateInDialogButton.md) instead. - ## Props `` accepts the following props: diff --git a/docs/EditDialog.md b/docs/EditDialog.md index d2c8941429c..93fefbafc49 100644 --- a/docs/EditDialog.md +++ b/docs/EditDialog.md @@ -321,4 +321,4 @@ const CompanyShow = () => ( ); ``` -Check [the `` component](./EditInDialogButton.md) for more details. \ No newline at end of file +Check [the `` component](./EditInDialogButton.md) for more details. diff --git a/docs/SaveButton.md b/docs/SaveButton.md index 8796fa09335..2239d647a07 100644 --- a/docs/SaveButton.md +++ b/docs/SaveButton.md @@ -46,6 +46,8 @@ const PostEdit = () => ( ); ``` +## Props + `` accepts the following props: - [`icon`](#icon) diff --git a/docs/Toolbar.md b/docs/Toolbar.md index 9a0a5f1352a..8160931fb37 100644 --- a/docs/Toolbar.md +++ b/docs/Toolbar.md @@ -40,6 +40,8 @@ const CommentCreate = () => ( ); ``` +## Props + `` accepts the following props: - [`children`](#children) diff --git a/docs/useCreateContext.md b/docs/useCreateContext.md index ab720e5b6bc..19c7e9554fc 100644 --- a/docs/useCreateContext.md +++ b/docs/useCreateContext.md @@ -40,14 +40,14 @@ const PostCreateForm = () => { ## Return Value -The `useCreateContext` hook returns an object with the same keys as returned by [`useCreateController`](./useCreateController.md): +`useCreateContext` returns an object with the same keys as [`useCreateController`](./useCreateController.md): ```jsx const { - defaultTitle, // the translated title based on the resource, e.g. 'Create New Post' - redirect, // the default redirection route. Defaults to 'list' - resource, // the resource name, deduced from the location. e.g. 'posts' - save, // the update callback, to be passed to the underlying form as submit handler - saving, // boolean that becomes true when the dataProvider is called to create the record + defaultTitle, // Translated title based on the resource, e.g. 'Create New Post' + redirect, // Default redirect route. Defaults to 'list' + resource, // Resource name, deduced from the location. e.g. 'posts' + save, // Update callback to be passed to the underlying form as submit handler + saving, // Boolean, true when the dataProvider is called to create the record } = useCreateContext(); ``` diff --git a/docs/useCreateController.md b/docs/useCreateController.md index 5ac114b80b7..1cdddc15270 100644 --- a/docs/useCreateController.md +++ b/docs/useCreateController.md @@ -44,31 +44,31 @@ export const BookCreate = () => { **Tip**: If you just use the return value of `useCreateController` to put it in an `CreateContext`, use [the `` component](./CreateBase.md) instead for simpler markup. -## Input Format -`useCreateController` accepts an options argument, with the following fields, all optional: +## Parameters -* [`disableAuthentication`](./Create.md#disableauthentication): disable the authentication check -* [`mutationOptions`](./Create.md#mutationoptions): options for the `dataProvider.create()` call -* [`record`](./Create.md#record): use the provided record as base instead of fetching it -* [`redirect`](./Create.md#redirect): change the redirect location after successful creation -* [`resource`](./Create.md#resource): override the name of the resource to create -* [`transform`](./Create.md#transform): transform the form data before calling `dataProvider.create()` +`useCreateController` accepts an object with the following keys, all optional: + +* [`disableAuthentication`](./Create.md#disableauthentication): Disable the authentication check +* [`mutationOptions`](./Create.md#mutationoptions): Options for the `dataProvider.create()` call +* [`record`](./Create.md#record): Use the provided record as base instead of fetching it +* [`redirect`](./Create.md#redirect): Change the redirect location after successful creation +* [`resource`](./Create.md#resource): Override the name of the resource to create +* [`transform`](./Create.md#transform): Transform the form data before calling `dataProvider.create()` These fields are documented in [the `` component](./Create.md) documentation. ## Return Value -`useCreateController` returns an object with the following fields: +`useCreateController` returns an object with the following keys: ```jsx const { - defaultTitle, // the translated title based on the resource, e.g. 'Create New Post' - record, // the default values of the creation form - redirect, // the default redirection route. Defaults to 'list' - resource, // the resource name, deduced from the location. e.g. 'posts' - save, // the update callback, to be passed to the underlying form as submit handler - saving, // boolean that becomes true when the dataProvider is called to create the record + defaultTitle, // Translated title based on the resource, e.g. 'Create New Post' + record, // Default values of the creation form + redirect, // Default redirect route. Defaults to 'list' + resource, // Resource name, deduced from the location. e.g. 'posts' + save, // Update callback to be passed to the underlying form as submit handler + saving, // Boolean, true when the dataProvider is called to create the record } = useCreateController(); ``` - diff --git a/docs/useEditContext.md b/docs/useEditContext.md index d918e431846..184c8ce7291 100644 --- a/docs/useEditContext.md +++ b/docs/useEditContext.md @@ -45,21 +45,21 @@ const Aside = () => { ## Return Value -The `useEditContext` hook returns an object with the same keys as returned by [`useEditController`](./useEditController.md): +`useEditContext` returns an object with the same keys as [`useEditController`](./useEditController.md): ```jsx const { - defaultTitle, // the translated title based on the resource, e.g. 'Post #123' - error, // error returned by dataProvider when it failed to fetch the record. Useful if you want to adapt the view instead of just showing a notification using the `onError` side effect. - isFetching, // boolean that is true while the record is being fetched, and false once the record is fetched - isLoading, // boolean that is true until the record is available for the first time - mutationMode, // mutation mode argument passed as parameter, or 'undoable' if not defined - record, // record fetched via dataProvider.getOne() based on the id from the location - redirect, // the default redirection route. Defaults to 'list' - refetch, // a function that allows you to refetch the record - resource, // the resource name, deduced from the location. e.g. 'posts' - save, // the update callback, to be passed to the underlying form as submit handler - saving, // boolean that becomes true when the dataProvider is called to update the record + defaultTitle, // Translated title based on the resource, e.g. 'Post #123' + isFetching, // Boolean, true while the record is being fetched, false once done fetching + isLoading, // Boolean, true until the record is available for the first time + mutationMode, // Mutation mode argument passed as parameter, or 'undoable' if not defined + record, // Either the record fetched via dataProvider.getOne() based on the id from the location, a cached version of the record (see also the Caching documentation page) or undefined + redirect, // Default redirection route. Defaults to 'list' + refetch, // Function that allows you to refetch the record + resource, // Resource name deduced from the location. e.g. 'posts' + save, // Update callback to be passed to the underlying form as submit handler + saving, // Boolean, true when dataProvider is called to update the record + error, // Error returned by dataProvider when it failed to fetch the record. Useful if you want to adapt the view instead of just showing a notification using the onError side effect. } = useEditContext(); ``` diff --git a/docs/useEditController.md b/docs/useEditController.md index 85b54cd8a27..5deb7890cdb 100644 --- a/docs/useEditController.md +++ b/docs/useEditController.md @@ -45,18 +45,19 @@ export const BookEdit = () => { **Tip**: If you just use the return value of `useEditController` to put it in an `EditContext`, use [the `` component](./EditBase.md) instead for simpler markup. -## Input Format -`useEditController` accepts an options argument, with the following fields, all optional: +## Parameters -* [`disableAuthentication`](./Edit.md#disableauthentication): disable the authentication check -* [`id`](./Edit.md#id): the id of the record to edit -* [`mutationMode`](./Edit.md#mutationmode): switch to optimistic or pessimistic mutations (undoable by default) -* [`mutationOptions`](./Edit.md#mutationoptions): options for the `dataProvider.update()` call -* [`queryOptions`](./Edit.md#queryoptions): options for the `dataProvider.getOne()` call -* [`redirect`](./Edit.md#redirect): change the redirect location after successful creation -* [`resource`](./Edit.md#resource): override the name of the resource to create -* [`transform`](./Edit.md#transform): transform the form data before calling `dataProvider.update()` +`useEditController` accepts an object with the following keys, all optional: + +* [`disableAuthentication`](./Edit.md#disableauthentication): Disable the authentication check +* [`id`](./Edit.md#id): The id of the record to edit +* [`mutationMode`](./Edit.md#mutationmode): Switch to optimistic or pessimistic mutations (undoable by default) +* [`mutationOptions`](./Edit.md#mutationoptions): Options for the `dataProvider.update()` call +* [`queryOptions`](./Edit.md#queryoptions): Options for the `dataProvider.getOne()` call +* [`redirect`](./Edit.md#redirect): Change the redirect location after successful creation +* [`resource`](./Edit.md#resource): Override the name of the resource to create +* [`transform`](./Edit.md#transform): Transform the form data before calling `dataProvider.update()` These fields are documented in [the `` component](./Edit.md) documentation. @@ -66,16 +67,17 @@ These fields are documented in [the `` component](./Edit.md) documentation ```jsx const { - defaultTitle, // the translated title based on the resource, e.g. 'Post #123' - error, // error returned by dataProvider when it failed to fetch the record. Useful if you want to adapt the view instead of just showing a notification using the `onError` side effect. - isFetching, // boolean that is true while the record is being fetched, and false once the record is fetched - isLoading, // boolean that is true until the record is available for the first time - mutationMode, // mutation mode argument passed as parameter, or 'undoable' if not defined - record, // record fetched via dataProvider.getOne() based on the id from the location - redirect, // the default redirection route. Defaults to 'list' - refetch, // a function that allows you to refetch the record - resource, // the resource name, deduced from the location. e.g. 'posts' - save, // the update callback, to be passed to the underlying form as submit handler - saving, // boolean that becomes true when the dataProvider is called to update the record + defaultTitle, // Translated title based on the resource, e.g. 'Post #123' + isFetching, // Boolean, true while the record is being fetched, false once done fetching + isLoading, // Boolean, true until the record is available for the first time + mutationMode, // Mutation mode argument passed as parameter, or 'undoable' if not defined + record, // Either the record fetched via dataProvider.getOne() based on the id from the location, a cached version of the record (see also the Caching documentation page) or undefined + redirect, // Default redirection route. Defaults to 'list' + refetch, // Function that allows you to refetch the record + resource, // Resource name deduced from the location. e.g. 'posts' + save, // Update callback to be passed to the underlying form as submit handler + saving, // Boolean, true when dataProvider is called to update the record + error, // Error returned by dataProvider when it failed to fetch the record. Useful if you want to adapt the view instead of just showing a notification using the onError side effect. } = useEditController(); ``` + diff --git a/docs/useList.md b/docs/useList.md index 9611b6ea5a1..47ea0d54604 100644 --- a/docs/useList.md +++ b/docs/useList.md @@ -61,12 +61,13 @@ const MyComponent = () => { ); }; ``` +## Parameters -The `useList` parameter accepts the following options: +`useList` expects an object with the following keys: * [`data`](#data) * [`filter`](#filter) -* [`filterCallback](#filtercallback) +* [`filterCallback`](#filtercallback) * [`isFetching`](#isfetching) * [`isLoading`](#isloading) * [`page`](#page) @@ -255,39 +256,39 @@ const { data } = useList({ ## Return Value -`useList` returns an object matching the shape of the `ListContext`: +`useList` returns an object with keys matching the shape of the `ListContext`: ```jsx const { - // fetched data - data, // a paginated, sorted, and filtered array of records, e.g. [{ id: 123, title: 'hello world' }, { ... }] - total, // the total number of results for the current filters, excluding pagination. Useful to build the pagination controls, e.g. 23 - isFetching, // boolean that is true while the data is being fetched, and false once the data is fetched - isLoading, // boolean that is true until the data is available for the first time - // pagination - page, // the current page. Starts at 1 - perPage, // the number of results per page. Defaults to 1000 - setPage, // a callback to change the page, e.g. setPage(3) - setPerPage, // a callback to change the number of results per page, e.g. setPerPage(25) - hasPreviousPage, // boolean, true if the current page is not the first one - hasNextPage, // boolean, true if the current page is not the last one - // sorting - sort, // a sort object { field, order }, e.g. { field: 'date', order: 'DESC' } - setSort, // a callback to change the sort, e.g. setSort({ field: 'name', order: 'ASC' }) - // filtering - filterValues, // a dictionary of filter values, e.g. { title: 'lorem', nationality: 'fr' } - displayedFilters, // a dictionary of the displayed filters, e.g. { title: true, nationality: true } - setFilters, // a callback to update the filters, e.g. setFilters(filters, displayedFilters) - showFilter, // a callback to show one of the filters, e.g. showFilter('title', defaultValue) - hideFilter, // a callback to hide one of the filters, e.g. hideFilter('title') - // record selection - selectedIds, // an array listing the ids of the selected rows, e.g. [123, 456] - onSelect, // callback to change the list of selected rows, e.g. onSelect([456, 789]) - onToggleItem, // callback to toggle the selection of a given record based on its id, e.g. onToggleItem(456) - onUnselectItems, // callback to clear the selection, e.g. onUnselectItems(); - // misc - defaultTitle, // empty string - resource, // undefined - refetch, // a function that throws an error, as refetch doesn't make sense for local data -} = useList({ data }); + // Data + data, // Array of the list records, e.g. [{ id: 123, title: 'hello world' }, { ... } + total, // Total number of results for the current filters, excluding pagination. Useful to build the pagination controls, e.g. 23 + isFetching, // Boolean, true while the data is being fetched, false once the data is fetched + isLoading, // Boolean, true until the data is available for the first time + // Pagination + page, // Current page. Starts at 1 + perPage, // Number of results per page. Defaults to 25 + setPage, // Callback to change the page, e.g. setPage(3) + setPerPage, // Callback to change the number of results per page, e.g. setPerPage(25) + hasPreviousPage, // Boolean, true if the current page is not the first one + hasNextPage, // Boolean, true if the current page is not the last one + // Sorting + sort, // Sort object { field, order }, e.g. { field: 'date', order: 'DESC' } + setSort, // Callback to change the sort, e.g. setSort({ field: 'name', order: 'ASC' }) + // Filtering + filterValues, // Dictionary of filter values, e.g. { title: 'lorem', nationality: 'fr' } + displayedFilters, // Dictionary of displayed filters, e.g. { title: true, nationality: true } + setFilters, // Callback to update the filters, e.g. setFilters(filters, displayedFilters) + showFilter, // Callback to show one of the filters, e.g. showFilter('title', defaultValue) + hideFilter, // Callback to hide one of the filters, e.g. hideFilter('title') + // Record selection + selectedIds, // Array listing the ids of the selected records, e.g. [123, 456] + onSelect, // Callback to change the list of selected records, e.g. onSelect([456, 789]) + onToggleItem, // Callback to toggle the record selection for a given id, e.g. onToggleItem(456) + onUnselectItems, // Callback to clear the record selection, e.g. onUnselectItems(); + // Misc + 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 +} = useList(); ``` diff --git a/docs/useListContext.md b/docs/useListContext.md index 8e2983d94c2..02b95849921 100644 --- a/docs/useListContext.md +++ b/docs/useListContext.md @@ -56,40 +56,40 @@ export const PostList = () => ( ## Return Value -The `useListContext` hook returns an object with the following keys: +`useListContext` returns an object with the following keys: ```jsx const { - // fetched data - data, // an array of the list records, e.g. [{ id: 123, title: 'hello world' }, { ... }] - total, // the total number of results for the current filters, excluding pagination. Useful to build the pagination controls, e.g. 23 - isFetching, // boolean that is true while the data is being fetched, and false once the data is fetched - isLoading, // boolean that is true until the data is available for the first time - // pagination - page, // the current page. Starts at 1 - perPage, // the number of results per page. Defaults to 25 - setPage, // a callback to change the page, e.g. setPage(3) - setPerPage, // a callback to change the number of results per page, e.g. setPerPage(25) - hasPreviousPage, // boolean, true if the current page is not the first one - hasNextPage, // boolean, true if the current page is not the last one - // sorting - sort, // a sort object { field, order }, e.g. { field: 'date', order: 'DESC' } - setSort, // a callback to change the sort, e.g. setSort({ field: 'name', order: 'ASC' }) - // filtering - filterValues, // a dictionary of filter values, e.g. { title: 'lorem', nationality: 'fr' } - displayedFilters, // a dictionary of the displayed filters, e.g. { title: true, nationality: true } - setFilters, // a callback to update the filters, e.g. setFilters(filters, displayedFilters) - showFilter, // a callback to show one of the filters, e.g. showFilter('title', defaultValue) - hideFilter, // a callback to hide one of the filters, e.g. hideFilter('title') - // record selection - selectedIds, // an array listing the ids of the selected rows, e.g. [123, 456] - onSelect, // callback to change the list of selected rows, e.g. onSelect([456, 789]) - onToggleItem, // callback to toggle the selection of a given record based on its id, e.g. onToggleItem(456) - onUnselectItems, // callback to clear the selection, e.g. onUnselectItems(); - // misc - defaultTitle, // the translated title based on the resource, e.g. 'Posts' - resource, // the resource name, deduced from the location. e.g. 'posts' - refetch, // callback for fetching the list data again + // Data + data, // Array of the list records, e.g. [{ id: 123, title: 'hello world' }, { ... } + total, // Total number of results for the current filters, excluding pagination. Useful to build the pagination controls, e.g. 23 + isFetching, // Boolean, true while the data is being fetched, false once the data is fetched + isLoading, // Boolean, true until the data is available for the first time + // Pagination + page, // Current page. Starts at 1 + perPage, // Number of results per page. Defaults to 25 + setPage, // Callback to change the page, e.g. setPage(3) + setPerPage, // Callback to change the number of results per page, e.g. setPerPage(25) + hasPreviousPage, // Boolean, true if the current page is not the first one + hasNextPage, // Boolean, true if the current page is not the last one + // Sorting + sort, // Sort object { field, order }, e.g. { field: 'date', order: 'DESC' } + setSort, // Callback to change the sort, e.g. setSort({ field: 'name', order: 'ASC' }) + // Filtering + filterValues, // Dictionary of filter values, e.g. { title: 'lorem', nationality: 'fr' } + displayedFilters, // Dictionary of displayed filters, e.g. { title: true, nationality: true } + setFilters, // Callback to update the filters, e.g. setFilters(filters, displayedFilters) + showFilter, // Callback to show one of the filters, e.g. showFilter('title', defaultValue) + hideFilter, // Callback to hide one of the filters, e.g. hideFilter('title') + // Record selection + selectedIds, // Array listing the ids of the selected records, e.g. [123, 456] + onSelect, // Callback to change the list of selected records, e.g. onSelect([456, 789]) + onToggleItem, // Callback to toggle the record selection for a given id, e.g. onToggleItem(456) + onUnselectItems, // Callback to clear the record selection, e.g. onUnselectItems(); + // Misc + 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 } = useListContext(); ``` diff --git a/docs/useListController.md b/docs/useListController.md index f3eee4896d6..ea83f80134e 100644 --- a/docs/useListController.md +++ b/docs/useListController.md @@ -105,21 +105,21 @@ const MyList = () => { }; ``` -## Input Format - -`useListController` expects one 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 +## Parameters + +`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 Here are their default values: @@ -217,39 +217,39 @@ You can disable this feature by setting the `storeKey` prop to `false`. When dis ## Return Value -The return value of `useListController` has the following shape: +`useListController` returns an object with the following keys: -```js +```jsx const { - // fetched data - data, // an array of the list records, e.g. [{ id: 123, title: 'hello world' }, { ... }] - total, // the total number of results for the current filters, excluding pagination. Useful to build the pagination controls, e.g. 23 - isFetching, // boolean that is true while the data is being fetched, and false once the data is fetched - isLoading, // boolean that is true until the data is available for the first time - // pagination - page, // the current page. Starts at 1 - perPage, // the number of results per page. Defaults to 25 - setPage, // a callback to change the page, e.g. setPage(3) - setPerPage, // a callback to change the number of results per page, e.g. setPerPage(25) - hasPreviousPage, // boolean, true if the current page is not the first one - hasNextPage, // boolean, true if the current page is not the last one - // sorting - sort, // a sort object { field, order }, e.g. { field: 'date', order: 'DESC' } - setSort, // a callback to change the sort, e.g. setSort({ field: 'name', order: 'ASC' }) - // filtering - filterValues, // a dictionary of filter values, e.g. { title: 'lorem', nationality: 'fr' } - displayedFilters, // a dictionary of the displayed filters, e.g. { title: true, nationality: true } - setFilters, // a callback to update the filters, e.g. setFilters(filters, displayedFilters) - showFilter, // a callback to show one of the filters, e.g. showFilter('title', defaultValue) - hideFilter, // a callback to hide one of the filters, e.g. hideFilter('title') - // record selection - selectedIds, // an array listing the ids of the selected rows, e.g. [123, 456] - onSelect, // callback to change the list of selected rows, e.g. onSelect([456, 789]) - onToggleItem, // callback to toggle the selection of a given record based on its id, e.g. onToggleItem(456) - onUnselectItems, // callback to clear the selection, e.g. onUnselectItems(); - // misc - defaultTitle, // the translated title based on the resource, e.g. 'Posts' - resource, // the resource name, deduced from the location. e.g. 'posts' - refetch, // callback for fetching the list data again -} = listContext; + // Data + data, // Array of the list records, e.g. [{ id: 123, title: 'hello world' }, { ... } + total, // Total number of results for the current filters, excluding pagination. Useful to build the pagination controls, e.g. 23 + isFetching, // Boolean, true while the data is being fetched, false once the data is fetched + isLoading, // Boolean, true until the data is available for the first time + // Pagination + page, // Current page. Starts at 1 + perPage, // Number of results per page. Defaults to 25 + setPage, // Callback to change the page, e.g. setPage(3) + setPerPage, // Callback to change the number of results per page, e.g. setPerPage(25) + hasPreviousPage, // Boolean, true if the current page is not the first one + hasNextPage, // Boolean, true if the current page is not the last one + // Sorting + sort, // Sort object { field, order }, e.g. { field: 'date', order: 'DESC' } + setSort, // Callback to change the sort, e.g. setSort({ field: 'name', order: 'ASC' }) + // Filtering + filterValues, // Dictionary of filter values, e.g. { title: 'lorem', nationality: 'fr' } + displayedFilters, // Dictionary of displayed filters, e.g. { title: true, nationality: true } + setFilters, // Callback to update the filters, e.g. setFilters(filters, displayedFilters) + showFilter, // Callback to show one of the filters, e.g. showFilter('title', defaultValue) + hideFilter, // Callback to hide one of the filters, e.g. hideFilter('title') + // Record selection + selectedIds, // Array listing the ids of the selected records, e.g. [123, 456] + onSelect, // Callback to change the list of selected records, e.g. onSelect([456, 789]) + onToggleItem, // Callback to toggle the record selection for a given id, e.g. onToggleItem(456) + onUnselectItems, // Callback to clear the record selection, e.g. onUnselectItems(); + // Misc + 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 +} = useListController(); ``` diff --git a/docs/useRecordContext.md b/docs/useRecordContext.md index 14c44fd77da..b79b09214e3 100644 --- a/docs/useRecordContext.md +++ b/docs/useRecordContext.md @@ -32,7 +32,7 @@ const BookShow = () => ( ## Optimistic Rendering -As react-admin uses optimistic rendering, `useRecordContext` may return an undefined record on load. Make sure you prepare for that! +As react-admin uses optimistic rendering, `useRecordContext` may be `undefined` or a cached version of the record on load (see also [Caching](./Caching.md#optimistic-rendering)). Make sure you prepare for that! ```jsx const BookAuthor = () => { diff --git a/docs/useRegisterMutationMiddleware.md b/docs/useRegisterMutationMiddleware.md index 41fd4665262..05748392a5b 100644 --- a/docs/useRegisterMutationMiddleware.md +++ b/docs/useRegisterMutationMiddleware.md @@ -58,9 +58,9 @@ React-admin will wrap each call to the `dataProvider.create()` mutation with the `useRegisterMutationMiddleware` unregisters the middleware function when the component unmounts. For this to work correctly, you must provide a stable reference to the function by wrapping it in a `useCallback` hook for instance. -## Params +## Parameters -`useRegisterMutationMiddleware` expects a single parameter: a middleware function. +`useRegisterMutationMiddleware` expects a single argument: a middleware function. A middleware function must have the following signature: diff --git a/docs/useSaveContext.md b/docs/useSaveContext.md index 0bd80181fa4..b8f1761eb1e 100644 --- a/docs/useSaveContext.md +++ b/docs/useSaveContext.md @@ -14,11 +14,7 @@ title: "useSaveContext" ```jsx import { useSaveContext } from 'react-admin'; -const { - save, // the create or update callback, which receives the form data and calls the dataProvider - saving, // boolean that becomes true when the dataProvider is called - mutationMode, // the current mutation mode, either 'undoable', 'optimistic', or 'pessimistic' -} = useSaveContext(); +const { save, saving, mutationMode } = useSaveContext(); ``` You can create a custom `SaveContext` to override the default `save` callback: @@ -41,3 +37,15 @@ const MyComponent = () => { } ``` {% endraw %} + +## Return Value + +`useSaveContext` returns an object with the following keys: + +```jsx +const { + save, // Create or update callback which receives form data and calls dataProvider + saving, // Boolean, true when dataProvider is called + mutationMode, // Current mutation mode, either 'undoable', 'optimistic' or 'pessimistic' +} = useSaveContext(); +``` diff --git a/docs/useShowContext.md b/docs/useShowContext.md index 9a20f7acce4..7a7c1128477 100644 --- a/docs/useShowContext.md +++ b/docs/useShowContext.md @@ -15,22 +15,16 @@ You can use `useShowContext` inside show components to access the data computed import { useShowContext, SimpleShowLayout, Show } from 'react-admin'; const PostShowLayout = () => { - const { - defaultTitle, // the translated title based on the resource, e.g. 'Post #123' - error, // error returned by dataProvider when it failed to fetch the record. Useful if you want to adapt the view instead of just showing a notification using the `onError` side effect. - isFetching, // boolean that is true while the record is being fetched, and false once the record is fetched - isLoading, // boolean that is true until the record is available for the first time - record, // record fetched via dataProvider.getOne() based on the id from the location - refetch, // callback to refetch the record via dataProvider.getOne() - resource, // the resource name, deduced from the location. e.g. 'posts' - } = useShowContext(); + const { defaultTitle, error, isLoading } = useShowContext(); if (isLoading) { return
Loading...
; } + if (error) { return
Error!
; } + return ( <>

{defaultTitle}

@@ -49,6 +43,22 @@ const PostShow = () => ( ) ``` +## Return Value + +`useShowContext` returns an object with the same keys as [`useShowController`](./useShowController.md): + +```jsx +const { + defaultTitle, // Translated title based on the resource, e.g. 'Post #123' + isFetching, // Boolean, true while the record is being fetched, and false once done fetching + isLoading, // Boolean, true until the record is available for the first time + record, // Either the record fetched via dataProvider.getOne() based on the id from the location, a cached version of the record (see also the Caching documentation page) or undefined + refetch, // Callback to refetch the record via dataProvider.getOne() + resource, // The resource name, deduced from the location. e.g. 'posts' + error, // Error returned by dataProvider when it failed to fetch the record. Useful if you want to adapt the view instead of just showing a notification using the onError side effect. +} = useShowContext(); +``` + ## TypeScript The `useShowContext` hook accepts a generic parameter for the record type: diff --git a/docs/useShowController.md b/docs/useShowController.md index 76f49ee6d19..790082db28e 100644 --- a/docs/useShowController.md +++ b/docs/useShowController.md @@ -19,15 +19,7 @@ You can use `useShowController` to create your own custom Show view, like this o import { useShowController, RecordContextProvider, SimpleShowLayout } from 'react-admin'; const PostShow = () => { - const { - defaultTitle, // the translated title based on the resource, e.g. 'Post #123' - error, // error returned by dataProvider when it failed to fetch the record. Useful if you want to adapt the view instead of just showing a notification using the `onError` side effect. - isFetching, // boolean that is true while the record is being fetched, and false once the record is fetched - isLoading, // boolean that is true until the record is available for the first time - record, // record fetched via dataProvider.getOne() based on the id from the location - refetch, // callback to refetch the record via dataProvider.getOne() - resource, // the resource name, deduced from the location. e.g. 'posts' - } = useShowController(); + const { defaultTitle, error, isLoading, record } = useShowController(); if (isLoading) { return
Loading...
; @@ -53,14 +45,13 @@ This custom Show view has no action buttons - it's up to you to add them in pure ## Parameters -`useShowController` expects one parameter argument. It's an object with the following attributes: +`useShowController` accepts an object with the following keys, all optional: + +* [`disableAuthentication`](#disableauthentication): Boolean, set to `true` to disable the authentication check. +* [`id`](#id): Record identifier. If not provided, it will be deduced from the URL. +* [`queryOptions`](#queryoptions): Options object to pass to the [`useQuery`](./Actions.mdl#usequery-and-usemutation) hook. +* [`resource`](#resource): Resource name, e.g. `posts` -| Name | Required | Type | Default | Description -|------------------|----------|-------------------|---------|-------------------------------------------------------- -| `disable Authentication` | Optional | `boolean` | | Set to `true` to disable the authentication check. -| `id` | Optional | `string` | | The record identifier. If not provided, it will be deduced from the URL. -| `queryOptions` | Optional | `object` | | The options to pass to the [`useQuery`](./Actions.md#usequery-and-usemutation) hook. -| `resource` | Optional | `string` | | The resource name, e.g. `posts` ## `disableAuthentication` @@ -174,6 +165,22 @@ const PostShow = () => { }; ``` +## Return Value + +`useShowController` returns an object with the following keys: + +```jsx +const { + defaultTitle, // Translated title based on the resource, e.g. 'Post #123' + isFetching, // Boolean, true while the record is being fetched, and false once done fetching + isLoading, // Boolean, true until the record is available for the first time + record, // Either the record fetched via dataProvider.getOne() based on the id from the location, a cached version of the record (see also the Caching documentation page) or undefined + refetch, // Callback to refetch the record via dataProvider.getOne() + resource, // The resource name, deduced from the location. e.g. 'posts' + error, // Error returned by dataProvider when it failed to fetch the record. Useful if you want to adapt the view instead of just showing a notification using the onError side effect. +} = useShowController(); +``` + ## Controlled Mode By default, `useShowController` reads the resource name from the resource context, and the record id from the browser location. diff --git a/docs/useUnique.md b/docs/useUnique.md index 7eb6a2dfa83..0e482f5def9 100644 --- a/docs/useUnique.md +++ b/docs/useUnique.md @@ -30,14 +30,16 @@ const UserCreateForm = () => { }; ``` -## Options - -| Option | Required | Type | Default | Description | -| ------------------- | -------- | -------------- | -------- | ---------------------------------------------------------------------------------- | -| `message` | Optional | `string` | `ra.validation.unique` | A custom message to display when the validation fails | -| `debounce` | Optional | `number` | 1000 | The number of milliseconds to wait for new changes before validating | -| `filter` | Optional | `object` | - | Additional filters to pass to the `dataProvider.getList` call | -| `resource` | Optional | `string` | current from Context | The resource targeted by the `dataProvider.getList` call | +## Parameters + +`useUnique` accepts an object with the following keys, all optional: + +| Key | Type | Default | Description | +| ----------------------- | -------------- | ---------------------- | -------------------------------------------------------------------- | +| [`message`](#message) | `string` | `ra.validation.unique` | A custom message to display when the validation fails | +| [`debounce`](#debounce) | `number` | 1000 | The number of milliseconds to wait for new changes before validating | +| [`filter`](#filter) | `object` | - | Additional filters to pass to the `dataProvider.getList` call | +| [`resource`](#resource) | `string` | current from Context | The resource targeted by the `dataProvider.getList` call | ## `message`