Settings¶

To enable the modification of configuration settings from elements, you can use JSON to create configurable settings that are translated into UI controls during visual editing. These settings can be defined within component files and setting files, allowing for seamless integration with the visual interface. This approach ensures that developers and content editors can easily customize and adjust settings directly within the user interface, providing greater flexibility and control over the appearance and behavior of elements without requiring manual code changes. By utilizing JSON, these settings can be dynamically updated, offering a streamlined and intuitive editing experience that enhances productivity and reduces development time. Settings can be defined through components or dedicated setting files, providing flexibility in customization and configuration. Components allow settings to be directly associated with specific features or elements, enabling granular control. Meanwhile, setting files offer a centralized approach to manage global configurations, making it easier to maintain consistency across the system. This dual approach ensures adaptability, whether you're fine-tuning individual components or applying broader adjustments to the overall user experience.

Standard Setting Attributes¶

Attribute	Type	Required	Description	Default Value
`id`	String	Yes	The setting ID, which is used to access the setting value.	-
`type`	String	Yes	The setting type, which can be any of the system types or user defined types input setting types.	-
`label`	String	No	The setting label, which will show in the theme editor.	-
`default`	Any	No	The default value for the setting.	-

System Types¶

boolean¶

A setting of type boolean outputs a set of radio buttons for true and false, providing a clear and simple interface for binary choices. These fields are ideal for toggling features on and off, such as enabling or disabling an announcement bar, showing or hiding optional content, or activating specific functionality. With its intuitive design, the boolean setting ensures users can make quick decisions, enhancing the flexibility and interactivity of the configuration process.

{
    "id": "showAnnouncement",
    "type": "boolean",
    "label": "Show announcement",
    "default": true
}

number¶

A setting of type number outputs a single input field designed for capturing precise numerical values. These fields are ideal for scenarios where a specific quantity or range is required, such as determining the number of products to display per page, setting a minimum order amount, or defining pagination limits. The number field can support additional configurations, like setting default values, specifying ranges, or enforcing step intervals to ensure consistent input. This versatile setting streamlines data entry and offers granular control, making it an essential tool for tailoring user experiences and optimizing content presentation.

{
    "id": "productsPerPage",
    "type": "number",
    "label": "Products per page",
    "default": 20
}

radio¶

A setting of type radio generates a radio button field, allowing users to select a single option from multiple predefined choices. In addition to the standard attributes applicable to input settings, radio type settings include attributes specific to managing and displaying these selectable options effectively.

Fields with a required options attribute accept an array of value and label definitions, enabling the creation of predefined multi-option selections. These fields are especially useful for scenarios where users must choose from a set of specific configurations, such as aligning a header logo to the left, center, or right. The clear structure of the options array ensures consistency and prevents invalid inputs, streamlining the user interface for precise customization and seamless design control.

{
  "id": "logoAligment",
  "type": "radio",
  "label": "Logo alignment",
  "options": [
    {
      "value": "left",
      "label": "Left"
    },
    {
      "value": "centered",
      "label": "Centered"
    }
  ],
  "default": "left"
}

range¶

A setting of type range generates a range slider accompanied by an input field, allowing users to select a numeric value within a specified range. This type of setting is ideal for scenarios where precise control is required over adjustable parameters, such as font size, opacity levels, or spacing. In addition to the standard attributes common to input settings, range type settings support the following attributes:

Attribute	Type	Required	Description	Default Value
`min`	Number	Yes	The minimum value of the input	-
`max`	Number	Yes	The maximum value of the input	-
`step`	Number	No	The increment size between steps of the slider. Defaults to `1` when omitted.	1
`unit`	String	No	The unit for the input. For example, you can set `px` for a font-size slider.	-

{
  "id": "fontSize",
  "type": "range",
  "min": 12,
  "max": 24,
  "step": 1,
  "unit": "px",
  "label": "Font size",
  "default": 16
}

select¶

