Theme Settings

Introduction

Theme support dynamic settings for use in in a theme that can be managed in the store dashboard theme editor. Theme settings consist of two JSON files in the config directory.

• settings_schema.json - Used to create the settings schema to create the settings form in the dashboard theme editor.

• settings_data.json - Used to store theme settings values for access in templates for template compiling.

Theme settings location

In the configs directory of a theme, theme developers can edit/manage dynamic settings that can be used to customize a theme.

configs
  └── settings_schema.json
  └── settings_data.json

Using Settings in Templates

Settings are passed to templates settings context variable allowing you to access settings values by their name. See example below of changing the layout by conditionally adding a class based on a radio setting.

Settings Schema

{
    "General": {
        "Settings": [
            {
                "name": "store_name",
                "label": "Store Name",
                "help_text": "Public name of your store.",
                "type": "text",
                "max_length": 250,
                "required": 1,
                "default": "Store Name"
            },
            {
                "name": "layout",
                "label": "Layout Style",
                "help_text": "Control the layout style.",
                "type": "radio",
                "options": [
                    {
                        "name": "Boxed",
                        "value": "boxed"
                    },
                    {
                        "name": "Full Width",
                        "value": "full"
                    }
                ],
                "default": "boxed"
            }
        ]
    }
}

Template

<div class="{% if settings.layout == 'boxed' %}container{% endif %}">
    <h1>Welcome to {{ settings.store_name }}!</h1>
    <div>Contionally boxed or full width content</div>
</div>

Attribute Reference

Attribute	Required	Description
type	Yes	Type of form input, see Schema Input Types.
name	Yes	Name of the setting and key for access in template settings object variable.
label	Yes	Theme settings form input label.
help_text	No	Theme settings form input help text that shows below the input.
required	No	JSON boolean, accepts true or false, false by default.
default	No	Default value for the setting.
options	No	List of key:value pairs for options. Applicable to radio and select field types for their choices.
max_length	No	Applicable to text field types to limit the length of text input.
max_value	No	Applicable to number field types to limit the max value.
min_value	No	Applicable to number field types to set a min value.

Schema Input Types

Schema input types map to input fields that will be rendered in the theme settings form in the dashboard.

checkbox

{
    "name": "enable_cookie_msg",
    "label": "Enable Cookie Message Pop",
    "help_text": "Enable cookie message to site visitors.",
    "type": "checkbox",
    "default": true
}

color

{
    "type": "color",
    "name": "btn_primary_color",
    "label": "Primary Button Color",
    "help_text": "Primary color for buttons.",
    "default": ""
}

email

{
    "type": "email",
    "name": "contact_email_address",
    "label": "Public contact email address.",
    "help_text": "Email to show in site footer.",
    "default": ""
}

file

{
    "type": "file",
    "name": "logo",
    "label": "Store Logo",
    "help_text": "Primary logo used throughout the site.",
    "default": "uploads/logo.png"
}

menu

{
    "name": "header_menu",
    "label": "Header Menu",
    "type": "menu",
    "required": true,
    "help_text": "Header Menu"
}

multi-select

{
    "type": "select",
    "multi-select": true,
    "name": "accepted_payment_methods",
    "label": "Accepted Payment Methods",
    "help_text": "Control which payment methods are shown.",
    "options": [
        {
            "name": "Visa",
            "value": "visa"
        },
        {
            "name": "Master Card",
            "value": "mastercard"
        },
        {
            "name": "American Express",
            "value": "amex"
        },
        {
            "name": "Paypal",
            "value": "paypal"
        },
        {
            "name": "Klarna",
            "value": "klarna"
        }
    ],
    "default": [
        "visa",
        "mastercard"
    ]
}

number

{
    "type": "number",
    "name": "homepage_testimonials_count",
    "label": "Homepage Number Testimonials to Show",
    "help_text": "Control the number of homepage testimonials to show",
    "max_value": 10,
    "min_value": 0,
    "default": 3
}

product

{
    "name": "hero_product",
    "label": "Hero Product",
    "type": "product",
    "help_text": "Hero product on homepage banner."
}

products

{
    "name": "featured_products",
    "label": "Featured Products",
    "type": "products",
    "help_text": "Featured products for homepage."
}

product_category

{
    "name": "featured_products",
    "label": "Featured Product Category",
    "type": "product_category",
    "help_text": "Featured product category for homepage"
}

product_categories

{
    "name": "top_product_categories",
    "label": "Top Product Categories",
    "type": "product_categories",
    "help_text": "Featured product categories for homepage"
}

radio

{
    "type": "radio",
    "name": "layout",
    "label": "Layout Style",
    "help_text": "Control the layout style.",
    "options": [
        {
            "name": "Boxed",
            "value": "boxed"
        },
        {
            "name": "Full Width",
            "value": "full"
        }
    ],
    "default": "boxed"
}

select

{
    "type": "select",
    "name": "header_style",
    "label": "Header Style",
    "help_text": "Choose header layout style.",
    "options": [
        {
            "name": "Full Width",
            "value": "full"
        },
        {
            "name": "Boxed",
            "value": "boxed"
        },
        {
            "name": "Overlay",
            "value": "overlay"
        }
    ],
    "default": "full"
}

text

{
    "type": "text",
    "name": "store_name",
    "label": "Store Name",
    "help_text": "Public name for your store.",
    "max_length": 250,
    "required": true,
    "default": "My New Store Name"
}

textarea

{
    "type": "textarea",
    "name": "description",
    "label": "Description",
    "help_text": "Example input textarea",
    "default": "Test"
}

url

{
    "type": "url",
    "name": "social_link",
    "label": "Social Media Link",
    "help_text": "Link to your social media page.",
    "default": ""
}