[Docs] Tools: document the new portlet and the UI/UX changes
Open
@hmoreras is already working on this.
Since Sep 2, 2026.
dotCMS : Admin Tools
Team : Modernization
Type : Documentation
- Dominant language
- Java
- Stars
- 970
- Forks
- 486
- Avg merge
- 3d 33m
- Merged PRs (30d)
- 170
Description
Goal
Document the Tools portlet so an admin can find it, understand what it controls, and know where granting lives — and so a developer knows how to opt in and how to roll back.
Scope
User docs
- What Tools is: the surface that defines the backend navigation — the sections in the left menu, the tools inside each section, and the order of both.
- The boundary that matters most: Tools is the master list. Putting a tool in a section does not give anyone access to it. Access is granted per role in Settings → Roles & Tools. Say this early and plainly, because it is the question every admin will have.
- Where the screen lives and how to reach it.
- Sections: creating one from a name and an icon, renaming it, changing its icon, deleting it, and dragging to set its position in the navigation.
- Tools in a section: checking a tool to add it, unchecking or using the remove control to take it out, dragging to set the order inside the section, and searching the catalog.
- Custom content tools: what a tool created through New Tool actually is — a filtered content list — and what each field does, including the id and when to change it, the content to display, and the difference between the List and Card data view modes.
- What deleting a section costs, per the spike's findings, so the confirmation dialog is not the first place an admin learns it.
- Where the equivalent settings used to live for anyone coming from the older screen.
Developer note
- The Beta portlet id is
tools-beta, display nameTools (Beta), served at/#/c/tools-beta. - It ships opt-in: not in any default layout and not added by an
UpgradeTask. An admin adds it through Add Portlet. - Rolling back means removing it from the layout. No code change, no redeploy, and nothing about the existing navigation is modified by installing it.
- The
/v1endpoints the portlet uses, and the note that the equivalentRoleAjaxDWR methods remain in place for the Dojo screen.
Inputs
- Epic #37351 and the spike's artifacts
- The shipped portlet on a running instance
- Design: https://claude.ai/design/p/879ff4e6-1b23-486d-9926-327709e91953?via=share&file=Tools.dc.html (internal — auth required)
Definition of Done
- User docs published, covering every surface and action the portlet ships.
- The Tools versus Roles & Tools boundary is stated explicitly, near the top.
- The developer note covers the Beta portlet id, how to opt in, and how to roll back.
- Screenshots match the shipped UI, not the design mockups.
Refs #37351
Contributor guide
First steps
- Read the whole issue, then the project's contributing guide.
- Comment on the issue to say you are picking it up — it saves two people doing the same work.
- Fork the repository and make your change on a branch.
- Open a pull request that references the issue number.
Assessment
This issue has not been assessed yet.