From f66d0a8942b3bdf09ac419225330e20fb3f544ea Mon Sep 17 00:00:00 2001 From: Alan Poulain Date: Mon, 29 Nov 2021 18:03:14 +0100 Subject: [PATCH] feat(admin): add Mercure documentation --- admin/authentication-support.md | 12 +++-- admin/components.md | 62 ++++++++++++++---------- admin/customizing.md | 21 ++++----- admin/file-upload.md | 2 +- admin/getting-started.md | 3 +- admin/handling-relations.md | 83 +++++++++++++-------------------- admin/index.md | 1 + admin/performance.md | 20 +++----- admin/real-time-mercure.md | 43 +++++++++++++++++ outline.yaml | 1 + 10 files changed, 140 insertions(+), 108 deletions(-) create mode 100644 admin/real-time-mercure.md diff --git a/admin/authentication-support.md b/admin/authentication-support.md index 4ccad2e326a..b0bc344004c 100644 --- a/admin/authentication-support.md +++ b/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 () => ( ( ); ``` -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). diff --git a/admin/components.md b/admin/components.md index aa50937eabf..7d2ab4bf5df 100644 --- a/admin/components.md +++ b/admin/components.md @@ -4,11 +4,11 @@ ### AdminGuesser -`` renders automatically an [ 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 [ 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. +`` 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. -`` renders all exposed resources by default, but you can choose what resource you want to render by passing [ components](components.md#resourceguesser) as children. +`` 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 `` component. ```javascript @@ -45,7 +45,8 @@ export default App; ### ResourceGuesser -Based on React Admin [ component](https://marmelab.com/react-admin/Resource.html), `ResourceGuesser` provides default props [](components.md#createguesser), [](components.md#listguesser), [](components.md#editguesser) and [](components.md#showguesser). +Based on React Admin [Resource component](https://marmelab.com/react-admin/Resource.html), `` 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 [ 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 [](https://marmelab.com/react-admin/List.html), ListGuesser displays a list of resources in a [](https://marmelab.com/react-admin/List.html#the-datagrid-component), according to children passed to it (usually [](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), `` 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, `` comes with [](components.md#pagination). +By default, `` 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 [](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 [](https://marmelab.com/react-admin/CreateEdit.html) and [](https://marmelab.com/react-admin/CreateEdit.html#the-simpleform-component) components. -For simple inputs, you can pass as children API Platform Admin [](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 [](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 [](https://marmelab.com/react-admin/CreateEdit.html) and [](https://marmelab.com/react-admin/CreateEdit.html#the-simpleform-component) components. -For simple inputs, you can use API Platform Admin [](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 [](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 [ component](https://marmelab.com/react-admin/Show.html). You can pass [](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 [ 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 [``](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 [](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} > { /* ... */ } @@ -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 [ component](components.md#listguesser), the `Pagination` component uses React Admin [ 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 diff --git a/admin/customizing.md b/admin/customizing.md index f1c5ebe658b..02ad7aca961 100644 --- a/admin/customizing.md +++ b/admin/customizing.md @@ -6,7 +6,7 @@ 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 [`` 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. @@ -14,11 +14,10 @@ However, it's also possible to display only specific resources, and to order the To cherry-pick the resources to make available through the admin, pass a list of `` components as children of the root component: ```javascript -import React from "react"; import { HydraAdmin, ResourceGuesser } from "@api-platform/admin"; export default () => ( - + @@ -28,14 +27,13 @@ export default () => ( ); ``` -Instead of using the `` component provided by API Platform Admin, you can also pass custom React Admin's [`` components](https://marmelab.com/react-admin/Resource.html), or any other React components that are supported by React Admin's [``](https://marmelab.com/react-admin/Admin.html). +Instead of using the `` 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 () => ( - + {/* ... */} @@ -70,7 +68,6 @@ In addition to the `` 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 () => ( - + {/* ... */} @@ -107,7 +104,6 @@ In addition to the `` 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 () => ( - + {/* ... */} @@ -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 () => ( - + {/* ... */} @@ -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/). diff --git a/admin/file-upload.md b/admin/file-upload.md index bcc0c974001..379dedb4838 100644 --- a/admin/file-upload.md +++ b/admin/file-upload.md @@ -25,7 +25,7 @@ const MediaObjectsCreate = props => ( ); export default () => ( - + {/* ... */} diff --git a/admin/getting-started.md b/admin/getting-started.md index ffe3f51fe12..31c4b8a0b9a 100644 --- a/admin/getting-started.md +++ b/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 () => ( - + ); ``` diff --git a/admin/handling-relations.md b/admin/handling-relations.md index 9946bbf9129..acd13912d6f 100644 --- a/admin/handling-relations.md +++ b/admin/handling-relations.md @@ -16,23 +16,23 @@ you can keep the embedded data by setting the `useEmbedded` parameter of the Hyd ```javascript // admin/src/App.js -import React from "react"; import { HydraAdmin, fetchHydra, hydraDataProvider } from "@api-platform/admin"; import { parseHydraDocumentation } from "@api-platform/api-doc-parser"; const entrypoint = process.env.REACT_APP_API_ENTRYPOINT; -const dataProvider = hydraDataProvider( +const dataProvider = hydraDataProvider({ entrypoint, - fetchHydra, - parseHydraDocumentation, - true // useEmbedded parameter -); + httpClient: fetchHydra, + apiDocumentationParser: parseHydraDocumentation, + mercure: true, + useEmbedded: true, +}); export default () => ( ); ``` @@ -79,7 +79,6 @@ For instance, if your API returns: If you want to display the author first name in the list, you need to write the following code: ```javascript -import React from "react"; import { HydraAdmin, FieldGuesser, @@ -99,7 +98,7 @@ const BooksList = (props) => ( ); export default () => ( - + ( If the `useEmbedded` parameter is set to `true` (will be the default behavior in 3.0), you need to use the dot notation to display a field: ```javascript -import React from "react"; import { HydraAdmin, FieldGuesser, @@ -130,7 +128,7 @@ const BooksList = (props) => ( ); export default () => ( - + ( ); export default () => ( - + ( ); export default () => ( - + ` component: + +```javascript +import { HydraAdmin } from "@api-platform/admin"; + +export default () => ( + +); +``` + +Or in the data provider factory: + +```javascript +import { hydraDataProvider, fetchHydra } from "@api-platform/admin"; +import { parseHydraDocumentation } from "@api-platform/api-doc-parser"; + +const dataProvider = baseHydraDataProvider({ + entrypoint, + httpClient: fetchHydra, + apiDocumentationParser: parseHydraDocumentation, + mercure: true, +}); +``` + +If you want to disable Mercure, use `false` for the `mercure` value instead. + +## Advanced Configuration + +The `mercure` value can also takes an object to customize the default configuration. + +The object has the following properties: +- `hub`: the URL to your Mercure hub (default value: entrypoint/.well-known/mercure) +- `jwt`: a subscriber JWT to access your Mercure hub (default value: null) +- `topicUrl`: the topic URL of your resources (default value: entrypoint) diff --git a/outline.yaml b/outline.yaml index 81fb5eff228..e1f333a984f 100644 --- a/outline.yaml +++ b/outline.yaml @@ -67,6 +67,7 @@ chapters: - handling-relations - schema.org - validation + - real-time-mercure - authentication-support - file-upload - performance