Merge pull request #9453 from sebashwa/doc-link-to-caching-page

Link to caching documentation page for hooks returning records

docs/CreateBase.md

@@ -40,6 +40,8 @@ export const BookCreate = () => (
 );
 ```
 
+## Props
+
 You can customize the `<CreateBase>` component using the following props, documented in the `<Create>` component:
 
 * `children`: the components that renders the form

docs/CreateDialog.md

@@ -68,7 +68,6 @@ In the related `<Resource>`, you don't need to declare a `create` component as t
 
 **Note**: You can't use the `<CreateDialog>` and have a standard `<Edit>` specified on your `<Resource>`, because the `<Routes>` declarations would conflict. If you need this, use the [`<CreateInDialogButton>`](./CreateInDialogButton.md) instead.
 
-
 ## Props
 
 `<CreateDialog>` accepts the following props:

docs/EditDialog.md

@@ -321,4 +321,4 @@ const CompanyShow = () => (
 );
 ```
 
-Check [the `<EditInDialogButton>` component](./EditInDialogButton.md) for more details.
+Check [the `<EditInDialogButton>` component](./EditInDialogButton.md) for more details.

docs/SaveButton.md

@@ -46,6 +46,8 @@ const PostEdit = () => (
 );
 ```
 
+## Props
+
 `<SaveButton>` accepts the following props:
 
 - [`icon`](#icon)

docs/Toolbar.md

@@ -40,6 +40,8 @@ const CommentCreate = () => (
 );
 ```
 
+## Props
+
 `<Toolbar>` accepts the following props:
 
 - [`children`](#children)

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();
 ```

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 `<CreateBase>` 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 `<Create>` 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();
 ```
-

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();
 ```
 

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 `<EditBase>` 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 `<Edit>` component](./Edit.md) documentation.
 
@@ -66,16 +67,17 @@ These fields are documented in [the `<Edit>` 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();
 ```
+

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();
 ```