Skip to content

Commit 8f8c024

Browse files
justinezahirijustinezahiri
authored
docs (admin): added Components section (#1200)
1 parent 65833f1 commit 8f8c024

File tree

2 files changed

+270
-0
lines changed

2 files changed

+270
-0
lines changed

‎admin/components.md

Lines changed: 269 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,269 @@
1+
# Components
2+
3+
## Resource Components
4+
5+
### AdminGuesser
6+
7+
`<AdminGuesser>` creates a complete Admin Context and Interface, rendering automatically an [`<AdminUI>` component](https://marmelab.com/react-admin/Admin.html#unplugging-the-admin-using-admincontext-and-adminui) 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](admin/components.md#hydraadmin) instead). It also creates a [`schemaAnalyzer`](admin/components.md#schemaAnalyzer) context, where the schemaAnalyzer service (for getting information about the provided API documentation) is stored.
8+
The `<AdminGuesser>` renders all exposed resources by default, but you can choose what resource you want to render by passing [`<ResourceGuesser>` components](admin/components/#resourceguesser) as children.
9+
Deprecated resources are hidden by default, but you can add them back using an explicit `<ResourceGuesser>` component.
10+
11+
```javascript
12+
//App.js
13+
import { AdminGuesser, ResourceGuesser } from '@api-platform/admin';
14+
15+
const App = () => (
16+
<AdminGuesser
17+
entrypoint={entrypoint}
18+
dataProvider={dataProvider}
19+
authProvider={authProvider}>
20+
<ResourceGuesser
21+
name"books"
22+
list={BooksList}
23+
show={BooksShow}
24+
edit={BooksEdit}
25+
create={BooksCreate} />
26+
<ResourceGuesser name"authors" />
27+
</AdminGuesser>
28+
)
29+
30+
export default App;
31+
```
32+
33+
**Props**
34+
| Name | Type | Value | required | Description |
35+
|-------------------|--------------------|----------------|----------|----------------------------------------------------------------------------------|
36+
| dataProvider | object or function | - | yes | communicates with your API |
37+
| schemaAnalyzer | object | schemaAnalyzer | yes | retrieves resource type according to [Schema.org](https://schema.org) vocabulary |
38+
| children | node or function | - | no | - |
39+
| theme | object | theme | no | theme of your Admin App |
40+
| includeDeprecated | boolean | true or false | no | displays or not deprecated resources |
41+
42+
### ResourceGuesser
43+
44+
Based on React-Admin's [`<Resource>` component](https://marmelab.com/react-admin/Resource.html), the ResourceGuesser provides default props [`<CreateGuesser>`](admin/components.md#createguesser), [`<ListGuesser>`](admin/components.md#listguesser), [`<EditGuesser>`](admin/components.md#editguesser) and [`<ShowGuesser>`](admin/components.md#showguesser). Otherwise you can pass it your own CRUD components using `create`, `list`, `edit`, `show` props.
45+
46+
```javascript
47+
// App.js
48+
import { AdminGuesser, ResourceGuesser } from '@api-platform/admin';
49+
50+
const App = () => (
51+
<AdminGuesser
52+
entrypoint={entrypoint}
53+
dataProvider={dataProvider}
54+
schemaAnalyzer={schemaAnalyzer}
55+
>
56+
<ResourceGuesser
57+
name="books"
58+
list={BooksList}
59+
show={BooksShow}
60+
create={BooksCreate}
61+
edit={BooksEdit} />
62+
<ResourceGuesser name="reviews" />
63+
</AdminGuesser>
64+
);
65+
66+
export default App;
67+
```
68+
69+
**Props**
70+
| Name | Type | Value | required | Description |
71+
|------|--------|-------|----------|--------------------------|
72+
| name | string | - | yes | endpoint of the resource |
73+
74+
You can also use props accepted by React-Admin's [`<Resource>` component](https://marmelab.com/react-admin/Resource.html). For example, the props `list`, `show`, `create` & `edit`.
75+
76+
## Page Components
77+
78+
### ListGuesser
79+
80+
Based on React-Admin's [`<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>`](admin/components/#fieldguesser) or any [`field` component](https://marmelab.com/react-admin/Fields.html#basic-fields) available in React-Admin).
81+
Use `hasShow` and `hasEdit` props if you want to display `show` and `edit` buttons (both set to `true` by default).
82+
By default, `<ListGuesser>` comes with [`<Pagination>`](admin/components.md#pagination).
83+
84+
```javascript
85+
// BooksList.js
86+
import { FieldGuesser, ListGuesser } from '@api-platform/admin';
87+
import { ReferenceField, TextField } from 'react-admin';
88+
89+
export const BooksList = props => (
90+
<ListGuesser {...props}>
91+
<FieldGuesser source="author" />
92+
<FieldGuesser source="title" />
93+
<FieldGuesser source="rating" />
94+
<FieldGuesser source="description" />
95+
<FieldGuesser source="publicationDate" />
96+
</ListGuesser>
97+
);
98+
```
99+
**Props**
100+
| Name | Type | Value | required | Description |
101+
|----------|------------------|-------|----------|-----------------------------------------|
102+
| children | node or function | - | no | - |
103+
| resource | string | - | yes | endpoint of the resource |
104+
| filters | element | - | no | filters that can be applied to the list |
105+
106+
107+
You can also use props accepted by React-Admin's [`<List>`](https://marmelab.com/react-admin/List.html).
108+
109+
### CreateGuesser
110+
111+
Displays a creation page for a single item. Uses React-Admin's [`<Create>`](https://marmelab.com/react-admin/Edit.html) and [`<SimpleForm>`](https://marmelab.com/react-admin/CreateEdit.html#the-simpleform-component).
112+
For simple inputs, you can pass as children API Platform Admin's [`<InputGuesser>`](admin/components.md#inputguesser), or any React-Admin's [`Input components`](https://marmelab.com/react-admin/Inputs.html#input-components) for more complex inputs.
113+
114+
```javascript
115+
// BooksCreate.js
116+
import { CreateGuesser, InputGuesser } from '@api-platform/admin';
117+
118+
export const BooksCreate = props => (
119+
<CreateGuesser {...props}>
120+
<InputGuesser source="author" />
121+
<InputGuesser source="title" />
122+
<InputGuesser source="rating" />
123+
<InputGuesser source="description" />
124+
<InputGuesser source="publicationDate" />
125+
</CreateGuesser>
126+
);
127+
```
128+
129+
**Props**
130+
| Name | Type | Value | required | Description |
131+
| Name | Type | Value | required | Description |
132+
|----------|------------------|-------|----------|--------------------------|
133+
| children | node or function | - | no | - |
134+
| resource | string | - | yes | endpoint of the resource |
135+
136+
You can also use props accepted by React-Admin's [`<Create>`](https://marmelab.com/react-admin/Edit.html).
137+
138+
### EditGuesser
139+
140+
Displays an edition page for a single item. Uses React-Admin's [`<Edit>`](https://marmelab.com/react-admin/Edit.html) and [`<SimpleForm>`](https://marmelab.com/react-admin/CreateEdit.html#the-simpleform-component) components.
141+
For simple inputs, you can use API Platform Admin's [`<InputGuesser>`](admin/components.md#inputguesser), or any React-Admin's [`Input components`](https://marmelab.com/react-admin/Inputs.html#input-components) for more complex inputs.
142+
143+
```javascript
144+
// BooksEdit.js
145+
import { EditGuesser, InputGuesser } from '@api-platform/admin';
146+
147+
export const BooksEdit = props => (
148+
<EditGuesser {...props}>
149+
<InputGuesser source="author" />
150+
<InputGuesser source="title" />
151+
<InputGuesser source="rating" />
152+
<InputGuesser source="description" />
153+
<InputGuesser source="publicationDate" />
154+
</EditGuesser>
155+
);
156+
```
157+
158+
**Props**
159+
| Name | Type | Value | required | Description |
160+
|----------|------------------|-------|----------|--------------------------|
161+
| children | node or function | - | no | - |
162+
| resource | string | - | yes | endpoint of the resource |
163+
164+
You can also use props accepted by React-Admin's [`<Edit>`](https://marmelab.com/react-admin/Edit.html).
165+
166+
### ShowGuesser
167+
168+
Displays a detailed page for one item. Based on React-Admin's [`<Show>` component](https://marmelab.com/react-admin/Show.html). You can pass [`<FieldGuesser>`](admin/components.md#fieldguesser) as children for simple fields, or use any of React-Admin's [`Basic Fields`](https://marmelab.com/react-admin/Fields.html#basic-fields) for more complex fields.
169+
170+
```javascript
171+
// BooksShow.js
172+
import { FieldGuesser, ShowGuesser } from '@api-platform/admin';
173+
174+
export const BooksShow = props => (
175+
<ShowGuesser {...props}>
176+
<FieldGuesser source="author" />
177+
<FieldGuesser source="title" />
178+
<FieldGuesser source="rating" />
179+
<FieldGuesser source="description" />
180+
<FieldGuesser source="publicationDate" />
181+
</ShowGuesser>
182+
);
183+
```
184+
185+
**Props**
186+
| Name | Type | Value | required | Description |
187+
|----------|------------------|-------|----------|--------------------------|
188+
| children | node or function | - | no | - |
189+
| resource | string | - | yes | endpoint of the resource |
190+
191+
You can also use props accepted by React-Admin's [`<Show>` component](https://marmelab.com/react-admin/Show.html).
192+
193+
## Hydra
194+
195+
### HydraAdmin
196+
197+
Creates a complete Admin Context and Interface, as [`<AdminGuesser>`](/admin/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 the [`<AdminGuesser>`](admin/components.md#adminguesser) instead.
198+
199+
```javascript
200+
// App.js
201+
import { HydraAdmin, ResourceGuesser } from '@api-platform/admin';
202+
203+
const App = () => (
204+
<HydraAdmin
205+
entrypoint={entrypoint}
206+
dataProvider={dataProvider}
207+
authProvider={authProvider}
208+
>
209+
<ResourceGuesser name="books" />
210+
{ /* ... */ }
211+
</HydraAdmin>
212+
);
213+
214+
export default App;
215+
```
216+
217+
**Props**
218+
| Name | Type | Value | required | Description |
219+
|------------|--------|-------|----------|-----------------------|
220+
| entrypoint | string | - | yes | entrypoint of the API |
221+
222+
### dataProvider
223+
224+
Based on React-Admin's `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.
225+
Note that the `dataProvider` can be overrided to fit your API needs.
226+
227+
### schemaAnalyzer
228+
229+
Analyses your resources and retrieves their types according to the [Schema.org](https://schema.org) vocabulary.
230+
231+
## Other Components
232+
233+
### Pagination
234+
235+
Set by default in the [`<ListGuesser/>` component](/admin/components.md#listguesser), the `<Pagination/> component` uses React-Admin's [`<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](https://api-platform.com/docs/core/pagination/#pagination).
236+
237+
### FieldGuesser
238+
239+
Renders fields according to their types, using [`schemaAnalyzer`](/admin/components.md#schemaanalyzer). Based on React-Admin's [`<ReferenceField>` component](https://marmelab.com/react-admin/Fields.html#referencefield).
240+
241+
```javascript
242+
// BooksShow.js
243+
import { FieldGuesser, ShowGuesser } from '@api-platform/admin';
244+
245+
export const BooksShow = props => (
246+
<ShowGuesser {...props}>
247+
<FieldGuesser source="author" />
248+
<FieldGuesser source="title" />
249+
<FieldGuesser source="rating" />
250+
<FieldGuesser source="description" />
251+
<FieldGuesser source="publicationDate" />
252+
</ShowGuesser>
253+
)
254+
```
255+
**Props**
256+
| Name | Type | Value | required | Description |
257+
|--------|--------|-------|----------|--------------------------|
258+
| source | string | - | yes | endpoint of the resource |
259+
260+
You can also use props accepted by React-Admin's [`Basic Fields`](https://marmelab.com/react-admin/Fields.html#basic-fields).
261+
262+
### InputGuesser
263+
264+
Uses React-Admin's [`<ReferenceInput>`](https://marmelab.com/react-admin/Inputs.html#referenceinput) to generate inputs according to your API documentation (e.g. number HTML input for numbers, checkbox for booleans, selectbox for relationships...)
265+
266+
**Props**
267+
| Name | Type | Value | required | Description |
268+
|--------|--------|-------|----------|--------------------------|
269+
| source | string | - | yes | endpoint of the resource |

‎outline.yaml

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -66,6 +66,7 @@ chapters:
6666
- authentication-support
6767
- performance
6868
- customizing
69+
- components
6970
- title: The Client Generator Component
7071
path: client-generator
7172
items:

0 commit comments

Comments
 (0)