Sections

Write a section: markup, settings, blocks and the store data it reads.

A section is one part of a page that a merchant can add, move, edit and remove: a banner, a product grid, a footer. Each section is a .vasc file in the theme's sections/ folder, made of Vascula markup and a {% schema %} block.

A first section#

vascula

<section class="testimonials">
  <h2>{{ settings.heading }}</h2>
</section>
{% schema %}
{
  "name": "testimonials",
  "settings": [
    { "id": "heading", "type": "text", "default": "What customers say",
      "editor": { "label": "Heading", "group": "content" } }
  ]
}
{% endschema %}

The schema names the section and declares its settings. The theme editor shows a text field labelled "Heading", and the template reads the value as settings.heading. Give every setting a good default, so the section looks finished as soon as it is added.

List the section in theme.json and allow it on the pages where merchants can add it; see Theme package structure.

Add blocks#

Blocks are repeatable items inside a section, such as slides, quotes or columns. Merchants add, reorder, hide and remove them.

vascula

<section class="testimonials">
  <h2>{{ settings.heading }}</h2>
  {% for b in settings.blocks %}
    {% unless b.disabled %}
      {{ b._editor_block_open }}
      <blockquote>
        <p>{{ b.settings.text }}</p>
        <cite>{{ b.settings.author }}</cite>
      </blockquote>
      {{ b._editor_block_close }}
    {% endunless %}
  {% endfor %}
</section>
{% schema %}
{
  "name": "testimonials",
  "settings": [
    { "id": "heading", "type": "text", "default": "What customers say",
      "editor": { "label": "Heading", "group": "content" } }
  ],
  "blocks": {
    "max": 6,
    "default": ["quote", "quote"],
    "types": [
      { "type": "quote",
        "editor": { "label": "Quote" },
        "settings": [
          { "id": "text", "type": "textarea", "default": "Absolutely love it.",
            "editor": { "label": "Quote", "group": "content" } },
          { "id": "author", "type": "text", "default": "A happy customer",
            "editor": { "label": "Author", "group": "content" } }
        ] }
    ]
  }
}
{% endschema %}

Each block has id, type, settings and, when hidden, disabled. {{ b._editor_block_open }} and {{ b._editor_block_close }} make a block selectable in the theme editor and print nothing on the live store. For blocks shared across sections, see Theme blocks.

Read store data#

Declare the store data a section reads in ctx_needs, then use it by name:

vascula

<p>{{ shop.name }} · {{ cart.item_count }} items</p>
{% schema %}
{
  "name": "store-bar",
  "ctx_needs": ["shop", "cart.item_count"]
}
{% endschema %}

A section can read only what it declares. Reading anything else fails when the theme is imported or published, with the line and column of the read. The data available under each name is documented in CTX.

Section kinds#

kind is optional and defaults to section.

Kind	Use
`section`	A section merchants place on a page.
`layout`	A section for a global surface such as the header or footer. Declares a `target`, for example `global_body_start`.
`embed`	A section for the overlay layer, such as a cart drawer or popup. Declares a `target`, for example `global_overlay`.
`block`	A theme block in `blocks/`.

Checks#

A section is checked when the theme is imported or published:

the schema is valid JSON with a name, and appears once, outside any other tag;
every setting uses a supported type;
the markup compiles;
every ctx_needs name exists, and every name the section reads is declared.

Next: Section schema lists every field and setting type.