Skip to content

Commit a52707f

Browse files
dunglasdunglas
authored
Add documentation for admin v1 beta (#872)
* Add documentation for admin v1 beta * Update admin/customize.md Co-Authored-By: Alan Poulain <[email protected]> * Update admin/customize.md Co-Authored-By: Alan Poulain <[email protected]> * Update admin/customize.md Co-Authored-By: Alan Poulain <[email protected]> * Update admin/customize.md Co-Authored-By: Alan Poulain <[email protected]> * Update admin/customize.md Co-Authored-By: Alan Poulain <[email protected]> * Update admin/index.md Co-Authored-By: Alan Poulain <[email protected]> * Update admin/schema.org.md Co-Authored-By: Alan Poulain <[email protected]> * Review
1 parent 3b5a6ad commit a52707f

File tree

8 files changed

+423
-1015
lines changed

8 files changed

+423
-1015
lines changed

‎admin/authentication-support.md‎

Lines changed: 1 addition & 103 deletions
Original file line numberDiff line numberDiff line change
@@ -1,107 +1,5 @@
11
# Authentication Support
22

3-
Authentication can easily be handled when using the API Platform's admin library.
4-
In the following section, we will assume [the API is secured using JWT](../core/jwt.md), but the
5-
process is similar for other authentication mechanisms. The `authenticationTokenUri` is the full URI to the path / route specified by the `firewalls.{name}.json_login.check_path` config in the [JWT documentation](../core/jwt.md).
6-
7-
The first step is to create a client to handle the authentication process:
8-
9-
```javascript
10-
// admin/src/authProvider.js
11-
import { AUTH_LOGIN, AUTH_LOGOUT, AUTH_ERROR, AUTH_CHECK } from 'react-admin';
12-
13-
// Change this to be your own authentication token URI.
14-
const authenticationTokenUri = `${process.env.REACT_APP_API_ENTRYPOINT}/authentication_token`;
15-
16-
export default (type, params) => {
17-
switch (type) {
18-
case AUTH_LOGIN:
19-
const { username, password } = params;
20-
const request = new Request(authenticationTokenUri, {
21-
method: 'POST',
22-
body: JSON.stringify({ email: username, password }),
23-
headers: new Headers({ 'Content-Type': 'application/json' }),
24-
});
25-
26-
return fetch(request)
27-
.then(response => {
28-
if (response.status < 200 || response.status >= 300) throw new Error(response.statusText);
29-
30-
return response.json();
31-
})
32-
.then(({ token }) => {
33-
localStorage.setItem('token', token); // The JWT token is stored in the browser's local storage
34-
window.location.replace('/');
35-
});
36-
37-
case AUTH_LOGOUT:
38-
localStorage.removeItem('token');
39-
break;
40-
41-
case AUTH_ERROR:
42-
if (401 === params.status || 403 === params.status) {
43-
localStorage.removeItem('token');
44-
45-
return Promise.reject();
46-
}
47-
break;
48-
49-
case AUTH_CHECK:
50-
return localStorage.getItem('token') ? Promise.resolve() : Promise.reject();
51-
52-
default:
53-
return Promise.resolve();
54-
}
55-
}
56-
```
57-
58-
Then, configure the `Admin` component to use the authentication client we just created:
59-
60-
```javascript
61-
import React from 'react';
62-
import parseHydraDocumentation from '@api-platform/api-doc-parser/lib/hydra/parseHydraDocumentation';
63-
import { HydraAdmin, hydraClient, fetchHydra as baseFetchHydra } from '@api-platform/admin';
64-
import authProvider from './authProvider';
65-
import { Route, Redirect } from 'react-router-dom';
66-
67-
const entrypoint = process.env.REACT_APP_API_ENTRYPOINT; // Change this by your own entrypoint if you're not using API Platform distribution
68-
const fetchHeaders = {'Authorization': `Bearer ${localStorage.getItem('token')}`};
69-
const fetchHydra = (url, options = {}) => baseFetchHydra(url, {
70-
...options,
71-
headers: new Headers(fetchHeaders),
72-
});
73-
const dataProvider = api => hydraClient(api, fetchHydra);
74-
const apiDocumentationParser = entrypoint =>
75-
parseHydraDocumentation(entrypoint, {
76-
headers: new Headers(fetchHeaders),
77-
}).then(
78-
({ api }) => ({ api }),
79-
result => {
80-
const { api, status } = result;
81-
82-
if (status === 401) {
83-
return Promise.resolve({
84-
api,
85-
status,
86-
customRoutes: [
87-
<Route path="/" render={() => <Redirect to="/login" />} />,
88-
],
89-
});
90-
}
91-
92-
return Promise.reject(result);
93-
}
94-
);
95-
96-
export default () => (
97-
<HydraAdmin
98-
apiDocumentationParser={apiDocumentationParser}
99-
authProvider={authProvider}
100-
entrypoint={entrypoint}
101-
dataProvider={dataProvider}
102-
/>
103-
);
104-
```
105-
3+
API Platform Admin delegates the authentication support to React Admin.
1064
Refer to [the chapter dedicated to authentication in the React Admin documentation](https://marmelab.com/react-admin/Authentication.html)
1075
for more information.

‎admin/customize.md‎

Lines changed: 188 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,188 @@
1+
# Customizing the Admin
2+
3+
Customizing API Platform Admin is easy and idiomatic. The tool gives you the ability to customize everything, from the list of resource types that must be administrable to every single inputs or buttons.
4+
5+
To do so, you can use the React components provided by API Platform Admin itself, [React Admin](https://marmelab.com/react-admin/), [Material UI](https://material-ui.com/), [community libraries](https://github.com/brillout/awesome-react-components), or [write your own](https://reactjs.org/tutorial/tutorial.html).
6+
7+
## Customizing the Admin's Main Page and the Resource List
8+
9+
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.
10+
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.
11+
Resources are listed in the order they appear in the machine-readable documentation.
12+
13+
However, it's also possible to display only specific resources, and to order them, while still benefiting of all discovery features provided by API Platform Admin.
14+
To cherry-pick the resources to make available through the admin, pass a list of `<ResourceGuesser>` components as children of the root component:
15+
16+
```javascript
17+
import React from "react";
18+
import { HydraAdmin, ResourceGuesser } from "@api-platform/admin";
19+
20+
export default () => (
21+
<HydraAdmin entrypoint="https://demo.api-platform.com">
22+
<ResourceGuesser name="books" />
23+
<ResourceGuesser name="reviews" />
24+
25+
{/* While deprecated resources are hidden by default, using an explicit ResourceGuesser component allows to add them back. */}
26+
<ResourceGuesser name="parchments" />
27+
</HydraAdmin>
28+
);
29+
```
30+
31+
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).
32+
33+
## Customizing the List View
34+
35+
The list view can be customized following the same pattern:
36+
37+
```javascript
38+
import React from "react";
39+
import {
40+
HydraAdmin,
41+
ResourceGuesser,
42+
ListGuesser,
43+
FieldGuesser
44+
} from "@api-platform/admin";
45+
46+
const ReviewsList = props => (
47+
<ListGuesser {...props}>
48+
<FieldGuesser source="author" />
49+
<FieldGuesser source="book" />
50+
51+
{/* While deprecated fields are hidden by default, using an explicit FieldGuesser component allows to add them back. */}
52+
<FieldGuesser source="letter" />
53+
</ListGuesser>
54+
);
55+
56+
export default () => (
57+
<HydraAdmin entrypoint="https://demo.api-platform.com">
58+
<ResourceGuesser name="reviews" list={ReviewsList} />
59+
{/* ... */}
60+
</HydraAdmin>
61+
);
62+
```
63+
64+
In this example, only the fields `author`, `book` and `letter` (that is hidden by default because it is deprecated) will be displayed. The defined order will be respected.
65+
66+
In addition to the `<FieldGuesser>` component, [all React Admin Fields components](https://marmelab.com/react-admin/Fields.html) can be passed as children of `<ListGuesser>`.
67+
68+
## Customizing the Show View
69+
70+
For the show view:
71+
72+
```javascript
73+
import React from "react";
74+
import {
75+
HydraAdmin,
76+
ResourceGuesser,
77+
ShowGuesser,
78+
FieldGuesser
79+
} from "@api-platform/admin";
80+
81+
const ReviewsShow = props => (
82+
<ShowGuesser {...props}>
83+
<FieldGuesser source="author" addLabel={true} />
84+
<FieldGuesser source="book" addLabel={true} />
85+
<FieldGuesser source="rating" addLabel={true} />
86+
87+
{/* While deprecated fields are hidden by default, using an explicit FieldGuesser component allows to add them back. */}
88+
<FieldGuesser source="letter" addLabel={true} />
89+
90+
<FieldGuesser source="body" addLabel={true} />
91+
<FieldGuesser source="publicationDate" addLabel={true} />
92+
</ShowGuesser>
93+
);
94+
95+
export default () => (
96+
<HydraAdmin entrypoint="https://demo.api-platform.com">
97+
<ResourceGuesser name="reviews" show={ReviewsShow} />
98+
{/* ... */}
99+
</HydraAdmin>
100+
);
101+
```
102+
103+
In addition to the `<FieldGuesser>` component, [all React Admin Fields components](https://marmelab.com/react-admin/Fields.html) can be passed as children of `<ShowGuesser>`.
104+
105+
## Customizing the Create Form
106+
107+
Again, the same logic applies to forms, here is how to customize the create form:
108+
109+
```javascript
110+
import React from "react";
111+
import {
112+
HydraAdmin,
113+
ResourceGuesser,
114+
CreateGuesser,
115+
InputGuesser
116+
} from "@api-platform/admin";
117+
118+
const ReviewsCreate = props => (
119+
<CreateGuesser {...props}>
120+
<InputGuesser source="author" />
121+
<InputGuesser source="book" />
122+
<InputGuesser source="rating" />
123+
124+
{/* While deprecated fields are hidden by default, using an explicit InputGuesser component allows to add them back. */}
125+
<InputGuesser source="letter" />
126+
127+
<InputGuesser source="body" />
128+
<InputGuesser source="publicationDate" />
129+
</CreateGuesser>
130+
);
131+
132+
export default () => (
133+
<HydraAdmin entrypoint="https://demo.api-platform.com">
134+
<ResourceGuesser name="reviews" create={ReviewsCreate} />
135+
{/* ... */}
136+
</HydraAdmin>
137+
);
138+
```
139+
140+
In addition to the `<InputGuesser>` component, [all React Admin Input components](https://marmelab.com/react-admin/Inputs.html) can be passed as children of `<CreateGuesser>`.
141+
142+
For instance, using an autocomplete input is straightforward, [check out the dedicated documentation entry](handling-relations-to-collections.md#using-an-autocomplete-input)!
143+
144+
## Customizing the Edit Form
145+
146+
Finally, you can customize the edit form the same way:
147+
148+
```javascript
149+
import React from "react";
150+
import {
151+
HydraAdmin,
152+
ResourceGuesser,
153+
EditGuesser,
154+
InputGuesser
155+
} from "@api-platform/admin";
156+
157+
const ReviewsEdit = props => (
158+
<EditGuesser {...props}>
159+
<InputGuesser source="author" />
160+
<InputGuesser source="book" />
161+
<InputGuesser source="rating" />
162+
163+
{/* While deprecated fields are hidden by default, using an explicit InputGuesser component allows to add them back. */}
164+
<InputGuesser source="letter" />
165+
166+
<InputGuesser source="body" />
167+
<InputGuesser source="publicationDate" />
168+
</EditGuesser>
169+
);
170+
171+
export default () => (
172+
<HydraAdmin entrypoint="https://demo.api-platform.com">
173+
<ResourceGuesser edit={ReviewsEdit}/>
174+
{/* ... */}
175+
</HydraAdmin>
176+
);
177+
```
178+
179+
In addition to the `<InputGuesser>` component, [all React Admin Input components](https://marmelab.com/react-admin/Inputs.html) can be passed as children of `<EditGuesser>`.
180+
181+
For instance, using an autocomplete input is straightforward, [checkout the dedicated documentation entry](handling-relations-to-collections.md#using-an-autocomplete-input)!
182+
183+
## Going Further
184+
185+
API Platform is built on top of [React Admin](https://marmelab.com/react-admin/).
186+
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.
187+
188+
To learn more about these capabilities, refer to [the React Admin documentation](https://marmelab.com/react-admin/).

0 commit comments

Comments
 (0)