Merge pull request #5363 from marmelab/ra-ee-links-in-doc

[Doc] Add mentions of the Enterprise Edition components in documentation
marmelab · Oct 8, 2020 · a1351cd · a1351cd
2 parents 8b29391 + b284f63
commit a1351cd
Show file tree

Hide file tree

Showing 13 changed files with 714 additions and 43 deletions.
diff --git a/docs/Admin.md b/docs/Admin.md
@@ -27,25 +27,22 @@ export default App;
 
 Here are all the props accepted by the component:
 
-- [The `<Admin>` Component](#the-admin-component)
-  - [`dataProvider`](#dataprovider)
-  - [`authProvider`](#authprovider)
-  - [`i18nProvider`](#i18nprovider)
-  - [`title`](#title)
-  - [`dashboard`](#dashboard)
-  - [`catchAll`](#catchall)
-  - [`menu`](#menu)
-  - [`theme`](#theme)
-  - [`layout`](#layout)
-  - [`customReducers`](#customreducers)
-  - [`customSagas`](#customsagas)
-  - [`customRoutes`](#customroutes)
-  - [`loginPage`](#loginpage)
-  - [`logoutButton`](#logoutbutton)
-  - [`initialState`](#initialstate)
-  - [`history`](#history)
-  - [Declaring resources at runtime](#declaring-resources-at-runtime)
-  - [Using react-admin without `<Admin>` and `<Resource>`](#using-react-admin-without-admin-and-resource)
+- [`dataProvider`](#dataprovider)
+- [`authProvider`](#authprovider)
+- [`i18nProvider`](#i18nprovider)
+- [`title`](#title)
+- [`dashboard`](#dashboard)
+- [`catchAll`](#catchall)
+- [`menu`](#menu)
+- [`theme`](#theme)
+- [`layout`](#layout)
+- [`customReducers`](#customreducers)
+- [`customSagas`](#customsagas)
+- [`customRoutes`](#customroutes)
+- [`loginPage`](#loginpage)
+- [`logoutButton`](#logoutbutton)
+- [`initialState`](#initialstate)
+- [`history`](#history)
 
 ## `dataProvider`
 

diff --git a/docs/CreateEdit.md b/docs/CreateEdit.md
@@ -864,6 +864,136 @@ export const PostEdit = (props) => (
 );
 ```
 
+## The `<AccordionForm>` Component
+
+This [Enterprise Edition](https://marmelab.com/ra-enterprise)<img class="icon" src="./img/premium.svg" /> component offers an alternative layout for Edit and Create forms, where Inputs are grouped into expandable panels.
+
+![AccordionForm](https://marmelab.com/ra-enterprise/modules/assets/ra-accordion-form-overview.gif)
+
+```jsx
+import {
+    Edit,
+    TextField,
+    TextInput,
+    DateInput,
+    SelectInput,
+    ArrayInput,
+    SimpleFormIterator,
+    BooleanInput,
+} from 'react-admin';
+
+import { AccordionForm, AccordionFormPanel } from '@react-admin/ra-form-layout';
+
+// don't forget the component="div" prop on the main component to disable the main Card
+const CustomerEdit: FC = props => (
+    <Edit {...props} component="div">
+        <AccordionForm autoClose>
+            <AccordionFormPanel label="Identity">
+                <TextField source="id" />
+                <TextInput source="first_name" validate={required()} />
+                <TextInput source="last_name" validate={required()} />
+                <DateInput source="dob" label="born" validate={required()} />
+                <SelectInput source="sex" choices={sexChoices} />
+            </AccordionFormPanel>
+            <AccordionFormPanel label="Occupations">
+                <ArrayInput source="occupations" label="">
+                    <SimpleFormIterator>
+                        <TextInput source="name" validate={required()} />
+                        <DateInput source="from" validate={required()} />
+                        <DateInput source="to" />
+                    </SimpleFormIterator>
+                </ArrayInput>
+            </AccordionFormPanel>
+            <AccordionFormPanel label="Preferences">
+                <SelectInput
+                    source="language"
+                    choices={languageChoices}
+                    defaultValue="en"
+                />
+                <BooleanInput source="dark_theme" />
+                <BooleanInput source="accepts_emails_from_partners" />
+            </AccordionFormPanel>
+        </AccordionForm>
+    </Edit>
+);
+```
+
+You can also use the `<AccordionSection>` component as a child of `<SimpleForm>` for secondary inputs:
+
+![Accordion section](https://marmelab.com/ra-enterprise/modules/assets/ra-accordion-section-overview.gif)
+
+Check [the `ra-form-layout` documentation](https://marmelab.com/ra-enterprise/modules/ra-form-layout) for more details.
+
+## The `<WizardForm>` Component
+
+This [Enterprise Edition](https://marmelab.com/ra-enterprise)<img class="icon" src="./img/premium.svg" /> component offers an alternative layout for large Create forms, allowing users to enter data step-by-step.
+
+![WizardForm](https://marmelab.com/ra-enterprise/modules/assets/ra-wizard-form-overview.gif)
+
+```jsx
+import React, { FC } from 'react';
+import { Create, TextInput, required } from 'react-admin';
+import { WizardForm, WizardFormStep } from '@react-admin/ra-form-layout';
+
+const PostCreate: FC = props => (
+    <Create {...props}>
+        <WizardForm>
+            <WizardFormStep label="First step">
+                <TextInput source="title" validate={required()} />
+            </WizardFormStep>
+            <WizardFormStep label="Second step">
+                <TextInput source="description" />
+            </WizardFormStep>
+            <WizardFormStep label="Third step">
+                <TextInput source="fullDescription" validate={required()} />
+            </WizardFormStep>
+        </WizardForm>
+    </Create>
+);
+```
+
+Check [the `ra-form-layout` documentation](https://marmelab.com/ra-enterprise/modules/ra-form-layout) for more details.
+
+## The `<CreateDialog>` and `<EditDialog>` Components
+
+These [Enterprise Edition](https://marmelab.com/ra-enterprise)<img class="icon" src="./img/premium.svg" /> components offer an alternative layout for adding or updating a record without leaving the context of the list page.
+
+![EditDialog](https://marmelab.com/ra-enterprise/modules/assets/edit-dialog.gif)
+
+```jsx
+import React from 'react';
+import { List, Datagrid, SimpleForm, TextField, TextInput, DateInput, required } from 'react-admin';
+import { EditDialog, CreateDialog } from '@react-admin/ra-form-layout';
+
+const CustomerList = props => (
+    <>
+        <List {...props}>
+            <Datagrid>
+                ...
+            </Datagrid>
+        </List>
+        <EditDialog {...props}>
+            <SimpleForm>
+                <TextField source="id" />
+                <TextInput source="first_name" validate={required()} />
+                <TextInput source="last_name" validate={required()} />
+                <DateInput source="date_of_birth" label="born" validate={required()} />
+            </SimpleForm>
+        </EditDialog>
+        <CreateDialog {...props}>
+            <SimpleForm>
+                <TextField source="id" />
+                <TextInput source="first_name" validate={required()} />
+                <TextInput source="last_name" validate={required()} />
+                <DateInput source="date_of_birth" label="born" validate={required()} />
+            </SimpleForm>
+        </CreateDialog>
+    </>
+);
+```
+
+Check [the `ra-form-layout` documentation](https://marmelab.com/ra-enterprise/modules/ra-form-layout) for more details.
+
 ## Default Values
 
 To define default values, you can add a `initialValues` prop to form components (`<SimpleForm>`, `<TabbedForm>`, etc.), or add a `defaultValue` to individual input components. Let's see each of these options.

diff --git a/docs/DataProviders.md b/docs/DataProviders.md
@@ -52,16 +52,19 @@ const dataProvider = {
 
 You can find an example Data Provider implementation at the end of this chapter.
 
+**Tip**: A Data Provider can have more methods than the 9 methods listed above. For instance, you create a dataProvider with custom methods for calling non-REST API endpoints, manipulating tree structures, subscribing to real time updates, etc.
+
 **Tip**: In react-admin v2, Data Providers used to be functions, not objects. React-admin v3 can detect a legacy Data Provider and wrap an object around it. So Data Providers developed for react-admin v2 still work with react-admin v3.
 
 ## Available Providers
 
-The react-admin project includes 4 Data Providers:
+The react-admin project includes 5 Data Providers:
 
 * Simple REST: [marmelab/ra-data-simple-rest](https://github.com/marmelab/react-admin/tree/master/packages/ra-data-simple-rest) ([read more below](#usage)). It serves mostly as an example. Incidentally, it is compatible with the [FakeRest](https://github.com/marmelab/FakeRest) API.
 * **[JSON server](https://github.com/typicode/json-server)**: [marmelab/ra-data-json-server](https://github.com/marmelab/react-admin/tree/master/packages/ra-data-json-server). Great for prototyping an admin over a yet-to-be-developed REST API.
 * [Simple GraphQL](https://graphql.org/): [marmelab/ra-data-graphql-simple](https://github.com/marmelab/react-admin/tree/master/packages/ra-data-graphql-simple). A GraphQL provider built with Apollo and tailored to target a simple GraphQL implementation.
 * Local JSON: [marmelab/ra-data-fakerest](https://github.com/marmelab/react-admin/tree/master/packages/ra-data-fakerest). Based on a local object, it doesn't even use HTTP. Use it for testing purposes.
+* Local Storage: [marmelab/ra-data-localstorage](https://github.com/marmelab/react-admin/tree/master/packages/ra-data-localstorage). User editions are persisted across refreshes and between sessions. This allows local-first apps, and can be useful in tests.
 
 Developers from the react-admin community have open-sourced Data Providers for many more backends:
 
@@ -499,9 +502,10 @@ export default {
 
 Let's say that you want to map the react-admin requests to a REST backend exposing the following API:
 
-```
-# getList
 
+### getList
+
+```
 GET http://path.to.my.api/posts?sort=["title","ASC"]&range=[0, 4]&filter={"author_id":12}
 
 HTTP/1.1 200 OK
@@ -514,17 +518,21 @@ Content-Range: posts 0-4/27
     { "id": 123, "title": "hello, world", "author_id": 12 },
     { "id": 125, "title": "howdy partner", "author_id": 12 }
 ]
+```
 
-# getOne
+### getOne
 
+```
 GET http://path.to.my.api/posts/123
 
 HTTP/1.1 200 OK
 Content-Type: application/json
 { "id": 123, "title": "hello, world", "author_id": 12 }
+```
 
-# getMany
+### getMany
 
+```
 GET http://path.to.my.api/posts?filter={"id":[123,124,125]}
 
 HTTP/1.1 200 OK
@@ -534,9 +542,11 @@ Content-Type: application/json
     { "id": 124, "title": "good day sunshine", "author_id": 12 },
     { "id": 125, "title": "howdy partner", "author_id": 12 }
 ]
+```
 
-# getManyReference
+### getManyReference
 
+```
 GET http://path.to.my.api/comments?sort=["created_at","DESC"]&range=[0, 24]&filter={"post_id":123}
 
 HTTP/1.1 200 OK
@@ -546,45 +556,54 @@ Content-Range: comments 0-1/2
     { "id": 667, "title": "I agree", "post_id": 123 },
     { "id": 895, "title": "I don't agree", "post_id": 123 }
 ]
+```
 
-# create
+### create
 
+```
 POST http://path.to.my.api/posts
 { "title": "hello, world", "author_id": 12 }
 
 HTTP/1.1 200 OK
 Content-Type: application/json
 { "id": 123, "title": "hello, world", "author_id": 12 }
+```
 
+### update
 
-# update
-
+```
 PUT http://path.to.my.api/posts/123
 { "title": "hello, world!" }
 
 HTTP/1.1 200 OK
 Content-Type: application/json
 { "id": 123, "title": "hello, world!", "author_id": 12 }
+```
 
-# updateMany
+### updateMany
 
+```
 PUT http://path.to.my.api/posts?filter={"id":[123,124,125]}
 { "title": "hello, world!" }
 
 HTTP/1.1 200 OK
 Content-Type: application/json
 [123, 124, 125]
+```
 
-# delete
+### delete
 
+```
 DELETE http://path.to.my.api/posts/123
 
 HTTP/1.1 200 OK
 Content-Type: application/json
 { "id": 123, "title": "hello, world", "author_id": 12 }
+```
 
-# deleteMany
+### deleteMany
 
+```
 DELETE http://path.to.my.api/posts?filter={"id":[123,124,125]}
 
 HTTP/1.1 200 OK
@@ -723,3 +742,37 @@ const UserProfile = ({ record }) => {
 ```
 
 You will find complete usage documentation for the data provider hooks in the [Querying the API](./Actions.md) documentation chapter.
+
+## Real-Time Updates And Locks
+
+Teams where several people work in parallel on a common task need to allow live updates, real-time notifications, and prevent data loss when two editors work on the same resource concurrently. 
+
+[`ra-realtime`](https://marmelab.com/ra-enterprise/modules/ra-realtime) (an [Enterprise Edition <img class="icon" src="./img/premium.svg" />](https://marmelab.com/ra-enterprise) module) provides hooks and UI components to lock records, and update views when the underlying data changes. It's based on the Publish / Subscribe (PubSub) pattern, and requires a backend supporting this pattern (like GraphQL, Mercure). 
+
+For instance, here is how to enable live updates on a List view:
+
+```diff
+import {
+-   List,
+    Datagrid,
+    TextField,
+    NumberField,
+    Datefield,
+} from 'react-admin';
++import { RealTimeList } from '@react-admin/ra-realtime';
+
+const PostList = props => (
+-   <List {...props}>
++   <RealTimeList {...props}>
+        <Datagrid>
+            <TextField source="title" />
+            <NumberField source="views" />
+            <DateField source="published_at" />
+        </Datagrid>
+-   </List>
++   </RealTimeList>
+);
+```
+
+Check [the `ra-realtime` documentation](https://marmelab.com/ra-enterprise/modules/ra-realtime) for more details.
+