Templates ​

Templates control what’s rendered on each page in a theme.

Each page type in the storefront should have an associated template type. These can be used to add functionalities and experiences that belong in said pages. For example, you can add upsells in the cart page template.

Location ​

Templates are located in the templates directory of the theme

└── theme
    ├── layout
    ├── templates
    |   ├── article.json
    |   ├── product.json
    |   ...
    ...

Template types ​

Each available template type represents a type of page that is available in the seller’s storefront. No types are required, but you must have implemented a type for each page that you want to render, otherwise it will fall back to the defaults.

Schema ​

A JSON template only accepts a JSON file with a fixed schema and a list of possible attributes or props.

Template wrapper ​

The wrapper property makes it possible to surround the injected sections with custom HTML tags. The following tags are available: <div>, <main>, and <section>. The format should be a valid CSS selector, that will be converted into a full HTML tag like the following:

{
  ...
  "wrapper": "section#section_identifier.section_class[data-attr=attr_value]",
  ...
}

<section id="section_identifier" class="section_class" data-attr="attr_value">
    <!-- injected sections -->
</section>

Section data ​

The sections attribute in a template holds the data for the sections that will be rendered within. Section data cannot be shared across JSON theme templates, so each section must have an identifier that is unique within the template. Templates can render up to 25 sections, and each section can render up to 50 blocks.

Sections can be added to a template in code, or through the Theme Editor. The sections that are able to be socketed may be limited by the templates attribute of the section schema. If no templates attribute is defined, then the section can be socketed into any template.

The following table elaborates on section data format, note that values wrapped in < > are to be provided by the integrator.

sections: {
  <section_id>: {
    "type": <section_type>,
    "disabled": <section_disabled>,
    "settings": {
      <setting_id>: <setting_value>
    },
    "blocks": {
      <block_id>: {
        "type": <block_type>,
        "settings": {
          <setting_id>: <setting_value>
        }
      }
    },
    "block_order": <block_order>
  }
}

For example, the following template renders the main-product.liquid and the upsells.liquid sections on the product page, and renders the variants block in the main product section. The filename is templates/product.json:

{
    "label": "A product template",
    "sections": {
        "main": {
            "type": "main-product",
            "settings": {
                "show_discount": false
            },
            "blocks": {
                "some_block": {
                    "type": "variants",
                    "settings": {
                        "show_all": false
                    }
                }
            },
            "block_order": ["some_block"]
        },
        "some_other_id": {
            "type": "upsells"
        }
    },
    "order": ["main", "some_other_id"]
}

The following example is the bare minimum template definition:

{
    "sections": {
        "some_id": {
            "type": "main_product"
        }
    },
    "order": ["some_id"]
}

index ​

The index template handles the rendering of the landing page of the store. It is the usually the first page a customer sees, and must therefore provide a large selection of customization options allowing sellers to customize their stores and create unique first impressions and use experiences.

Location ​

The index template is located in the templates directory of the theme.

└── theme
    ├── layout
    ├── templates
    |   ...
    |   ├── index.json
    |   ...
    ...

product ​

The product templates handles the rendering of the product page. It is responsible for displaying the product's information, media, and the appropriate forms for variant selection and adding to cart.

Location ​

The product template is located in the templates directory of the theme.

└── theme
    ├── layout
    ├── templates
    |   ...
    |   ├── product.json
    |   ...
    ...

Content ​

The product template should include the following:

• The global Product object.
• The Product form, implementing the modules listed below.

Variant selector ​

Quantity input ​

Checkout inputs ​

Usage ​