Skip to content

liferay/liferay-portal / workspaces/clarity-solution-workspace/.agents/skills/scaffold-form-fragment

scaffold-form-fragment

Verified

Create 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-fragment when 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 TypeObject Field It Binds To
booleanBoolean
captchaNone — renders a CAPTCHA, not a field
dateDate
date-timeDate and Time
emailText constrained to email
fileAttachment
formButtonNone — renders the submit control
friendly-urlText constrained to a friendly URL
htmlRich Text
long-textLong Text
multiselectPicklist, multiple values
numberInteger, Decimal, Precision Decimal
phone-numberText constrained to a phone number
relationshipRelationship
selectPicklist, single value
stepperNone — renders form step navigation
textText

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.

PropertyTypeHolds
input.attributesmapType specific metadata, plus readOnly. Contents vary by field type
input.errorMessagestringValidation message from the server; empty when valid
input.helpTextstringAuthor supplied help text
input.labelstringThe field label
input.localizablebooleanWhether the field stores a value per locale
input.namestringThe name attribute the container reads on submit
input.readOnlybooleanWhether the field rejects edits
input.requiredbooleanWhether the field is mandatory
input.showHelpTextbooleanWhether the author chose to show help text
input.showLabelbooleanWhether the author chose to show the label
input.typestringThe bound field's type
input.valuestringCurrent value, populated when editing an existing entry
input.valueI18nmapPer 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:

ConditionMessage
captcha listed alongside any other field typeCaptcha field type cannot be mixed with other field types
fieldTypes present on any type other than inputOnly fragment type input can have field types
stepper listed alongside any other field typeStepper field type cannot be mixed with other field types
type: "input" with an empty or absent fieldTypesFragment 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.

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: 198kUpdated Claude CodeCodexVerifiedInstall
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: 194kUpdated Claude CodeCodexVerifiedInstall
ponytail-debtDietrichGebert/ponytailHarvest every shortcut: comment into one debt ledger, so deferrals get tracked instead of forgotten. One-shot report.Stars: 194kUpdated Claude CodeCodexVerifiedInstall
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: 194kUpdated Claude CodeCodexVerifiedInstall