liferay/liferay-portal / workspaces/clarity-solution-workspace/.agents/skills/scaffold-form-fragment
scaffold-form-fragment
VerifiedCreate a Liferay input fragment that lives inside a Form Container and binds to an object field. Use when the user asks to build a form field, add a custom input to a form, create a picker or stepper for a form, or make a fragment that submits to an object.
Scaffold Form Fragment
Build a fragment of type input — a form field an author drops into a Form Container, which binds it to a field on the container's object.
When to Invoke
- "Build a form field", "add a custom input to a form", "make a date picker for this form"
- "Create a fragment that submits to an object"
- Called by
scaffold-fragmentwhen the fragment being built is a form field rather than a display component
For a display fragment — hero, card, section — use scaffold-fragment instead. Everything about collections, naming, deploy, and reprovision lives there and is not repeated here.
Prerequisites
- A published object with the target field. Load
manage-objects; an unpublished definition exposes no fields to bind against. - A page carrying a Form Container bound to that object. Load
manage-pages.
No feature flag gates input fragments.
Workflow
Declare the Fragment as an Input
fragment.json needs two things beyond a normal fragment: "type": "input", and a typeOptions block naming the field types the fragment can bind to.
{
"cacheable": false,
"fragmentEntryKey": "brand-email-input",
"icon": "envelope-closed",
"name": "Brand Email Input",
"type": "input",
"typeOptions": {
"fieldTypes": [
"email"
]
}
}
fieldTypes is nested inside typeOptions — not a top level key. typeOptions is schema validated with additionalProperties: false, so fieldTypes is the only key it accepts.
Declare only the types the fragment actually renders. The Form Container offers the fragment for a field whose type appears in this list, so an overly broad list surfaces the fragment where it cannot work.
| Field Type | Object Field It Binds To |
|---|---|
boolean | Boolean |
captcha | None — renders a CAPTCHA, not a field |
date | Date |
date-time | Date and Time |
email | Text constrained to email |
file | Attachment |
formButton | None — renders the submit control |
friendly-url | Text constrained to a friendly URL |
html | Rich Text |
long-text | Long Text |
multiselect | Picklist, multiple values |
number | Integer, Decimal, Precision Decimal |
phone-number | Text constrained to a phone number |
relationship | Relationship |
select | Picklist, single value |
stepper | None — renders form step navigation |
text | Text |
Set "cacheable": false. Liferay refuses to cache an input fragment regardless, and stating it keeps the file honest.
Source: FragmentEntryValidatorImpl and the built in input fragments under modules/apps/fragment/fragment-collection-contributor/fragment-collection-contributor-inputs.
Render the Field
The container injects an input object into the template. Read the field's label, value, and state from it — never hardcode them, and never invent a name.
| Property | Type | Holds |
|---|---|---|
input.attributes | map | Type specific metadata, plus readOnly. Contents vary by field type |
input.errorMessage | string | Validation message from the server; empty when valid |
input.helpText | string | Author supplied help text |
input.label | string | The field label |
input.localizable | boolean | Whether the field stores a value per locale |
input.name | string | The name attribute the container reads on submit |
input.readOnly | boolean | Whether the field rejects edits |
input.required | boolean | Whether the field is mandatory |
input.showHelpText | boolean | Whether the author chose to show help text |
input.showLabel | boolean | Whether the author chose to show the label |
input.type | string | The bound field's type |
input.value | string | Current value, populated when editing an existing entry |
input.valueI18n | map | Per locale values, keyed by language ID |
${input.name} is the whole binding. The container maps the submitted value to the object field by that name, so a hardcoded or misspelled name submits nothing and reports no error.
Namespace every id with ${fragmentElementId} so the fragment survives being placed twice on one page.
<div class="form-group [#if input.errorMessage?has_content]has-error[/#if] mb-0" id="${fragmentElementId}-form-group">
<label class="[#if !input.showLabel || !input.label?has_content]sr-only[/#if]" for="${fragmentElementId}-input" id="${fragmentElementId}-input-label">${htmlUtil.escape(input.label)}
[#if input.required][@clay["icon"] className="reference-mark" symbol="asterisk" /][/#if]</label>
<input class="form-control" id="${fragmentElementId}-input" name="${input.name}" [#if input.readOnly]readonly[/#if] ${input.required?then('required', '')} type="email" [#if input.value??]value="${input.value}"[/#if] />
[#if input.showHelpText && input.helpText?has_content]
<p class="mb-0 mt-1 text-secondary" id="${fragmentElementId}-input-help-text">${htmlUtil.escape(input.helpText)}</p>
[/#if]
</div>
Escape input.label and input.helpText with htmlUtil.escape in the template. The JSON handed to index.js is already escaped; the FreeMarker object is not.
Use Lexicon classes (form-group, form-control, has-error, sr-only) and the Clay icon macro so the field matches every other field in the container.
Wire the Value
Three things belong in index.js.
Disable the control in edit mode. layoutMode is 'edit' while an author composes the page. Leaving the field live lets an author type into a form they are only arranging.
const inputElement = document.getElementById(`${fragmentElementId}-input`);
if (layoutMode === 'edit') {
inputElement.setAttribute('disabled', true);
}
Register the field so error rendering and localization behave like the built in inputs. @liferay/fragment-impl/api exposes registerInputFeedback for error display, and registerLocalizedInput / registerUnlocalizedInput for value handling. Branch on input.localizable — a localizable field needs the per locale inputs the helper creates, and skipping it silently drops every locale but the default.
Sync custom UI to a hidden input. A slider, a map picker, or a multi select built from divs submits nothing on its own. Carry a hidden input named ${input.name}, write to it, and dispatch a bubbling change so the container notices.
customControl.addEventListener('change', (event) => {
hiddenInput.value = event.target.value;
hiddenInput.dispatchEvent(new Event('change', {bubbles: true}));
});
Without the dispatched event the value sits in the DOM and the container reads the previous one.
Deploy and Place
Deploy exactly as a display fragment — the fragment lives in the site initializer tree and appears when the site is provisioned. See scaffold-fragment for the file layout and rules/site-initializer-format.md for the reprovision recipe.
Then bind it: open the page, select the Form Container's field, and choose the fragment from the field's input list. It appears only for fields whose type is in typeOptions.fieldTypes.
When the field is placed through the live page API instead, send the fragment's real html, css, and js on the FormFragment's fragmentInstance. With an empty html, the field renders empty and submits nothing, silently (verified on 2026.Q3.2; see manage-form-containers).
A CMS File Picker Input
DXP has no picker that browses CMS files from a site page (manage-form-containers, "Fields"). A custom file input can: browse a Space over /o/search/v1.0/search and write the picked file's DLFileEntry ID (embedded.file.id) into a hidden input named ${input.name}, which is what the stock input posts and what an edit form fills in (input.value, with the name in input.attributes.fileName). input.attributes.allowedFileExtensions (.pdf,.txt,.srt) and maxFileSize (MB, 0 for no limit) say what the field accepts. A hidden input is never validated by the browser, so check a required one yourself on the form's submit. Verified on 2026.Q3.5 with a Form Container, a DPT edit form and a form in a modal. The liferay-base project ships two, base-cms-file-upload and base-cms-image-upload (base-form-fragment-site-initializer), whose code is the import map module @liferay-base/cms-picker (base-cms-picker-js).
The viewer sees what search lets them see, which for a Space's depot role grants means its members only.
Patterns and Gotchas
Four fieldTypes mistakes throw and abort the fragment import — the collection fails to load and the fragment never appears:
| Condition | Message |
|---|---|
captcha listed alongside any other field type | Captcha field type cannot be mixed with other field types |
fieldTypes present on any type other than input | Only fragment type input can have field types |
stepper listed alongside any other field type | Stepper field type cannot be mixed with other field types |
type: "input" with an empty or absent fieldTypes | Fragment type input must have at least one field type |
input exists only for type: "input". The renderer injects it behind an isTypeInput() check, so referencing input from a component or section fragment throws a reference error at render. configuration, fragmentElement, fragmentElementId, and fragmentEntryLinkNamespace are injected for every fragment type.
Use fragmentElementId, not fragmentEntryLinkNamespace, for element IDs. Both are injected, and the built in input fragments use fragmentElementId throughout — matching them keeps IDs consistent with the helpers in @liferay/fragment-impl/api, which take it as their namespace.
A hidden field still submits. CSS display: none removes a conditionally shown field from view and leaves it in the form, so it posts a value the visitor never entered. Remove it from the DOM in index.js instead. Conditional visibility built with <lfr-drop-zone> has the same trap — see scaffold-fragment → "Drop Zones".
Public forms are write only. A form open to anonymous visitors needs ADD_OBJECT_ENTRY and not VIEW on the object; VIEW at the company level publishes every submission to the world. The visitor's own POST still returns the created entry, so the fragment can confirm back what was recorded. Read rules/guest-access.md before exposing a form on a public page.
Edit mode styling. An input fragment with scroll animations or collapsed sections needs the has-edit-mode-menu treatment so an author can reach the field. See scaffold-fragment → "Edit Mode Awareness".
Success Signal
The fragment appears in the input list for a field of a declared type, and a submission through it lands as an object entry:
curl \
--silent \
--url "http://localhost:${PORT}/o/c/<pluralLabel>" \
--user "test@liferay.com:test" \
| jq '.items[-1]'
The submitted value appears on the field named by input.name. A 200 with the field empty or absent means the name attribute did not reach the container — check for a hardcoded name or a missing dispatched change.
Related skills
| Skill | Stars | Updated | Works with | Status | Install |
|---|---|---|---|---|---|
| slack-gif-creatoranthropics/skillsKnowledge and utilities for creating animated GIFs optimized for Slack. Provides constraints, validation tools, and animation concepts. Use when users request animated GIFs for Slack like "make me a GIF of X doing Y for Slack." | Stars: 198k | Updated | Claude CodeCodex | Verified | Install |
| ponytailDietrichGebert/ponytailLazy senior dev mode for any coding task: the smallest change that fully solves it, and a reply a busy human understands in one read. | Stars: 194k | Updated | Claude CodeCodex | Verified | Install |
| ponytail-debtDietrichGebert/ponytailHarvest every shortcut: comment into one debt ledger, so deferrals get tracked instead of forgotten. One-shot report. | Stars: 194k | Updated | Claude CodeCodex | Verified | Install |
| ponytail-debtDietrichGebert/ponytailList every `shortcut:` comment (and older `ponytail:` ones) as a debt ledger. One-shot report, changes nothing. Use for "ponytail debt", "what did ponytail defer", "list the shortcuts", /ponytail-debt. | Stars: 194k | Updated | Claude CodeCodex | Verified | Install |