Skip to content

liferay/liferay-portal / workspaces/clarity-solution-workspace/.agents/skills/manage-pages

manage-pages

Verified

Create and configure site pages, navigation menus, display page templates, page templates, and SEO settings via the Headless Admin Site API. Use when the user asks to create a page, set up navigation, build a display page template for an object, or configure page SEO.

Manage Pages

Create and wire site pages, navigation menus, and page templates. The reliable path is to author pages in the site initializer (the layouts directory) and provision the site from it; live page creation through the Headless Admin Site API is kept only as a fallback. See rules/site-initializer-format.md for the source of truth and reprovision model.

When to Invoke

  • "Create a page", "add a home page", "set up the site navigation"
  • "Build a display page template for Books"
  • "Set the page title, description, and URL"
  • Called by build-site during the page composition phase

Page Types

Consult rules/page-types.md for the full table. Common types:

TypeUseAPI
Content PageFragment based layoutheadless-admin-site
Widget PagePortlet based (legacy)headless-admin-site
Display Page TemplateObject/content type landing pageheadless-admin-site
Page TemplateReusable page blueprintheadless-admin-site

Workflow

Author Pages in the Site Initializer (Primary)

Pages live in the initializer tree and come into being when the initializer is triggered. This avoids the unreliable live page creation API and keeps the page definitions in source control.

Write page.json

Create site-initializer/layouts/<NN-page-name>/page.json. The NN prefix controls creation order. Set the type, name, friendly URL, and any per role permissions (see the page.json format in rules/site-initializer-format.md):

{
	"friendlyURL": "/<page-url-slug>",
	"hidden": false,
	"name": "<Page Name>",
	"name_i18n": {
		"en_US": "<Page Name>"
	},
	"private": false,
	"type": "Content"
}

Write page-definition.json

Compose the layout in site-initializer/layouts/<NN-page-name>/page-definition.json. Reference each fragment by its key and siteKey (the fragments must exist under site-initializer/fragments/group/<collection-key>/fragments):

{
	"pageElement": {
		"pageElements": [
			{
				"definition": {
					"fragment": {
						"key": "<fragment-name>",
						"siteKey": "[$GROUP_KEY$]"
					}
				},
				"type": "Fragment"
			}
		],
		"type": "Root"
	},
	"version": "1.0"
}

The key is the fragment's directory name under the collection's fragments folder (e.g. a folder fragments/group/myco/fragments/hero → "key": "hero"). The siteKey token [$GROUP_KEY$] resolves to the current site at provision time and tells the importer the fragment lives in this site's collection (omit siteKey only for built in fragments, which use a combined key like "key": "BASIC_COMPONENT-paragraph"). Do not use collectionExternalReferenceCode/fragmentEntryKey here — the site initializer importer reads key/siteKey and silently drops any fragment element it cannot resolve, leaving the page blank.

Navigation and SEO

Set sitewide navigation and theme in site-initializer/layout-set/public/metadata.json. Per page SEO metadata lives alongside the page in page.json.

Provision

Trigger (or, for changes to the layouts directory on an existing site, reprovision) the site — delete and recreate it from the initializer. See rules/site-initializer-format.md for the commands. Because the source tree is current and object data is scoped at the company level, runtime entries survive the reprovision.

Display Object Data on a Page

To show a list of object entries on a page, use a Collection Display, rendered on the server, not a fetch on the client. A browser fetch to /o/c/<pluralLabel> carries the visitor's cookies, so the headless object API evaluates the request as the Guest user and typically returns 0 items (Guest lacks entry level view permission).

The Collection element does not sidestep that permission — it evaluates entry level permissions as the visiting user too, so an object backed listing renders empty for anonymous visitors while looking correct to you. Grant the object to Guest in resource-permissions.json before assuming the page works. See rules/guest-access.md.

Compose it in page-definition.json (see the Collection / CollectionItem element types in rules/page-types.md):

  1. Collection element — bind it to the object definition:

    {
    	"definition": {
    		"collectionConfig": {
    			"collectionReference": {
    				"className": "[$OBJECT_DEFINITION_CLASS_NAME:<Name>$]"
    			},
    			"collectionType": "CollectionProvider"
    		},
    		"numberOfItems": 20,
    		"numberOfColumns": 1,
    		"paginationType": "Numeric"
    	},
    	"type": "Collection",
    	"pageElements": [ /* one CollectionItem, below */ ]
    }
    

    Give a Collection its columns per viewport. On 2026.Q2.7 a numberOfColumns: 1 Collection with no collectionViewports renders its items col-lg-12 col-sm-1 col-1: a twelfth of the width below 768px, one word per line. Set them in the tree: "collectionViewports": [{"collectionViewportDefinition": {"numberOfColumns": 1}, "id": "landscapeMobile"}, …] for landscapeMobile, portraitMobile, and tablet gives col-12 (verified by render).

    A paginated Collection shows at most numberOfPages × numberOfItemsPerPage entries unless "displayAllPages": true, which pages through all of them; numberOfItems caps only an unpaginated one (displayAllItems lifts that). Showing every page costs nothing extra per request: the Collection fetches one page either way and takes the total from the same result, and the numeric bar prints "Showing 1 to 10 of N entries." on the server (CollectionPaginationUtil, 2026.Q2.7).

  2. CollectionItem element — nest one inside the Collection; its child pageElements are the per entry template (typically a custom card fragment from scaffold-fragment).

  3. Map fragment fields to object fields — on each editable fragment field, point the mapping at the object field and source it from the current collection item:

    "fragmentFields": [
    	{
    		"id": "<editable-id>",
    		"value": {
    			"text": {
    				"mapping": {
    					"fieldKey": "ObjectField_<field>",
    					"itemReference": {"contextSource": "CollectionItem"}
    				}
    			}
    		}
    	}
    ]
    

Setting Literal Text (Not Mapped)

The same fragmentFields array also sets a fixed value, using value_i18n where a mapped field would use mapping. Use it whenever one section fragment appears on several pages — without it every instance renders the fragment's default text, so a shared heading silently reads "Upcoming Events" on the register page:

