Skip to content

Commit 43a8a10

Browse files
alanpoulainalanpoulain
authored
feat: documentation for admin 3.0 (#1526)
1 parent 8192b40 commit 43a8a10

File tree

5 files changed

+95
-94
lines changed

5 files changed

+95
-94
lines changed

‎admin/authentication-support.md

Lines changed: 28 additions & 25 deletions
Original file line numberDiff line numberDiff line change
@@ -7,12 +7,15 @@ for more information.
77
In short, you have to tweak the data provider and the API documentation parser like this:
88

99
```typescript
10-
// pwa/pages/admin/index.tsx
10+
// components/admin/Admin.tsx
1111

1212
import Head from "next/head";
13-
import { Redirect, Route } from "react-router-dom";
13+
import { useState } from "react";
14+
import { Navigate, Route } from "react-router-dom";
15+
import { CustomRoutes } from "react-admin";
1416
import {
1517
fetchHydra as baseFetchHydra,
18+
HydraAdmin,
1619
hydraDataProvider as baseHydraDataProvider,
1720
useIntrospection,
1821
} from "@api-platform/admin";
@@ -35,10 +38,12 @@ const RedirectToLogin = () => {
3538
introspect();
3639
return <></>;
3740
}
38-
return <Redirect to="/login" />;
41+
return <Navigate to="/login" />;
3942
};
40-
const apiDocumentationParser = async () => {
43+
const apiDocumentationParser = (setRedirectToLogin) => async () => {
4144
try {
45+
setRedirectToLogin(false);
46+
4247
return await parseHydraDocumentation(ENTRYPOINT, { headers: getHeaders });
4348
} catch (result) {
4449
const { api, response, status } = result;
@@ -49,40 +54,38 @@ const apiDocumentationParser = async () => {
4954
// Prevent infinite loop if the token is expired
5055
localStorage.removeItem("token");
5156

57+
setRedirectToLogin(true);
58+
5259
return {
5360
api,
5461
response,
5562
status,
56-
customRoutes: [
57-
<Route key="/" path="/" component={RedirectToLogin} />
58-
],
5963
};
6064
}
6165
};
62-
const dataProvider = baseHydraDataProvider({
66+
const dataProvider = (setRedirectToLogin) => baseHydraDataProvider({
6367
entrypoint: ENTRYPOINT,
6468
httpClient: fetchHydra,
65-
apiDocumentationParser,
69+
apiDocumentationParser: apiDocumentationParser(setRedirectToLogin),
6670
});
6771

68-
const AdminLoader = () => {
69-
if (typeof window !== "undefined") {
70-
const { HydraAdmin } = require("@api-platform/admin");
71-
return <HydraAdmin dataProvider={dataProvider} authProvider={authProvider} entrypoint={window.origin} />;
72-
}
73-
74-
return <></>;
75-
};
72+
const Admin = () => {
73+
const [redirectToLogin, setRedirectToLogin] = useState(false);
7674

77-
const Admin = () => (
78-
<>
79-
<Head>
80-
<title>API Platform Admin</title>
81-
</Head>
75+
return (
76+
<>
77+
<Head>
78+
<title>API Platform Admin</title>
79+
</Head>
8280

83-
<AdminLoader />
84-
</>
85-
);
81+
<HydraAdmin dataProvider={dataProvider(setRedirectToLogin)} authProvider={authProvider} entrypoint={window.origin}>
82+
<CustomRoutes>
83+
{redirectToLogin ? <Route path="/" element={<RedirectToLogin />} /> : null}
84+
</CustomRoutes>
85+
</HydraAdmin>
86+
</>
87+
);
88+
}
8689
export default Admin;
8790
```
8891

‎admin/components.md

Lines changed: 0 additions & 7 deletions
Original file line numberDiff line numberDiff line change
@@ -252,13 +252,6 @@ Analyses your resources and retrieves their types according to the [Schema.org](
252252

253253
## Other Components
254254

255-
### Pagination
256-
257-
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).
258-
By default, it renders 30 items per page and displays a navigation UI.
259-
If you want to change the number of items per page or disable the pagination, see the [Pagination documentation](../core/pagination.md).
260-
It is also capable to handle partial pagination.
261-
262255
### FieldGuesser
263256

264257
Renders fields according to their types, using the [schema analyzer](components.md#schemaanalyzer).

‎admin/customizing.md

Lines changed: 6 additions & 6 deletions
Original file line numberDiff line numberDiff line change
@@ -77,15 +77,15 @@ import {
7777

7878
const ReviewsShow = props => (
7979
<ShowGuesser {...props}>
80-
<FieldGuesser source="author" addLabel={true} />
81-
<FieldGuesser source="book" addLabel={true} />
82-
<FieldGuesser source="rating" addLabel={true} />
80+
<FieldGuesser source="author" />
81+
<FieldGuesser source="book" />
82+
<FieldGuesser source="rating" />
8383

8484
{/* While deprecated fields are hidden by default, using an explicit FieldGuesser component allows to add them back. */}
85-
<FieldGuesser source="letter" addLabel={true} />
85+
<FieldGuesser source="letter" />
8686

87-
<FieldGuesser source="body" addLabel={true} />
88-
<FieldGuesser source="publicationDate" addLabel={true} />
87+
<FieldGuesser source="body" />
88+
<FieldGuesser source="publicationDate" />
8989
</ShowGuesser>
9090
);
9191

‎admin/handling-relations.md

Lines changed: 60 additions & 55 deletions
Original file line numberDiff line numberDiff line change
@@ -6,12 +6,14 @@ Thanks to [the Schema.org support](schema.org.md), you can easily display the na
66

77
## Embedded Relations
88

9-
If a relation is an array of [embeddeds or an embedded](../core/serialization.md#embedding-relations) resource,
10-
by default, the admin automatically replaces the embedded resources' data by their IRI.
11-
However, the embedded data is inserted to a local cache: it will not be necessary to make more requests if you reference some fields of the embedded resource later on.
9+
If a relation is an array of [embeddeds or an embedded](../core/serialization.md#embedding-relations) resource, the admin will keep them by default.
1210

13-
If you need to edit the embedded data or if you want to display some of the nested fields by using the dot notation for complex structures,
14-
you can keep the embedded data by setting the `useEmbedded` parameter of the Hydra data provider to `true`.
11+
The embedded data will be displayed as text field and editable as text input: the admin cannot determine the fields present in it.
12+
To display the fields you want, see [this section](handling-relations.md#display-a-field-of-an-embedded-relation).
13+
14+
You can also ask the admin to automatically replace the embedded resources' data by their IRI,
15+
by setting the `useEmbedded` parameter of the Hydra data provider to `false`.
16+
Embedded data is inserted to a local cache: it will not be necessary to make more requests if you reference some fields of the embedded resource later on.
1517

1618
```javascript
1719
// admin/src/App.js
@@ -26,7 +28,7 @@ const dataProvider = hydraDataProvider({
2628
httpClient: fetchHydra,
2729
apiDocumentationParser: parseHydraDocumentation,
2830
mercure: true,
29-
useEmbedded: true,
31+
useEmbedded: false,
3032
});
3133

3234
export default () => (
@@ -37,16 +39,40 @@ export default () => (
3739
);
3840
```
3941

40-
The embedded data will be displayed as text field and editable as text input: the admin cannot determine the fields present in it.
41-
To display the fields you want, see [this section](handling-relations.md#display-a-field-of-an-embedded-relation).
42-
43-
This behavior will be the default one in 3.0.
44-
4542
## Display a Field of an Embedded Relation
4643

4744
If you have an [embedded relation](../core/serialization.md#embedding-relations) and need to display a nested field, the code you need to write depends of the value of `useEmbedded` of the Hydra data provider.
4845

49-
If `false` (default behavior), make sure you write the code as if the relation needs to be fetched as a reference.
46+
If `true` (default behavior), you need to use the dot notation to display a field:
47+
48+
```javascript
49+
import {
50+
HydraAdmin,
51+
FieldGuesser,
52+
ListGuesser,
53+
ResourceGuesser
54+
} from "@api-platform/admin";
55+
import { TextField } from "react-admin";
56+
57+
const BooksList = (props) => (
58+
<ListGuesser {...props}>
59+
<FieldGuesser source="title" />
60+
{/* Use react-admin components directly when you want complex fields. */}
61+
<TextField label="Author first name" source="author.firstName" />
62+
</ListGuesser>
63+
);
64+
65+
export default () => (
66+
<HydraAdmin entrypoint={process.env.REACT_APP_API_ENTRYPOINT}>
67+
<ResourceGuesser
68+
name="books"
69+
list={BooksList}
70+
/>
71+
</HydraAdmin>
72+
);
73+
```
74+
75+
If `useEmbedded` is explicitly set to `false`, make sure you write the code as if the relation needs to be fetched as a reference.
5076

5177
In this case, you *cannot* use the dot separator to do so.
5278

@@ -108,35 +134,6 @@ export default () => (
108134
);
109135
```
110136

111-
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:
112-
113-
```javascript
114-
import {
115-
HydraAdmin,
116-
FieldGuesser,
117-
ListGuesser,
118-
ResourceGuesser
119-
} from "@api-platform/admin";
120-
import { TextField } from "react-admin";
121-
122-
const BooksList = (props) => (
123-
<ListGuesser {...props}>
124-
<FieldGuesser source="title" />
125-
{/* Use react-admin components directly when you want complex fields. */}
126-
<TextField label="Author first name" source="author.firstName" />
127-
</ListGuesser>
128-
);
129-
130-
export default () => (
131-
<HydraAdmin entrypoint={process.env.REACT_APP_API_ENTRYPOINT}>
132-
<ResourceGuesser
133-
name="books"
134-
list={BooksList}
135-
/>
136-
</HydraAdmin>
137-
);
138-
```
139-
140137
## Using an Autocomplete Input for Relations
141138

142139
Let's go one step further thanks to the [customization capabilities](customizing.md) of API Platform Admin by adding autocompletion support to form inputs for relations.
@@ -218,10 +215,12 @@ const ReviewsCreate = props => (
218215
<ReferenceInput
219216
source="book"
220217
reference="books"
221-
label="Books"
222-
filterToQuery={searchText => ({ title: searchText })}
223218
>
224-
<AutocompleteInput optionText="title" />
219+
<AutocompleteInput
220+
filterToQuery={searchText => ({ title: searchText })}
221+
optionText="title"
222+
label="Books"
223+
/>
225224
</ReferenceInput>
226225

227226
<InputGuesser source="rating" />
@@ -237,10 +236,12 @@ const ReviewsEdit = props => (
237236
<ReferenceInput
238237
source="book"
239238
reference="books"
240-
label="Books"
241-
filterToQuery={searchText => ({ title: searchText })}
242239
>
243-
<AutocompleteInput optionText="title" />
240+
<AutocompleteInput
241+
filterToQuery={searchText => ({ title: searchText })}
242+
optionText="title"
243+
label="Books"
244+
/>
244245
</ReferenceInput>
245246

246247
<InputGuesser source="rating" />
@@ -260,7 +261,7 @@ export default () => (
260261
);
261262
```
262263

263-
If the book is embedded into a review and if the `useEmbedded` parameter is set to `true` (will be the default behavior in 3.0),
264+
If the book is embedded into a review and if the `useEmbedded` parameter is `true` (default behavior),
264265
you need to change the `ReferenceInput` for the edit component:
265266

266267
```javascript
@@ -279,10 +280,12 @@ const ReviewsCreate = props => (
279280
<ReferenceInput
280281
source="book"
281282
reference="books"
282-
label="Books"
283-
filterToQuery={searchText => ({ title: searchText })}
284283
>
285-
<AutocompleteInput optionText="title" />
284+
<AutocompleteInput
285+
filterToQuery={searchText => ({ title: searchText })}
286+
optionText="title"
287+
label="Books"
288+
/>
286289
</ReferenceInput>
287290

288291
<InputGuesser source="rating" />
@@ -298,11 +301,13 @@ const ReviewsEdit = props => (
298301
<ReferenceInput
299302
source="book"
300303
reference="books"
301-
label="Books"
302-
filterToQuery={searchText => ({ title: searchText })}
303-
format={v => v['@id'] || v}
304304
>
305-
<AutocompleteInput optionText="title" />
305+
<AutocompleteInput
306+
filterToQuery={searchText => ({ title: searchText })}
307+
format={v => v['@id'] || v}
308+
optionText="title"
309+
label="Books"
310+
/>
306311
</ReferenceInput>
307312

308313
<InputGuesser source="rating" />

‎admin/index.md

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -14,7 +14,7 @@ according to the API-first paradigm.
1414
API Platform Admin parses the API documentation then uses the awesome [React Admin](https://marmelab.com/react-admin/)
1515
library to expose a nice, responsive, management interface (Create-Retrieve-Update-Delete) for all documented resource types.
1616

17-
You can **customize everything** by using provided React Admin and [Material UI](https://material-ui.com/) components, or by writing your custom [React](https://reactjs.org/) components.
17+
You can **customize everything** by using provided React Admin and [MUI](https://mui.com/) components, or by writing your custom [React](https://reactjs.org/) components.
1818

1919
## Features
2020

0 commit comments

Comments
 (0)