Skip to content

Commit 2180bc5

Browse files
fzaninottofzaninotto
committed
[doc] Improve AutoPersistInStore doc
1 parent bb66163 commit 2180bc5

File tree

7 files changed

+197
-22
lines changed

7 files changed

+197
-22
lines changed

‎docs/AccordionForm.md‎

Lines changed: 31 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -830,11 +830,39 @@ const PersonEdit = () => (
830830
```
831831
{% endraw %}
832832

833-
Note that you **must** set the `<AccordionForm resetOptions>` prop to `{ keepDirtyValues: true }`. If you forget that prop, any change entered by the end user after the autosave but before its acknowledgement by the server will be lost.
833+
Check [the `<AutoSave>` component](./AutoSave.md) documentation for more details.
834834

835-
If you're using it in an `<Edit>` page, you must also use a `pessimistic` or `optimistic` [`mutationMode`](./Edit.md#mutationmode) - `<AutoSave>` doesn't work with the default `mutationMode="undoable"`.
835+
An alternative to the `<AutoSave>` component is to use [the `<AutoPersistInStore>` component](./AutoPersistInStore.md). This component saves the form values in the local storage of the browser. This way, if the user navigates away without saving, the form values are reapplied when the user comes back to the page. This is useful for long forms where users may spend a lot of time.
836836

837-
Check [the `<AutoSave>` component](./AutoSave.md) documentation for more details.
837+
To enable this behavior, add the `<AutoPersistInStore>` component inside the form component:
838+
839+
```tsx
840+
import { AccordionForm, AutoPersistInStore } from '@react-admin/ra-form-layout';
841+
import { Create, TextInput, DateInput, SelectInput } from 'react-admin';
842+
843+
const CustomerCreate = () => (
844+
<Create>
845+
<AccordionForm>
846+
<AccordionForm.Panel label="Identity">
847+
<TextInput source="first_name" />
848+
<TextInput source="last_name" />
849+
<DateInput source="born" />
850+
<SelectInput source="sex" choices={[
851+
{ id: 'male', name: 'Male' },
852+
{ id: 'female', name: 'Female' },
853+
{ id: 'other', name: 'Other' },
854+
]} />
855+
</AccordionForm.Panel>
856+
<AccordionForm.Panel label="Work">
857+
{/* ... */}
858+
</AccordionForm.Panel>
859+
<AutoPersistInStore />
860+
</AccordionForm>
861+
</Create>
862+
);
863+
```
864+
865+
Check [the `<AutoPersistInStore>` component](./AutoPersistInStore.md) documentation for more details.
838866

839867
## Access Control
840868

‎docs/AutoPersistInStore.md‎

Lines changed: 22 additions & 7 deletions
Original file line numberDiff line numberDiff line change
@@ -5,14 +5,17 @@ title: "The AutoPersistInStore Component"
55

66
# `<AutoPersistInStore>`
77

8-
This [Enterprise Edition](https://react-admin-ee.marmelab.com)<img class="icon" src="./img/premium.svg" alt="React Admin Enterprise Edition icon" /> component saves a form data in the store on unmount (e.g. when users leave the page) and reapplies it on mount.
9-
It's ideal to ensure users don't loose their already filled data in an edit or a create form when they navigate to another page.
8+
This [Enterprise Edition](https://react-admin-ee.marmelab.com)<img class="icon" src="./img/premium.svg" alt="React Admin Enterprise Edition icon" /> prevents data loss in forms by automatically saving the form data in the store when users navigate away from the page. When users return to the page, it reapplies the saved data to the form.
109

1110
<video controls autoplay playsinline muted loop>
1211
<source src="./img/AutoPersistInStore.mp4" type="video/mp4"/>
1312
Your browser does not support the video tag.
1413
</video>
1514

15+
The temporary form data is only saved when the user navigates away from the page, and it is removed when the user submits the form or closes the tab. Users can opt out of the prefilling by clicking the "Cancel" button in the notification.
16+
17+
Saved data is not sent to the server. It is only persisted using the [store](./Store.md) and is removed when the user logs out.
18+
1619
## Usage
1720

1821
Add `<AutoPersistInStore>` inside a react-admin form (`<SimpleForm>`, `<TabbedForm>`, `<LongForm>`, etc.):
@@ -32,17 +35,26 @@ const PostEdit = () => (
3235
);
3336
```
3437

38+
The component will automatically save the form data in the store on unmount and reapply it when the form is mounted again.
39+
40+
It works both on create and edit forms.
41+
3542
## Props
3643

3744
| Prop | Required | Type | Default | Description |
3845
| --------------------- | -------- | ---------- | -------------------------------------------------------- | ------------------------------------------------------------- |
3946
| `getStoreKey` | - | `function` | - | Function to use your own store key. |
40-
| `notificationMessage` | - | `string` | `"ra-form-layout.` `auto_persist_ in_store` `.applied_changes"` | Notification message to inform users that their previously saved changes have been applied. |
47+
| `notificationMessage` | - | `string` | "Applied previous unsaved changes" | Notification message to inform users that their previously saved changes have been applied. |
4148

4249
## `getStoreKey`
4350

44-
To save the current form data in the [store](./useStoreContext.md), `<AutoPersistInStore>` uses a default key that can be overridden with the `getStoreKey` prop.
45-
It accepts a function with two parameters:
51+
To save the current form data in the [store](./useStoreContext.md), `<AutoPersistInStore>` uses the following store key:
52+
53+
`ra-persist-[RESOURCE_NAME]-[RECORD_ID]`
54+
55+
For example, if you are editing a `posts` resource with the ID `123`, the store key will be: `ra-persist-posts-123`. In case of a create form, the record ID is replaced by `"create"`
56+
57+
You can override this key by passing a custom function as the `getStoreKey` prop. It expects two parameters:
4658

4759
- `resource`: The current resource.
4860
- `record`: The current record if you are in an [edit context](./useEditContext.md).
@@ -56,11 +68,14 @@ It accepts a function with two parameters:
5668
/>
5769
```
5870

59-
The default key is `ra-persist-YOUR_RESOURCE-RECORD_ID` (in case of a create form, the record `id` is replaced by `"create"`), e.g. `ra-persist-customers-5`.
6071

6172
## `notificationMessage`
6273

63-
When `<AutoPersistInStore>` component applies the changes from the store to a form, react-admin's inform users with a notification. You can customize it with the `notificationMessage` prop:
74+
When `<AutoPersistInStore>` component applies the changes from the store to a form, react-admin informs users with a notification.
75+
76+
The default notification message is `ra-form-layout.auto_persist_in_store.applied_changes`, which is translated using the i18n provider (the default English translation is `Applied previous unsaved changes`).
77+
78+
You can customize it with the `notificationMessage` prop:
6479

6580
```tsx
6681
<AutoPersistInStore notificationMessage="Modifications applied" />

‎docs/Form.md‎

Lines changed: 28 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -292,6 +292,34 @@ If you're using it in an `<Edit>` page, you must also use a `pessimistic` or `op
292292

293293
Check [the `<AutoSave>` component](./AutoSave.md) documentation for more details.
294294

295+
An alternative to the `<AutoSave>` component is to use [the `<AutoPersistInStore>` component](./AutoPersistInStore.md). This component saves the form values in the local storage of the browser. This way, if the user navigates away without saving, the form values are reapplied when the user comes back to the page. This is useful for long forms where users may spend a lot of time.
296+
297+
<video controls autoplay playsinline muted loop>
298+
<source src="./img/AutoPersistInStore.mp4" type="video/mp4"/>
299+
Your browser does not support the video tag.
300+
</video>
301+
302+
To enable this behavior, add the `<AutoPersistInStore>` component inside the form component:
303+
304+
```tsx
305+
import { AutoPersistInStore } from '@react-admin/ra-form-layout';
306+
import { Edit, Form, TextInput } from 'react-admin';
307+
308+
const PostEdit = () => (
309+
<Edit>
310+
<Form>
311+
<Stack>
312+
<TextInput source="title" />
313+
<TextInput source="teaser" />
314+
</Stack>
315+
<AutoPersistInStore />
316+
</Form>
317+
</Edit>
318+
);
319+
```
320+
321+
Check [the `<AutoPersistInStore>` component](./AutoPersistInStore.md) documentation for more details.
322+
295323
## Linking Two Inputs
296324

297325
<iframe src="https://www.youtube-nocookie.com/embed/YkqjydtmfcU" 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;"></iframe>

‎docs/Forms.md‎

Lines changed: 25 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -621,11 +621,33 @@ const PersonEdit = () => (
621621
```
622622
{% endraw %}
623623
624-
Note that you **must** set the `<SimpleForm resetOptions>` prop to `{ keepDirtyValues: true }`. If you forget that prop, any change entered by the end user after the autosave but before its acknowledgment by the server will be lost.
624+
Check [the `<AutoSave>` component](./AutoSave.md) documentation for more details.
625625
626-
If you're using it in an `<Edit>` page, you must also use a `pessimistic` or `optimistic` [`mutationMode`](https://marmelab.com/react-admin/Edit.html#mutationmode) - `<AutoSave>` doesn't work with the default `mutationMode="undoable"`.
626+
An alternative to the `<AutoSave>` component is to use [the `<AutoPersistInStore>` component](./AutoPersistInStore.md). This component saves the form values in the local storage of the browser. This way, if the user navigates away without saving, the form values are reapplied when the user comes back to the page. This is useful for long forms where users may spend a lot of time.
627627
628-
Check [the `<AutoSave>` component](./AutoSave.md) documentation for more details.
628+
<video controls autoplay playsinline muted loop>
629+
<source src="./img/AutoPersistInStore.mp4" type="video/mp4"/>
630+
Your browser does not support the video tag.
631+
</video>
632+
633+
To enable this behavior, add the `<AutoPersistInStore>` component inside the form component:
634+
635+
```tsx
636+
import { AutoPersistInStore } from '@react-admin/ra-form-layout';
637+
import { Edit, SimpleForm, TextInput } from 'react-admin';
638+
639+
const PostEdit = () => (
640+
<Edit>
641+
<SimpleForm>
642+
<TextInput source="title" />
643+
<TextInput source="teaser" />
644+
<AutoPersistInStore />
645+
</SimpleForm>
646+
</Edit>
647+
);
648+
```
649+
650+
Check [the `<AutoPersistInStore>` component](./AutoPersistInStore.md) documentation for more details.
629651
630652
## Adding Fields With Labels
631653

‎docs/LongForm.md‎

Lines changed: 31 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -705,11 +705,39 @@ const PersonEdit = () => (
705705
```
706706
{% endraw %}
707707

708-
Note that you **must** set the `<LongForm resetOptions>` prop to `{ keepDirtyValues: true }`. If you forget that prop, any change entered by the end user after the autosave but before its acknowledgement by the server will be lost.
708+
Check [the `<AutoSave>` component](./AutoSave.md) documentation for more details.
709709

710-
If you're using it in an `<Edit>` page, you must also use a `pessimistic` or `optimistic` [`mutationMode`](./Edit.md#mutationmode) - `<AutoSave>` doesn't work with the default `mutationMode="undoable"`.
710+
An alternative to the `<AutoSave>` component is to use [the `<AutoPersistInStore>` component](./AutoPersistInStore.md). This component saves the form values in the local storage of the browser. This way, if the user navigates away without saving, the form values are reapplied when the user comes back to the page. This is useful for long forms where users may spend a lot of time.
711711

712-
Check [the `<AutoSave>` component](./AutoSave.md) documentation for more details.
712+
To enable this behavior, add the `<AutoPersistInStore>` component inside the form component:
713+
714+
```tsx
715+
import { LongForm, AutoPersistInStore } from '@react-admin/ra-form-layout';
716+
import { Create, TextInput, DateInput, SelectInput } from 'react-admin';
717+
718+
const CustomerCreate = () => (
719+
<Create>
720+
<LongForm>
721+
<LongForm.Section label="Identity">
722+
<TextInput source="first_name" />
723+
<TextInput source="last_name" />
724+
<DateInput source="born" />
725+
<SelectInput source="sex" choices={[
726+
{ id: 'male', name: 'Male' },
727+
{ id: 'female', name: 'Female' },
728+
{ id: 'other', name: 'Other' },
729+
]} />
730+
</LongForm.Section>
731+
<LongForm.Section label="Work">
732+
{/* ... */}
733+
</LongForm.Section>
734+
<AutoPersistInStore />
735+
</LongForm>
736+
</Create>
737+
);
738+
```
739+
740+
Check [the `<AutoPersistInStore>` component](./AutoPersistInStore.md) documentation for more details.
713741

714742
## Access Control
715743

‎docs/SimpleForm.md‎

Lines changed: 25 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -618,11 +618,33 @@ const PersonEdit = () => (
618618
```
619619
{% endraw %}
620620

621-
Note that you **must** set the `<SimpleForm resetOptions>` prop to `{ keepDirtyValues: true }`. If you forget that prop, any change entered by the end user after the autosave but before its acknowledgement by the server will be lost.
621+
Check [the `<AutoSave>` component](./AutoSave.md) documentation for more details.
622622

623-
If you're using it in an `<Edit>` page, you must also use a `pessimistic` or `optimistic` [`mutationMode`](https://marmelab.com/react-admin/Edit.html#mutationmode) - `<AutoSave>` doesn't work with the default `mutationMode="undoable"`.
623+
An alternative to the `<AutoSave>` component is to use [the `<AutoPersistInStore>` component](./AutoPersistInStore.md). This component saves the form values in the local storage of the browser. This way, if the user navigates away without saving, the form values are reapplied when the user comes back to the page. This is useful for long forms where users may spend a lot of time.
624624

625-
Check [the `<AutoSave>` component](./AutoSave.md) documentation for more details.
625+
<video controls autoplay playsinline muted loop>
626+
<source src="./img/AutoPersistInStore.mp4" type="video/mp4"/>
627+
Your browser does not support the video tag.
628+
</video>
629+
630+
To enable this behavior, add the `<AutoPersistInStore>` component inside the form component:
631+
632+
```tsx
633+
import { AutoPersistInStore } from '@react-admin/ra-form-layout';
634+
import { Edit, SimpleForm, TextInput } from 'react-admin';
635+
636+
const PostEdit = () => (
637+
<Edit>
638+
<SimpleForm>
639+
<TextInput source="title" />
640+
<TextInput source="teaser" />
641+
<AutoPersistInStore />
642+
</SimpleForm>
643+
</Edit>
644+
);
645+
```
646+
647+
Check [the `<AutoPersistInStore>` component](./AutoPersistInStore.md) documentation for more details.
626648

627649
## Versioning
628650

‎docs/TabbedForm.md‎

Lines changed: 35 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -788,12 +788,44 @@ const PostEdit = () => (
788788
```
789789
{% endraw %}
790790

791-
Note that you **must** set the `<TabbedForm resetOptions>` prop to `{ keepDirtyValues: true }`. If you forget that prop, any change entered by the end user after the autosave but before its acknowledgement by the server will be lost.
791+
Check [the `<AutoSave>` component](./AutoSave.md) documentation for more details.
792792

793-
If you're using it in an `<Edit>` page, you must also use a `pessimistic` or `optimistic` [`mutationMode`](https://marmelab.com/react-admin/Edit.html#mutationmode) - `<AutoSave>` doesn't work with the default `mutationMode="undoable"`.
793+
An alternative to the `<AutoSave>` component is to use [the `<AutoPersistInStore>` component](./AutoPersistInStore.md). This component saves the form values in the local storage of the browser. This way, if the user navigates away without saving, the form values are reapplied when the user comes back to the page. This is useful for long forms where users may spend a lot of time.
794794

795-
Check [the `<AutoSave>` component](./AutoSave.md) documentation for more details.
795+
<video controls autoplay playsinline muted loop>
796+
<source src="./img/AutoPersistInStore.mp4" type="video/mp4"/>
797+
Your browser does not support the video tag.
798+
</video>
799+
800+
To enable this behavior, add the `<AutoPersistInStore>` component inside the form component:
801+
802+
```tsx
803+
import { AutoPersistInStore } from '@react-admin/ra-form-layout';
804+
import { Create, TabbedForm, TextInput, DateInput, SelectInput } from 'react-admin';
805+
806+
const CustomerCreate = () => (
807+
<Create>
808+
<TabbedForm>
809+
<TabbedForm.Tab label="Identity">
810+
<TextInput source="first_name" />
811+
<TextInput source="last_name" />
812+
<DateInput source="born" />
813+
<SelectInput source="sex" choices={[
814+
{ id: 'male', name: 'Male' },
815+
{ id: 'female', name: 'Female' },
816+
{ id: 'other', name: 'Other' },
817+
]} />
818+
</TabbedForm.Tab>
819+
<TabbedForm.Tab label="Work">
820+
{/* ... */}
821+
</TabbedForm.Tab>
822+
<AutoPersistInStore />
823+
</TabbedForm>
824+
</Create>
825+
);
826+
```
796827

828+
Check [the `<AutoPersistInStore>` component](./AutoPersistInStore.md) documentation for more details.
797829

798830
## Versioning
799831

0 commit comments

Comments
 (0)