Making a Fragment Configurable

Defining configuration options for a Fragment gives it more flexibility, reducing the number of Fragments you must maintain. To make a Fragment configurable,

  1. Navigate to the Site BuilderPage Fragments page.

  2. Click the Actions button (Actions) → Edit for the Fragment (Section or Component) you want to make configurable.

  3. 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.

    Figure 1: Switch from the Code tab to the Configuration tab to create your configuration logic.

  4. In the editor, add your JSON code. This code is added to your fragment’s index.json file. For example, the code below provides the select 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} returns dark or light depending on the configuration value selected by the user.

  5. 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 is true.

  6. 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.

    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!

« Developing FragmentsManaging Fragments and Collections »
Was this article helpful?
0 out of 0 found this helpful