A setting of type select outputs different selector fields, depending on certain criteria. In addition to the standard attributes of an input setting, select type settings include a required options attribute that accepts an array of value and label definitions. You can use these fields to capture a multi-option selection that exceeds three or more options.

{
  "id": "countries",
  "type": "select",
  "label": "Countries",
  "options": [
    {
      "value": "US",
      "label": "United States"
    },
    {
      "value": "MX",
      "label": "Mexico"
    },
    {
      "value": "AF",
      "label": "Afghanistan"
    },
    {
      "value": "BF",
      "label": "Burundi"
    },
    {
      "value": "ER",
      "label": "Eritrea"
    },
    {
      "value": "GT",
      "label": "Guatemala"
    }

  ],
  "default": "left"
}

richtext¶

A setting of type richtext outputs a multiline text field, allowing for detailed content input. The default output of a richtext setting is HTML, enabling the inclusion of formatted text, links, images, and other HTML elements. This setting is ideal for capturing complex content such as descriptions, posts, or notes that require rich formatting.

{
  "id": "description",
  "type": "richtext",
  "label": "The Description",
  "default": "<p>This is the default description text</p>"
}

text¶

A setting of type text outputs a single line text field. In addition to the standard attributes of an input setting, text type settings have the following attribute:

Attribute	Type	Required	Description	Default Value
`pattern`	string	No	Regex pattern for validation-	-

{
  "id": "phoneNumber",
    "type": "text",
    "label": "Cell Phone",
    "default": true,
    "pattern": "^\\d{3}[-.\\s]?\\d{3}[-.\\s]?\\d{4}$ "
}

color¶

A setting of type color outputs a color picker field. You can use these fields to capture a color selection for various theme elements, such as the body text color.

{
  "id": "bodyText",
    "type": "color",
   "label": "Body text",
   "default": "#000000"
}

media¶

A setting of type media allows users to select from existing media elements or create new ones directly from the digital asset manager (DAM). This setting provides flexibility in managing and integrating various media assets, such as images, videos, and documents, into the platform seamlessly. This type of setting allows users to easily manage and incorporate media, such as images, videos, or audio, into their configurations.

{
  "id": "backgroundMedia",
  "type": "media",
  "label": "Background Media",
  "default": null
}

array¶

A setting of type array allows a dynamic list of a particular type of setting to be created. In addition to the standard attributes, array type settings have the following attributes:

Attribute	Type	Required	Description	Default Value
`of`	string	Yes	The type of setting to be used in the array (e.g., "text", "number", "custom").	-
`maxLength`	integer	No	The maximum number of items allowed in the array, including nested arrays. Leave blank for unlimited items.	-

{
  "type": "array",
  "of": "number",
  "id": "numbers",
  "label": "My Numbers",
  "default": [1,2,3,4],
  "maxLength": 5
}

User Defined Types¶

User-defined setting types expand upon the functionality of the system types. These custom types are created by defining them within a schema file, allowing for greater flexibility and customization. A single schema file can define multiple custom types, streamlining the process of adding unique settings tailored to specific needs.

Custom Type Attributes¶

Attribute	Type	Required	Description	Default Value
`id`	string	yes	the custom type identifier	-
`settings`	array	yes	Array of settings	-

In this example we will create two user defined types and put them in a schema file called custom-types.schema

custom-types.schema

[
  {
    "id": "customType1",
    "settings": [
      {
        "type": "text",
        "id": "someText",
        "label": "Some Text",
        "default": "Default Text 1"
      },
      {
        "type": "color",
        "id": "textColor",
        "label": "Text Color",
        "default": "#FF0000"
      }
    ]
  },
  {
    "id": "customType2",
    "settings": [
      {
        "type": "number",
        "id": "myNumber",
        "label": "My Number",
        "default": 10
      },
      {
        "type": "boolean",
        "id": "myBoolean",
        "label": "My Boolean",
        "default": true
      }
    ]
  }
]

Once the custom-types schema is defined it can be used inside a component or setting object file

