JSON templates​

JSON templates enable you to use sections to manage the display of various pages on your online store.

JSON templates store a list of sections and related settings to render the corresponding page template. Merchants can add, remove, and arrange these sections in the theme editor.

When rendering a page with JSON templates, sections will be shown in the order specified by the order attribute, without HTML between sections. JSON templates can display up to 25 sections.

Although JSON templates differ from HTML templates in content, they still support the following SHOPLINE theme features:

When you create JSON templates, you should also create a section that includes the template's main functionality. For example, when you create a collections_all JSON template, it should reference a section using the collections object.

Schema​

JSON templates must be a valid JSON file. This file's root object includes the following attributes:

Attribute NameTypeRequiredDescription
nameStringYesThe file name of the page, e.g., index.html
layoutString or falseNoUses the file from the layout directory to render the template. For example, specifying "full-width" renders layout/full-width.html

Defaults to layout/theme.html

Using false will directly use layout/theme.html
wrapperStringNoDefines the HTML tag wrapping the sections, see wrapper attribute
sectionsObjectNoAn object containing sections with their IDs and data in key-value pairs

Duplicate section IDs are not allowed

This configuration follows the same rules as config/settings_data.json, see sections data for details.
orderArrayNoAn array of section IDs specifying the order of sections on the page. Section IDs must be keys in the above sections configuration, and duplicates are not allowed
Tip

Section files must define presets in their schema to support adding them to JSON templates using the theme editor. Sections without presets must be manually included in the JSON file and cannot be removed using the theme editor.

Naming JSON Templates​

File names must be valid theme template types, with optional suffixes for alternate templates. For example, a collection template can be named collection.json or collection.alternate.json.

Templates can only exist as JSON or HTML templates. If both exist, the JSON template will be used.

Wrapper Attribute​

The wrapper attribute can wrap all sections in a JSON template with an HTML tag.

For example, a JSON file using the wrapper attribute would produce the following output:

{
  "wrapper": "div#div_id.div_class[data-video=value]",
  "sections": {
    "video": {
      "type": "video"
    }
  },
  "order": [
    "video"
  ]
}
<div id="div_id" class="div_class" data-video="value">
  <!-- index.json sections -->
</div>

Section Data​

The sections attribute of JSON templates holds the data for sections to be displayed by the template. These can be theme sections or app sections. Section data cannot be shared across JSON templates, so each section must have a unique ID within the template.

JSON templates can display up to 25 sections.

You can add sections via code or the theme editor.

Here are the section configuration options and explanations:

ValueTypeRequiredDescription
<SectionID>String-The unique ID of the section, only letters and numbers are allowed
<SectionType>StringYesThe file path and name in the sections folder, excluding the file extension
<SectionDisabled>BooleanNoWhen set to true, this section will not be rendered but can still be customized in the theme editor, defaults to false
<BlockID>String-The unique ID of the block, only letters and numbers are allowed
<BlockType>StringYesThe block type, found in the section file's schema definition
<BlockOrder>ArrayNoAn array of block IDs specifying their display order. Block IDs must be defined in the blocks object, and duplicates are not allowed
<SettingID>String-The setting ID defined in the block or section schema
<SettingValue>(multiple)-The valid value for the corresponding configuration

For example:

sections: {
  <SectionID>: {
    "type": <SectionType>,
    "disabled": <SectionDisabled>,
    "settings": {
      <SettingID>: <SettingValue>
    },
    "blocks": {
      <BlockID>: {
        "type": <BlockType>,
        "settings": {
          <SettingID>: <SettingValue>
        }
      }
    },
    "block_order": <BlockOrder>
  }
}

For example: the following template displays product-preview.html and recently-viewed.html section files on the product page:

{
  "name": "products/detail.html",
  "wrapper": "div#page-product-detail",
  "sections": {
    "product-preview": {
      "type": "product/detail/product-preview",
      "disabled": false,
      "settings": {
        "default_selected_sku": true
      },
      "blocks": {
        "block-1": {
          "type": "title",
          "settings": {}
        },
        "block-2": {
          "type": "abstract",
          "settings": {}
        }
      },
      "block_order":["block-1","block-2"]
    },
    "recently-viewed":{
      "type": "product/recently-viewed",
      "settings": {
        "show_product_number": 6,
        "product_image_ratio": "0"
      }
    }
  },
  "order": ["product-preview", "recently-viewed"]
}
Caution

All sections included in the template (not app sections) must exist in the theme. If they do not, this will cause an error.

Was this article helpful to you?
SHOPLINE
SHOPLINE
SHOPLINE Enterprise
Legal
Privacy
Terms
Developer Agreement
LinkedInEmail
LinkedInEmail
© Copyright 2013-2025 SHOPLINE Limited.