liferay-fragment-development

name	liferay-fragment-development
description	Guidelines and workflows for creating, structuring, developing, and mapping properties for page fragments in Liferay DXP.

Liferay Fragment Development Skill

This skill guides AI agents and developers in creating, styling, structuring, and localizing Liferay page fragments according to the repository's rules.

Configuration Gate Check — Do This First

This configuration check needs to happen first.

First step: Before scaffolding any fragment, verify if the current collection directory requires any specific theme-aware HTML or configuration setup. Stop and ask the user for clarification if the target collection path is not specified.

1. Creating a Fragment

To bootstrap a new fragment with standard scaffolding, run the following command from the workspace root:

npm run create-fragment "[Collection Name]" "[Fragment Name]"

This runs scripts/create-fragment.js, which does the following:

• If the collection directory is new, creates collection.json at <Collection Name>/main/collection.json with a display name and description. This file is required — the build script (create-fragment-zips.sh) discovers collections by looking for this file, and without it the collection is silently excluded from all ZIP builds.
• Scaffolds a directory at <Collection Name>/main/<safe-fragment-name>/.
• Creates fragment.json with explicit paths.
• Creates fragment-build.json linking commons.js by default.
• Creates boilerplate configuration (configuration.json), HTML (index.html), JS (index.js), CSS (index.css), and metadata (test/metadata.json).
• Automatically inserts default labels and descriptions into <Collection Name>/main/Language_en_US.properties.

1.1 Configuration Schema Data Types

Load: references/configuration-schema.md when defining configuration.json.

2. Structure & Metadata

Every fragment must follow these structural guidelines:

• Explicit Paths: fragment.json must explicitly define htmlPath, jsPath, cssPath, and configurationPath. Do not rely on Liferay's implicit folder naming defaults.
• JavaScript Encapsulation:
  • All client-side JavaScript must be encapsulated within an initialization function (e.g. initMyFragment()).
  • Top-level return statements are strictly prohibited.
  • To prevent collision with other fragments on the page, always query internal elements using fragmentElement.querySelector instead of the global document.querySelector.
• Template Extension Rule (FTL vs HTML):
  • Use .ftl if the fragment contains ANY FreeMarker logic (e.g., conditional checks [#if], loops [#list], [#assign]) or references Liferay variables (e.g., ${siteSpritemap}).
  • Use .html ONLY for strictly static HTML or basic data-lfr-editable fields.
• Input Type Fragments & Context Variables:
  • Any fragment designed to capture user inputs (e.g. form fields, rating components, date/signature selectors) must have "type": "input" (instead of "type": "component") and a typeOptions mapping in fragment.json (e.g., "typeOptions": { "fieldTypes": ["text", "number"] }).
  • Specifying "type": "input" instructs Liferay DXP to inject the input context map (containing input.label, input.required, input.errorMessage, input.readOnly, input.name) into the FreeMarker template context.
  • When referencing the input context map in your template code, always declare a defensive fallback (e.g. [#assign lfrInput = input!{}]) to prevent Liferay DXP from raising compile-time NullPointerException errors during import and saving it in DRAFT status.

3. Theme & Styling Fidelity

• Safe Tokens: Fragments must be theme-aware and use CSS variable tokens defined in THEMES.md.
• No Hardcoded Hex Values: Hardcoded hex values (e.g. #ffffff, #333333) are prohibited in index.css and will fail the linter. Always use var() tokens (e.g. var(--primary), var(--body-bg)).
• Targeted Overrides: If theme-specific overrides are needed, scope the CSS selectors with theme-specific body classes (e.g., .meridian-theme, .liferay-dialect-theme, .classic-theme).

4. Localization (i18n)

• Comprehensive Coverage: ALL labels and descriptions in configuration.json (including those within validValues arrays) MUST have a corresponding entry in the collection's Language_en_US.properties file.
• Root-level Localization: Some collections (such as form-fragments) consolidate all per-fragment properties into a single root-level Language_en_US.properties file. Check if the collection root has this file.
• No Lazy Keys: Property entries where the key equals the value (e.g. lfr.key=lfr.key) are prohibited.
• Descriptions: Every field in configuration.json must have a meaningful description to assist content creators.

5. Site-Scoped Object Discovery

Load: references/site-scoped-discovery.md when the fragment interacts with custom objects to use the Dynamic Discovery Pattern.

6. Mappable Field Ergonomics

• Requirements: Non-title mappable fields (data-lfr-editable) MUST be wrapped in a .meta-editor-mappable-fields container.
• Behavior: This container should be styled to be hidden during runtime but visible/editable within the page editor.

7. Documentation

• Sync Rule: Whenever a fragment is created or updated, its corresponding markdown documentation in docs/fragments/ must be created or updated.
• Layout: The documentation file name must match either the name property (slugified) or the folder name of the fragment. It must contain the following sections:
  • Overview: Description of what the fragment does.
  • Configuration: Explanation of all configuration.json fieldSets and fields.
  • Usage: Guidelines on how to add and configure it in the page editor.