Introduction

What Is Live Preview Function

The theme customization page allows online store owners to configure their themes while viewing a real-time preview of their storefronts. Themes are edited in the theme menu, and changes are previewed in real time in the left window. The theme customization page looks like this:

customization overview

All themes include a schema.json file which controls how theme settings are displayed in the theme menu. The schema.json file is located in the theme’s metadata directory.

How to Apply Live Preview

Follow below steps to apply the live preview function to your theme customization page:

  • Define Theme Customization Page

Edit the schema.json file in the metadata directory following the specified file format.

  • Modify Theme Files

Modify theme twig and assets files to apply customization settings.

Mixed HTTP and HTTPS Content

Live preview window uses iframe to display the online store themes. As HTTPS is used in the backend theme customization page, so it’s essential that the theme also supports the using HTTPS, and it contains no hard-coded HTTP assets.

Theme Menu Definition

What Is schema.json

schema.json controls the layout and content of the theme menu, and it must follow the specified file format.

Define schema.json

The structure of schema.json is as follows:

Sections

schema.json contains sections. Each section controls a corresponding section in the theme menu.

Section attributes are shown in the table below:

attribute mandatory description

label

mandatory

section name

icon

optional

section icon

settings

mandatory

section page content settings

Example:

[
    {
        "label": "General",
        "icon": "icon-setting iconfont-anw",
        "settings": [
            {
                "type": "group",
                "members": [
                    {
                        "id": "bg_color",
                        "type": "color",
                        "label": "Body background color",
                        "default": "transparent"
                    },
                    {
                        "id": "header_logo_text_color",
                        "type": "color",
                        "label": "Logo text color",
                        "default": "#333333"
                    }
                ]
            }
    }
]

Output:

settings siderbar
section

Components

The theme settings consist of a number of components which can be used by the online store owners to configure the theme for their store. The online store owners access the theme settings from the theme menu.

Component attributes are shown in the table below:

attribute mandatory description

id

mandatory

description

type

mandatory

component name

label

mandatory

component icon

default

optional

component default value

Basic Components

Basic components are used to change the theme’s common variables, such as texts, numbers and images. The preview page will refresh when the values of the basic components change

  • Checkbox

checkbox is used for toggling preferences on or off, for example, displaying or hiding elements on a page.

Example:

{
    "id": "homepage_slides_auto_rotate",
    "type": "checkbox",
    "label": "Enable slides auto rotate",
    "default": true
}

Output:

checkbox
  • Image

image represents an image the media library.

Example:

{
    "id": "header_custom_favicon",
    "type": "image",
    "label": "Custom favicon",
    "default": ""
}

Output:

image
  • Text

text is used to input a string.

Example:

{
    "id": "homepage_slide1_text",
    "type": "text",
    "label": "Slider1 text",
    "default": ""
}

Output:

text
  • Number

number is used to input a number.

Example:

{
    "id": "header_logo_height",
    "type": "number",
    "label": "Logo area height",
    "default": "96px"
}

output:

number
  • URL

url is used to input a URL.

Example:

{
    "id": "homepage_slide1_url",
    "type": "url",
    "label": "Slider1 url",
    "default": ""
}

Output:

url
  • Select

select is used to select an option.

Example:

{
    "id": "homepage_option",
    "type": "select",
    "label": "Select an option",
    "options": [
        { "value": "8", "label": "8 Customers"},
        { "value": "16", "label": "16 Customers"},
        { "value": "24", "label": "24 Customers"}
     ],
	 "default": "8"
}

Output:

select
CSS Components

CSS components are used to change the CSS variables. The preview page will not refresh when the values of the CSS components are changed.

  • Color

color represents a color picker, for example, changing background colors, text colors and menu colors.

Example:

{
    "id": "bg_color",
    "type": "color",
    "label": "Body background color",
    "default": "transparent"
}

Output:

color
  • _Background _

background represents an image in the media library. It is used to change the theme’s background image only.

Example:

{
    "id": "bg_image",
    "type": "background",
    "label": "Background image",
    "default": ""
}

Output:

background
  • Font Size

font_size represents a dropdown select. It is used to select a font size for a text.

Example:

{
    "id": "font_size",
    "type": "font_size",
    "label": "Font Size",
    "default": "14px"
}

Output:

fontsize
  • Font Family

font_family represents a dropdown select. It is used to select a font family for a text.

Example:

{
    "id": "font_family",
    "type": "font_family",
    "label": "Font family",
    "default": "Arial, 'Microsoft Yahei', sans-serif"
}

Output:

fontfamily
Backend Data Components

Backend data components are used to change the theme’s backend data variables, such as menus, pages and collections. The preview page will refresh when the values of the Backend components are changed.

  • Menu

menu represents a dropdown select. It is used to select a menu.

Example:

{
    "id": "header_brand_menu",
    "type": "menu",
    "label": "Brand menu",
    "default": "default-menu"
}

Output:

menu
  • Collection

collection represents a dropdown select. It is used to select a collection.

Example:

{
    "id": "homepage_featured_products_collection",
    "type": "collection",
    "label": "Featured products source collection",
    "default": "all"
}

Output:

collection
  • Page

page represents a dropdown select used to select a page.

Example:

{
    "id": "select_page_as_homepage",
    "type": "page",
    "label": "Select a page as the homepage",
    "default": ""
}

Output:

page

Sample

To get the sample schema.json file, access the Starter theme code, and open the metadata folder.

Modify Theme Files

Modify your twig and less files to apply the settings in schema.json.

Modify Less Files

To apply the CSS components, modify the less files. For example, to change the background color, add code in both schema.json and the less files.

schema.json:

{
    "id": "bg_color",
    "type": "color",
    "label": "Body background color",
    "default": "transparent"
}

less file:

body {
  background-color: @bg_color;
}

Modify Twig Files

To apply the Basic components and Backend data components, please modify the twig files. You can get the values in twig files by themeOptions[id]. For example, to enable the slide show add code in both schema.json and the twig files.

schema.json:

{
    "id": "homepage_enable_slides",
    "type": "checkbox",
    "label": "Enable slides",
    "default": false
}

twig file:

{% if themeOptions['homepage_enable_slides'] %}
            <div class="slides section-margin large">
                <!------   Slide Section ------>
            </div>
{% endif %}