liferay/liferay-portal / workspaces/clarity-solution-workspace/.agents/skills/manage-pages
manage-pages
VerifiedCreate 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-siteduring the page composition phase
Page Types
Consult rules/page-types.md for the full table. Common types:
| Type | Use | API |
|---|---|---|
| Content Page | Fragment based layout | headless-admin-site |
| Widget Page | Portlet based (legacy) | headless-admin-site |
| Display Page Template | Object/content type landing page | headless-admin-site |
| Page Template | Reusable page blueprint | headless-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.jsonbefore assuming the page works. Seerules/guest-access.md.
Compose it in page-definition.json (see the Collection / CollectionItem element types in rules/page-types.md):
-
Collectionelement — 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: 1Collection with nocollectionViewportsrenders its itemscol-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"}, …]forlandscapeMobile,portraitMobile, andtabletgivescol-12(verified by render).A paginated Collection shows at most
numberOfPages × numberOfItemsPerPageentries unless"displayAllPages": true, which pages through all of them;numberOfItemscaps only an unpaginated one (displayAllItemslifts 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). -
CollectionItemelement — nest one inside the Collection; its childpageElementsare the per entry template (typically a custom card fragment fromscaffold-fragment). -
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 h2styles 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…h4rules 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 inskills/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
hrefwith"fieldKey": "displayPageURL"and"itemReference": {"contextSource": "CollectionItem"}. It resolves to the default DPT for the type (seerules/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
Formbound 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>"}}. AnObjectEntryclassName plusclassTypeimports 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 aCollection'scollectionReference.className, and indisplay-page-template.json'scontentType.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 areINPUTS-*fragments withfragmentConfig.inputFieldId: "ObjectField_<field>". Verified on 2026.Q3.2 with a real submission. - A
Form's success redirect isformConfig.formSuccessSubmissionResult. The live DTO'ssuccessFormContainerSubmissionResult, andsuccessFormSubmissionResult, 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>, withentryIdwritten into the fragment markup fromINFO_ITEM.objectEntryId(2026.Q1.12). That URL needingclassNameIdis 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 gets404(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 asfragmentConfigvalues on its placement (twotextfields in itsconfiguration.json, published as data attributes), so the values specific to the environment sit inpage-definition.jsonand 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 infriendlyUrlPath_i18nfromGET /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
Fragmentwhosekeyis the renderer's class name,com.liferay.fragment.renderer.menu.display.internal.MenuDisplayFragmentRenderer(aFragmentRenderer's key defaults to its class name;menu-displayis only its collection key). Its configuration issource,displayStyle(horizontaldefault, orstacked),sublevels,hoveredItemColor, andselectedItemColor. Placed in a master from a site initializer tree with nofragmentConfig, 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.sourceis JSON encoded as a string. Use"source": "{\"siteNavigationMenuExternalReferenceCode\": \"<menu-erc>\"}"for a specific menu, or{"contextualMenu": "children"}(alsoparent-and-its-siblings,self-and-siblings) for relative navigation. Withsourceabsent, 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:hoverrule with an empty color (hoveredItemColorunset). 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 asul.child-menuinsideul.navbar-nav.navbar-site(NAVBAR-BLANK-FTL);stackedusesLIST-MENU-FTL. So a fragment script can rebuild it (a mega menu) when the Menu Display sits in that fragment's drop zone (aFragmentDropZonechild in the tree). Anodeitem renders with nohref, and alayoutitem 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:
-
DateTimevalues 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; seerules/feature-flags-catalog.md), but it drills into relationships of custom objects only — unmodifiable system objects likeUserare 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-datecannot format an object entry's date. The fragment formats a mapped value with itsdateFormatonly when the value is ajava.util.Date(FragmentEntryProcessorHelperImpl,instanceof Date, in the viewer's time zone), and object entries hand their dates over asLocalDateTime(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 sameObjectEntry_displayDatein 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 theconfig.dateFormatstored but ignored (verified, editable values read fromfragmententrylink).
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')), wheresiteTimeZoneis the site's IANA zone (a fragment configuration value, for example). Parsing the value with no time zone as local time, as liferay-base'sformatted-datefragment does, shifts it by the visitor's offset and can change the day near midnight. A report that the date fragment formattedObjectEntry_displayDateon 2026.Q3.1 was not reproduced on 2026.Q2.7 or 2026.Q3.5. - 2026.Q3.5: mapped to
-
An
Attachmentfield maps only by its numeric field ID:ObjectField_<objectFieldId>#previewURLor#fileURL(the two render the same URL) in an image editable,#downloadURLin a link.ObjectField_<name>renders the file's ID as the imagesrc. 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 arich-texteditable. The import sanitizesBASIC_COMPONENT-paragraphand heading values with AntiSamy, whose fragment policy (fragment-sanitizer-configuration.xml,offsiteURL) accepts onlyhttp(s),ftp, andmailto:(WARN [AntiSamySanitizerImpl:129] … tel:…). The same markup in aBASIC_COMPONENT-htmlkeeps it. - Demo Categorization's
tagsfragment works on an object entry's display page:LIFERAY_SHARED_LAYOUT_ASSET_ENTRYis 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.cssasdisplay: none/display: blockrules per media query, and the content stays in the HTML (socurltext 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: thedisplay: blockoverride would replace the row's flex. - An element's
customCSScarries whatfragmentStylecannot (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::beforelayer:.[$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. fragmentStylevalues 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-accordionis one panel (title editableaccordion-title, starts expanded) with one drop zone.BASIC_COMPONENT-tabstakesfragmentConfig.numberOfTabsas a string, titles intitle1…titleNand 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'soverflow-hiddencrops it. Usew-100and cap the fragment withfragmentStyle.maxWidthat the size the source showed.- A text editable's literal value is escaped once:
"Boards & Commissions"renders as "Boards & Commissions", never&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:
| Requirement | Why 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 time | See "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 nativefetch(skills/scaffold-client-extension/SKILL.md). Aggregationserializes as a string — an event with two registrations returns"registrationCount": "2".capacity - countconcatenates 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 this | Author it here instead |
|---|---|
| Create a page | layouts/<NN-name>/page.json + page-definition.json |
| Place fragments on a page | page-definition.json — see "Authoring Pages" above |
| Navigation menu | site-navigation-menus.json |
| Display page template | layout-page-templates/display-page-templates/<name> |
| SEO settings | page.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'spageDefinition. - Localized fields are
*_i18nmaps (name_i18n,friendlyUrlPath_i18n).SitePagehas notitlefield. This module keys those mapsen-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. DisplayPageTemplatebinds throughcontentTypeReference, not flatcontentType/contentSubtype. For a Liferay Object the class name iscom.liferay.object.model.ObjectEntryand the subtype is the object definition's ERC.- A custom fragment reference uses
BasicFragment+fragmentReferenceTypeover the live API, andkey+siteKeyin the initializer tree. Neither acceptscollectionExternalReferenceCode/fragmentEntryKey— that form is silently dropped and the section renders blank. See "Custom Fragment Placement via the Headless API" below. - Three distinct
typevocabularies. Live API:ContentPage/WidgetPage/LinkToURLPage/EmbeddedPage/PageSetPage/LinkToPagePage. Initializerpage.json:Content/Portlet/URL/Embedded.headless-deliveryuses a separatepageType. - Every
site-pagesandmaster-pagescall requiresLPD-35443("Page Management API", off by default). Without it they answer400 UnsupportedOperationException("Feature flag LPD-35443 is disabled for company …"). Verified on 2026.Q3.8. - Page element operations require the
LPD-74328flag.
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 insite-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 nodescriptionfield, every entry page printsog:descriptionas the literal word "description" (LayoutSEOTemplateProcessorImplprints an unknown name as itself). Set them from the tree in the template's ownpage-definition.json,settings.themeSettings: the importer copies everythemeSettingskey into the layout's type settings (LayoutsImporterImpl._updateLayoutSettings, which removes onlylfr-theme:keys first). Name object fields${ObjectField_<name>}:{"mapped-description": "${ObjectField_subtitle}", "mapped-openGraphDescription": "${ObjectField_subtitle}"}gave both<meta name="description">andog:descriptionthe entry's text (verified as Guest on 2026.Q2.7). Map a plain text field; a RichText one would print its markup. hreflangalternates 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 settingsinheritLocales=falseandlocales=<languageIds>(LanguageImpl, thenresetAvailableGroupLocales), which no site initializer file sets; withlocales=en_USa page listed onlyen-USandx-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 aModelListener<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'sfriendlyURLSeparator(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, aString[]of"<regex> <destination> <user agent>"(re2j; the regex is anchored at the start and matched against the URL without its leading slash;$1works in the destination; user agentall,bot, orhuman). A pattern redirect is always a302; an exact entry is301when permanent. Write them withRedirectPatternConfigurationProvider.updatePatternStrings(groupId, entries);site-settings.jsoncannot 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:
-
Confirm the CET is verified active first (see
deploy-and-verify). -
Ask the user which page to add it to — do not assume.
-
If the widget is already on the page, ask whether to replace or add a new one.
-
Place the widget via MCP, the Headless Admin Site API, or the Liferay UI depending on what the environment supports. See
mcp-serverfor 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:
-
Read the write endpoint's schema from the OpenAPI spec (via the
get-openapiMCP 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. -
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 -
For built in fragment collection keys not present on any existing page, do NOT decompile JARs. Search the liferay-portal GitHub repository for
fragment.jsonundermodules/apps/fragmentto extractfragmentEntryKeyand 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-elementsoperations: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}. ThePOST /page-specifications/{specERC}/publishendpoint 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 viadraftContentPageSpecificationExternalReferenceCode. -
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-specificationscan 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 levelpageExperiences[]with at least one entry per specname_i18non eachpageExperience
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 fromGET .../master-pages). A body without that field, or without thesettingsblock, returns200and 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
-draftspec alone, no master renders, so set it on both. It can also be set at page creation. - Leave
scopeout of the reference. A reference carrying one returns400 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 noLayoutPageTemplateEntryis accepted: a typo, a page's ERC, or a utility page's ERC (LFR-404-ERROR). The response is200, the GET returns that ERC, and the page renders with no master. The only trace is aWARN [LogUtil:34] Optional reference generated for missing LayoutPageTemplateEntry with external reference code <erc>, logged once per spec. So check the ERC againstGET .../master-pagesbefore the PUT, and check the rendered page after it — neither the200nor the GET proves the master exists. - Such a dangling reference resolves at render time. Create a master with that exact ERC later (
POST .../master-pageswith a chosenexternalReferenceCodereturns200) 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/globalCSSCET to one page goes in the spec'ssettings.globalJSClientExtensions/globalCSSClientExtensions. The shape is{"clientExtensionConfig": {"loadType": "default", "scriptLocation": "head"}, "externalReferenceCode": "LXC:<cet-key>"}. A bare{"externalReferenceCode": "<cet-key>"}returns200, 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 samesettingskeys 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.mdholds the full Form Container contract: field fragment keys per type, the submit button, multistep, success results, and theADD_OBJECT_ENTRYgrant 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 writesObjectField_<name>, and a bare<name>binds too. AFormFragmentwithoutfieldKeystill 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 nofieldKey;"formButton"is harmless. Verified on 2026.Q3.2 with real submissions.fragmentInstance.fragmentReference.defaultFragmentKey— the INPUTS fragment keylabel_i18n— localized labelmarkAsRequired— booleanshowLabel— 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):
PATCHsilently does nothing. It answers200with the element, and moves the link'smodifieddate, but the storededitablevaluesdo not change.PUTworks. Send the element exactly as that spec'sGET …/page-specificationsreturns it, with only the value changed, plusparentExternalReferenceCodeandposition. 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.fragmentInstanceExternalReferenceCodenames that spec's own link. The live body sent to the draft answers400 UnsupportedOperationException. - A background image editable does not come back when read. An imported fragment with
data-lfr-background-image-idstores the value underBackgroundImageFragmentEntryProcessorand an empty{}underEditableFragmentEntryProcessor.FragmentEditableElementUtilmerges the two and the empty one wins, so the element comes back with no editable value. APUTof that body cannot set it, and could clear it. A container'sfragmentStylebackground, 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"withdefaultFragmentKey— 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:
-
Probe without credentials.
curlwith no--userand 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 — seerules/guest-access.md.curl --silent --url "http://localhost:${PORT}/web/<site>/<page>" > /tmp/page.html -
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.
-
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
fragmentFieldsentry rather than relying on the fragment default. -
Check that every page has a heading. Each page needs at least one
h1–h3, with anh1on the home page, or it has no outline and the site's heading style has nothing to apply to. A count of0on a page whose title is overridden means the heading is wrapped inside arich-textregion (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][ >]' -
Open it in a browser before declaring success. Anything driven by JavaScript — a computed value, a populated
select— is invisible tocurl, which executes none of it. Confirm signed out too: sign in state changes what calls on the client return.
Related skills
| Skill | Stars | Updated | Works with | Status | Install |
|---|---|---|---|---|---|
| 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 implementation | Stars: 322k | Updated | Claude CodeCodex | Verified | Install |
| requesting-code-reviewobra/superpowersUse when completing tasks, implementing major features, or before merging to verify work meets requirements | Stars: 322k | Updated | Claude CodeCodex | Verified | Install |
| 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 fallback | Stars: 322k | Updated | Claude CodeCodex | Verified | Install |
| 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 always | Stars: 322k | Updated | Claude CodeCodex | Verified | Install |