sections​

The sections directory contains all sections for a theme. A section is the core element for page construction, primarily used to define the structure and functions of different page modules. Merchants can freely add, delete, move, and edit sections in a theme.

Directory structure​

Within the sections directory, each section must have its unique directory, containing an .html file with the same name as the directory. A section can consist of the following three types of files:

• .html (required): Used to define the HTML layout of the section.
• .css (optional): Used to define the styling of the section.
• .js (optional): Used to define the interaction logic of the section.

sections
├── announcement-bar
│   ├── announcement-bar.css
│   ├── announcement-bar.js
│   └── announcement-bar.html
├── blog
│   ├── blog.css
│   └── blog.html

Create a section​

The .html file of each section generally contains the following two parts:

• HTML: defines the layout of the section.
• schema: defines the configuration settings of the section. These settings display in the theme editor, allowing merchants to make custom configurations.

The following parts take the featured-collection as an example, showing the steps of creating a section.

1.Add section files​

Create a new directory named featured-collection under the sections directory, and then create an .html file with the same name inside the new directory. The following shows the directory structure:

sections
└── featured-collection
    └── featured-collection.html

2.Define the schema configuration​

Add the schema tag in the featured-collection.html file.

<!-- sections/featured-collection/featured-collection.html -->
{{#schema}}
{
  "name": "featured-collection",
  "settings": [
    {
      "type": "collection",
      "id": "collection",
      "label": "collection"
    }
  ]
}
{{/schema}}

3.Render the schema configuration​

In the .html file, obtain the section configuration by specifying section.settings, and use the collection control to get the collection title selected by the merchant. The ID of the section setting is collection.

The configuration example is as follows:

<!-- sections/featured-collection/featured-collection.html -->
<section>
  title: {{section.settings.collection.title}}
</section>
{{#schema}}
{
  "name": "featured-collection",
  "settings": [
    {
      "type": "collection",
      "id": "collection",
      "label": "collection"
    }
  ]
}
{{/schema}}

The output is as follows:

<section>
  title: /collections/foo
</section>

Create a private block in the section​

Blocks are supported within sections. You can segment a section's functionality into different blocks and assemble them in the section.

1.Add files of private blocks​

The private blocks for a section must be stored in the blocks directory within the section.

Create the private block directory blocks under the sections/featured-collection section, shown as follows:

sections
└── featured-collection
    ├── featured-collection.html
    └── blocks
        ├── heading.html          # The title block
        └── product-list.html     # The product list block

2.Define the HTML layout for the block​

In the heading.html block file, use the props object to obtain the text field passed in the section.

<!-- sections/featured-collection/blocks/heading.html -->
<div class="heading">
  <div>{{props.text}}</div>
</div>

In the product-list.html file:

1. Use the props object to obtain the collection field passed in the section.
2. Use the get_product_pagination filter to obtain the product pagination data.
3. Render the product content by using the for tag.

<!-- sections/featured-collection/blocks/product-list.html -->
{{#var products_pagination = props.collection | get_product_pagination(4) /}}
{{#var products = products_pagination.list /}}
<ul>
  {{#for product in products}}
    <li>
      <div>{{product.title}}</div>
    </li>
  {{/for}}
</ul>

3.Render blocks​

After creating blocks, you can reference them in the section.

• Within the div element, use the blocks and block tags to render blocks.
• Within the schema, add block-related fields.

<div>
  {{#blocks}}
    {{#if forblock.type == "$heading"}}
      <!-- Pass section.settings.collection.title to the heading block-->
      {{#block text=section.settings.collection.title /}}
    {{#else if forblock.type == "$product-list" /}}
      <!-- Pass section.settings.collection to the product-list block-->
      {{#block collection=section.settings.collection/}}
    {{/if}}
  {{/blocks}}
</div>
{{#schema}}
{
  "name": "featured-collection",
  "settings": [
    {
      "type": "collection",
      "id": "collection",
      "label": "collection"
    }
  ],
  "blocks": [
    {
      "type": $heading",
      "limit": 1
    },
    {
      "type": "$product-list",
      "limit": 1
    }
  ]
}
{{/schema}}

Section group​

A section group is a collection of related sections, used to manage the sections and their configurations that will render together. The section group is defined by .json files, which must be stored under the root directory sections. The directory structure example is as follows:

sections
├── header-group.json     
└── footer-group.json

Schema​

The following shows the JSON data specification of a section group:

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

The following table explains the fields in the JSON data specification.

The following example shows the schema in header-group.json.

{
  "name": "Header Group",
  "type": "header",
  "sections": {
    "announcement-bar": {
      "type": "announcement-bar",
      "blocks": {
        "announcement-bar__item1": {
          "type": "$item"
        }
      },
      "block_order": ["announcement-bar__item1"]
    },
    "header": {
      "type": "header"
    }
  },
  "order": ["announcement-bar", "header"]
}

Using section groups​

Use section groups through the sections tag.

The following example shows how to reference the header-group.json section group within the layout/theme.html file.

<!DOCTYPE html>
<html lang="{{request.locale.iso_code}}">
  <head>
    ...
  </head>
  <body>
    ...
    {{#sections "header-group" /}}
    ...
  </body>
</html>

Merchants can add, delete, and reorder sections within the section group via the theme editor.

Fixed sections​

Fixed sections are part of the theme that merchants cannot add, delete, or rearrange through the theme editor, such as the page header and footer. Merchants can only modify settings of these sections.

The fixed sections must be included and referenced in the layout file.

Using fixed sections​

You can reference fixed sections in the layout file by using the section tag.

As shown in the following example, in the Bottle theme, fixed sections are referenced in the layout file for the password protection page.

<!-- layout/password.html -->
<!DOCTYPE html>
<html>
<head>
  {{#content "header" /}}
</head>
<body class="password-page">
  {{#section "main-password-header" /}}	<!-- Reference the fixed section main-password-header -->
  ...
  {{#content "layout" /}}
  ...
  {{#section "main-password-footer" /}}	<!-- Reference the fixed section main-password-footer -->
  {{#content "footer" /}}
</body>
</html>

Asynchronous section rendering​

You can use the capability of asynchronous section rendering by sending AJAX requests to fetch specific section HTML snippets. These snippets can then be used to dynamically replace page elements and update the content without the need to reload the entire page.

For more details, refer to Section rendering API.

Section schema​

In the schema tag of a section, you can define various attributes of the section, such as the section name. The schema of a section includes the following attributes:

• name
• class
• settings
• blocks
• max_blocks
• presets
• icon

name​

The name attribute defines the section title displayed in the theme editor.

The following example shows name specified in the schema.

{{#schema}}
{
  "name": "Slideshow"
}
{{/schema}}

The section title rendered in the theme editor is shown as follows:

class​

When you render a section in a theme page, the section is automatically wrapped in an HTML element with the default shopline-section class. You can append the class value by defining the class attribute in the section schema.

For example, the class attribute in a section is defined as follows:

{{#schema}}
{
  "name": "Slideshow",
  "class": "slideshow"
}
{{/schema}}

Then the new HTML output is as follows, with the new class value of shopline-section slideshow.

<section id="shopline-section-[id]" class="shopline-section slideshow">
  // ...
</section>

settings​

You can create section configuration settings for merchants to customize the section in the theme editor.

{{#schema}}
{
  "name": "Richtext",
  "settings": [
    {
      "type": "richtext",
      "id": "title",    
      "label": "Title",
      "default": "Rich text"
    }
  ]
}
{{/schema}}

Access configuration settings​

You can access configuration settings for the section via section.settings.

<div>{{ section.settings.title }}</div>
{{#schema}}
{
  "name": "Slideshow",
  "settings": [
    {
      "type": "richtext",
      "id": "title",
      "label": "Title",
      "default": "Rich text"
    }
  ]
}
{{/schema}}

blocks​

You can create reusable blocks for a section. The blocks can be added, deleted, and reordered in a section.

blocks contains a list of blocks, with the following attributes:

{{#schema}}
{
  "name": "Slideshow",
  "blocks": [
    {
      "type": "heading-with-link/heading-with-link",
      "limit": 1
    },
    {
      "type": "product-list/list",
      "limit": 1
    }
  ]
}
{{/schema}}

max_blocks​

The max_blocks attribute indicates the maximum quantity of blocks that a merchant can use in the section via the theme editor. The following shows an example:

{{#schema}}
{
  "name": "Slideshow",
	"max_blocks": 5
}
{{/schema}}

presets​

The presets attribute is used to define the display of the section's preset configurations when the section is added through the theme editor.

This attribute is an array, where the number of elements in the array represents the number of preset configurations available for the section. Each section must contain at least one preset configuration.

When a merchant adds a section in the theme editor, the preset configuration of the selected section is added to the corresponding JSON Template.

Each item in presets has the following attributes:

The following shows a presets example in a section.

{{#schema}}
{
  "name": "Slideshow",
  "settings": [
    {
      "type": "text",
      "id": "title",
      "label": "Title"
    }
  ],
  "presets": [
  	{
      "name": "Image slideshow",
    	"settings": {
      	"title": "Image"
      },
      "blocks": [
        {
          "type": "$image",
          "settings": {
            "text": "image item"
          }
        }
      ]
    }
  ]
}
{{/schema}}

icon​

The icon attribute is used to display the section icon in the drag-and-drop zone in the theme editor. Valid values are as follows:

Value	Icon to display
footer
header
testimonials
orderPlacement
products
collection
collectionList
productThumbnail
filter
featuredProduct
productHighlightWithCover
content
image
slideshow
heroImageWithTextBox
textWithImage
textColumnsWithIcons
video
logoList
imageTextGrid
timeline
campaignPromotion
footerPromotion
announcementBar
discountBanner
email
navigation
frequentlyAskedQuestions
code
brandList
sideColumnFilter
socialMedia
sideColumn
inquiryForm
externalLink
generalSection
company
marketSelector
cardComponent
blog
title
button
general
checkoutPage
homePage
additionalPages
shoppingCart
loyaltyPoints
toggleSwitch
starRating
date
measurement
dataReference
colorPicker
fileUpload
number
addCustomField
linkCustomField
customer
currency
productSku
vector
addButton
divider
socialMedia
gallery
discountTag
orderNotes
addToCart
abandonedCart
favoriteStar
storeIcon
groupIcon
dropdownSelect
upgradeOption
cartTotal
giftCard
userLevel

The following example shows how icons are displayed in the theme editor.