Adding Configuration Options to Fragments
Available: Liferay DXP 7.2 SP1+
Configurable options help make your Fragments flexible, so you don’t have to maintain many similar Fragments. For example, instead of having one Fragment that has a heading with style A and another Fragment that has a heading with style B, you can create one Fragment that has a configurable style for the heading with options for style A and B. Here you’ll learn how to add configuration options to a Fragment:
- Deploy a Configurable Fragment
- Examine the Configuration
- Modify the Configuration
- Propagate the Changes and Test
- Related Information
For Liferay DXP 7.4+, Fragment Collections are called Fragment Sets in the Liferay UI.
Deploy a Configurable Fragment
Start a new Liferay instance by running
docker run -it -m 8g -p 8080:8080 liferay/portal:7.4.3.112-ga112
Sign in to Liferay at http://localhost:8080. Use the email address test@liferay.com and the password test. When prompted, change the password to learn.
Then, follow these steps to deploy an example to see how Fragment configuration options work:
-
Download and unzip the example Fragment Set:
curl https://resources.learn.liferay.com/dxp/latest/en/site-building/developer-guide/developing-page-fragments/liferay-c7f8.zip -O
unzip liferay-c7f8.zip
-
Set up the Fragments Toolkit:
cd liferay-c7f8
./setup_tutorial.sh
-
Import the Fragment Collection to the Docker container using the Fragments Toolkit. Alternatively, you can import the Fragment manually.
yarn run import > yo liferay-fragments:import ? Liferay host & port http://localhost:8080 ? Username test@liferay.com ? Password [hidden] Checking connection... Connection successful ? Company ID liferay.com ? Group ID Liferay Building project... Importing project... ✔ Fragment C7F8 Card imported Project imported
-
Verify the Fragment Set is available. Open the Site Menu (
) and go to Design → Fragments. The Set should appear in the list.
noteFor Liferay DXP 7.1 and 7.2, instead navigate to Site → Site Builder → Page Fragments under the Product Menu to get to the Fragments page.
-
Go to a Content Page and click the Edit icon (
) to begin editing.
-
Expand the C7F8 Set heading in the Fragments and Widgets panel and drag the C7F8 Card Fragment onto the page.
-
Select the C7F8 Card on the page to open the Fragment Configuration Menu. In the General tab, set the component’s text style to dark or light.
Great! You successfully imported and configured a configurable Fragment.
Examine the Configuration
You can edit a Fragment’s configuration options in Liferay’s built-in Fragments Editor or in a text file.
Using the Fragments Editor: In the UI, edit the Fragment with the Fragments Editor and click Configuration tab. The Fragment’s configuration appears in the editor.
Editing a Fragment Configuration File: If you don’t have the Fragment files, export them from the Fragment by opening the Fragment’s actions menu and clicking Export. The configurationPath
field (optional) in a Fragment’s fragment.json
file specifies the configuration .json
file. If it doesn’t have a configuration file, create one and set the configurationPath
field to the configuration file name.
Open the example’s fragment.json
file to determine the Fragment’s configuration file.
{
"configurationPath": "index.json",
"cssPath": "index.css",
"htmlPath": "index.html",
"jsPath": "index.js",
"name": "C7F8 Card",
"type": "component"
}
The "configurationPath": "index.json"
property indicates this Fragment’s configuration file is index.json
.
Open the configuration file.
{
"fieldSets": [
{
"fields": [
{
"dataType": "string",
"defaultValue": "dark",
"label": "Text Style",
"name": "c7f8TextStyle",
"type": "select",
"typeOptions": {
"validValues": [
{
"value": "dark"
},
{
"value": "light"
}
]
}
}
],
"label": "C7F8"
}
]
}
The configuration file above, specifies a selector for applying a dark or light text style to the Fragment. The configuration has a field named c7f8TextStyle
. The field’s type
is select
, which makes it a selector component. See Fragment Configuration Types for details. The selector’s valid values are dark
or light
. The "dataType": "string"
property means that the selector operates on string data.
This selector is a part of a field set labeled C7F8 (the label is optional). In the UI, this selector is found in the Fragment’s configuration section labeled C7F8. The selector is labeled Text Style
per the field’s label
property. The figure below shows the selector.
The Fragments Editor won’t save the configuration until it’s valid. Make sure your JSON configuration is valid before previewing it.
The configuration values selected by the user are made available to the HTML through the FreeMarker context. They are referenced in the HTML with the notation ${configuration.fieldName}
. The example (${configuration.textAppliedStyle}
) returns dark
or light
depending on the configuration value selected by the user, setting the CSS class to text-light
or text-dark
:
<div class="component-c7f8-card">
<div class="card">
<img
class="card-img-top"
data-lfr-editable-id="01-image"
data-lfr-editable-type="image"
src="https://clayui.com/images/home/lexicon_symbol.svg"
/>
<div class="card-body">
<h5
class="card-title text-${configuration.c7f8TextStyle}"
data-lfr-editable-id="02-title"
data-lfr-editable-type="rich-text"
>
Editable Card Title
</h5>
<p
class="card-text text-${configuration.c7f8TextStyle}"
data-lfr-editable-id="03-text"
data-lfr-editable-type="rich-text"
>
Here is some editable text.
</p>
<a
class="btn btn-primary"
data-lfr-editable-id="04-label"
data-lfr-editable-type="link"
href="#"
>
Editable Link
</a>
</div>
</div>
</div>
The example demonstrates a select configuration. See the Configuration Types Reference for a complete list of the available Fragment configuration types.
Modify the Configuration
Now that you know how the configuration works, you can modify it.
-
Open the Site Menu (
) and go to Design → Fragments.
noteFor Liferay DXP 7.1 and 7.2, instead navigate to Site → Site Builder → Page Fragments under the Product Menu to get to the Fragments page.
-
Select the C7F8 Set, click the Actions button (
) for the C7F8 Card and select Edit. This opens the Fragments Editor.
-
Click the Configuration tab and update the configuration with a checkbox field to hide/show the card’s description. Insert this code on a new line after the
c7f8TextStyle
field’s closing brace and comma (},
){ "name": "showDescription", "label": "Show Description", "description": "show-description", "type": "checkbox", "defaultValue": true }
tipYou can add a
configurationRole
value to the field set (alongside thefields
object in the JSON) to specify which tab the associated fields appear in. Set the value asstyles
to make the fields appear in the Styles tab, or set it toadvanced
to make them appear in the Advanced tab (only in Liferay DXP versions U23+ or GA23+). If noconfigurationRole
is set, then they appear in the General tab by default. -
Go back to the HTML pane in the Code tab and wrap the paragraph element with a conditional statement to check for the checkbox’s value. Click Publish to apply the changes.
[#if configuration.showDescription] <p data-lfr-editable-id="03-card-text" data-lfr-editable-type="rich-text" class="card-text text-${configuration.textAppliedStyle}"> Here is some editable text. </p> [/#if]
You can also access the configuration’s value through the JavaScript with the syntax const configurationValue = configuration.textAppliedStyle;
.
Propagate the Changes and Test
Now you can test the updates.
-
Propagate the changes so they’re reflected on the Content Page. Click Actions (
) for the C7F8 Card and select View Usages.
-
Check the box for the Content Page and click the (
) button.
-
Go back to the Content Page and once again click the (
) icon to edit the Content Page.
-
Select the C7F8 Card again to show Selection panel on the right.
-
In the General tab, check/uncheck the Show Description checkbox to show/hide the card’s text.
Great! Now you know how to add configuration options to your Fragments. For more configuration examples, please see Please see Fragment Configuration Types.