Blocks

Blocks are Liquid files that allow you to create reusable modules of content that can be customized in the Basker Studio.

For example, you can create an Image with an Upload field that displays an image and text side-by-side with options for editors to choose the image, set the text, and select the display order.

Blocks can also be included statically, which can provide editors with in-context customization options for static content.

By default, blocks are available for any template. You can limit which templates have access in the block schema.

Location

Layout files are located in the layouts directory of the theme:

└── theme
    ├── blocks
    |   ├── well.liquid
    |   ...
    ├── templates
    ...

Block Schema

Blocks support the {% schema %} Liquid tag. This tag allows you to define various attributes of a blokc, such as the block name, and settings to allow for customization in the Basker Studio.

Schema

Each section can have only a single {% schema %} tag, which must contain only valid JSON using the attributes listed in Content below. The tag should be placed at the bottom of the block file.

The following is an example of a valid block schema:

1
{% schema %}
2
  {
3
    "name": "well",
4
    "singular": "Well",
5
    "plural": "Wells",
6
    "label": "Well Block",
7
    "settings": [
8
      {
9
        "type": "text",
10
        "label": "Title",
11
        "name": "title"
12
      },
13
      {
14
        "type": "richtext",
15
        "label": "Content",
16
        "name": "content"
17
      },
18
      {
19
        "type": "checkbox",
20
        "label": "Center Title?",
21
        "name": "centered"
22
      }
23
    ]
24
  }
25
{% endschema %}

Content

The content of {% schema %} can include the following attributes:

name (required): A unique name that will be used to reference this block from the template. This name must match the name of a block in the theme’s blocks directory.
singular: The singular version of the name, which is displayed when there are multiple instances of the block on a page.
plural: The plural version of the name, which is displayed when there is only one instance of the block on a page.
label: A human readable label for the block that will be used in Basker Studio.
settings (optional): An array of settings to customize this block’s appearance and behavior.

name

The name attribute is required and must be a unique name that will be used to reference this block from the template. This name must match the name of a block in the theme’s blocks directory.

singular

The singular attribute is optional, but if provided it must be a string that will be used as the singular version of the name when there are multiple instances of this block on a page. If not provided, the value of name will be used for the singular version.

plural

The plural attribute is optional, but if provided it must be a string that will be used as the plural version of the name when there are multiple instances of this block on a page. If not provided, the value of name will be used for the plural version.

label

The label attribute is optional, but if provided it must be a string that will be used as the label for this block when displayed in Basker Studio. If not provided, the value of name will be used for the label.

settings

You can create block specific settings to allow editors to customize the block with the settings object:

1
{% schema %}
2
{
3
  "name": "Slideshow",
4
  "singular": "Slideshow",
5
  "plural": "Slideshows",
6
  "label": "Slideshow",
7
  "settings": [
8
    {
9
      "type": "text",
10
      "label": "Header",
11
      "name": "header"
12
    }
13
  ]
14
}
15
{% endschema %}

Rendering Blocks

In your template’s Liquid file, you can loop over the blocks of the page and render each block based on its type. You can access the settings of the block using the block Liquid tag. The following is an example:

1
{% for block in page.blocks %}
2
  {%- case block.type -%}
3
    {%- when "well" -%}
4
      <h1>{{ block.title }}</h1>
5
  {% endcase %}
6
{% endfor %}