Site Directory

The files in the site directory represent the pages and settings of your site. Site files can reference specific site data like item or category IDs.

Directory Structure

site
├── pages
│   ├── page1.json
│   ├── anotherPage.json
│   └── ...

Page JSON Files

The files in the pages directory represent your site’s pages.

Example Page JSON

{
  "template": "templates/pages/page1",
  "route": "featured-product",
  "name": "Item Page #1",
  "passwordProtected": false,
  "props": {
    "item": {
      "filter": {
        "id": 1
      }
    },
    "someString": "value"
  }
}

Fields

Field	Description
template	Optional field that defines which template in the `theme` directory to use for rendering the page content.
route	The url where this page can be viewed. In this example you would be able to view the page at the `/featured-product` route.
props	A JSON object of stored variables and queries that supplies site data for the keys defined in the page template schema.
name	Optional field which defines a custom name to display in the Editor when editing this Page. If left blank, the default name from the Page’s Controls Schema will be used.
passwordProtected	Optional boolean field to password protect the page (`false` by default). Must have a site password configured in the Square Online dashboard for this to take effect.

Route variables

Routes can assign parts of a URI to variables that can be used in the page JSON. This can be used to create dynamic routes where resources are loaded based on the value of the URI part.

collection.json

{
    "template": "templates/pages/collection",
    "route": "collection/:category_name/:category_id",
    "props": {
        "category": {
            "filters": {
                "id": "request_data(path.category_id)"
            }
        }
    }
}

collection.html.twig

{{ category.name }}

{% schema %}
{
	"category": {
		"type": "category"
	}
}
{% endschema %}

request_data function

In addition to having path variables available in the page JSON, developers also have access to the request’s route and request’s query params. Simply use the object property with the request_data function in your prop.

request_data(x.y.z)

// Sample `request_data` for a request to
// mysite.com/categories/accessories/3?per_page=50&current_page=1&random_query_param=xyz
{
  "route": "categories/:category_name/:category_id",
  "path": {
    "category_name": "accessories",
    "category_id": "3"
  },
  "query": {
    "per_page": "50",
    "current_page": "1,
    "random_query_param": "xyz"
  }
}

In addition, a default value can be provided as a second parameter if no match is found for the property.

To provide a default request_data property, provide it without any quotes. If no match is found on the default, an empty string is returned.

request_data(x.y.z, a.b.c)

Otherwise, to provide a default string, surround it with quotes.

request_data(x.y.z, 'fallback string')

request_data props are only resolved on initial render of the page. It will not be properly resolved if attempting to pass in a template API prop. You must pass the resolved values as the props for the template API request.

config function

The config function allows you to load configuration data from the theme’s config files. This data can then be injected and used in your HTML Twig templates.

config(x.y.z)

// Sample config usage

// Define your config JSON
// theme/config/header.json
{
    "header_colors": {
         "red": {
             "hex": "#FF0000",
             "rgb": "rgb(255,0,0)"
         }
    },
    "colors": [
        "red",
        "blue",
        "yellow"
    ]    
}

// Use the config function to load it into your page JSON
// site/pages/page1.json
{
    "props": {
        "color": "config(header.header_colors.red.hex)", // this should be "#FF0000"
        "colors": "config(colors)" // this will output the entire array: ["red", "blue", "yellow"]
    }
}

// Use it in your template as below
// theme/templates/pages/page1.html.twig
{{ color }}
{{ colors|join(', ') }}
{% schema %}
{
    "color": {
        "type": "string"
    },
    "colors": {
        "type": "array"
    }
}
{% endschema %}

If the input is not given or the relevant config object is not found, an empty string will be returned.

You can access elements in arrays by their index, e.g., config(header.colors.0) and this will return ‘red’.

global_settings function

The global_settings function allows you to load global settings data from the site’s global settings file. This data can then be injected and used in your HTML Twig templates.

global_settings(x.y.z)

// Sample global_settings usage

// Define your global settings JSON
// site/settings/global.json
{
    "size": "large",
    "sizes": ["small", "medium", "large"]
}

// Use the global_settings function to load it into your page JSON
// site/pages/page1.json
{
    "props": {
        "size": "global_settings(size)", // this should be "large"
        "sizes": "global_settings(sizes)" // this will output the entire array: ["small", "medium", "large"]
    }
}

// Use it in your template as below
// theme/templates/pages/page1.html.twig
{{ size }}
{{ sizes|join(', ') }}
{% schema %}
{
    "size": {
        "type": "string"
    },
    "sizes": {
        "type": "array"
    }
}
{% endschema %}

If the input is not given or the relevant global settings object is not found, an empty string will be returned.

You can access elements in arrays by their index, e.g., global_settings(sizes.0) and this will return ‘small’.

Self-referencing in global settings

The global_settings function supports self-referencing, allowing you to define settings that reference other settings within the same global settings file.

// Example of self-referencing global settings

// site/settings/global.json
{
  "heritable": {
    "primaryColor": "global_settings(foo.bar.baz)"
  },
  "foo": {
    "bar": {
      "baz": "red"
    }
  }
}

// Use the global_settings function to load self-referenced settings into your page JSON
// site/pages/page1.json
{
    "props": {
        "primaryColor": "global_settings(heritable.primaryColor)"
    }
}

// Use it in your template as below
// theme/templates/pages/page1.html.twig
{{ primaryColor }}
{% schema %}
{
    "primaryColor": {
        "type": "string"
    }
}
{% endschema %}

If a circular reference is detected within the global settings file, an error view page will be displayed when rendering the page, showing the source file of the global settings. This requires the developer to correct the circular reference in the JSON.

Escaping functions

If you don’t want the functionality to be triggered for the function above and just want the raw string, simply prefix the function with \ (e.g. "\request_data(x.y.z, a.b.c)").

request global context

Alternatively, all request_data props can be used directly in a template directly via the request global context.

{{ request.path.category_name }}

However, note that like request_data, request will only resolve on initial render of the page. It will not be properly resolved if the template is loaded via the template API.