Skip to content

feat(admin): add Mercure documentation #1479

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
merged 1 commit into from
Nov 29, 2021
Merged

feat(admin): add Mercure documentation #1479

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
12 changes: 8 additions & 4 deletions admin/authentication-support.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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";
Expand Down Expand Up @@ -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
Expand All @@ -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).
62 changes: 37 additions & 25 deletions admin/components.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand Down Expand Up @@ -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
Expand Down Expand Up @@ -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
Expand All @@ -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
Expand All @@ -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
Expand All @@ -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
Expand All @@ -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
Expand All @@ -217,6 +219,7 @@ const App = () => (
entrypoint={entrypoint}
dataProvider={dataProvider}
authProvider={authProvider}
mercure={true}
>
<ResourceGuesser name="books" />
{ /* ... */ }
Expand All @@ -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
Expand All @@ -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
Expand Down
21 changes: 8 additions & 13 deletions admin/customizing.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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" />

Expand All @@ -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,
Expand All @@ -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>
Expand All @@ -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,
Expand All @@ -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>
Expand All @@ -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,
Expand All @@ -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>
Expand All @@ -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,
Expand All @@ -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>
Expand All @@ -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/).
2 changes: 1 addition & 1 deletion admin/file-upload.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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>
Expand Down
3 changes: 1 addition & 2 deletions admin/getting-started.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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} />
);
```

Expand Down
Loading