Page Templates

Page templates have template markup with a schema tag that defines what parameters the template plans to use.

Schemas

Schemas are JSON objects enclosed between {% schema %} and {% endschema %} tags. An example schema looks like this:

{
    "key1": {
        "type": "string"
    },
    "key2": {
        "type": "item",
        "optional": true
    },
    "key3": {
        "type": "string",
        "optional": true,
        "default": "default string"
    }
}

A template’s schema creates a contract between the template and the page definition. The schema obligates the page to provide values for the items listed in the schema. The page does this via the page properties which are represented as JSON files.

Using twig to generate schema

Twig is supported within schema tags. You can use it to do all of the usual things you’d do in a template. Do note that the schema tag doesn’t get access to schema values because it defines them.

One example use case is for setting defaults from a global config:

theme/config/defaults.json

{
    "footer": {
        "socials": [
            {
                "link": {
                    "company": "twitter",
                    "label": "X",
                    "type": "external",
                    "href": "https://www.x.com"
                }
            },
            {
                "link": {
                    "company": "instagram",
                    "label": "Instagram",
                    "type": "external",
                    "href": "https://www.instagram.com"
                }
            }
        ]
    }
}

theme/components/sections/footer.html.twig

...
{% schema %}
	{
		"socials": {
			"type": "array",
			"optional": true,
			"default": {{ config.defaults.footer.socials | json_encode }}
		}
	}
{% endschema %}

Page Example

theme/layouts/my_layout.html.twig 

<!DOCTYPE html>
<html lang="{{ square.site.language }}">
	<head>
		{% block head %}

		{% endblock %}
	</head>
	<body>
		{% block main_content %}
		{% endblock %}
	</body>
</html>

theme/templates/pages/my_page.html.twig 

{% extends "layouts/my_layout" %}

{% block main_content %}
	<p>Example Item: {{ product.name }}</p>
	<p>Example Category: {{ cat.name }}</p>
	<p>Example String: {{ simple }}</p>
	<p>Example Optional: {{ optional }}</p>
{% endblock %}

{% schema %}
{
	"product": {
		"type": "item"
	},
	"cat": {
		"type": "category"
	},
	"simple": {
		"type": "string"
	},
	"optional": {
		"type": "string",
		"optional": true,
		"default": "Default string"
	}
}
{% endschema %}

site/pages/myPage.json 

{
	"template": "theme/pages/my_page",
	"name": "My Page (for Product #5)",
	"props": {
		"product": {
			"filters": {
			"id": 5
			}
		},
		"cat": {
			"filters": {
			"id": 1
			}
		},
		"simple": "example"
	}
}

Output 

<html>
	<head>
		<title>My Site</title>
	</head>
	<body>
		<p>Example Item: ITEM NAME</p>
		<p>Example Category: CATEGORY NAME</p>
		<p>Example String: example</p>
		<p>Example String: Default string</p>
	</body>
</html>

System Page Templates

Pages that handle core store functionality (such as the Shop All page, Product Detail page, and Category Detail page) are called System Pages, and can always be accessed on a site. By default, they are rendered by the Square Online app, but can be overridden by uploading an associated template file to the theme/templates/store directory. Each System Page is associated with a unique template filename which is used for rendering the page. Each System Page also has preconfigured properties which is passed through for use in the template.

See System Page Templates for more details.