dotCMS / dotCMS/core

[Docs] Tools: document the new portlet and the UI/UX changes

Open
#37,355 0 comments 0 reactions 1 assignee View on GitHub

@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 name Tools (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 /v1 endpoints the portlet uses, and the note that the equivalent RoleAjax DWR methods remain in place for the Dojo screen.

Inputs

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

Open the contributing guide

First steps

  1. Read the whole issue, then the project's contributing guide.
  2. Comment on the issue to say you are picking it up — it saves two people doing the same work.
  3. Fork the repository and make your change on a branch.
  4. Open a pull request that references the issue number.

Assessment

This issue has not been assessed yet.

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.