Previewing theme editor changes

Fields can be set to update the theme preview when their value changes.

Theme editor field preview

By default a field does not show it's changes in the preview area of the theme editor. A developer needs to configure the field in the theme-settings.json or theme-styles.json file with how the field should be previewed. This allows the developer to choose which fields are best to preview and how they should be previewed.

The preview configuration is done with the render data for the field.

{
  "label": "Page heading",
  "name": "pageHeading",
  "type": "text",
  "render": {
    "type": "content",
    "contentSelector": ".someSelector"
  }
}

The render data can have the following values:

contentSelector The CSS selector for one or more HTML elements that will be updated when the field value changes. This is used if type is content or replace.
cssSelector The name of the CSS selector to output with the field value. This is used if type is css-head.
cssProperty The name of the CSS property to output with the field value. This is used if type is css-head.
cssVariable. The name of the CSS variable to output with the field value. This is used if type is css-head.
mediaQuery The CSS media query to apply the style under. This is used if type is css-head.
state The element state to apply the style to. This is used if type is css-head. Allowed values include active, focus, and hover.
template The template for the field value if you need to alter it before previewing the value. This can be used with all of the type values.
type (required) This specifies how the field value will be previewed. Allowed values include css-head, content, and replace.

How the field changes are previewed

If a field has the render configuration set, then the value changes are previewed under one of two events:

When the individual field value changes it's value is immediately previewed in the theme.
When one field changes, all other fields that have render configured are also processed.

The reason that all fields are processed when one field changes is so that you can access other field's values when preparing the preview value for an individual field. There are some instances where you need to include another field's value in a field's preview output.

Preview types

There are three ways that field changes can be previewed:

Inline CSS change.
Update the inner HTML of one or more HTML elements.
Replace one or more HTML elements.

Inline CSS change.

If the render type is set to css-head then some inline CSS gets injected into the <head> area of the theme preview when the field value changes. The same CSS will also be set when you save the changes in the theme editor. That CSS will be output automatically in the <head> area of your website where the {{ _page.themeStyles() }} tag is in your template.

See the theme styles page for more information.

Update the inner HTML of one or more HTML elements

If your field is for some content then replacing the inner HTML of an HTML element is a common approach to preview that content change.

Here is how you replace the inner HTML an HTML element with the value of a field.

Set the type value to content.
Set the contentSelector to the DOM selector for the element that will be replaced.

The content render type is not used to update templates when the theme settings and styles are saved. You need to use the _core.theme.settings data in your templates to output the data. See the Theme Settings page for more information.

Supposed that you have a div tag that holds a heading for a page like this:

<div class="TextHeading">My heading here</div>

In the theme settings we want to have a text field to configure the heading value. Here is the field JSON and the render configuration to display that in the .TextHeading div.

{
  "label": "Heading text",
  "name": "headingText",
  "type": "text",
  "render": {
    "type": "content",
    "contentSelector": ".TextHeading"
  }
}

The above configuration tells the theme settings to find one or more HTML elements with a class name of TextHeading and replace it's inner content with the value of this text field.

You can also use the template value to control how the content is output. In this example we're going to output a copyright symbol in front of a company name.

{
  "label": "Company name",
  "name": "companyName",
  "type": "text",
  "render": {
    "type": "content",
    "contentSelector": ".CopywriteCompany",
    "template": "&copy; {{ value }}"
  }
}

Replace one or more HTML elements

In some situations, it may be better to replace an HTML element in the theme preview instead of replacing its inner content. An example scenario is to replace an image or a link tag.

Here is how you replace an HTML element with the value of a field.

Set the type value to replace.
Set the contentSelector to the DOM selector for the element that will be replaced.
Ideally, use template to output the value with the same HTML as the element that was just replaced.

The replace render type is not used to update templates when the theme settings and styles are saved. You need to use the _core.theme.settings data in your templates to output the data. See the Theme Settings page for more information.

Below is an example of previewing a logo image change.

{
  "label": "Logo",
  "name": "logo",
  "type": "image",
  "render": {
    "type": "replace",
    "contentSelector": ".Logo",
    "template": "<img src=\"{{ url }}\" height=\"{{ imageHeight }}\" width=\"{{ imageWidth }}\" alt=\"{{ alt }}\" class=\"Logo\">"
  }
}

Theme editor-only CSS selector

If you are adding a selector to an HTML element only for the theme settings then it's recommended to use a data attribute on the HTML element.

Something like this:

<div data-theme="mySelector"></div>

You can then set that as the contentSelector like this: [data-theme='mySelector'].

{
  "label": "Company name",
  "name": "companyName",
  "type": "text",
  "render": {
    "type": "content",
    "contentSelector": "[data-theme='mySelector']",
    "template": "&copy; {{ value }}"
  }
}

Preview output templates

You can use the template value if you need more control over the preview output or you need some logic to determine the preview output.

We use a Javascript version of Twig to allow developers to incorporate some basic logic in the preview output templates.

The Javascript Twig syntax does not have any of the custom filters, functions, or tags that are unique to Aptuitiv. Only core Twig syntax can be used.

The Twig rendering engine is sensitive to curly brackets. Don't place Twig tags or variables right after the curly brackets for a CSS declaration. They will be interpreted as variables. Put a space after and before the CSS declaration curly brackets.

{# Don't do this #}
"template": ".Accordion-heading {{% if value == 'before' %} justify-content: flex-end; flex-direction: row-reverse;{% else %} justify-content: {{ value }};{% endif %}}"

{# Do this: place a space after the opening { and before the closing } for the CSS #}
"template": ".Accordion-heading { {% if value == 'before' %} justify-content: flex-end; flex-direction: row-reverse;{% else %} justify-content: {{ value }};{% endif %} }"

Access other field's values

Within the template value you can access other field's values. There may be a case where you need to use multiple field's together to output a CSS style. Or, you may need to use another field's value in some logic to determine how to output the value of a field.

All of the other theme setting field values can be accessed under the fields variable like this:

{{ fields.fieldName.value }}

Replace "fieldName" with the name that you set for that field.

All field values are available in the fields variable, even if they don't have the render configuration.