Fragment Configuration Types Reference

Below are the available configuration types for fragments. See Adding Configuration Options to Fragments for more on how to make a fragment configurable.

These are the configurable fragment types available to implement:

• text
• select
• checkbox
• colorPicker (Available Liferay 7.4+)
• length (Available Liferay 7.4+ U44/GA44)
• itemSelector
• url (Available Liferay 7.4+)
• videoSelector (Available Liferay 7.4+)
• collectionSelector
• colorPalette
• navigationMenuSelector (Available Liferay 7.4+)

Note

Configuration values inserted into the FreeMarker context honor the defined datatype value specified in the JSON file. For example, if the dataType is String, configuration.[name-value]?is_string is true.

Text Configuration

This JSON configuration creates an input text field for adding text manually:

{
   "fieldSets": [
      {
         "fields": [
               {
                  "name": "buttonText",
                  "label": "Button Text",
                  "description": "button-text",
                  "type": "text",
                  "typeOptions": {
                     "placeholder": "Placeholder"
                  },
                  "dataType": "string",
                  "defaultValue": "Go Somewhere"
               }
         ]
      }
   ]
}

Select Configuration

This JSON configuration creates a selector for selecting a predefined option:

{
   "fieldSets": [
      {
         "fields": [
               {
                  "name": "numberOfFeatures",
                  "label": "Number Of Features",
                  "description": "number-of-features",
                  "type": "select",
                  "dataType": "int",
                  "typeOptions": {
                     "validValues": [
                           {"value": "1"},
                           {"value": "2"},
                           {"value": "3"}
                     ]
                  },
                  "defaultValue": "3"
               }
         ]
      }
   ]
}

Checkbox Configuration

This JSON configuration creates a checkbox for selecting Boolean values:

{
   "fieldSets": [
      {
         "fields": [
               {
                  "name": "hideBody",
                  "label": "Hide Body",
                  "description": "hide-body",
                  "type": "checkbox",
                  "defaultValue": false
               }
         ]
      }
   ]
}

Color Picker Configuration

Liferay 7.4+

The color picker JSON configuration creates a flexible color selector for selecting any color. You can use these methods to select a color:

• Click the color on the left side to choose a color from the color picker.

• Enter a color’s hex code into the text box.

• Click Value from Stylebook to open a menu of pre-defined colors defined in the current style book. This links the field’s value to the selected token until you press the button again to unlink it. Unlinking the token value converts the chosen color to its equivalent hex code value again.

• If the color picker has no default value defined, click the Default drop-down menu to select any color from the current style book. This works the same as the Value from Stylebook button when you select a value.

Note

