modernization(query-tool) #35709: migrate Query Tool portlet from Dojo JSP to Angular

[hmoreras]

Summary

Migrates the Query Tool portlet from the legacy Dojo/Dijit JSP to a new Angular + PrimeNG implementation, with a query-tool-legacy rollback entry preserved in portlet.xml.

Resolves #35709 (sub-task of epic #34735).

What changed

New Angular portlet — core-web/libs/portlets/dot-query-tool/

• Shell + page component + DotQueryToolStore (NgRx SignalStore) + data-access service
• PrimeNG layout: two-pane splitter, Monaco editor (plain-text Lucene), collapsible Parameters panel, stats bar + Results / Raw tabs
• Help popover with four canonical Lucene examples
• URL query-param state sync (q, offset, limit, sort, userId) replacing the legacy rememberQuery session flag — implemented as a reactive effect() using Router.createUrlTree + Location.go (canonical dot-content-drive-shell pattern) so address-bar updates do not re-mount the component
• MAX_RESULTS = 1000 cap mirroring ES Search's MAX_HITS, with a <p-message> warn when the user-supplied limit is capped
• Result row click opens the target contentlet in a new tab:
  • HTML pages → /dotAdmin/#/edit-page/content?url=…&language_id=…
  • New editor (CONTENT_EDITOR2_ENABLED=true) → /dotAdmin/#/content/{inode}
  • Legacy editor → /dotAdmin/#/c/content/{inode}
  • about:blank is opened synchronously inside the click handler to avoid popup-blocker rejection, then location.href is assigned once the async getContentType() lookup resolves
• Consumes POST /api/v1/content/_search (v1 wrapper, preferred per ContentResource JavaDoc)

Cross-portlet shared helpers (consumed by both Query Tool and ES Search)

• libs/utils: buildCurlSnippet, buildFetchSnippet (POSIX-shell-safe) + unit tests
• libs/ui: DOT_MONACO_BASE_OPTIONS, DOT_MONACO_RAW_OPTIONS
• Store: apiRequestBody computed — single source of truth for the search payload so runSearch and the curl/fetch snippets cannot drift
• DotClipboardUtil replaces hand-rolled navigator.clipboard.writeText; getDownloadLink replaces hand-rolled <a> download anchors

ES Search alignment

• Stats bar format harmonized: Showing X of Y results · N ms
• Share / Export button parity
• Tab count-badges removed from both portlets; Raw editor gains bottom padding

Backend wiring

• portlet.xml: query-tool now points at PortletController (Angular shell); query-tool-legacy entry preserved as live-toggle rollback to the existing JSP without redeploy
• PortletID: QUERY_TOOL_LEGACY added (mirrors TAGS_LEGACY precedent)
• Language.properties: com.dotcms.repackage.javax.portlet.title.query-tool-legacy = Query Tool Legacy so the legacy twin shows up under Roles → Tools (parity with es-search-legacy / tags-legacy)
• queryTool.action.run: Submit → Run (button label + empty-state hint copy); help tooltip / aria-label: Click for query examples

Tests

• Jest + Spectator coverage for shell, page, store, and service (27 passing) — limit-cap behavior, Location.go URL-sync assertions, menu-driven export tests via exportItems[i].command() + clipboard spy, error paths through httpErrorManager.handle
• New unit tests for buildCurlSnippet / buildFetchSnippet in libs/utils

Definition of Done (from epic #34735)

• Admin runs a valid Lucene query — matching contentlets render with contentTook / queryTook timings
• Admin runs an invalid Lucene query — inline error surfaced via httpErrorManager; results table unchanged
• Non-admin role blocked (server-side gate; userId forwarded only when set)
• Unlicensed instance blocked (existing license gate preserved)
• Rollback to legacy JSP without redeploy — query-tool-legacy portlet entry
• Pagination across limit-size pages with URL-synced offset

Test plan

• yarn nx test dot-query-tool — all unit tests pass
• yarn nx test dot-es-search — ES Search regression suite passes (shared helpers)
• yarn nx lint dot-query-tool clean
• yarn nx serve dotcms-ui → open Query Tool portlet as admin:
  • Valid Lucene query renders results + timings
  • Invalid query surfaces inline error, results unchanged
  • Pagination forward/back updates offset and URL params
  • Limit > 1000 shows the cap warning and capped result set
  • Share / Export (curl, fetch, JSON) copy and download correctly
  • Clicking a result opens the correct editor in a new tab (HTML page, new editor, legacy editor)
  • URL params (q, offset, limit, sort, userId) round-trip on reload
• Toggle portlet.xml to query-tool-legacy → legacy JSP renders without redeploy
• Non-admin login → portlet access denied per existing gating

🤖 Generated with Claude Code

[claude]

Claude finished @hmoreras's task in 4m 0s —— View job

---

Review

Mostly clean. The big pieces (store, shared resolver, URL sync, portlet wiring, tests) hang together well. The findings below are minor — none are blockers, but a few merit a second look before merge.

---

Worth a second look

1. onResultClick error branch is effectively dead code
core-web/libs/portlets/dot-query-tool/src/lib/dot-query-tool-page/dot-query-tool-page.component.ts:231-249

DotContentletEditUrlService.resolveEditUrl already swallows errors via catchError(() => of(null)) (see dot-contentlet-edit-url.service.ts:112), so the error: branch in onResultClick.subscribe cannot fire in practice. The placeholder.close() + #globalMessage.error() lines look like a safety net but are unreachable. Either drop the error branch or — better — give callers a way to know the resolver hit a transient lookup failure (the JSDoc currently invites callers who care to "query DotContentTypeService.getContentType() directly", which is a worse contract than just propagating).

2. Popup-blocker rejection is silent
Same file, line 237-238:

const '_blank');
if (!placeholder) return;

