Skip to content
ToolShedby Wasim Shaikh

Liferay Fragment Configuration Builder

Build a valid Liferay page fragment configuration.json visually. It uses Liferay's fieldSets schema and supports all 11 field types, validation rules and the General, Styles and Advanced tabs. Import an existing file to edit it, preview the configuration panel and copy the FreeMarker to use each value.

Liferay Fragment Config Builder

Build valid Liferay fragment configuration.json (fieldSets) visually: all 11 field types, validation, import, panel preview and FreeMarker snippets.

Valid fieldSets configuration.

{
  "fieldSets": [
    {
      "label": "Content",
      "fields": [
        {
          "name": "heading",
          "label": "Heading",
          "type": "text",
          "dataType": "string",
          "defaultValue": "Card title",
          "typeOptions": {
            "placeholder": "Enter a heading"
          },
          "localizable": true
        },
        {
          "name": "columns",
          "label": "Columns",
          "type": "select",
          "dataType": "int",
          "defaultValue": "3",
          "typeOptions": {
            "validValues": [
              {
                "value": "2"
              },
              {
                "value": "3"
              },
              {
                "value": "4"
              }
            ]
          }
        },
        {
          "name": "showButton",
          "label": "Show button",
          "type": "checkbox",
          "defaultValue": true
        },
        {
          "name": "buttonLink",
          "label": "Button link",
          "type": "url"
        },
        {
          "name": "image",
          "label": "Image",
          "type": "itemSelector",
          "typeOptions": {
            "itemType": "com.liferay.portal.kernel.repository.model.FileEntry",
            "mimeTypes": [
              "image/png",
              "image/jpeg",
              "image/webp"
            ]
          }
        }
      ]
    },
    {
      "configurationRole": "styles",
      "label": "Appearance",
      "fields": [
        {
          "name": "headingColor",
          "label": "Heading color",
          "type": "colorPicker",
          "defaultValue": "#0B5FFF"
        },
        {
          "name": "maxWidth",
          "label": "Max width",
          "type": "length",
          "defaultValue": "960px"
        }
      ]
    }
  ]
}

Point your fragment.json at it with "configurationPath": "configuration.json".

About Fragment Configuration Files

A Liferay page fragment is a reusable HTML, CSS, and JavaScript component that can be added to portal pages. A configuration.json file makes your fragment configurable — it defines which settings site administrators can edit when they add your fragment to a page. Without it, fragments are static. With it, they become flexible tools that editors can customize without code.

Why Use Fragment Configuration?

  • Editability: Site admins can customize your fragment without touching code.
  • Reusability: One fragment can be configured differently on different pages.
  • Professional: Fragments with configuration feel more polished and production-ready.
  • Reduces Code Duplication: No need to build multiple similar fragments.

Configuration Field Types

TypeSinceUse it for
text7.2+Free text input, with optional placeholder and validation.
select7.2+Dropdown of predefined values.
checkbox7.2+Boolean toggle.
colorPicker7.4+Hex color or Style Book token.
colorPalette7.2+Theme palette color (use colorPicker on 7.4+).
length7.4 GA44+Number with CSS units, e.g. 300px or 2rem.
itemSelector7.3+Pick one content item (web content, blog, document…).
url7.4+URL typed in or a page from the same site.
videoSelector7.4+Embed an external video.
collectionSelector7.3+Pick a collection or collection provider.
navigationMenuSelector2024.Q1+Pick a navigation menu as the source.

The configuration.json Format

Liferay expects a fieldSets array. Each field set can have a label and a configurationRole, and holds a list of fields:

{
  "fieldSets": [
    {
      "label": "Content",
      "fields": [
        {
          "name": "columns",
          "label": "Columns",
          "type": "select",
          "dataType": "int",
          "typeOptions": {
            "validValues": [{ "value": "2" }, { "value": "3" }, { "value": "4" }]
          },
          "defaultValue": "3"
        }
      ]
    }
  ]
}

How to Use This Builder

  1. Plan your fields. Decide which settings site admins should customize.
  2. Add each field. Pick a type, then fill in its name, label, default and type options.
  3. Pick the tab. Put style settings in a field set shown in the Styles tab.
  4. Check it. Fix any errors listed above the JSON, and look at the panel preview.
  5. Download or copy. Download the file directly or copy it to your clipboard.
  6. Deploy. Add the file to your fragment folder, set configurationPath in fragment.json and deploy.

Example: A Color Theme Fragment

Suppose you have a carousel fragment that displays products. You might want to let site admins customize:

  • Which products to show (Collection Selector)
  • Display mode: Grid or Carousel (Select)
  • Number of columns (Select with int data type)
  • Background color and card width (Color Picker and Length, in the Styles tab)

This tool lets you build that configuration.json without writing any JSON by hand.

Fragment Project Structure

Once you download your configuration.json, your fragment project should look like:

my-fragment/ ├── configuration.json ├── fragment.json ← "configurationPath": "configuration.json" ├── index.html ├── index.css ├── index.js └── thumbnail.png

Frequently Asked Questions

What is a fragment configuration.json?
It defines the settings editors can change when they add your page fragment to a page. Liferay reads a top-level "fieldSets" array; each field set holds "fields", and each field has a name, label, type, optional dataType, defaultValue and typeOptions. Values are read in the fragment HTML with ${configuration.fieldName}.
Which field types does Liferay support?
text, select, checkbox, colorPicker (7.4+), colorPalette, length (7.4 GA44+), itemSelector (7.3+), url, videoSelector (7.4+), collectionSelector (7.3+) and navigationMenuSelector (DXP 2024.Q1+). This builder supports all eleven.
How do I put fields in the Styles or Advanced tab?
Set "configurationRole" on the field set: "styles" shows its fields in the Styles tab and "advanced" in the Advanced tab (7.4 GA23+). Without it, fields appear in the General tab. Use the "Shown in" menu on each field set.
Can I validate what editors type into a text field?
Yes. Text fields accept typeOptions.validation with a type of text, number, email, url or pattern, plus minLength/maxLength, min/max or regexp and a custom errorMessage. Validation only applies in the page editor configuration panel.
Can I edit an existing configuration.json?
Yes. Use Import JSON, paste your file and the builder loads every field set and field so you can change, reorder and re-export it.
Where does the file go?
Put configuration.json in the fragment folder next to index.html, index.css and index.js, and reference it from fragment.json with "configurationPath": "configuration.json". Then build and import the fragment set as usual.

Official Resources