Skip to content

README.md

Latest commit

 

History

History
324 lines (269 loc) · 13 KB

README.md

File metadata and controls

324 lines (269 loc) · 13 KB

Liferay Fragments Documentation

A collection of robust, accessible, and responsive Liferay fragments for DXP platforms.

📋 Table of Contents

🚀 Deployment

Option 1: Automated Deployment (Recommended)

Use the provided deploy-fragment-zips.sh script to automate the deployment of your fragment and Language ZIPs.

Usage

./deploy-fragment-zips.sh [TARGET_PATH] [--all | folder_name1 folder_name2 ...]
  • TARGET_PATH: The root of a Liferay Workspace or a standalone Liferay bundle.
  • --all: Deploys all ZIPs found in the /zips directory.
  • folder_name: Space-separated list of specific fragment or collection folder names to deploy.

Example

./deploy-fragment-zips.sh ~/liferay-workspace --all
./deploy-fragment-zips.sh /opt/liferay gemini-generated master-page-background-colour

Option 3: Showcase Data Deployment

To demonstrate the data-driven capabilities of fragments like Activity Heatmap or Object-Linked Chart, you can deploy the sample showcase datasets.

Note: Liferay 2025.Q4.10 or later is required for these datasets to function correctly due to site-scoping requirements.

./deploy-fragment-zips.sh [TARGET_PATH] --showcase

This will deploy all showcase resources found in other-resources/showcase-data/.

Option 4: Manual Deployment

  1. Build the assets: Run ./create-fragment-zips.sh to generate the ZIP files.
  2. Deploy Fragments: Copy the .zip files from ./zips/fragments/ to your Liferay instance's /deploy folder.
  3. Deploy Language Overrides: Copy the -language-batch-cx.zip files from ./zips/language/ to your Liferay instance's /osgi/client-extensions/ folder.
  4. Deploy Special Resources: Copy any .zip files from /other-resources/*/dist/ to your Liferay instance's /osgi/client-extensions/ folder.

Liferay will automatically import the fragments and register the language overrides as Client Extensions.

Custom Build Options

If you want to target a specific Virtual Instance or Site, set these environment variables before running ./create-fragment-zips.sh:

  • COMPANY_WEB_ID: The Web ID of the Virtual Instance (Defaults to * / Global).
  • GROUP_KEY: The Site Friendly URL or Name (Ignored if COMPANY_WEB_ID is *).

Core Fragments

These fragments provide foundational utility and data display capabilities.

Specialized Collections

Gemini Generated

A suite of high-fidelity, data-driven fragments designed for modern Liferay portals.

Integration & Data

Advanced UI & Interactivity

Layout & Theme

User & Account

🛠️ Developer Resources

For more information on developing Liferay fragments, refer to the following official Liferay Learn guides:

🛠 Fragment Development Standards

To maintain high quality and compatibility across all fragments, all contributions must adhere to these mandatory standards:

1. Structure & Metadata

  • Explicit Paths: fragment.json MUST explicitly define htmlPath, jsPath, cssPath, and configurationPath. Defaults are not permitted.
  • JS Encapsulation: All JavaScript must be encapsulated in an initialization function (e.g., initMyFragment()). Top-level return statements are strictly prohibited.
  • Site-Scoping: Fragments using Object APIs must support Site-scoped data via dynamic discovery (see gemini.md for the pattern).

2. Configuration & Dependencies

  • Grouped Fields: Fields must be logically grouped into named field sets (e.g., Data, Behavior, Style).
  • Dependency Scope: Dependent fields and their source fields MUST reside within the same field set. Liferay does not support cross-field-set dependencies.
  • Holistic Renaming: Renaming a field in configuration.json requires immediate, coordinated updates to all references in index.js, index.html, and index.ftl.

3. Localization (i18n)

  • Comprehensive Coverage: ALL labels and descriptions in configuration.json (including validValues) MUST have a corresponding entry in Language_en_US.properties.
  • No Lazy Keys: Properties where the key equals the value (e.g., lfr.key=lfr.key) are prohibited and will fail the audit.
  • Mandatory Descriptions: Every configuration field MUST have a meaningful description to assist content creators in the Page Editor.

4. Styling & Quality Gate

  • Safe Tokens: Use CSS variables defined in THEMES.md. Avoid hardcoded hex colors.
  • Linter Enforcement: Every change must pass the local audit script before submission: 
    npm run lint

📚 Resources