Defining configuration options for a Fragment gives it more flexibility, reducing the number of Fragments you must maintain. To make a Fragment configurable,
-
Navigate to the Site Builder → Page Fragments page.
-
Click the Actions button (
) → Edit for the Fragment (Section or Component) you want to make configurable.
-
Select the Configuration tab at the top of the page.
Figure 1: Switch from the Code tab to the Configuration tab to create your configuration logic.
-
In the editor, add your JSON code. This code is added to your fragment’s
index.json
file. For example, the code below provides theselect
option to choose dark or light for a Fragment’s heading:{ "fieldSets": [ { "label": "heading", "fields": [ { "name": "headingAppliedStyle", "label": "applied-style", "description": "this-is-the-style-that-will-be-applied", "type": "select", "dataType": "string", "typeOptions": { "validValues": [ { "value": "dark" }, { "value": "light" } ] }, "defaultValue": "light" } ] } ] }
The configuration values selected by the user are made available to the Fragment developer through the FreeMarker context. A configuration value can be referenced using the notation
${configuration.[fieldName]}
. For the example snippet above,${configuration.headingAppliedStyle}
returnsdark
orlight
depending on the configuration value selected by the user. -
You can refer to your Fragment’s configuration values in its HTML file (e.g.,
index.html
). Navigate back to the Code tab at the top of the page and add your HTML. For example,[#if configuration.headingAppliedStyle == 'dark'] ... [#else] ... [/#if]
Configuration values inserted into the FreeMarker context honor the defined
datatype
value specified in the JSON file. Therefore, for this example,configuration.headingAppliedStyle?is_string
istrue
. -
Click Publish to save your work and make it available to add to a Content Page.
Figure 2: You can click your Fragment to view its configuration options.
Although this example highlights accessing configuration values in HTML via the FreeMarker context, you can also access these values via JavaScript. JavaScript configuration objects are named the same as their FreeMarker counterparts.
For example, a configuration object could be built like this:
var configuration = {
field1: value1,
field2: value2
}
Another example of setting the configuration object and using it is shown below:
const configurationValue = configuration.field1
console.log(configurationValue);
For more examples of Fragment configuration, see Fragment Configuration Types.
Awesome! You now have a configurable Fragment!