docs: Revamp API Platform Admin docs #2141
Open
Conversation
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
slax57
force-pushed
the
revamp-admin-docs
branch
from
1fca087 to
9dbcf96
Compare
slax57
changed the title
fzaninotto
requested changes
Mar 12, 2025
djhi
approved these changes
Mar 17, 2025
fzaninotto
approved these changes
Mar 18, 2025
fzaninotto
approved these changes
Mar 24, 2025
alanpoulain
reviewed
Mar 24, 2025
|
|
||
| Thanks to its built-in **guessers**, API Platform Admin parses the API documentation then uses React Admin to expose a nice, responsive management interface (Create-Retrieve-Update-Delete, i.e. CRUD) for all documented resource types. | ||
|
|
||
| Afterwards, you can **customize everything** by using the numerous components provided [React Admin](https://marmelab.com/react-admin/documentation.html) and [MUI](https://mui.com/), or even writing your own [React](https://reactjs.org/) components. |
There was a problem hiding this comment.
Suggested change
| Afterwards, you can **customize everything** by using the numerous components provided [React Admin](https://marmelab.com/react-admin/documentation.html) and [MUI](https://mui.com/), or even writing your own [React](https://reactjs.org/) components. | |
| Afterwards, you can **customize everything** by using the numerous components provided by [React Admin](https://marmelab.com/react-admin/documentation.html) and [MUI](https://mui.com/), or even writing your own [React](https://reactjs.org/) components. |
alanpoulain
reviewed
Mar 24, 2025
| ``` | ||
|
|
||
| **Tip:** if you don't want to hardcode the API URL, you can [use an environment variable](https://vite.dev/guide/env-and-mode). |
There was a problem hiding this comment.
This tip is only available if the user has used CRA, if the distribution is used it's Next.js instead (we should probably use Vite instead tough 😄).
alanpoulain
reviewed
Mar 24, 2025
| @@ -0,0 +1,147 @@ | |||
| # Customizing the Schema | |||
There was a problem hiding this comment.
Maybe the filename should just be schema.md.
alanpoulain
reviewed
Mar 24, 2025
|
|
||
| ## Adding Filtering Capabilities | ||
|
|
||
| You can add the [`ApiFilter` attribute](../core/filters.md#apifilter-attribute) to an Entity to configure a filter on a property. |
There was a problem hiding this comment.
Suggested change
| You can add the [`ApiFilter` attribute](../core/filters.md#apifilter-attribute) to an Entity to configure a filter on a property. | |
| You can add the [`ApiFilter` attribute](../core/filters.md#apifilter-attribute) to an API Platform resource to configure a filter on a property. |
alanpoulain
reviewed
Mar 24, 2025
|
|
||
| You can add the [`ApiFilter` attribute](../core/filters.md#apifilter-attribute) to an Entity to configure a filter on a property. | ||
|
|
||
| For instance, here is how configure filtering on the `id`, `title` and `author` properties of a `Book` entity: |
There was a problem hiding this comment.
Suggested change
| For instance, here is how configure filtering on the `id`, `title` and `author` properties of a `Book` entity: | |
| For instance, here is how configure filtering on the `id`, `title` and `author` properties of a `Book` resource: |
alanpoulain
reviewed
Mar 24, 2025
|
|
||
| ## Adding Sorting Capabilities | ||
|
|
||
| You can also use the [`ApiFilter` attribute](../core/filters.md#apifilter-attribute) on an Entity to configure sorting. |
There was a problem hiding this comment.
Suggested change
| You can also use the [`ApiFilter` attribute](../core/filters.md#apifilter-attribute) on an Entity to configure sorting. | |
| You can also use the [`ApiFilter` attribute](../core/filters.md#apifilter-attribute) on an API Plaform resource to configure sorting. |
alanpoulain
reviewed
Mar 24, 2025
|
|
||
| You can also use the [`ApiFilter` attribute](../core/filters.md#apifilter-attribute) on an Entity to configure sorting. | ||
|
|
||
| For instance, here is how to configure sorting on the `id`, `isbn`, `title`, `author` and `publicationDate` properties of a `Book` entity: |
There was a problem hiding this comment.
Suggested change
| For instance, here is how to configure sorting on the `id`, `isbn`, `title`, `author` and `publicationDate` properties of a `Book` entity: | |
| For instance, here is how to configure sorting on the `id`, `isbn`, `title`, `author` and `publicationDate` properties of a `Book` resource: |
alanpoulain
reviewed
Mar 24, 2025
|
|
||
| By default, `<ResourceGuesser>` will render a `<ListGuesser>` component as the list view for a resource. | ||
|
|
||
| Again, this component will automatically introspect the API schema and generate a list view with all the fields of the resource. |
There was a problem hiding this comment.
Suggested change
| Again, this component will automatically introspect the API schema and generate a list view with all the fields of the resource. | |
| This component will automatically introspect the API schema and generate a list view with all the fields of the resource. |
alanpoulain
reviewed
Mar 24, 2025
|
|
||
| This is already usable, but may not provide the best user experience yet. | ||
|
|
||
| Here, too, to start customizing the list view, you can look at the DevTools console. You will see messages like this: |
There was a problem hiding this comment.
Suggested change
| Here, too, to start customizing the list view, you can look at the DevTools console. You will see messages like this: | |
| To start customizing the list view, you can look at the DevTools console. You will see messages like this: |
alanpoulain
reviewed
Mar 24, 2025
|
|
||
| ## Customizing the `<ShowGuesser>` | ||
|
|
||
| Following the same principles (including looking at the DevTools console) we can customize the show view. |
There was a problem hiding this comment.
Suggested change
| Following the same principles (including looking at the DevTools console) we can customize the show view. | |
| Following the same principles as the `<ListGuesser>` (including looking at the DevTools console) we can customize the show view. |
alanpoulain
reviewed
Mar 24, 2025
|
|
||
| ## Customizing the Edit Form | ||
| Again, we can start by looking at the DevTools console to get the initial code of the components. |
There was a problem hiding this comment.
Suggested change
| Again, we can start by looking at the DevTools console to get the initial code of the components. | |
| We can start by looking at the DevTools console to get the initial code of the components. |
alanpoulain
reviewed
Mar 24, 2025
|
|
||
|  | ||
|
|
||
| **Tip:** Here, we leveraged the `multiline` and `readOnly` props of the `<InputGuesser>` component. But you can use any [common input prop](https://marmelab.com/react-admin/Inputs.html#common-input-props) supported by react-admin [Inputs](https://marmelab.com/react-admin/Inputs.html) on them. |
There was a problem hiding this comment.
Suggested change
| **Tip:** Here, we leveraged the `multiline` and `readOnly` props of the `<InputGuesser>` component. But you can use any [common input prop](https://marmelab.com/react-admin/Inputs.html#common-input-props) supported by react-admin [Inputs](https://marmelab.com/react-admin/Inputs.html) on them. | |
| **Tip:** Here, we leveraged the `multiline` and `readOnly` props of the `<InputGuesser>` component. But you can use any [common input prop](https://marmelab.com/react-admin/Inputs.html#common-input-props) supported by React Admin [Inputs](https://marmelab.com/react-admin/Inputs.html) on them. |
alanpoulain
reviewed
Mar 24, 2025
|
|
||
|  | ||
|
|
||
| **Tip:** Here, we leveraged the `multiline` and `readOnly` props of the `<InputGuesser>` component. But you can use any [common input prop](https://marmelab.com/react-admin/Inputs.html#common-input-props) supported by react-admin [Inputs](https://marmelab.com/react-admin/Inputs.html) on them. |
There was a problem hiding this comment.
Suggested change
| **Tip:** Here, we leveraged the `multiline` and `readOnly` props of the `<InputGuesser>` component. But you can use any [common input prop](https://marmelab.com/react-admin/Inputs.html#common-input-props) supported by react-admin [Inputs](https://marmelab.com/react-admin/Inputs.html) on them. | |
| **Tip:** Here, we leveraged the `multiline` and `readOnly` props of the `<InputGuesser>` component. But you can use any [common input prop](https://marmelab.com/react-admin/Inputs.html#common-input-props) supported by React Admin [Inputs](https://marmelab.com/react-admin/Inputs.html) on them. |
alanpoulain
reviewed
Mar 24, 2025
|
|
||
| ## Going Further | ||
| The above examples limit to customizing the various API Platform Admin Guessers, but this is just the tip of the iceberg. |
There was a problem hiding this comment.
Suggested change
| The above examples limit to customizing the various API Platform Admin Guessers, but this is just the tip of the iceberg. | |
| The above examples are limited to customizing the various API Platform Admin Guessers, but this is just the tip of the iceberg. |
alanpoulain
reviewed
Mar 24, 2025
|
|
||
| However the UX can often be improved by setting a default action when clicking on a row, and removing the `Show` and `Edit` buttons. | ||
|
|
||
| To hide these buttons, we will need to replace the `<ListGuesser>` by a [`<List>`](https://marmelab.com/react-admin/List.html) component, provided by `react-admin`. |
There was a problem hiding this comment.
That's too bad, I think this example is not really suited: we should be able to change the <ListGuesser> component to support removing its buttons.
It's the philosophy of API Platform Admin: making sure the user can customize simple things by keeping the guessers as most as possible.
alanpoulain
reviewed
Mar 24, 2025
|
|
||
| If the user clicks on the undo button, the record will be restored to its previous state. Otherwise, the change is persisted to the API. | ||
|
|
||
| Let's, for instance, add the possibility to undo an update to a book. To do that, we will replace the generated `<EditGuesser>` by the [`<Edit>`](https://marmelab.com/react-admin/Edit.html) component, provided by `react-admin`. Undoable mutations are enabled by default for the `<Edit>` component. |
There was a problem hiding this comment.
Same as my previous comment, setting the mutationMode prop of <EditGuesser> is sufficient to do this.
alanpoulain
reviewed
Mar 24, 2025
|
|
||
| When the user tries to navigate away from a form with unsaved changes, a confirmation dialog will be displayed, asking the user if they want to leave the page. This prevents the risk of losing unsaved data. | ||
|
|
||
| Reusing the `BookEdit` component from the previous example, all we need to do is to leverage the [`warnWhenUnsavedChanges`](https://marmelab.com/react-admin/SimpleForm.html#warnwhenunsavedchanges) prop of the `<SimpleForm>` component to enable this feature. |
There was a problem hiding this comment.
Same as my previous comments: this props is exposed by the <EditGuesser> component.
alanpoulain
reviewed
Mar 24, 2025
|
|
||
| Speaking of tabbed layout, a common pattern is to display related records in a dedicated tab of the show view of the main record. | ||
|
|
||
| For instance, let's leverage the [`<TabbedShowLayout>`](https://marmelab.com/react-admin/TabbedShowLayout.html) component provided by `react-admin` to display the reviews of a book in a dedicated tab. |
There was a problem hiding this comment.
Suggested change
| For instance, let's leverage the [`<TabbedShowLayout>`](https://marmelab.com/react-admin/TabbedShowLayout.html) component provided by `react-admin` to display the reviews of a book in a dedicated tab. | |
| For instance, let's leverage the [`<TabbedShowLayout>`](https://marmelab.com/react-admin/TabbedShowLayout.html) component provided by React Admin to display the reviews of a book in a dedicated tab. |
alanpoulain
reviewed
Mar 24, 2025
| import { Rating } from '@mui/material'; | ||
|
|
||
| const ReviewShow = () => ( | ||
| <Show> |
There was a problem hiding this comment.
Why not using the <ShowGuesser> component here?
alanpoulain
reviewed
Mar 24, 2025
Comment on lines
+418
to
+419
| <Edit warnWhenUnsavedChanges> | ||
| <SimpleForm sx={{ maxWidth: 500 }}> |
There was a problem hiding this comment.
Why not using the <EditGuesser> component here?
alanpoulain
reviewed
Mar 24, 2025
| - [SolarLayout](https://marmelab.com/react-admin/SolarLayout.html) | ||
| - And many more... | ||
|
|
||
| React Admin already includes 230+ hooks and components. And it always allow you to make your own, thanks to the building blocks it provides. Feel free to read through its [All Features](https://marmelab.com/react-admin/Features.html) documentation page to discover them all. |
There was a problem hiding this comment.
Suggested change
| React Admin already includes 230+ hooks and components. And it always allow you to make your own, thanks to the building blocks it provides. Feel free to read through its [All Features](https://marmelab.com/react-admin/Features.html) documentation page to discover them all. | |
| React Admin already includes 230+ hooks and components. And it always allows you to make your own, thanks to the building blocks it provides. Feel free to read through its [All Features](https://marmelab.com/react-admin/Features.html) documentation page to discover them all. |
alanpoulain
reviewed
Mar 24, 2025
Comment on lines
+255
to
+257
| We can improve the UX further by rendering an [`<AutocompleteInput>`](https://marmelab.com/react-admin/AutocompleteInput.html) instead. | ||
|
|
||
| `<AutocompleteInput>` allows to search for a related record by typing its name in an input field. This is much more convenient when there are many records to choose from. |
There was a problem hiding this comment.
There is a lot of tip for replacing the <InputGuesser> by an <AutocompleteInput>. I think API Platform Admin should provide a prop to do this instead.
alanpoulain
reviewed
Mar 24, 2025
| @@ -9,9 +9,9 @@ the admin will fetch the relations one by one. | |||
|
|
|||
| In this case, it can be improved by doing only one request for all the related resources instead. | |||
|
|
|||
| To do so, you need to make sure the [search filter](../core/filters.md#search-filter) is enabled for the identifier of the related resource. | |||
| To do so, you need to make sure the [search filter](../core/filters.md#apifilter-attribute) is enabled for the identifier of the related resource. | |||
There was a problem hiding this comment.
Suggested change
| To do so, you need to make sure the [search filter](../core/filters.md#apifilter-attribute) is enabled for the identifier of the related resource. | |
| To do so, you need to make sure the [search filter](../core/doctrine-filters.md#search-filter) is enabled for the identifier of the related resource. |
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.
This suggestion is invalid because no changes were made to the code.
Suggestions cannot be applied while the pull request is closed.
Suggestions cannot be applied while viewing a subset of changes.
Only one suggestion per line can be applied in a batch.
Add this suggestion to a batch that can be applied as a single commit.
Applying suggestions on deleted lines is not supported.
You must change the existing code in this line in order to create a valid suggestion.
Outdated suggestions cannot be applied.
This suggestion has been applied or marked resolved.
Suggestions cannot be applied from pending reviews.
Suggestions cannot be applied on multi-line comments.
Suggestions cannot be applied while the pull request is queued to merge.
Suggestion cannot be applied right now. Please check back later.
This PR aims at generally improving the API Platform Admin documentation, notably:
This PR relies on customization examples brought by api-platform/admin#600
Here is the new TOC I implemented:
i. General intro about what API Platform Admin is
ii. When can I use it
iii. Introduce React Admin
iv. Feature @fzaninotto 's presentation given at the API Platform Conference 2024
v. List features offered by the Admin
i. Introduce HydraAdmin
ii. Introduce OpenApiAdmin
i. Show how to customize the Admin with just PHP changes
ii. Includes the 'Using the Schema.org Vocabulary' content
i. Learn how to use FieldGuesser and InputGuesser
ii. Includes current section 'Customizing the Admin'
i. Provide examples of more advanced customization, leveraging React Admin components
TODO
How to test
docs-versions.txtto add a version namedrevamp-admin-docs(name of the branch of this PR)hugo.tomlto add a version namedrevamp-admin-docswith pathvrevamp-admin-docshugoon your machine (sudo apt install hugo)README.mdof thedocs-websiterepohugo serve