feat(admin): add Mercure documentation (#1479)

Author: alanpoulain

admin/authentication-support.md

@@ -4,12 +4,11 @@ API Platform Admin delegates the authentication support to React Admin.
 Refer to [the chapter dedicated to authentication in the React Admin documentation](https://marmelab.com/react-admin/Authentication.html)
 for more information.
 
-In short, you have to tweak data provider and api documentation parser, like this:
+In short, you have to tweak the data provider and the api documentation parser like this:
 
 ```javascript
 // admin/src/App.js
 
-import React from "react";
 import { Redirect, Route } from "react-router-dom";
 import { HydraAdmin, hydraDataProvider as baseHydraDataProvider, fetchHydra as baseFetchHydra, useIntrospection } from "@api-platform/admin";
 import parseHydraDocumentation from "@api-platform/api-doc-parser/lib/hydra/parseHydraDocumentation";
@@ -53,7 +52,12 @@ const apiDocumentationParser = async (entrypoint) => {
     throw result;
   }
 };
-const dataProvider = baseHydraDataProvider(entrypoint, fetchHydra, apiDocumentationParser);
+const dataProvider = baseHydraDataProvider({
+  entrypoint,
+  httpClient: fetchHydra,
+  apiDocumentationParser,
+  mercure: true, // or false if you don't use Mercure
+});
 
 export default () => (
   <HydraAdmin
@@ -64,4 +68,4 @@ export default () => (
 );
 ```
 
-For the implementation of the auth provider, you can find a working example in the [API Platform's demo application](https://github.com/api-platform/demo/blob/master/admin/src/authProvider.js).
+For the implementation of the auth provider, you can find a working example in the [API Platform's demo application](https://github.com/api-platform/demo/blob/main/pwa/utils/authProvider.tsx).

admin/components.md

@@ -4,11 +4,11 @@
 
 ### AdminGuesser
 
-`<AdminGuesser>` renders automatically an [<Admin> component](https://marmelab.com/react-admin/Admin.html) for resources exposed by a web API documented with any format supported by `@api-platform/api-doc-parser` (for Hydra documented APIs,
-use the [<HydraAdmin> component](components.md#hydraadmin) instead).
-It also creates a [schema analyzer](components.md#schemaanalyzer) context, where the `schemaAnalyzer` service (for getting information about the provided API documentation) is stored.
+`<AdminGuesser>` renders automatically an [Admin component](https://marmelab.com/react-admin/Admin.html) for resources exposed by a web API documented with any format supported by `@api-platform/api-doc-parser` (for Hydra documented APIs,
+use the [HydraAdmin component](components.md#hydraadmin) instead).
+It also creates a [schema analyzer](components.md#schema-analyzer) context, where the `schemaAnalyzer` service (for getting information about the provided API documentation) is stored.
 
-`<AdminGuesser>` renders all exposed resources by default, but you can choose what resource you want to render by passing [<ResourceGuesser> components](components.md#resourceguesser) as children.
+`<AdminGuesser>` renders all exposed resources by default, but you can choose what resource you want to render by passing [ResourceGuesser components](components.md#resourceguesser) as children.
 Deprecated resources are hidden by default, but you can add them back using an explicit `<ResourceGuesser>` component.
 
 ```javascript
@@ -45,7 +45,8 @@ export default App;
 
 ### ResourceGuesser
 
-Based on React Admin [<Resource> component](https://marmelab.com/react-admin/Resource.html), `ResourceGuesser` provides default props [<CreateGuesser>](components.md#createguesser), [<ListGuesser>](components.md#listguesser), [<EditGuesser>](components.md#editguesser) and [<ShowGuesser>](components.md#showguesser).
+Based on React Admin [Resource component](https://marmelab.com/react-admin/Resource.html), `<ResourceGuesser>` provides default props [CreateGuesser](components.md#createguesser), [ListGuesser](components.md#listguesser), [EditGuesser](components.md#editguesser) and [ShowGuesser](components.md#showguesser).
+
 Otherwise, you can pass it your own CRUD components using `create`, `list`, `edit`, `show` props.
 
 ```javascript
@@ -77,18 +78,18 @@ export default App;
 |------|--------|-------|----------|--------------------------|
 | name | string | -     | yes      | endpoint of the resource |
 
-You can also use props accepted by React Admin [<Resource> component](https://marmelab.com/react-admin/Resource.html). For example, the props `list`, `show`, `create` or `edit`.
+You can also use props accepted by React Admin [Resource component](https://marmelab.com/react-admin/Resource.html). For example, the props `list`, `show`, `create` or `edit`.
 
 ## Page Components
 
 ### ListGuesser
 
-Based on React Admin [<List>](https://marmelab.com/react-admin/List.html), ListGuesser displays a list of resources in a [<Datagrid>](https://marmelab.com/react-admin/List.html#the-datagrid-component), according to children passed to it (usually [<FieldGuesser>](components.md#fieldguesser) or any [field component](https://marmelab.com/react-admin/Fields.html#basic-fields)
+Based on React Admin [List](https://marmelab.com/react-admin/List.html), `<ListGuesser>` displays a list of resources in a [Datagrid](https://marmelab.com/react-admin/List.html#the-datagrid-component), according to children passed to it (usually [FieldGuesser](components.md#fieldguesser) or any [field component](https://marmelab.com/react-admin/Fields.html#basic-fields)
 available in React Admin).
 
 Use `hasShow` and `hasEdit` props if you want to display `show` and `edit` buttons (both set to `true` by default).
 
-By default, `<ListGuesser>` comes with [<Pagination>](components.md#pagination).
+By default, `<ListGuesser>` comes with [Pagination](components.md#pagination).
 
 ```javascript
 // BooksList.js
@@ -114,12 +115,12 @@ export const BooksList = props => (
 | resource | string           | -     | yes      | endpoint of the resource                |
 | filters  | element          | -     | no       | filters that can be applied to the list |
 
-You can also use props accepted by React Admin [<List>](https://marmelab.com/react-admin/List.html).
+You can also use props accepted by React Admin [List](https://marmelab.com/react-admin/List.html).
 
 ### CreateGuesser
 
-Displays a creation page for a single item. Uses React Admin [<Create>](https://marmelab.com/react-admin/CreateEdit.html) and [<SimpleForm>](https://marmelab.com/react-admin/CreateEdit.html#the-simpleform-component) components.
-For simple inputs, you can pass as children API Platform Admin [<InputGuesser>](components.md#inputguesser), or any React Admin [Input components](https://marmelab.com/react-admin/Inputs.html#input-components) for more complex inputs.
+Displays a creation page for a single item. Uses React Admin [Create](https://marmelab.com/react-admin/CreateEdit.html) and [SimpleForm](https://marmelab.com/react-admin/CreateEdit.html#the-simpleform-component) components.
+For simple inputs, you can pass as children API Platform Admin [InputGuesser](components.md#inputguesser), or any React Admin [Input components](https://marmelab.com/react-admin/Inputs.html#input-components) for more complex inputs.
 
 ```javascript
 // BooksCreate.js
@@ -143,12 +144,12 @@ export const BooksCreate = props => (
 | children | node or function | -     | no       | -                        |
 | resource | string           | -     | yes      | endpoint of the resource |
 
-You can also use props accepted by React Admin [<Create>](https://marmelab.com/react-admin/CreateEdit.html).
+You can also use props accepted by React Admin [Create](https://marmelab.com/react-admin/CreateEdit.html).
 
 ### EditGuesser
 
-Displays an edition page for a single item. Uses React Admin [<Edit>](https://marmelab.com/react-admin/CreateEdit.html) and [<SimpleForm>](https://marmelab.com/react-admin/CreateEdit.html#the-simpleform-component) components.
-For simple inputs, you can use API Platform Admin [<InputGuesser>](components.md#inputguesser), or any React Admin [Input components](https://marmelab.com/react-admin/Inputs.html#input-components) for more complex inputs.
+Displays an edition page for a single item. Uses React Admin [Edit](https://marmelab.com/react-admin/CreateEdit.html) and [SimpleForm](https://marmelab.com/react-admin/CreateEdit.html#the-simpleform-component) components.
+For simple inputs, you can use API Platform Admin [InputGuesser](components.md#inputguesser), or any React Admin [Input components](https://marmelab.com/react-admin/Inputs.html#input-components) for more complex inputs.
 
 ```javascript
 // BooksEdit.js
@@ -172,11 +173,11 @@ export const BooksEdit = props => (
 | children | node or function | -     | no       | -                        |
 | resource | string           | -     | yes      | endpoint of the resource |
 
-You can also use props accepted by React Admin [<Edit>](https://marmelab.com/react-admin/CreateEdit.html).
+You can also use props accepted by React Admin [Edit](https://marmelab.com/react-admin/CreateEdit.html).
 
 ### ShowGuesser
 
-Displays a detailed page for one item. Based on React Admin [<Show> component](https://marmelab.com/react-admin/Show.html). You can pass [<FieldGuesser>](components.md#fieldguesser) as children for simple fields, or use any of React Admin [basic fields](https://marmelab.com/react-admin/Fields.html#basic-fields) for more complex fields.
+Displays a detailed page for one item. Based on React Admin [Show component](https://marmelab.com/react-admin/Show.html). You can pass [FieldGuesser](components.md#fieldguesser) as children for simple fields, or use any of React Admin [basic fields](https://marmelab.com/react-admin/Fields.html#basic-fields) for more complex fields.
 
 ```javascript
 // BooksShow.js
@@ -200,13 +201,14 @@ export const BooksShow = props => (
 | children | node or function | -     | no       | -                        |
 | resource | string           | -     | yes      | endpoint of the resource |
 
-You can also use props accepted by React Admin [<Show> component](https://marmelab.com/react-admin/Show.html).
+You can also use props accepted by React Admin [Show component](https://marmelab.com/react-admin/Show.html).
 
 ## Hydra
 
 ### HydraAdmin
 
-Creates a complete Admin, as [`<AdminGuesser>`](components.md#adminguesser), but configured specially for [Hydra](https://www.hydra-cg.com/). If you want to use other formats (see supported formats: `@api-platform/api-doc-parser`) use [<AdminGuesser>](components.md#adminguesser) instead.
+Creates a complete Admin, as [AdminGuesser](components.md#adminguesser), but configured specially for [Hydra](https://www.hydra-cg.com/).
+If you want to use other formats (see supported formats: `@api-platform/api-doc-parser`) use [AdminGuesser](components.md#adminguesser) instead.
 
 ```javascript
 // App.js
@@ -217,6 +219,7 @@ const App = () => (
     entrypoint={entrypoint}
     dataProvider={dataProvider}
     authProvider={authProvider}
+    mercure={true}
    >
      <ResourceGuesser name="books" />
      { /* ... */ }
@@ -228,13 +231,20 @@ export default App;
 
 #### HydraAdmin Props
 
-| Name       | Type   | Value | required | Description           |
-|------------|--------|-------|----------|-----------------------|
-| entrypoint | string | -     | yes      | entrypoint of the API |
+| Name       | Type           | Value | required | Description                  |
+|------------|----------------|-------|----------|------------------------------|
+| entrypoint | string         | -     | yes      | entrypoint of the API        |
+| mercure    | boolean|object | *     | yes      | configuration to use Mercure |
+
+\* `false` to explicitly disable, `true` to enable with default parameters or an object with the following properties:
+- `hub`: the URL to your Mercure hub
+- `jwt`: a subscriber JWT to access your Mercure hub
+- `topicUrl`: the topic URL of your resources
 
 ### Data Provider
 
-Based on React Admin `create`, `delete`, `getList`, `getManyReference`, `getOne`, `update` methods, the `dataProvider` is used by API Platform Admin to communicate with the API. In addition, the specific `introspect` method parses your API documentation.
+Based on React Admin `create`, `delete`, `getList`, `getManyReference`, `getOne`, `update` methods, the `dataProvider` is used by API Platform Admin to communicate with the API.
+In addition, the specific `introspect` method parses your API documentation.
 Note that the `dataProvider` can be overridden to fit your API needs.
 
 ### Schema Analyzer
@@ -245,13 +255,15 @@ Analyses your resources and retrieves their types according to the [Schema.org](
 
 ### Pagination
 
-Set by default in the [<ListGuesser> component](components.md#listguesser), the `Pagination` component uses React Admin [<Pagination> component](https://marmelab.com/react-admin/List.html#pagination).
-By default, it renders 30 items per page and displays a navigation UI. If you want to change the number of items per page or disable the pagination, see the [Pagination documentation](../core/pagination.md).
+Set by default in the [ListGuesser component](components.md#listguesser), the `Pagination` component uses React Admin [Pagination component](https://marmelab.com/react-admin/List.html#pagination).
+By default, it renders 30 items per page and displays a navigation UI.
+If you want to change the number of items per page or disable the pagination, see the [Pagination documentation](../core/pagination.md).
 It is also capable to handle partial pagination.
 
 ### FieldGuesser
 
-Renders fields according to their types, using the [schema analyzer](components.md#schemaanalyzer). Based on React Admin [field components](https://marmelab.com/react-admin/Fields.html).
+Renders fields according to their types, using the [schema analyzer](components.md#schemaanalyzer).
+Based on React Admin [field components](https://marmelab.com/react-admin/Fields.html).
 
 ```javascript
 // BooksShow.js

admin/customizing.md

@@ -6,19 +6,18 @@ To do so, you can use the React components provided by API Platform Admin itself
 
 ## Customizing the Admin's Main Page and the Resource List
 
-By default, API Platform Admin automatically builds a tailored [`<Resource>` component](https://marmelab.com/react-admin/Resource.html) (and all its appropriate children) for each resource type exposed by a web API.
+By default, API Platform Admin automatically builds a tailored [Resource component](https://marmelab.com/react-admin/Resource.html) (and all its appropriate children) for each resource type exposed by a web API.
 Under the hood it uses the `@api-platform/api-doc-parser` library to parse the API documentation. The API documentation can use Hydra, OpenAPI and any other format supported by the library.
 Resources are listed in the order they appear in the machine-readable documentation.
 
 However, it's also possible to display only specific resources, and to order them, while still benefiting from all discovery features provided by API Platform Admin.
 To cherry-pick the resources to make available through the admin, pass a list of `<ResourceGuesser>` components as children of the root component:
 
 ```javascript
-import React from "react";
 import { HydraAdmin, ResourceGuesser } from "@api-platform/admin";
 
 export default () => (
-  <HydraAdmin entrypoint="https://demo.api-platform.com">
+  <HydraAdmin entrypoint="https://demo.api-platform.com" mercure={true}>
     <ResourceGuesser name="books" />
     <ResourceGuesser name="reviews" />
 
@@ -28,14 +27,13 @@ export default () => (
 );
 ```
 
-Instead of using the `<ResourceGuesser>` component provided by API Platform Admin, you can also pass custom React Admin's [`<Resource>` components](https://marmelab.com/react-admin/Resource.html), or any other React components that are supported by React Admin's [`<Admin>`](https://marmelab.com/react-admin/Admin.html).
+Instead of using the `<ResourceGuesser>` component provided by API Platform Admin, you can also pass custom React Admin's [Resource components](https://marmelab.com/react-admin/Resource.html), or any other React components that are supported by React Admin's [Admin](https://marmelab.com/react-admin/Admin.html).
 
 ## Customizing the List View
 
 The list view can be customized following the same pattern:
 
 ```javascript
-import React from "react";
 import {
   HydraAdmin,
   ResourceGuesser,
@@ -54,7 +52,7 @@ const ReviewsList = props => (
 );
 
 export default () => (
-  <HydraAdmin entrypoint="https://demo.api-platform.com">
+  <HydraAdmin entrypoint="https://demo.api-platform.com" mercure={true}>
     <ResourceGuesser name="reviews" list={ReviewsList} />
     {/* ... */}
   </HydraAdmin>
@@ -70,7 +68,6 @@ In addition to the `<FieldGuesser>` component, [all React Admin Fields component
 For the show view:
 
 ```javascript
-import React from "react";
 import {
   HydraAdmin,
   ResourceGuesser,
@@ -93,7 +90,7 @@ const ReviewsShow = props => (
 );
 
 export default () => (
-  <HydraAdmin entrypoint="https://demo.api-platform.com">
+  <HydraAdmin entrypoint="https://demo.api-platform.com" mercure={true}>
     <ResourceGuesser name="reviews" show={ReviewsShow} />
     {/* ... */}
   </HydraAdmin>
@@ -107,7 +104,6 @@ In addition to the `<FieldGuesser>` component, [all React Admin Fields component
 Again, the same logic applies to forms. Here is how to customize the create form:
 
 ```javascript
-import React from "react";
 import {
   HydraAdmin,
   ResourceGuesser,
@@ -130,7 +126,7 @@ const ReviewsCreate = props => (
 );
 
 export default () => (
-  <HydraAdmin entrypoint="https://demo.api-platform.com">
+  <HydraAdmin entrypoint="https://demo.api-platform.com" mercure={true}>
     <ResourceGuesser name="reviews" create={ReviewsCreate} />
     {/* ... */}
   </HydraAdmin>
@@ -146,7 +142,6 @@ For instance, using an autocomplete input is straightforward, [check out the ded
 Finally, you can customize the edit form the same way:
 
 ```javascript
-import React from "react";
 import {
   HydraAdmin,
   ResourceGuesser,
@@ -169,7 +164,7 @@ const ReviewsEdit = props => (
 );
 
 export default () => (
-  <HydraAdmin entrypoint="https://demo.api-platform.com">
+  <HydraAdmin entrypoint="https://demo.api-platform.com" mercure={true}>
     <ResourceGuesser edit={ReviewsEdit}/>
     {/* ... */}
   </HydraAdmin>
@@ -183,6 +178,6 @@ For instance, using an autocomplete input is straightforward, [checkout the dedi
 ## Going Further
 
 API Platform is built on top of [React Admin](https://marmelab.com/react-admin/).
-You can use all the features provided by the underlying library with API Platform Admin, including support for [file upload](https://marmelab.com/react-admin/DataProviders.html#decorating-your-data-provider-example-of-file-upload), [authentication](https://marmelab.com/react-admin/Authentication.html), [authorization](https://marmelab.com/react-admin/Authorization.html) and deeper customization.
+You can use all the features provided by the underlying library with API Platform Admin, including support for [authentication](https://marmelab.com/react-admin/Authentication.html), [authorization](https://marmelab.com/react-admin/Authorization.html) and deeper customization.
 
 To learn more about these capabilities, refer to [the React Admin documentation](https://marmelab.com/react-admin/).

admin/file-upload.md

@@ -25,7 +25,7 @@ const MediaObjectsCreate = props => (
 );
 
 export default () => (
-  <HydraAdmin entrypoint="https://demo.api-platform.com">
+  <HydraAdmin entrypoint="https://demo.api-platform.com" mercure={true}>
     <ResourceGuesser name="media_objects" create={MediaObjectsCreate} />
     {/* ... */}
   </HydraAdmin>

admin/getting-started.md

@@ -30,13 +30,12 @@ To initialize API Platform Admin, register it in your application.
 For instance, if you used Create React App, replace the content of `src/App.js` by:
 
 ```javascript
-import React from "react";
 import { HydraAdmin } from "@api-platform/admin";
 
 // Replace with your own API entrypoint
 // For instance if https://example.com/api/books is the path to the collection of book resources, then the entrypoint is https://example.com/api
 export default () => (
-  <HydraAdmin entrypoint="https://demo.api-platform.com" />
+  <HydraAdmin entrypoint="https://demo.api-platform.com" mercure={true} />
 );
 ```