"fragmentFields": [
	{
		"id": "<editable-id>",
		"value": {
			"fragmentLink": {},
			"text": {
				"value_i18n": {
					"en_US": "<literal text>"
				}
			}
		}
	}
]
A Literal Override Replaces the Editable's Inner Markup

The value is written as the editable region's content, so any tag inside that region is gone. A rich-text region authored as

<div class="section-heading__title" data-lfr-editable-id="title" data-lfr-editable-type="rich-text">
	<h2>Section title</h2>
</div>

renders on an overridden placement as <div class="section-heading__title" …>Coming up next</div> — verified on 2026.Q2. The <h2> is not preserved.

Two consequences, both quiet:

  • CSS targeting the inner tag stops matching. A rule written .section-heading__title h2 styles the fragment's default and nothing else, so the placements you actually ship lose their sizing. Style the wrapper class itself, or list both.
  • h1…h4 rules across the site skip these headings entirely — there is no heading element left to match. This is the trap for the master page heading rule in skills/theme-and-design/SKILL.md: the selector must name the title wrapper classes alongside the tags, or the overridden headings — the ones on every real page — silently keep the body font.

It also means the page has no <h2> where the author intended one. Make the heading tag the editable element itself, <h2 data-lfr-editable-id="title" data-lfr-editable-type="text">, and the override replaces only its text, keeping the h2. Verified on 2026.Q2 (scaffold-fragment → index.html).

Per Instance Configuration — fragmentConfig

fragmentFields sets editable regions. A sibling key, fragmentConfig, sets the fragment's configuration.json values for that one placement, and it is what lets a single fragment serve several pages with different behavior instead of forking it:

{
	"definition": {
		"fragment": {
			"key": "event-list",
			"siteKey": "[$GROUP_KEY$]"
		},
		"fragmentConfig": {
			"layout": "grid",
			"maxItems": "3",
			"showCapacity": false,
			"upcomingOnly": true
		}
	},
	"type": "Fragment"
}

fragmentConfig and fragmentFields are independent — use either, both, or neither on a placement.

Keys are the name values from configuration.json, and each value must match how that field is declared there — a checkbox takes a real JSON boolean, and a select whose validValues are strings takes the string (so "3", not 3). Verified in a site initializer page-definition.json on 2026.Q2: the same event-list fragment rendered maxItems="3" showCapacity=false layout="grid" on one page and 200 / true / rows on another. Whether a numeric select also accepts a bare number was not tested — declaring validValues as strings and passing strings is the form known to work.

This is cheap to verify without a browser. Have the fragment publish each flag as a data attribute (scaffold-fragment requires this anyway, since block directives do not run) and the values land in the server rendered HTML, where curl can assert them:

grep --extended-regexp --only-matching '<div[^>]*event-list-wrapper[^>]*' /tmp/page.html | tr ' ' '\n' | grep '^data-'

Match the class inside the tag as above rather than anchoring on class="…". A wrapper that also carries style classes (class="conference-hero-wrapper conference-hero--dark …") does not match class="conference-hero-wrapper", and the grep then returns nothing — indistinguishable from a config that never applied.

Assert on the page whose values differ from the configuration.json defaults. Those defaults are what a placement renders with no override, so a page configured to match them proves nothing about whether fragmentConfig was read at all — and defaults are usually chosen to suit the most common placement, which is exactly the page you would reach for first.

A Data Set is placed as a Fragment whose key is the renderer class com.liferay.frontend.data.set.fragment.web.internal.fragment.renderer.FDSFragmentRenderer (2026.Q2 and later; on 2026.Q1 the class is com.liferay.frontend.data.set.admin.web.internal.fragment.renderer.FDSAdminFragmentRenderer), with fragmentConfig.itemSelector pointing at the Data Set's ERC. It needs the LPD-102157 fix (2026.Q3.2). Shape and verification: skills/manage-data-sets/SKILL.md → "Place the Data Set Fragment".

Links, Forms, and Menus in the Tree

