docs: Revamp API Platform Admin docs #2141

slax57 · 2025-03-07T18:10:50Z

This PR aims at generally improving the API Platform Admin documentation, notably:

Updating the code, links, and screenshots
Reorganizing the pages to provide a linear, guided read-through for newcomers (see below)
Improve documentation regarding the ways to customize the generated Admin, most notably showcasing advanced customization using React Admin components
Fix minor issues found while proof-reading

This PR relies on customization examples brought by api-platform/admin#600

Here is the new TOC I implemented:

The API Platform Admin
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
Getting Started
i. Introduce HydraAdmin
ii. Introduce OpenApiAdmin
Customizing the Schema
i. Show how to customize the Admin with just PHP changes
ii. Includes the 'Using the Schema.org Vocabulary' content
Customizing Guessers
i. Learn how to use FieldGuesser and InputGuesser
ii. Includes current section 'Customizing the Admin'
Customizing the Admin
i. Provide examples of more advanced customization, leveraging React Admin components
Handling Relations
Validating Forms
Realtime Updates
Authentication
Handling File Upload
Performance -> renamed to Performance Tips
Components -> renamed to Components Reference

TODO

Finish the rewrite
update the menu
Much proof-reading

How to test

Clone https://github.com/api-platform/docs-website
Edit docs-versions.txt to add a version named revamp-admin-docs (name of the branch of this PR)
Edit hugo.toml to add a version named revamp-admin-docs with path vrevamp-admin-docs
Install hugo on your machine (sudo apt install hugo)
Follow the instructions from the README.md of the docs-website repo
Run hugo serve
Browse http://localhost:1313/docs/vrevamp-admin-docs/admin/

fzaninotto

Awesome work! Kudos for that.

The new chapters are 💯 . You helped improve the old ones, but some passages are still hard to follow.

admin/components.md

admin/handling-relations.md

admin/authentication-support.md

admin/index.md

alanpoulain · 2025-03-24T14:36:25Z

admin/getting-started.md

 ```

+**Tip:** if you don't want to hardcode the API URL, you can [use an environment variable](https://vite.dev/guide/env-and-mode).


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 😄).

Good point. I'll add a link for both.

alanpoulain · 2025-03-24T14:38:50Z

admin/schema-org.md

@@ -0,0 +1,147 @@
+# Customizing the Schema


Maybe the filename should just be schema.md.

I agree. I renamed the file to workaround a bug causing the section to not be highlighted in the left menu, but we can go even further with the renaming. I'll push a new commit.

admin/schema-org.md

admin/customizing.md

alanpoulain · 2025-03-24T15:02:27Z

admin/advanced-customization.md

+
+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`.


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.

I understand your POV.

To me, both requirements can coexist. API Platform Admin can allow to customize simple things by tweaking the guessers.
But we should also let the users break free of the guessers when they need to, and guide them towards the use of native RA components.

In the end:

