Skip to content

Commit 1a873b4

Browse files
fzaninottofzaninotto
committed
[doc] Improve Create page
1 parent f3835e9 commit 1a873b4

File tree

1 file changed

+75
-48
lines changed

1 file changed

+75
-48
lines changed

‎docs/Create.md‎

Lines changed: 75 additions & 48 deletions
Original file line numberDiff line numberDiff line change
@@ -55,51 +55,25 @@ export default App;
5555

5656
You can customize the `<Create>` component using the following props:
5757

58-
* [`actions`](#actions): override the actions toolbar with a custom component
59-
* [`aside`](#aside): component to render aside to the main content
60-
* `children`: the components that renders the form
61-
* `render`: Alternative to children. A function that renders the form, receive the create context as its argument
62-
* `className`: passed to the root component
63-
* [`component`](#component): override the root component
64-
* [`disableAuthentication`](#disableauthentication): disable the authentication check
65-
* [`mutationMode`](#mutationmode): switch to optimistic or undoable mutations (pessimistic by default)
66-
* [`mutationOptions`](#mutationoptions): options for the `dataProvider.create()` call
67-
* [`record`](#record): initialize the form with a record
68-
* [`redirect`](#redirect): change the redirect location after successful creation
69-
* [`resource`](#resource): override the name of the resource to create
70-
* [`sx`](#sx-css-api): Override the styles
71-
* [`title`](#title): override the page title
72-
* [`transform`](#transform): transform the form data before calling `dataProvider.create()`
73-
74-
## `render`
75-
76-
Alternatively to children you can pass a render prop to `<Create>`. The render prop will receive the create context as its argument, allowing to inline the render logic for the create form.
77-
When receiving a render prop the `<Create>` component will ignore the children property.
78-
79-
{% raw %}
80-
```tsx
81-
<Create render={(createContext) => {
82-
if (createContext.isPending) {
83-
return <div>Loading...</div>;
84-
}
85-
if (createContext.error) {
86-
return <div>Error: {error.message}</div>;
87-
}
88-
89-
return (
90-
<Box>
91-
<h1>{`Create new ${createContext.resource}`}</h1>
92-
<SimpleForm>
93-
<TextInput source="title" validate={[required()]} />
94-
<TextInput source="teaser" multiline={true} label="Short description" />
95-
<RichTextInput source="body" />
96-
<DateInput label="Publication date" source="published_at" defaultValue={new Date()} />
97-
</SimpleForm>
98-
</Box>
99-
);
100-
}} />
101-
```
102-
{% endraw %}
58+
| Prop | Required | Type | Default | Description |
59+
|---------------------|----------|---------------------|----------------|--------------------------------------------------------------------------------------------------|
60+
| `children` | Optional* | `ReactNode` | - | The components that render the form |
61+
| `render` | Optional* | `function` | - | Alternative to children. Function that renders the form, receives the create context as argument |
62+
| `actions` | Optional | `ReactNode` | Default toolbar| Override the actions toolbar with a custom component |
63+
| `aside` | Optional | `ReactNode` | - | Component to render aside to the main content |
64+
| `className` | Optional | `string` | - | Passed to the root component |
65+
| `component` | Optional | `string`/`Component`| `Card` | Override the root component |
66+
| `disableAuthentication` | Optional | `boolean` | `false` | Disable the authentication check |
67+
| `mutationMode` | Optional | `string` | `pessimistic` | Switch to optimistic or undoable mutations |
68+
| `mutationOptions` | Optional | `object` | - | Options for the `dataProvider.create()` call |
69+
| `record` | Optional | `object` | `{}` | Initialize the form with a record |
70+
| `redirect` | Optional | `string`/`function` | `'edit'` | Change the redirect location after successful creation |
71+
| `resource` | Optional | `string` | From URL | Override the name of the resource to create |
72+
| `sx` | Optional | `object` | - | Override the styles |
73+
| `title` | Optional | `string`/`ReactNode`| Translation | Override the page title |
74+
| `transform` | Optional | `function` | - | Transform the form data before calling `dataProvider.create()` |
75+
76+
* You must provide either `children` or `render`.
10377

10478
## `actions`
10579

@@ -151,6 +125,28 @@ const PostCreate = () => (
151125

152126
{% endraw %}
153127

128+
## `children`
129+
130+
The `<Create>` component will render its children inside a `CreateContext` provider, which the `save` function. Children can be any React node, but are usually a form component like [`<SimpleForm>`](./SimpleForm.md), [`<TabbedForm>`](./TabbedForm.md), or the headless [`<Form>`](./Form.md) component.
131+
132+
```tsx
133+
import { Create, SimpleForm, TextInput, DateInput, required } from 'react-admin';
134+
import RichTextInput from 'ra-input-rich-text';
135+
136+
export const PostCreate = () => (
137+
<Create>
138+
<SimpleForm>
139+
<TextInput source="title" validate={[required()]} />
140+
<TextInput source="teaser" multiline={true} label="Short description" />
141+
<RichTextInput source="body" />
142+
<DateInput label="Publication date" source="published_at" defaultValue={new Date()} />
143+
</SimpleForm>
144+
</Create>
145+
);
146+
```
147+
148+
**Tip**: Alternatively to `children`, you can pass a [`render`](#render) prop to `<Create>`.
149+
154150
## `component`
155151

156152
By default, the `<Create>` view render the main form inside a Material UI `<Card>` element. The actual layout of the form depends on the `Form` component you're using ([`<SimpleForm>`](./SimpleForm.md), [`<TabbedForm>`](./TabbedForm.md), or a custom form component).
@@ -191,9 +187,9 @@ const PostCreate = () => (
191187

192188
The `<Create>` view exposes a Save button, which perform a "mutation" (i.e. it creates the data). React-admin offers three modes for mutations. The mode determines when the side effects (redirection, notifications, etc.) are executed:
193189

194-
- `pessimistic` (default): The mutation is passed to the dataProvider first. When the dataProvider returns successfully, the mutation is applied locally, and the side effects are executed.
195-
- `optimistic`: The mutation is applied locally and the side effects are executed immediately. Then the mutation is passed to the dataProvider. If the dataProvider returns successfully, nothing happens (as the mutation was already applied locally). If the dataProvider returns in error, the page is refreshed and an error notification is shown.
196-
- `undoable`: The mutation is applied locally and the side effects are executed immediately. Then a notification is shown with an undo button. If the user clicks on undo, the mutation is never sent to the dataProvider, and the page is refreshed. Otherwise, after a 5 seconds delay, the mutation is passed to the dataProvider. If the dataProvider returns successfully, nothing happens (as the mutation was already applied locally). If the dataProvider returns in error, the page is refreshed and an error notification is shown.
190+
* `pessimistic` (default): The mutation is passed to the dataProvider first. When the dataProvider returns successfully, the mutation is applied locally, and the side effects are executed.
191+
* `optimistic`: The mutation is applied locally and the side effects are executed immediately. Then the mutation is passed to the dataProvider. If the dataProvider returns successfully, nothing happens (as the mutation was already applied locally). If the dataProvider returns in error, the page is refreshed and an error notification is shown.
192+
* `undoable`: The mutation is applied locally and the side effects are executed immediately. Then a notification is shown with an undo button. If the user clicks on undo, the mutation is never sent to the dataProvider, and the page is refreshed. Otherwise, after a 5 seconds delay, the mutation is passed to the dataProvider. If the dataProvider returns successfully, nothing happens (as the mutation was already applied locally). If the dataProvider returns in error, the page is refreshed and an error notification is shown.
197193

198194
By default, pages using `<Create>` use the `pessimistic` mutation mode as the new record identifier is often generated on the backend. However, should you decide to generate this identifier client side, you can change the `mutationMode` to either `optimistic` or `undoable`:
199195

@@ -346,6 +342,37 @@ Note that the `redirect` prop is ignored if you set [the `mutationOptions` prop]
346342

347343
If you want to allow the user to enter several records one after the other, setting `redirect` to `false` won't make it, as the form isn't emptied by default. You'll have to empty the form using the `mutationOptions`, and this option disables the `redirect` prop. Check [the Save And Add Another section](#save-and-add-another) for more details.
348344

345+
## `render`
346+
347+
Alternatively to `children`, you can pass a `render` prop to `<Create>`. It will receive the `CreateContext` as its argument, and should return a React node.
348+
349+
This allows to inline the render logic for the create page.
350+
351+
{% raw %}
352+
353+
```tsx
354+
const PostCreate = () => ()
355+
<Create render={({ save, saving }) => (
356+
<div>
357+
<h1>Create new Post</h1>
358+
<form onSubmit={save}>
359+
<input type="text" name="title" placeholder="Title" required />
360+
<textarea name="teaser" placeholder="Short description" rows={3} />
361+
<textarea name="body" placeholder="Body" rows={5} />
362+
<input type="date" name="published_at" defaultValue={new Date().toISOString().split('T')[0]} />
363+
<button type="submit" disabled={saving}>
364+
{saving ? 'Saving...' : 'Save'}
365+
</button>
366+
</form>
367+
</div>
368+
)} />
369+
);
370+
```
371+
372+
{% endraw %}
373+
374+
**Tip**: When receiving a render prop the `<Create>` component will ignore the children property.
375+
349376
## `resource`
350377

351378
Components based on `<Create>` are often used as `<Resource create>` props, and therefore rendered when the URL matches `/[resource]/create`. The `<Create>` component generates a call to `dataProvider.create()` using the resource name from the URL by default.

0 commit comments

Comments
 (0)