Tree keys that the live DTO names do not predict:

  • Link to an entry's display page: map the link's href with "fieldKey": "displayPageURL" and "itemReference": {"contextSource": "CollectionItem"}. It resolves to the default DPT for the type (see rules/page-types.md). A link to a specific DPT other than the default (LayoutPageTemplateEntry__ERC__<dpt-erc>) works through the live API, but the tree importer drops it silently in every shape tried on 2026.Q3.2. Make the target the default DPT, or build that URL in the fragment's JS.
  • A Form bound to another object (e.g. a form capturing leads in a drop zone on another object's DPT) takes "formConfig": {"formReference": {"className": "<the target's suffixed className, com.liferay.object.model.ObjectDefinition#XXXX>"}}. An ObjectEntry className plus classType imports cleanly and renders an empty drop zone. Write the className as the token [$OBJECT_DEFINITION_CLASS_NAME:<Name>$] rather than the suffix read from one instance: the token resolves here, in a Collection's collectionReference.className, and in display-page-template.json's contentType.className, also for an object created live outside the tree (2026.Q3.2). Use "contextSource": "DisplayPageItem" for a form on the DPT's own entity. Its field children are INPUTS-* fragments with fragmentConfig.inputFieldId: "ObjectField_<field>". Verified on 2026.Q3.2 with a real submission.
  • A Form's success redirect is formConfig.formSuccessSubmissionResult. The live DTO's successFormContainerSubmissionResult, and successFormSubmissionResult, are dropped at import without error. {"defaultDisplayPage": true} redirects to the type's default DPT and reads back as {"defaultDisplayPage": true, "type": "DisplayPage"}. A specific DPT other than the default ({"mapping": {"itemReference": {"fields": [{"fieldName": "externalReferenceCode", "fieldValue": "<dpt-erc>"}]}}}) loses the whole property at import, silently: the same limit as the link above. Verified on 2026.Q1.12, not run again on 2026.Q3.
  • "Form, then the full content" on the same entry, with a DPT other than the default: redirect from the browser. The success watcher (manage-form-containers → "Reacting to Success in the Browser") opens /web/<site>/e/<dpt-url>/<classNameId>/<entryId>, with entryId written into the fragment markup from INFO_ITEM.objectEntryId (2026.Q1.12). That URL needing classNameId is a platform gap: the ID differs per environment, no headless API exposes it, and there is no DPT URL based on an ERC (manage-data-sets). Until that changes, resolve it once at authoring time, as an administrator with Basic auth, and hardcode it: GET /api/jsonws/classname/fetch-class-name?value=<url-encoded suffixed className> → {"classNameId": "…"}. This is the one exception to "Never Recommend JSONWS" (rules/headless-apis.md): the page never calls it, and Guest gets 404 (verified on 2026.Q3.2). Say so to the user, and resolve it again on every environment the tree is promoted to. Pass it, and <dpt-url>, to the watcher's fragment as fragmentConfig values on its placement (two text fields in its configuration.json, published as data attributes), so the values specific to the environment sit in page-definition.json and not in fragment JS. <dpt-url> is the DPT's name lowercased and dashed ("White Paper Full Write-up" → white-paper-full-write-up), readable in friendlyUrlPath_i18n from GET /o/headless-admin-site/v1.0/sites/<site-erc>/display-page-templates. The whole pattern assembled: manage-form-containers → "Recipe: Gated Content on a Display Page".
  • Menu Display is placed as a Fragment whose key is the renderer's class name, com.liferay.fragment.renderer.menu.display.internal.MenuDisplayFragmentRenderer (a FragmentRenderer's key defaults to its class name; menu-display is only its collection key). Its configuration is source, displayStyle (horizontal default, or stacked), sublevels, hoveredItemColor, and selectedItemColor. Placed in a master from a site initializer tree with no fragmentConfig, it rendered for Guest on 2026.Q2.7, listing the site's public pages that are not hidden on the page's own virtual host. source is JSON encoded as a string. Use "source": "{\"siteNavigationMenuExternalReferenceCode\": \"<menu-erc>\"}" for a specific menu, or {"contextualMenu": "children"} (also parent-and-its-siblings, self-and-siblings) for relative navigation. With source absent, it renders the site's own pages. The ERC resolves at render time, so the menu may be created after the page. Read from 2026.Q3 source, not run.
  • Menu Display writes its link color with an ID (2026.Q2.7): each placement prints <style>#fragment-<id> .lfr-nav-item > a { color: inherit; } and a :hover rule with an empty color (hoveredItemColor unset). The ID outranks any class selector, so a theme's link and hover colors for menus drawn by it do nothing (the links inherit the parent's color, black in a white header). Write those rules under an ID the chrome sits in (#wrapper .my-header .lfr-nav-item > a), and set the hover there too.
  • Menu Display renders every level of a named menu on the server (2026.Q2.7): sublevels ("-1" for all, the default) becomes the navigation tag's display depth, and the horizontal style draws nested items as ul.child-menu inside ul.navbar-nav.navbar-site (NAVBAR-BLANK-FTL); stacked uses LIST-MENU-FTL. So a fragment script can rebuild it (a mega menu) when the Menu Display sits in that fragment's drop zone (a FragmentDropZone child in the tree). A node item renders with no href, and a layout item to a hidden page still renders (verified as Guest).

Mapping Limits — Denormalize Into Display Fields

Field mapping renders the raw stored value and cannot transform it. In particular:

  • DateTime values cannot be formatted through mapping (no date format option).

  • Related object fields cannot be mapped — you cannot reach across a relationship to display a field from the related entry. (A mapping picker for nested relationships exists behind the Deprecation flag LPD-60546 (stored off on a new database; see rules/feature-flags-catalog.md), but it drills into relationships of custom objects only — unmodifiable system objects like User are excluded, so an owner's full name is still unreachable; nested keys written by hand import as Unmapped.)

  • Aggregates over a relationship cannot be mapped — a count of related entries (registrations for an event, items in an order) is not a field, so it cannot be mapped.

  • Per record presentation values (e.g. a color that varies by entry) cannot be driven from mapping.

  • BASIC_COMPONENT-date cannot format an object entry's date. The fragment formats a mapped value with its dateFormat only when the value is a java.util.Date (FragmentEntryProcessorHelperImpl, instanceof Date, in the viewer's time zone), and object entries hand their dates over as LocalDateTime (ObjectEntryInfoItemFieldValuesProvider._getLocalDateTime, in the JVM default zone, UTC). What you see then depends on the release:

    • 2026.Q3.5: mapped to ObjectEntry_displayDate, _publishDate, _createDate, or _modifiedDate, it shows its own placeholder ("02/03/11 00:00 AM"). The same ObjectEntry_displayDate in a text editable (BASIC_COMPONENT-paragraph) renders "10/6/25, 5:04 PM".
    • 2026.Q2.7: it renders the raw value, 2026-10-08T20:11 (UTC, no zone), with the config.dateFormat stored but ignored (verified, editable values read from fragmententrylink).

    A Journal article's display date is a java.util.Date, so the same fragment does format that one; that is the case people remember working. For an object entry, map the date into a text editable and format it in the browser as UTC, in the site's time zone: new Intl.DateTimeFormat(lang, {dateStyle: 'long', timeZone: siteTimeZone}).format(new Date(raw + 'Z')), where siteTimeZone is the site's IANA zone (a fragment configuration value, for example). Parsing the value with no time zone as local time, as liferay-base's formatted-date fragment does, shifts it by the visitor's offset and can change the day near midnight. A report that the date fragment formatted ObjectEntry_displayDate on 2026.Q3.1 was not reproduced on 2026.Q2.7 or 2026.Q3.5.

  • An Attachment field maps only by its numeric field ID: ObjectField_<objectFieldId>#previewURL or #fileURL (the two render the same URL) in an image editable, #downloadURL in a link. ObjectField_<name> renders the file's ID as the image src. The ID differs per database, OOTB definitions included, so for a tree map an information template that prints the URL instead (rules/page-types.md, "An Attachment field's own mapping keys are not portable").

