[]

blocks

The blocks directory contains definitions for blocks that can be added to sections. Each block has its own configuration and can be reused within sections. There are three types of blocks:

Public blocks: can be used by any section or block.
Private blocks: can only be used within the specific section they belong to.
App block: created by apps to extend theme capabilities.

Directory structure

Each block in the blocks directory must include an .html file and can have optional .css and .js files.

blocks
├── product
│   ├── card.css
│   ├── card.js
│   └── card.html 
└── heading.html

The blocks directory can be located in two places:

Theme root directory: stores public blocks.
Section directory: stores private blocks specific to the section.

Public blocks

Public blocks are stored in the theme root directory and can be accessed by any section or block.

...
sections
blocks
├── product
│   ├── card.css
│   ├── card.js
│   └── card.html 
└── heading.html
templates
...

The following is an example of how the public block product/card is used in the featured-collection section:

<!-- sections/featured-collection/featured-collection.html -->
<section>
  {{#blocks}}
    {{#if forblock.type == "product/card"}}
      {{#var products_pagination = section.settings.collection | get_product_pagination(4) /}}
      <ul>
        {{#for product in products_pagination.list}}
          <li>
            {{#block product=product /}}          
          </li>
        {{/for}}
      </ul>
    {{/if}}
  {{/blocks}}
</section>
{{#schema}}
{
  "name": "featured-collection",
  "settings": {
    "type": "collection",
    "id": "collection",
    "label": "collection"
  },
  "blocks": [
    {
      "type": "product/card",
      "limit": 1
    }
  ]
}
{{/schema}}

In the above example:

The blocks tag is used in a loop to access the forblock object for conditionally rendering different types of blocks.
For the block of type product/card, the get_product_pagination filter retrieves paginated information of the products using section.settings.collection.
The products from products_pagination.list are then iterated over to render each product using the product/card block.

In scenarios where no custom rendering of block content or parameter passing is needed, the content tag can be used for direct rendering, as shown in the following example.

<div class="block-button-group">
  {{#content "blocks" /}}
</div>
{{#schema}}
{
  "name": "button-group",
  "blocks": [
    {
      "type": "button",
      "limit": 2
    }
  ]
}
{{/schema}}

Private blocks

For certain sections, it is essential to isolate proprietary functionalities into distinct blocks. This enables merchants to configure them independently within the theme editor. Such blocks are designated as private blocks and are restricted for use solely within the section they are defined.

The files for private blocks are stored within a blocks directory, which is situated inside the respective section's directory.

sections
├── blog
│   ├── blocks
│   │   ├── articles.css
│   │   └── articles.html
└── blog.html

When incorporating private blocks within a section, prefix the block file names with a $ symbol to denote that they are private blocks.

<!-- sections/blog/blog.html -->
<section>
{{#blocks}}
  {{#if forblock.type == "$articles" /}}
    {{#block blog=section.settings.blog /}}
  {{/if}}
{{/blocks}}
</section>
{{#schema}}
{
  "name": "blog",
  "settings": {
    "type": "blog",
    "id": "blog",
    "label": "blog"
  },
  "blocks": [
    {
      "type": "$articles",
      "limit": 1
    }
  ],
}
{{/schema}}

Nested blocks

Blocks can be nested within sections and other blocks, providing the theme editor with greater configurational flexibility. The maximum number of nesting levels that can be displayed by the theme editor is 6.

Taking the aforementioned private blocks as an example, consider nesting a public article/card block within the articles block. Use the props object in the block to retrieve passed parameters:

<!-- sections/blog/blocks/articles.html -->
{{#var articles_pagination = props.blog | get_article_pagination(10) /}}
{{#var articles = articles_pagination.list /}}
<ul>
  {{#blocks}}
    {{#for article in articles}}
      <li>
        {{#block article=article /}}
      </li>
    {{/for}}
  {{/blocks}}
</ul>
{{#schema}}
{
  "name": "articles",
  "blocks": [
    {
      "type": "article/card",
      "limit": 1
    }
  ]
}
{{/schema}}

App Block

The app block is a way to extend the theme through a SHOPLINE App, allowing merchants to add extensions in the theme editor. These app extensions will ultimately be presented on the theme pages. For detailed information, refer to Integrate apps with themes.

Schema

Blocks support the addition of a schema tag in which various attributes of a block can be defined, such as the block's name.

The attributes supported by a block schema are consistent with those supported by the section schema. For more details, refer to Section schema.

To access the values configured in a block, use the object block.settings. See the following example:

<!-- /blocks/article/card.html -->
{{#var articles_pagination = props.blog | get_article_pagination(10)}}
{{#var articles = articles_pagination.list}}
<h2>{{ block.settings.title }}</h2>
<ul>
  {{#blocks}}
    {{#for article in articles}}
      <li>
        {{#block article=article /}}
      </li>
    {{/for}}
  {{/blocks}}
</ul>
{{#schema}}
{
  "name": "articles",
  "settings": [
    {
      "type": "text",
      "id": "title",
      "label": "Title"
    }
  ],
  "blocks": [
    {
      "type": "article/card",
      "limit": 1
    }
  ]
}
{{/schema}}