When a popup blocker rejects the placeholder open, the click does nothing visible. At minimum show a #globalMessage.error() so the admin understands why the click "didn't work."

3. Race: in-flight runSearch will clobber the user's mid-edit limit value
core-web/libs/portlets/dot-query-tool/src/lib/dot-query-tool-page/store/dot-query-tool.store.ts:139-175

userLimit is captured at the start of switchMap. If the user changes the limit input while the search is in flight, the next: handler does:

limit: wasCapped ? MAX_RESULTS : userLimit

…which overwrites the user's current input with the value they had when they clicked Run. For a long-running query against a big index, this is a confusing UX paper-cut. Consider only patching limit when wasCapped is true (the cap-snap is the only reason this branch needs to exist) and leaving non-capped runs alone.

4. Share-URL vs cURL/fetch snippets are sourced from different states
dot-query-tool-page.component.ts:272-285

• copyShareUrl() reads location.href, which only updates on LOADED/ERROR (via the updateQueryParamsEffect).
• copyAs('curl'|'fetch') reads store.apiRequestBody() which reflects whatever's currently in the input fields — including unsaved edits.

So after a user edits the offset but doesn't re-run, the Share-URL and the cURL snippet disagree. Probably worth either (a) syncing the URL on input change, or (b) sourcing the share URL from apiRequestBody directly so both follow the same rule.

5. PR description vs code drift: Location.go → Location.replaceState
The PR body says the URL sync uses Router.createUrlTree + Location.go. The actual code uses Location.replaceState, and the inline comment + tests both confirm replaceState. replaceState is the correct choice (avoids polluting the back stack); just update the PR description so reviewers don't get whiplash.

6. License-gate claim in DoD
The DoD says "Unlicensed instance blocked (existing license gate preserved)". The route added in app.routes.ts:176-183 does not attach DotEnterpriseLicenseResolver (the way the es-search and analytics routes do), and the legacy lucene_search.jsp has no licens|enterprise|level text either — so "preserved" is trivially true (the legacy didn't gate either). If the intent really is unlicensed instance blocked, that needs to come from the /api/v1/content/_search server side; please verify, because the DoD reads like there is a UI gate when there isn't.

---

Smaller stuff

• buildPageEditUrl falls back to urlMap for HTMLPAGE (dot-contentlet-edit-url.service.ts:125). urlMap is conceptually for URL-mapped detail pages, not HTML pages. If an HTMLPAGE ever happens to carry a urlMap value, the resolver will hand back a misleading URL. The url lookup should be sufficient for the HTMLPAGE branch — drop the urlMap fallback or document why it's there.
• userId truthiness check is userId ? rather than userId.trim() ? (store.ts:108). A whitespace-only userId will be forwarded to the server. Trivial; the server gate makes it harmless.
• parseInt is lax (dot-query-tool-page.component.ts:292-296). ?limit=1abc hydrates as 1, ?limit=1e5 as 1. Acceptable for an admin tool, but worth knowing.
• buildFetchSnippet emits JSON.stringify({ … literal object … }) at runtime, which works because JSON-stringified output is also a valid JS object literal — but the wrapping JSON.stringify(...) call is redundant if the goal is a pasteable snippet. Stylistic.
• emptyStateConfig lives in the store. core-web/libs/portlets/CLAUDE.md says the store shouldn't own UI state. This is a borderline case (the value is { title, icon, subtitle } from i18n — data, not behavior), but worth noting since the pattern propagates to other portlets.

---

Tasks

• Read changed files (Angular portlet + backend wiring)
• Review store, page component, service, and URL sync logic
• Check shared helpers (buildCurlSnippet, buildFetchSnippet, DotContentletEditUrlService)
• Check backend wiring (portlet.xml, PortletID, Language.properties, SerializationHelperTest)
• Compile findings
  • Branch: issue-35709-query-tool-angular