I agree adding an option to <ListGuesser> to hide these buttons is a good idea (and likewise, I'll add it to our suggestions backlog)

But to me, it's also important to show them how they can use the native RA components instead, and what it will bring to them.

I agree this example will no longer be relevant when <ListGuesser> offers an option to hide the buttons (and if you have a better example I'll be glad to read about it!), but for now it's relevant so I think we should keep it.

alanpoulain · 2025-03-24T15:05:22Z

admin/advanced-customization.md

+
+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.


Same as my previous comment, setting the mutationMode prop of <EditGuesser> is sufficient to do this.

Same answer (encourage users to use RA components directly)

alanpoulain · 2025-03-24T15:07:08Z

admin/advanced-customization.md

+
+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.


Same as my previous comments: this props is exposed by the <EditGuesser> component.

Same answer as for <EditGuesser> (encourage users to use RA components directly).

This also highlights another advantage: helping users understand that the warnWhenUnsavedChanges is carried by <SimpleForm> will help them find other props they might need in the RA docs.

admin/advanced-customization.md

alanpoulain · 2025-03-24T15:11:12Z

admin/advanced-customization.md

+import { Rating } from '@mui/material';
+
+const ReviewShow = () => (
+  <Show>


Why not using the <ShowGuesser> component here?

Same answer as for <EditGuesser> (encourage users to use RA components directly)

alanpoulain · 2025-03-24T15:12:20Z

admin/advanced-customization.md

+  <Edit warnWhenUnsavedChanges>
+    <SimpleForm sx={{ maxWidth: 500 }}>


Why not using the <EditGuesser> component here?

You are right, we could! But the goal of this whole section is to encourage users to break out of the guessers and start using React Admin components directly. Besides, it also helps understanding that <EditGuesser> actually renders both an <Edit> and a <SimpleForm>. Lastly this makes it easier to move to a different Form component later on.

admin/advanced-customization.md

alanpoulain · 2025-03-24T15:25:22Z

admin/handling-relations.md

+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 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.

I agree! I've added the idea to our backlog so we can open a PR implementing that in the future 🙂

admin/performance.md

Co-authored-by: Alan Poulain <contact@alanpoulain.eu>

slax57

Thanks for the extensive review! 👍

slax57 · 2025-03-25T10:49:46Z

admin/handling-relations.md

+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.


I agree! I've added the idea to our backlog so we can open a PR implementing that in the future 🙂

slax57 · 2025-03-25T10:54:00Z

admin/advanced-customization.md

+  <Edit warnWhenUnsavedChanges>
+    <SimpleForm sx={{ maxWidth: 500 }}>


You are right, we could! But the goal of this whole section is to encourage users to break out of the guessers and start using React Admin components directly. Besides, it also helps understanding that <EditGuesser> actually renders both an <Edit> and a <SimpleForm>. Lastly this makes it easier to move to a different Form component later on.

slax57 · 2025-03-25T10:54:58Z

admin/advanced-customization.md

+import { Rating } from '@mui/material';
+
+const ReviewShow = () => (
+  <Show>


Same answer as for <EditGuesser> (encourage users to use RA components directly)

slax57 · 2025-03-25T10:57:48Z

admin/advanced-customization.md

+
+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.


Same answer as for <EditGuesser> (encourage users to use RA components directly).

This also highlights another advantage: helping users understand that the warnWhenUnsavedChanges is carried by <SimpleForm> will help them find other props they might need in the RA docs.

slax57 · 2025-03-25T10:58:54Z

admin/advanced-customization.md

+
+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.


Same answer (encourage users to use RA components directly)

slax57 · 2025-03-25T11:08:43Z

admin/advanced-customization.md

+
+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`.


I understand your POV.

To me, both requirements can coexist. API Platform Admin can allow to customize simple things by tweaking the guessers.
But we should also let the users break free of the guessers when they need to, and guide them towards the use of native RA components.

In the end:

I agree adding an option to <ListGuesser> to hide these buttons is a good idea (and likewise, I'll add it to our suggestions backlog)

But to me, it's also important to show them how they can use the native RA components instead, and what it will bring to them.

I agree this example will no longer be relevant when <ListGuesser> offers an option to hide the buttons (and if you have a better example I'll be glad to read about it!), but for now it's relevant so I think we should keep it.

slax57 · 2025-03-25T13:05:51Z

admin/schema-org.md

@@ -0,0 +1,147 @@
+# Customizing the Schema


I agree. I renamed the file to workaround a bug causing the section to not be highlighted in the left menu, but we can go even further with the renaming. I'll push a new commit.

slax57 · 2025-03-25T13:07:27Z

admin/getting-started.md

 ```

+**Tip:** if you don't want to hardcode the API URL, you can [use an environment variable](https://vite.dev/guide/env-and-mode).


Good point. I'll add a link for both.

slax57 added 3 commits March 7, 2025 11:43

docs: revamp the admin index page

505e82f

docs: revamp the getting started section

c873a42

docs: revamp schema.org doc

db1cb96

slax57 mentioned this pull request Mar 7, 2025

[Storybook] Improve Storybook examples api-platform/admin#600

Merged

slax57 added 4 commits March 10, 2025 11:24

docs: revamp the customizing the guessers doc

a9ac94e

docs: add new customizing the admin page

73a1fbe

docs: update handling relations doc

ade232e

docs: update validation doc

9dbcf96

slax57 force-pushed the revamp-admin-docs branch from 1fca087 to 9dbcf96 Compare March 10, 2025 17:34

slax57 added 5 commits March 12, 2025 12:09

docs: update file upload doc

52a2656

docs: update performance doc

aeb023a

[no ci] docs: update components reference doc

6d4f5a7

docs: update authentication doc

24c87b8

fix linter issues

8bfb644

slax57 changed the title ~~[Doc] Revamp API Platform Admin docs~~ docs: Revamp API Platform Admin docs Mar 12, 2025

slax57 added 3 commits March 12, 2025 18:24

doc: handling relations: add more links to RA doc

371d14c

comply with foolish linter rules

fe56516

fix links and make navigation more consistent

de13c04

fzaninotto requested changes Mar 12, 2025

View reviewed changes

slax57 added 11 commits March 13, 2025 10:55

fix linter blockquote issue

5890a02

docs: apply review on components reference

ea4865a

docs: apply review on handling relations

dc28485

docs: revamp the handling relations doc

17b67e8

docs: apply review on authentication support doc

9036ebe

Merge remote-tracking branch 'origin/4.1' into revamp-admin-docs

25b56df

docs: update the admin outline (menu)

2f2ffbb

fix linter again and again

2348e35

docs: add section about Validation With React Admin Inputs

078a77e

docs: schema: add screenshots for name instead of IRI

3254a5d

docs: minor updates after self-review

ae0b3a2

fzaninotto approved these changes Mar 18, 2025

View reviewed changes

fzaninotto approved these changes Mar 24, 2025

View reviewed changes