AGENTS.md

1# dotcms-ui — Agent Guide
2 
3Main admin UI application for dotCMS (`/dotAdmin`). **Angular 21.2.1** with standalone components, `dot-` prefix, built and served through the Nx workspace. Agents working in this directory should read this file first, then refer to the parent guide for shared standards.
4 
5## UI Stack
6 
7 
8| Layer             | Technology                             | Notes                                                                                                       |
9| ----------------- | -------------------------------------- | ----------------------------------------------------------------------------------------------------------- |
10| Component library | **PrimeNG**                            | Use `p-`* components (e.g. `p-button`, `p-select`, `p-dialog`) — check the PrimeNG MCP server for API/props |
11| Utility CSS       | **Tailwind CSS**                       | Use Tailwind utilities for layout, spacing, and typography                                                  |
12| Global styles     | `libs/dotcms-scss/angular/styles.scss` | Imported as a global stylesheet in the build                                                                |
13 
14 
15**Key rules:**
16 
17- Use Tailwind utilities (`grid`, `flex`, `gap-`*, `p-*`, etc.) for layout and spacing
18- Always use PrimeNG components for interactive UI (inputs, dropdowns, dialogs, tables) rather than raw HTML equivalents
19- PrimeNG icons ship via `primeicons` (`pi pi-*` class names); this package is included in the global styles
20 
21> **Standards reference**: All Angular syntax rules, component conventions, testing patterns (Jest + Spectator), and code-placement decisions are documented in **[../../CLAUDE.md](../../CLAUDE.md)**. Do not duplicate them here.
22 
23## Commands
24 
25All commands must be run from the `core-web/` workspace root and prefixed with `yarn nx` (Nx is not installed globally).
26 
27```bash
28# Development
29yarn nx serve dotcms-ui                              # Dev server at :4200, proxies /api/* → :8080
30yarn nx build dotcms-ui                             # Production build → dist/apps/dotcms-ui/
31yarn nx build dotcms-ui --configuration=development  # Dev build → ../../tomcat9/webapps/ROOT/dotAdmin
32 
33# Tests
34yarn nx test dotcms-ui                              # Run all unit tests
35yarn nx test dotcms-ui --testPathPattern=my.spec    # Run a specific spec file
36yarn nx lint dotcms-ui                              # Lint
37```
38 
39## Portlets
40 
41A **portlet** is an admin UI feature served under `/dotAdmin`, backed by a backend menu entry (`DotMenuItem`). The `dotcms-ui` app is a **shell**: it does not implement feature logic itself. It hosts portlets via Angular routing inside `MainComponentLegacyComponent`'s `<router-outlet>`.
42 
43 
44| Mode           | Where                                                        | Route pattern            |
45| -------------- | ------------------------------------------------------------ | ------------------------ |
46| Modern Angular | Nx lib or legacy app folder                                  | `/tags`, `/templates`, … |
47| Legacy JSP     | iframe                                                       | `/c/:id`                 |
48| Dynamic plugin | runtime registration via menu `initParams['angular-module']` | varies                   |
49 
50 
51### Where portlets live
52 
53```mermaid
54flowchart LR
55    subgraph newWork [New work]
56        Lib["libs/portlets/dot-feature/"]
57    end
58    subgraph legacy [Legacy - do not add here]
59        App["apps/dotcms-ui/src/app/portlets/"]
60    end
61    subgraph shell [App shell only]
62        Routes["app.routes.ts"]
63        View["view/components/ toolbar, login"]
64        Api["api/services/ guards"]
65    end
66    Lib --> Routes
67    App --> Routes
68    Routes --> View
69```
70 
71 
72 
73- **New portlets** → `[libs/portlets/{feature}/](../../libs/portlets/)` as Nx libraries. Canonical reference: `[dot-tags](../../libs/portlets/dot-tags/)`.
74- **Legacy portlets** → still under `[src/app/portlets/](src/app/portlets/)` (templates, content-types, form-builder, etc.). Migrate to `libs/portlets/` when touching them substantially — do not add new features here.
75- **App-local code** stays in the shell: `view/components/` (toolbar, login, contentlet editor), `api/services/` (guards, app services), `shared/models/`.
76 
77```
78apps/dotcms-ui/src/app/
79├── app.routes.ts       # portlet registry
80├── view/components/    # shell chrome (toolbar, login, editors)
81├── api/services/       # guards, app-level services
82└── portlets/           # legacy features only — see above
83```
84 
85### Nx lib pattern
86 
87Each modern portlet is an Nx library that exports routes for the app shell to lazy-load:
88 
891. Lib lives at `libs/portlets/dot-{feature}/` (complex features may split into `{feature}/portlet`, `{feature}/data-access`).
902. Lib exports `dot{Feature}Routes` from `src/index.ts` / `lib.routes.ts`.
913. Path alias in `[tsconfig.base.json](../../tsconfig.base.json)`: `@dotcms/portlets/dot-{feature}/portlet` (legacy app portlets use `@portlets/...`).
924. Nx project name: `portlets-dot-{feature}-portlet`; tags: `type:feature`, `scope:dotcms-ui`, `portlet:{feature}`.
935. For generator setup, SignalStore rules, shell/list/store/CRUD patterns, and testing — see `**[libs/portlets/CLAUDE.md](../../libs/portlets/CLAUDE.md)**` (`dot-tags` is the reference implementation).
94 
95### Wiring into routing
96 
97Central registry: `[src/app/app.routes.ts](src/app/app.routes.ts)`.
98 
991. Authenticated routes mount under `MainComponentLegacyComponent`.
1002. `PORTLETS_ANGULAR` lazy-loads each Angular portlet via `loadChildren`.
1013. Most entries use `MenuGuardService` to enforce backend menu permissions.
1024. Legacy JSP portlets use `PORTLETS_IFRAME` → `IframePortletLegacyComponent`.
103 
104Adding a new portlet requires **both** the lib routes export **and** a new entry in `PORTLETS_ANGULAR`.
105 
106**In the lib** (`libs/portlets/dot-tags/src/lib/lib.routes.ts`):
107 
108```typescript
109export const dotTagsRoutes: Route[] = [
110    { path: '', component: DotTagsShellComponent }
111];
112```
113 
114**In the app shell** (`app.routes.ts`):
115 
116```typescript
117{
118    path: 'tags',
119    canActivate: [MenuGuardService],
120    canActivateChild: [MenuGuardService],
121    loadChildren: () =>
122        import('@dotcms/portlets/dot-tags/portlet').then((m) => m.dotTagsRoutes)
123}
124```
125 
126### Legacy portlets (app folder)
127 
128Portlets still under `src/app/portlets/` use NgModule-based routing (`feature-name.module.ts`, `feature-name-routing.module.ts`) and the `@portlets/...` path alias. Example: `[dot-templates](src/app/portlets/dot-templates/)`. Do not use this pattern for new work.
129 
130## Where Code Goes
131 
132See also the [Portlets](#portlets) section above for how features connect to routing.
133 
134 
135| Scope                                | Location                                             |
136| ------------------------------------ | ---------------------------------------------------- |
137| New portlet / feature                | `libs/portlets/{feature}/` — **not** inside this app |
138| UI presentational components         | `libs/ui/`                                           |
139| Service to hit dotCMS rest apis      | `libs/data-access/`                                  |
140| TypeScript interfaces / types        | `libs/dotcms-models/`                                |
141| App-level component (toolbar, login) | `apps/dotcms-ui/src/app/view/components/`            |
142| App-level service / guard            | `apps/dotcms-ui/src/app/api/services/`               |
143 
144 
145For the full decision tree, see [../../CLAUDE.md § Code Placement Rules](../../CLAUDE.md).
146 
147## Key Assets Bundled at Build Time
148 
149The build copies several vendor assets into the output:
150 
151- `node_modules/tinymce` → `/tinymce/`
152- `node_modules/monaco-editor` → `assets/monaco-editor/`
153- `libs/block-editor/src/lib/assets` → `assets/block-editor/`
154- `libs/portlets/edit-ema/portlet/src/lib/assets` → `assets/edit-ema/`
155 
156If these paths change (e.g. the block-editor moves), update `assets` in `project.json`.
157 
158## Implicit Dependencies
159 
160This app declares `"implicitDependencies": ["dotcms-webcomponents"]` in `project.json`. Changes to web components will trigger a rebuild of this app in affected-mode CI runs.