Two import behaviors that change what a migrated layout shows (verified on 2026.Q3.5):

  • A tel: link loses its href in a rich-text editable. The import sanitizes BASIC_COMPONENT-paragraph and heading values with AntiSamy, whose fragment policy (fragment-sanitizer-configuration.xml, offsiteURL) accepts only http(s), ftp, and mailto: (WARN [AntiSamySanitizerImpl:129] … tel&#58;…). The same markup in a BASIC_COMPONENT-html keeps it.
  • Demo Categorization's tags fragment works on an object entry's display page: LIFERAY_SHARED_LAYOUT_ASSET_ENTRY is set, and it lists the entry's keywords.

Converting another page builder's layout into a tree (verified on 2026.Q2.7 by import and Guest render):

  • Visibility by viewport imports and renders. "fragmentStyle": {"hidden": true} hides an element on desktop, and "fragmentViewports": [{"fragmentViewportStyle": {"hidden": false}, "id": "tablet" | "landscapeMobile" | "portraitMobile"}] shows it again below 992px, 768px, and 576px. Both land in /o/layout-common-styles/main.css as display: none / display: block rules per media query, and the content stays in the HTML (so curl text checks still see it). It works on Sections and Fragments, so the copies of a block that a source layout shows only on desktop or mobile keep their behavior. Keep it off Rows: the display: block override would replace the row's flex.
  • An element's customCSS carries what fragmentStyle cannot (verified on 2026.Q2.7, Fragments and Sections, rendered for Guest): write it against .[$FRAGMENT_CLASS$], which the page's style sheet (/o/layout-common-styles/main.css, LayoutStructureCommonStylesCSSServlet) replaces with the element's own class; the site initializer's [$…$] token substitution leaves an unknown token as written (StringUtil.replaceToStringBundler). Used for a source builder's color overlay (a ::before layer: .[$FRAGMENT_CLASS$] { isolation: isolate; position: relative; } .[$FRAGMENT_CLASS$]::before { background: …; content: ""; inset: 0; opacity: …; position: absolute; z-index: -1; }, above the section's own background color or image, below its content), a button's own colors (.[$FRAGMENT_CLASS$] .btn { … }, which outranks Clay's .btn-primary), and the boxes of each element (background, border, radius, padding). A migration that drops these renders light text written for a dark overlay on the bare background.
  • fragmentStyle values that are not tokens are written raw: "#00376c", "rgba(178,210,232,0.5)", "maxWidth": "640px", and "marginLeft": "auto" all reach the style sheet as given. Spacing keys (paddingTop, ...) take Clay spacer indexes as strings.
  • The OOTB Accordion and Tabs take their content through drop zones. BASIC_COMPONENT-accordion is one panel (title editable accordion-title, starts expanded) with one drop zone. BASIC_COMPONENT-tabs takes fragmentConfig.numberOfTabs as a string, titles in title1…titleN and drop zones "1"…"N". Nest {"definition": {"fragmentDropZoneId": "<n>"}, "pageElements": [...], "type": "FragmentDropZone"} children on the Fragment element; the content renders for Guest. The Tabs' mobile toggle says "Tab 1" in the HTML until its script writes the active title there, so a placeholder grep must skip .navbar-toggler.
  • BASIC_COMPONENT-image's "original size" (imageSize: "w-0") has no CSS rule in Classic, so a large image renders at its natural width and the fragment's overflow-hidden crops it. Use w-100 and cap the fragment with fragmentStyle.maxWidth at the size the source showed.
  • A text editable's literal value is escaped once: "Boards &amp; Commissions" renders as "Boards & Commissions", never &amp;amp;.