In addition to the standard attributes, to use a user defined setting declaration have one additional attribute.

Attribute	Type	Required	Description	Default Value
`schema`	string	Yes	The path to the schema file containing the user defined type	-

{
  "type": "customType1",
  "schema": "custom-types.schema",
  "id": "customType1",
  "label": "Special Setting",
  "default": {
      "someText": "This is a test",
      "textColor": "#fffff"
  }
}

Setting Objects¶

User-defined setting schemas can also be used within setting files, allowing them to be converted into Liquid objects at render time. This provides the flexibility to dynamically generate content based on user input or predefined configurations, making it easier to manage and manipulate data as the page is processed. By leveraging these schemas, you can create highly customizable templates that respond to user settings in real-time, offering greater control over the content and layout of your site.

Attribute	Type	Required	Description	Default Value
`schema`	string	Yes	The path to the schema file containing the user defined type	-
`<setting object>`	object	Yes	Object of setting values as defined by the schema	-

In this example, we will create a setting file called custom-settings.setting and define values for the customType1 user-defined type from the previous example. This allows us to specify and manage custom settings within the template, ensuring that values specific to our custom type can be easily referenced and rendered. By associating the defined values with the custom type, we provide a flexible, structured way to control dynamic content based on user-defined configurations, enhancing the ability to tailor content and functionality within the platform.

custom-settings.setting

{
  "schema": "custom-types.schema",
  "settings": {
      "customType1": {
            "someText": "This is a test",
            "textColor": "#fffff"
      }
  }
}

Setting files can be requested during the liquid render phase, or created as global liquid objects during the pre-render phase.

Liquid Files¶

Inside liquid files, you can convert the setting json values into a liquid object by using the "resource_object" filter sample.snippet

{% assign customvalues = "custom-settings.setting" | resource_object %} 

<div style="color: {{ customvalues.customType1.textColor }}">
    {{ customvalues.customType1.someText }}
</div>

Global Liquid Objects¶

To create a global settings object that can be accessed by all Liquid files during the render phase, use the settingObjects attribute within the JSON page definition. This approach ensures that the defined settings are universally available across the site, allowing for consistent configuration management. By utilizing this attribute, developers can streamline the rendering process, centralize configuration settings, and maintain a cohesive structure for dynamic content rendering, ensuring flexibility and efficiency in the design and functionality of the website.

The settingObjects is an array that contains objects with the following attributes. Each object within this array represents a distinct set of settings that can be used globally across the website. These attributes define the structure and behavior of the settings, providing flexibility in how data is accessed and utilized during the render phase. By leveraging settingObjects, developers can easily manage multiple settings in a modular way, ensuring that all components can access the necessary data without redundancy.

Attribute	Type	Required	Description	Default Value
`id`	string	Yes	The path to the setting file	-
`type`	string	Yes	The name of the setting object	-
`liquidName`	string	Yes	The name of the liquid object	-

Here, we will use settingObjects to create a global Liquid object called customValues, which will be a Liquid object of customType1. This approach allows for the centralization of configuration data, making it accessible across all Liquid templates during the render phase. By defining customValues as a global object, we ensure that it can be referenced throughout the site, simplifying the management of custom settings and improving the maintainability of the code.

sample-page.page

{
    "layout": "main-layout.layout",
    "route": {
        "path": "/sample-page"
    },
    "settingObjects": [
      {
          "id" : "custom-settings.setting", 
          "type": "customType1",
          "liquidName": "customValues"
      }
    ]
}

customValues can now be used in any Liquid or JSON file as a Liquid object, providing seamless integration across your templates. By declaring it as a global object, customValues becomes accessible throughout the entire project, enabling you to easily reference and manipulate its values within different contexts. This flexibility enhances the reusability and consistency of your configuration data, allowing for dynamic content rendering and more efficient management of custom settings across various pages and components.

<div style="color: {{ customValues.textColor }}">
    {{ customValues.someText }}
</div>