If the theme you are using has no token definitions for style books, color picker configurations on the page are replaced with [color palette](#color-palette configuration) configurations.

This JSON configuration creates a color picker field called headingColor:

{
   "fieldSets": [
      {
         "fields": [
               {
                  "name": "headingColor",
                  "label": "Heading Color",
                  "description": "heading-color",
                  "type": "colorPicker",
                  "defaultValue": "#FF0000"
               }
         ]
      }
   ]
}

The colorPicker type stores an object holding the chosen color value with the configured name. Here’s how to reference this object in your fragment’s HTML:

<div class="fragment_69">
    <h1 style="color: ${configuration.headingColor}">
        This text's color is configurable.
    </h1>
</div>

When the fragment is rendered, the chosen color replaces the token ${configuration.OBJECT_NAME}. The type of value that it becomes depends on how the color is chosen:

• If you chose a color directly, it is replaced with the corresponding hex code value.
• If you chose a color from the current style book, it’s replaced with a CSS variable for the linked token (for example, var(--danger)).
• If the current theme does not have any token definitions to use (so a color palette is used instead), it is replaced with a CSS color (for example, rgb(255, 0, 0)).

Length Configuration

Liferay 7.4 U44 and GA44+

The length configuration type creates a field where you can enter a number and choose predefined units or specify your own units for settings like width, margins, and padding.

This JSON sample shows a field using the length configuration type. It includes properties defining the name, label, and default value.

{
   "fieldSets": [
      {
         "fields": [
               {
                  "defaultValue": "300px",
                  "label": "size",
                  "name": "size",
                  "type": "length"
               }
         ]
      }
   ]
}

In the user interface, you can choose from the available units or specify a custom unit.

Item Selector Configuration

Liferay 7.3+

This configuration creates a selector for selecting one existing piece of content (a document, web content article, blog entry, category, product, or knowledge base article by default) to include in the fragment.

Note

When a fragment with an itemSelector configuration is placed inside a Collection Display, the collection item becomes the selected content automatically. Manual selection is disabled because the Collection Display determines the content dynamically.

{
   "fieldSets": [
      {
         "fields": [
               {
                  "label": "select-content",
                  "name": "itemSelector1",
                  "type": "itemSelector",
                  "typeOptions": {
                     "enableSelectTemplate": true
                  }
               }
         ]
      }
   ]
}

You can provide a more advanced configuration for selecting only a specific type of content. The configuration below specifies that only web content articles can be selected. The optional itemSubtype property requires the selected web content article to use the structure article-structure-key-15 to be selected:

{
   "fieldSets": [
      {
         "fields": [
               {
                  "label": "select-content",
                  "name": "itemSelector1",
                  "type": "itemSelector",
                  "typeOptions": {
                     "itemType": "com.liferay.journal.model.JournalArticle",
                     "itemSubtype": "article-structure-key-15"
                  }
               }
         ]
      }
   ]
}

This example specifies that only a document with the image/png MIME type (.png file) can be selected:

{
   "fieldSets": [
      {
         "fields": [
         {
            "label": "select-content",
            "name": "itemSelector1",
            "type": "itemSelector",
            "typeOptions": {
               "itemType": "com.liferay.portal.kernel.repository.model.FileEntry",
               "mimeTypes": [
               "image/png"
               ]
            }
         }
         ]
      }
   ]
}

This example specifies that only blog entries can be selected:

{
   "fieldSets": [
      {
         "fields": [
               {
                  "label": "select-content",
                  "name": "itemSelector1",
                  "type": "itemSelector",
                  "typeOptions": {
                     "itemType": "com.liferay.blogs.model.BlogsEntry"
                  }
               }
         ]
      }
   ]
}

You can then render the content in your fragment with this HTML snippet for the blog entry:

<div class="fragment_name">
   [#if configuration.itemSelector1.content??]
         ${configuration.itemSelector1.content}
   [/#if]
</div>

If you need access to specific portions of the content, you can also access the Java object in your fragment using the name attribute and the Object suffix (itemSelector1Object, in this case). The example below renders the title, description, and content body of the blog entry.

<div class="fragment_name">
   [#if configuration.itemSelector1.content??]
         ${itemSelector1Object.getTitle()}
         ${itemSelector1Object.getDescription()}
         ${itemSelector1Object.getContent()}
   [/#if]
</div>

Note

Placing a fragment with an item selector configuration into a collection display widget automatically maps the collection item as the selected content.

URL Configuration

This configuration adds a field specifically for a URL to use in your fragment’s markup:

{
   "fieldSets": [
      {
         "fields": [
               {
                  "label": "My URL",
                  "name": "myURL",
                  "type": "url"
               }
         ]
      }
   ]
}

When you set a fragment with this configuration, you can enter a URL manually (URL) or select another page from the same site and use its complete URL (Page).

Here is an example of fragment HTML that uses the URL configuration in the above JSON to create a hyperlink:

<div class="fragment_1">
   <a href=${configuration.myURL}>Click this link!</a>
</div>

Video Selector

Liferay 7.4+

Using the videoSelector type, you can create a video selector to incorporate an external video fragment in another fragment.

{
   "fieldSets": [
      {
         "fields": [
               {
                  "label": "My Video Selector",
                  "name": "myVideoConfig",
                  "type": "videoSelector"
               }
         ]
      }
   ]
}

This is useful when you want a fragment that has an embedded video by default. The following JSON configuration sample shows how to incorporate a external video selector in a card fragment:

{
"fieldSets": [
   {
      "fields": [
         {
               "label": "Video",
               "name": "video",
               "type": "videoSelector"
         }
      ]
   },
   {
      "configurationRole": "style",
      "fields": [
         {
               "dataType": "string",
               "defaultValue": "w-100",
               "label": "image-size",
               "name": "imageSize",
               "type": "select",
               "typeOptions": {
                  "validValues": [
                     {
                           "label": "fit",
                           "value": "w-100"
                     },
                     {
                           "label": "original-size",
                           "value": "w-0"
                     }
                  ]
               }
         }
      ]
   }
]
}

Note

The videoSelector type is compatible with the external video fragment, but not with the video URL fragment.

Collection Selector

Liferay 7.3+

Using the collectionSelector configuration type, you can develop a fragment that includes a collection or collection provider. You can use the collectionSelector with both manual and dynamic collections.

Note

Developers can use collection providers to group items based on advanced criteria, such as recent content or most viewed items. Once grouped, you can use Information Templates to customize how these items are rendered on a page.

The following JSON configuration shows how to use the collectionSelector:

{
   "fieldSets": [
      {
      "label": "Collection",
      "fields": [
         {
               "name": "collection",
               "type": "collectionSelector"
         }
      ]
      }
   ]
}

You can use this fragment configuration with the FreeMarker code below to list the collection items. The collectionObjectList represents the collection selected in the content page editor.

To reference this collection in the FreeMarker, use the collection name in the JSON configuration and the ObjectList suffix. In the previous JSON code excerpt, the collection name is collection so the FreeMarker references the collection using collectionObjectList.

<div class="fragment_310">
   <h1>
      List of Items:
   </h1>
   <ul>
      [#if collectionObjectList??]
      [#list collectionObjectList as item]
      <li>${item.title}</li>
      [/#list]
      [/#if]
   </ul>
</div>

Filtering the Collection Selector

You can filter the collection selector using itemType in the collectionSelector configuration. For example, if you have different collections including web content and blogs, you can restrict the collection selector to show only blog collections. This JSON sample illustrates this configuration:

{
   "fieldSets": [
      {
         "label": "Collection",
         "fields": [
               {
                  "name": "collection",
                  "type": "collectionSelector",
                  "typeOptions": {
                     "itemType": "com.liferay.blogs.model.BlogsEntry"
                  }
               }
         ]
      }
   ]
}

Using this sample configuration, collections including both web content and blogs are filtered out of the collection selector because the collection type is asset.

Tip

In addition to the itemType, you can specify the itemSubtype in the configuration. The itemSubtype corresponds to the asset classPK.

Defining a Maximum Number of Returned Collection Items

By default, all items in the collection are returned if you do not define a limit to the maximum number of items. You can set this limit using numberOfItems in your JSON configuration.

{
   "fieldSets": [
      {
         "label": "Collection",
         "fields": [
               {
                  "name": "collection",
                  "type": "collectionSelector",
                  "typeOptions": {
                     "numberOfItems": 3
                  }
               }
         ]
      }
   ]
}

Color Palette Configuration

The color palette JSON configuration creates a color selector you can implement for cases where you must select a color. Unlike the color picker configuration, it only provides options based on the theme colors configured in the currently used style book’s color system.

This configuration creates a color palette field called textColor:

{
   "fieldSets": [
      {
         "fields": [
               {
                  "name": "textColor",
                  "label": "Text color",
                  "type": "colorPalette",
                  "dataType": "object",
                  "defaultValue": {
                     "color": "white"
                  }
               }
         ]
      }
   ]
}

The colorPalette type stores an object with the value: color.

For example, if you implement the snippet above, you can use it in FreeMarker:

<h3 class="text-${configuration.textColor.color}">Example</h3>

If you were to choose the color white, the h3 tag heading would have the class text-white.

Navigation Menu Selector Configuration

Liferay DXP 2024.Q1/Portal GA112

Using the navigationMenuSelector configuration type, you can access FreeMarker variables through the fragment HTML editor and define markup for rendering custom navigation menus.

To use FreeMarker variables in the fragment HTML editor, start by setting navigationMenuSelector as the configuration type. You can use the JSON snippet below as a model.

"fieldSets": [
   {
   "fields": [
      {
      "label": "source",
      "name": "source",
      "type": "navigationMenuSelector"
      }
   ]
   }
]

Now you can access the FreeMarker variables, which are found under [name]Object. In this example, sourceObject.navItems would return the navItems list located under sourceObject. The object is called sourceObject since source was the name used in the configuration.

These are the available variables for the navigation menu selector configuration type:

Variable	Use
branchNavItems	Represents the hierarchical structure of the navigation menu.
navItems	A list of NavItem objects, each representing a navigation item to be displayed.
rootLayoutLevel	Defines the level in the hierarchy.
rootLayoutType	Specifies how to interpret the root layout in relation to the current page (absolute, relative, or select).

To get a better look at the navigationMenuSelector type, download the navigation-menu fragment and import it into a fragment set. See Managing Fragments to learn more about importing a fragment.

Conditional Field Visibility Configuration

Liferay DXP 2025.Q2+/Portal GA135

Important

Currently, this feature is behind a release feature flag (LPD-46393). Read Release Feature Flags for more information.

You can control the visibility of fields in a fragment configuration based on the values of other fields within the same fieldset. Field visibility is determined by dependencies, where the visibility of one field can depend on the value of another. Supported field types for dependencies are text, select, and checkbox.

To create a field dependency, add a dependency key within the field’s typeOptions. Specify the field to compare with, and set the condition’s type to equal or not-equal to define how the value fields are compared.

The following example demonstrates two select fields, buttonType and submittedEntryStatus. The visibility of submittedEntryStatus depends on the value of buttonType:

{
	"fieldSets": [
		{
			"fields": [
				{
					"dataType": "string",
					"defaultValue": "standard",
					"label": "Subscription Plan",
					"name": "subscriptionPlan",
					"type": "select",
					"typeOptions": {
						"validValues": [
							{"value": "basic", "label": "Basic Plan"},
							{"value": "standard", "label": "Standard Plan"},
							{"value": "premium", "label": "Premium Plan"}
						]
					}
				},
				{
					"dataType": "string",
					"defaultValue": "no",
					"label": "Additional Features",
					"name": "additionalFeatures",
					"type": "select",
					"typeOptions": {
						"dependency": {
							"type": "equal",
							"value": "premium"
						},
						"validValues": [
							{"value": "1", "label": "Priority Support"},
							{"value": "2", "label": "Extra Storage"},
							{"value": "3", "label": "Custom Reports"}
						]
					}
				}
			]
		}
	]
}

The visibility dependency is defined as:

"typeOptions": {
   "dependency": {
      "subscriptionPlan": {
          "type": "equal",
          "value": "premium"
       }
   }
}

In this case, the additionalFeatures field only appears when the subscriptionPlan field is set to Premium Plan. If the user selects a different subscription plan, the additionalFeatures field remains hidden.

Tip

You can add multiple dependencies within the dependency object to control visibility based on other fields’ values.

Related Topics

• Developing Fragments
• Fragment Specific Tags and Attributes Reference
• Page Fragment Editor Interface Reference
• Using a Style Book to Standardize Site Appearance