The workaround is to denormalize: add a plain Text display field on the object and populate it with the presentation ready value, then map that field. For example add timeLabel (a preformatted time string instead of the raw DateTime) or speakerName (the related person's name copied onto the entry), and map ObjectField_timeLabel / ObjectField_speakerName.

Denormalizing is also the way to publish a number derived from private records. To show remaining capacity, put the count on the public object — preferably an Aggregation field (function: COUNT over the relationship), which is computed on the server and ignores entry level permissions, so the visitor reads the count without the underlying rows ever being granted to Guest. A counter maintained by an object action is the fallback where no aggregate function fits; note Groovy actions are disabled by default (rules/object-actions-catalog.md). See skills/manage-objects/SKILL.md for both.

An Aggregation field is still a computed field, so the "cannot be mapped" limit above is the reason it may not reach a Collection fragment through mapping — reading it over REST from fragment JavaScript is the verified path.

Never derive a number from records the visitor cannot read. That browser call runs as the visitor and returns 0 rows with a 200, so the arithmetic yields a confidently wrong figure rather than an error. See rules/guest-access.md.

The rule is about what the fetch reads, not about fetching. Read the line above as: never count the private object in the browser. A fetch of an object the visitor legitimately holds VIEW on is fine, and is sometimes the only option.

When a Collection Element Cannot Do the Job

Prefer the Collection, which renders on the server. But it renders stored values only, so a listing needs fragment JavaScript once it requires any of these — and a realistic "upcoming events with remaining capacity" listing requires all three at once:

RequirementWhy Collection mapping cannot serve it
Filter by date (upcoming only)OData Date/DateTime filters return BAD_REQUEST, so the filtering has to happen on the client anyway (skills/manage-objects/SKILL.md)
Format a date (Oct 14–16, 2026)Mapping has no date format option — it prints the raw value
Show the venue's timeSee "Read DateTime With the UTC Getters" below — the local getters shift it to the visitor's timezone
Show an aggregate (498 of 500 seats)Aggregates cannot be mapped, per the limits above

Denormalizing into Text display fields solves the first two, but each one then needs to be kept in sync, and it cannot solve a count that changes on every submission.

So the workable shape for a public listing is: grant Guest VIEW at the company level on the public object, keep the private object write only, put the count on the public object as an Aggregation field, and let fragment JavaScript fetch the public object and do the filtering, formatting, and subtraction. Verified end to end on 2026.Q2 — an unauthenticated request returned every event with a correct registrationCount while GET /o/c/registrations returned totalCount: 0 for the same visitor.

Two details that bite:

  • Use Liferay.Util.fetch, not native fetch (skills/scaffold-client-extension/SKILL.md).
  • Aggregation serializes as a string — an event with two registrations returns "registrationCount": "2". capacity - count concatenates in JavaScript. Parse first.
Read DateTime With the UTC Getters

A DateTime field stored convertToUTC comes back as 2026-10-14T09:00:00.000Z. new Date(...) parses that correctly, but getHours() / getDate() / getDay() then render it in the browser's time zone — so a 09:00 keynote displays as 02:00 to a visitor on US Pacific, and as a different time again to everyone else. Verified on 2026.Q2: the same listing read 09:00–10:30 on the server and 02:00–03:30 in the browser.

This is worse than an ordinary bug because it is plausible. The listing renders, the layout is fine, the date is right, and only the hour is wrong — so it survives every check short of reading the number against the source data.

For an event at a fixed venue the stored value is the venue's wall clock time, so read it back the way it was written:

pad(date.getUTCHours()) + ':' + pad(date.getUTCMinutes())

Use getUTCDay(), getUTCDate(), and getUTCMonth() for the date parts too, and compare toUTCString().slice(0, 16) rather than toDateString() when testing whether a start and end fall on the same day — the local variant flips near midnight. Only reach for the local getters when the time genuinely should follow the reader (a webinar), and say so in a comment, because the next person will assume it is this bug.

Verifying this is browser work, not curl work: curl executes no JavaScript, so an empty listing and a working one produce identical HTML. See "Success Signal" below.

Create Pages via the Live API (Fallback)

Use the Headless Admin Site API (/o/headless-admin-site/v1.0) only when reprovisioning is undesirable and the change is small. It is unreliable for page creation in particular. When the MCP server is available, prefer MCP tool calls over raw curl.

Everything below has a tree equivalent that is the verified path. Reach for the live API only for the last row:

To do thisAuthor it here instead
Create a pagelayouts/<NN-name>/page.json + page-definition.json
Place fragments on a pagepage-definition.json — see "Authoring Pages" above
Navigation menusite-navigation-menus.json
Display page templatelayout-page-templates/display-page-templates/<name>
SEO settingspage.json (title_i18n, description_i18n, keywords_i18n, robots_i18n) and site-settings.json (the title suffix); canonical and Open Graph only over the live API below

Corrections to Any Live API Example

Published examples for this module — including older ones in this pack's history — predate the current DTOs. Verify against the spec (get-openapi MCP tool, or GET /o/headless-admin-site/v1.0/openapi.json) and apply these:

  • Sites are addressed by external reference code, not numeric ID, and subresources nest under /sites/<site-erc>/…. There is no top level /site-pages/{id}.
  • The DTOs use pageSpecifications, not the initializer's pageDefinition.
  • Localized fields are *_i18n maps (name_i18n, friendlyUrlPath_i18n). SitePage has no title field. This module keys those maps en-US, with a hyphen ("friendlyUrlPath_i18n": {"en-US": "/event-session-speaker-"} on a display page template, verified 2026.Q3.5), unlike the object and list type APIs' en_US; a script reading ["en_US"] gets nothing. Read both, then fall back to any locale.
  • DisplayPageTemplate binds through contentTypeReference, not flat contentType/contentSubtype. For a Liferay Object the class name is com.liferay.object.model.ObjectEntry and the subtype is the object definition's ERC.
  • A custom fragment reference uses BasicFragment + fragmentReferenceType over the live API, and key + siteKey in the initializer tree. Neither accepts collectionExternalReferenceCode/fragmentEntryKey — that form is silently dropped and the section renders blank. See "Custom Fragment Placement via the Headless API" below.
  • Three distinct type vocabularies. Live API: ContentPage / WidgetPage / LinkToURLPage / EmbeddedPage / PageSetPage / LinkToPagePage. Initializer page.json: Content / Portlet / URL / Embedded. headless-delivery uses a separate pageType.
  • Every site-pages and master-pages call requires LPD-35443 ("Page Management API", off by default). Without it they answer 400 UnsupportedOperationException ("Feature flag LPD-35443 is disabled for company …"). Verified on 2026.Q3.8.
  • Page element operations require the LPD-74328 flag.

Ensure the Site Exists

curl \
	--silent \
	--url "http://localhost:${PORT}/o/headless-admin-site/v1.0/sites" \
	--user "test@liferay.com:test" \
	| jq '[.items[] | {externalReferenceCode, name, friendlyUrlPath}]'

Save the externalReferenceCode as <site-erc>. A siteInitializer CET that declares siteExternalReferenceCode provisions its own site on deploy, so creating one by hand is usually a sign the initializer is not wired up.

Configure SEO Settings

Most of it goes in the tree (read from 2026.Q2.7 source, BundleSiteInitializer._addOrUpdateLayout): page.json takes title_i18n (the HTML title), description_i18n, keywords_i18n, and robots_i18n, locale maps, on create and on every later run (addLayout/updateLayout). Three more facts, verified on 2026.Q2.7:

  • Liferay already writes a canonical link to the page's own URL on the host it is served on (<link rel="canonical">, og:url), so a migrated canonical that only pointed at the page itself needs nothing.
  • The title's suffix is a setting for each site: <title> is "Page - Site - Instance name" by default. com.liferay.layout.seo.internal.configuration.LayoutSEOGeneralGroupConfiguration (includeInstanceName, includeSiteName) goes in site-settings.json; includeInstanceName: "false" gives "Page - Site" (LayoutSEOLinkManagerImpl._getPageTitleSuffix).
  • A display page template's SEO fields map entry fields through the layout's type settings (mapped-title, mapped-description, mapped-openGraphTitle, mapped-openGraphDescription, mapped-openGraphImage), defaulting to ${title} and ${description}. For a type with no description field, every entry page prints og:description as the literal word "description" (LayoutSEOTemplateProcessorImpl prints an unknown name as itself). Set them from the tree in the template's own page-definition.json, settings.themeSettings: the importer copies every themeSettings key into the layout's type settings (LayoutsImporterImpl._updateLayoutSettings, which removes only lfr-theme: keys first). Name object fields ${ObjectField_<name>}: {"mapped-description": "${ObjectField_subtitle}", "mapped-openGraphDescription": "${ObjectField_subtitle}"} gave both <meta name="description"> and og:description the entry's text (verified as Guest on 2026.Q2.7). Map a plain text field; a RichText one would print its markup.
  • hreflang alternates follow the site's languages. A site that inherits the instance's languages lists an alternate per enabled locale on every page, translated or not. A site's own list is its group type settings inheritLocales=false and locales=<languageIds> (LanguageImpl, then resetAvailableGroupLocales), which no site initializer file sets; with locales=en_US a page listed only en-US and x-default (2026.Q2.7). Set it from a module after the run that creates the site has committed, since that run updates the group too. Every later run of the site's initializer resets it (the run rewrites the group's type settings, and the site inherits every language again), so apply it again from a ModelListener<Group> onAfterUpdate, after commit, which a later run then leaves in English only.

What can only be set on the live site is the canonical override, Open Graph, and custom meta tags (LayoutSEOEntry). Patch the page after it exists:

curl \
	--data '{
		"customMetaTags": [
			{"key": "description", "value": "<meta description>"}
		],
		"htmlTitle": {"en_US": "<SEO Title>"},
		"seoSettings": {
			"canonicalURL": {"en_US": "<canonical-url>"},
			"description_i18n": {"en_US": "<meta description>"},
			"robots": "index,follow",
			"title_i18n": {"en_US": "<SEO Title>"}
		}
	}' \
	--header "Content-Type: application/json" \
	--request PATCH \
	--silent \
	--url "http://localhost:${PORT}/o/headless-admin-site/v1.0/sites/<site-erc>/site-pages/<page-erc>" \
	--user "test@liferay.com:test"

Because this is applied live, it is lost on reprovision. Record it as a known manual step.

Redirects (Verified on 2026.Q2.7)

Liferay's Redirection (RedirectEntry exact entries and regex patterns for each site) is what keeps an old site's URLs working, and both are per site: a request on a site's virtual host is matched against that site's entries.

  • Redirects are consulted before Liferay resolves any page or entry URL (FriendlyURLServlet.getRedirect, the redirect provider first). An exact entry whose source is a live page's URL hides the page, and a pattern matching a live URL hides every page it matches. Check every source against the site's live URLs before writing it.
  • There is no headless API and no site initializer handler for either. Write exact entries from a module through RedirectEntryLocalService.addRedirectEntry(groupId, destinationURL, null, permanent, sourceURL, serviceContext); the source has no leading slash (one is refused) and is normalized (FriendlyURLNormalizer.normalizeWithEncoding: lowercased, encoded), so compare in that form.
  • A source whose first segment is reserved is refused with a bare LayoutFriendlyURLException: the same keyword check as a page URL, so an object's friendlyURLSeparator (venue/<slug>) cannot be an exact source. A pattern is not checked that way.
  • Patterns are the group configuration com.liferay.redirect.internal.configuration.RedirectPatternConfiguration, a String[] of "<regex> <destination> <user agent>" (re2j; the regex is anchored at the start and matched against the URL without its leading slash; $1 works in the destination; user agent all, bot, or human). A pattern redirect is always a 302; an exact entry is 301 when permanent. Write them with RedirectPatternConfigurationProvider.updatePatternStrings(groupId, entries); site-settings.json cannot carry them (rules/site-initializer-format.md).
  • A destination may be relative to the root (/l/12345); the browser resolves it on the host it asked.

A plain JAX-RS application that exposes such writes must return itself from getSingletons(). Without it the whiteboard registers the application with no resource methods (jaxrs:check lists none), and every request answers 404 "No service was found".

Place a Client Extension Widget on a Page

When the user wants to add a deployed Custom Element CET to a page:

  1. Confirm the CET is verified active first (see deploy-and-verify).

  2. Ask the user which page to add it to — do not assume.

  3. If the widget is already on the page, ask whether to replace or add a new one.

  4. Place the widget via MCP, the Headless Admin Site API, or the Liferay UI depending on what the environment supports. See mcp-server for MCP availability per DXP version.

Patterns and Gotchas

Schema Discovery Before Write Operations

Never guess field names or payload shapes from memory or GET responses. Before any POST or PATCH:

  1. Read the write endpoint's schema from the OpenAPI spec (via the get-openapi MCP tool or by fetching /o/headless-admin-site/v1.0/openapi.yaml). The OpenAPI surface is the source of truth — Liferay's hosted documentation lags. GET response structure does NOT equal POST/PATCH request structure; do not infer the request shape from a GET.

  2. Discover fragment keys from an existing page definition — there is no dedicated endpoint:

    GET /headless-delivery/v1.0/sites/{siteId}/site-pages/{friendlyURL}?nestedFields=pageDefinition
    
  3. For built in fragment collection keys not present on any existing page, do NOT decompile JARs. Search the liferay-portal GitHub repository for fragment.json under modules/apps/fragment to extract fragmentEntryKey and collection keys.

The spec itself has gaps — several fields required at runtime are marked optional. See the gotchas below.

Site Creation Can 500 With Ghost Success

POST /headless-admin-site/v1.0/sites may return 500 Internal Server Error due to a background NPE or permission error in the site initializer — but the site is still created. Always verify via GET before retrying. Retrying a successful creation produces a duplicate site.

Page Specification Workflow (Draft and Publish)

Modern Content Pages use a paired specification model: every page has a main spec and a linked draft spec (draftContentPageSpecificationExternalReferenceCode, suffixed -draft). The UI Publish button overwrites the main spec with whatever is in the draft.

  • Always write page element changes to the draft spec, never the main spec. Anything written directly to the main spec is silently overwritten when the next Publish runs.

  • Resolve the draft ERC from a page GET, then target it for page-elements operations:

    GET /headless-admin-site/v1.0/sites/{siteId}/site-pages/{friendlyURL}
    → use draftContentPageSpecificationExternalReferenceCode for subsequent POST/PUT
    
  • Publish with PUT /o/headless-admin-site/v1.0/sites/{siteERC}/site-pages/{pageERC}. The POST /page-specifications/{specERC}/publish endpoint is a stub — it returns 204 and does nothing.

  • pageSpecifications[] on the PUT must include both the published spec (status: "Approved") and the draft spec; the published spec references the draft via draftContentPageSpecificationExternalReferenceCode.

  • PUT /sites/{siteERC}/site-pages/{pageERC} is an upsert — it creates the page when the ERC does not exist and updates it when it does, so scripted page provisioning is safe to run again.

  • The draft spec appears asynchronously after page creation. Immediately after the create PUT, GET .../page-specifications can come back empty for a second or two — poll (a few retries with ~2 s delays) for the draft spec before writing elements or publishing, or the next call fails on a page that is actually fine.

A content page's specification cannot be PATCHed (verified on 2026.Q3.5): PATCH /sites/{siteERC}/page-specifications/{specERC} answers 400 "The page specification must be in draft status for content pages", the -draft specification of a published page included. To set a page's master or a placed fragment's configuration values, PUT the whole page: its GET plus pageSpecifications from GET …/site-pages/{erc}/page-specifications, changed only in settings.masterPageItemExternalReference and an element's fragmentInstance.fragmentConfigurationFieldValues ({"<field>": {"type": "Text", "value": "…"}}), on both specifications. Both took, and every fragment link was kept. When the site initializer later imported the page again, it reset the configuration values and kept the master.

Required fields missing from the OpenAPI spec (omitting any of these causes a server error):

  • pageSettings: {"type": "ContentPageSettings"} at the top level
  • pageExperiences[] with at least one entry per spec
  • name_i18n on each pageExperience

ERC suffixes autogenerated on page creation: draft spec is {pageERC}-draft, published experience is {pageERC}-default, draft experience is {pageERC}-draft-default.

A successful PUT response code is not a reliable success signal — verify by issuing an HTTP GET on the page URL.

Two more traps when you PUT the whole page:

  • It replaces the Master Page assignment along with everything else. The master lives in each spec's settings.masterPageItemExternalReference ({"externalReferenceCode": "<master-erc>"}, the ERC from GET .../master-pages). A body without that field, or without the settings block, returns 200 and removes the master: the page renders with no header or footer. Verified live on 2026.Q3.2:
    • To keep the master, send the GET back unchanged. The PUT accepts the fields that are read only as they come.
    • To set or restore it, put the reference on the published spec, which drives the render. On the -draft spec alone, no master renders, so set it on both. It can also be set at page creation.
    • Leave scope out of the reference. A reference carrying one returns 400 IllegalArgumentException ("…do not belong to the same scope…").
    • Validation depends on what the ERC names. A display page template is rejected with 400 ("…does not point to a master page"), and the page stays unchanged; a page template takes the same code path (from source), though only the DPT case was run. An ERC that names no LayoutPageTemplateEntry is accepted: a typo, a page's ERC, or a utility page's ERC (LFR-404-ERROR). The response is 200, the GET returns that ERC, and the page renders with no master. The only trace is a WARN [LogUtil:34] Optional reference generated for missing LayoutPageTemplateEntry with external reference code <erc>, logged once per spec. So check the ERC against GET .../master-pages before the PUT, and check the rendered page after it — neither the 200 nor the GET proves the master exists.
    • Such a dangling reference resolves at render time. Create a master with that exact ERC later (POST .../master-pages with a chosen externalReferenceCode returns 200) and the page picks it up with no new PUT. So a page can reference a master that a later deploy step creates.
  • Scoping a globalJS/globalCSS CET to one page goes in the spec's settings.globalJSClientExtensions / globalCSSClientExtensions. The shape is {"clientExtensionConfig": {"loadType": "default", "scriptLocation": "head"}, "externalReferenceCode": "LXC:<cet-key>"}. A bare {"externalReferenceCode": "<cet-key>"} returns 200, round trips on GET, and loads nothing. Shape taken from a Page Editor write and diffed, and verified on 2026.Q3.2. This live PUT is the way to bind a CET to one page: in the initializer tree the same settings keys work on a master only (rules/site-initializer-format.md).

headless-admin-site Schema Gotchas

type vs pageType — field names differ by API. headless-delivery uses pageType (plain string). headless-admin-site uses type (enum: ContentPage, WidgetPage, etc.). Using type against the delivery API returns 400 - The property "type" is not defined in SitePage.

FragmentReference uses a nonstandard discriminator. Every other polymorphic schema in headless-admin-site uses type. FragmentReference is the exception — it uses fragmentReferenceType. Using "type": "DefaultFragmentReference" returns 400 InvalidTypeIdException: missing type id property 'fragmentReferenceType'.

position is required despite the spec marking it optional. Omitting position from a page element POST returns 500 NullPointerException. Always include "position": 0 (or the intended 0 based index).

Building a form? skills/manage-form-containers/SKILL.md holds the full Form Container contract: field fragment keys per type, the submit button, multistep, success results, and the ADD_OBJECT_ENTRY grant without which the form does not render. The notes below cover the page API side of it.

FormContainerConfig.numberOfSteps is required despite the spec marking it optional. Same pattern — omitting it returns 500 NullPointerException (FormContainerConfig.getNumberOfSteps() is null). The value itself is lenient: 0 and 1 both give a working form with one step, with formContainerType Simple or Multistep. What the platform itself produces is "formContainerType": "Multistep", "numberOfSteps": 0 (verified 2026.Q3.2).

FormFragment elements nest via parentExternalReferenceCode. The POST endpoint for page elements is flat — all elements hit the same endpoint regardless of nesting depth. Parent child relationships are expressed through parentExternalReferenceCode, not nested objects. Key fields for FormFragment children:

  • fieldKey — binds the input to an Object field. The platform writes ObjectField_<name>, and a bare <name> binds too. A FormFragment without fieldKey still submits and shows the success message, but stores an empty value, so an unbound field reads as a successful form. The submit button (INPUTS-submit-button) needs no fieldKey; "formButton" is harmless. Verified on 2026.Q3.2 with real submissions.
  • fragmentInstance.fragmentReference.defaultFragmentKey — the INPUTS fragment key
  • label_i18n — localized label
  • markAsRequired — boolean
  • showLabel — boolean

Display page templates and master pages are writable the same way on 2026.Q3.2. A PUT of the whole resource at /sites/{siteERC}/display-page-templates/{erc} or /master-pages/{erc} carries both page specifications, like a site page. So does a PATCH of pageSpecifications. It returns 200, and the change renders on the DPT. POST …/page-specifications still fails with 400 "The draft page specification is not in draft status". Inline text in a fragment goes in htmlFragmentValue: {"type": "Inline", "fragmentInlineValue": {"value_i18n": {…}}}; the only type IDs are Inline and Mapped.

Changing One Element in Place (Verified on 2026.Q3.5)

To change one placed fragment (an image URL, a text) without replacing the page, use the element endpoint …/sites/{siteERC}/page-specifications/{specERC}/page-experiences/{experienceERC}/page-elements/{elementERC} (flag LPD-74328):

  • PATCH silently does nothing. It answers 200 with the element, and moves the link's modifieddate, but the stored editablevalues do not change.
  • PUT works. Send the element exactly as that spec's GET …/page-specifications returns it, with only the value changed, plus parentExternalReferenceCode and position. It updates the link in place: same link ID, no new rows, and the page renders the new value.
  • Live and draft each need their own body. Element ERCs are the same in both specs, but each element's fragmentInstance.fragmentInstanceExternalReferenceCode names that spec's own link. The live body sent to the draft answers 400 UnsupportedOperationException.
  • A background image editable does not come back when read. An imported fragment with data-lfr-background-image-id stores the value under BackgroundImageFragmentEntryProcessor and an empty {} under EditableFragmentEntryProcessor. FragmentEditableElementUtil merges the two and the empty one wins, so the element comes back with no editable value. A PUT of that body cannot set it, and could clear it. A container's fragmentStyle background, by contrast, does come back.

Custom Fragment Placement via the Headless API

When placing custom fragments via PUT /sites/{siteERC}/site-pages/{pageERC}, inline the fragment's html and css on the fragmentInstance. Both the draft and published specs must carry the same inlined content — otherwise the UI's next Publish reverts the affected sections to empty divs.

Discriminators for fragment placement:

  • Page element type: "type": "BasicFragment" (not "Fragment")
  • Fragment reference: keyed by "fragmentReferenceType" (not "type")
  • Custom fragments: "fragmentReferenceType": "FragmentItemExternalReference" with "externalReferenceCode": "<fragmentEntryKey>" — the fragment entry key IS the ERC
  • Out of the box fragments: "fragmentReferenceType": "DefaultFragmentReference" with defaultFragmentKey — inlining not required

Fragment Management API

Fragment CRUD lives in its own module, headless-admin-fragment — not in headless-admin-site, which is why it looks absent when you check the page API's spec. It is verified working on 2026.Q2 and absent on 2026.Q1, but it does not propagate edits to fragments already placed on a page. See skills/scaffold-fragment/SKILL.md → "The Live Fragment API". For programmatic placement on pages, use the discriminators above.

Success Signal

Applies to both paths — a page authored in the initializer tree and one created over the live API.

curl --head --silent --url "http://localhost:${PORT}/web/<site-friendly-url>/<page-url-slug>"

Expect 200 OK.

200 OK is not evidence the page works. A page whose Collection returned no rows, whose fragment reused another page's placeholder text, or whose mapping silently failed all return 200 with fragments present. Verify content, and verify it as the audience:

  1. Probe without credentials. curl with no --user and no cookie jar is exactly a Guest request, and it is the only cheap way to see what a visitor sees. Signed in verification hides every permission gap in this skill — see rules/guest-access.md.

    curl --silent --url "http://localhost:${PORT}/web/<site>/<page>" > /tmp/page.html
    
  2. Assert real data, not markup presence. Grep for a value that only exists in the database (an actual event name) and confirm the fragment's placeholder strings are absent — placeholders still present means the mapping did not resolve.

  3. Check each page's own text. Reusing a section fragment across pages carries its default text with it; a heading that reads "Upcoming Events" on the register page is a 200 with wrong content. Set per page values with a literal fragmentFields entry rather than relying on the fragment default.

  4. Check that every page has a heading. Each page needs at least one h1–h3, with an h1 on the home page, or it has no outline and the site's heading style has nothing to apply to. A count of 0 on a page whose title is overridden means the heading is wrapped inside a rich-text region (see "A Literal Override Replaces the Editable's Inner Markup").

    curl --silent --url "http://localhost:${PORT}/web/<site>/<page>" | grep --count --extended-regexp '<h[1-3][ >]'
    
  5. Open it in a browser before declaring success. Anything driven by JavaScript — a computed value, a populated select — is invisible to curl, which executes none of it. Confirm signed out too: sign in state changes what calls on the client return.

receiving-code-reviewobra/superpowersUse when receiving code review feedback, before implementing suggestions, especially if feedback seems unclear or technically questionable - requires technical rigor and verification, not performative agreement or blind implementationStars: 322kUpdated Claude CodeCodexVerifiedInstall
requesting-code-reviewobra/superpowersUse when completing tasks, implementing major features, or before merging to verify work meets requirementsStars: 322kUpdated Claude CodeCodexVerifiedInstall
using-git-worktreesobra/superpowersUse when starting feature work that needs isolation from current workspace or before executing implementation plans - ensures an isolated workspace exists via native tools or git worktree fallbackStars: 322kUpdated Claude CodeCodexVerifiedInstall
verification-before-completionobra/superpowersUse when about to claim work is complete, fixed, or passing, before committing or creating PRs - requires running verification commands and confirming output before making any success claims; evidence before assertions alwaysStars: 322kUpdated Claude CodeCodexVerifiedInstall