Sections e Blocks | Documentação para Web Designers

As sections são as unidades de composição de uma página e os blocks são seus componentes internos reutilizáveis. Ambos seguem a mesma estrutura: markup Twig na parte superior e um bloco {% schema %} ao final que declara seus settings, blocos aceitos e presets para o editor.

Sections

Ler settings

Os settings declarados no schema são acessados a partir de section.settings.*:

{% set has_blocks = section.blocks | length > 0 %}
{% set columns    = section.settings.columns %}
{% set format     = section.settings.format %}

Iterar blocks

Os blocks disponíveis na section são percorridos a partir de section.blocks:

{% for block in section.blocks %}
  {% if block.type == 'banner' %}
    <div class="banner-item">
      {% include 'blocks/banner.tpl' with { block: block } %}
    </div>
  {% endif %}
{% endfor %}

Schema de uma section

O schema é declarado entre {% schema %} e {% endschema %} ao final do arquivo:

{% schema %}
{
  "name": "t:names.banners",
  "class": "section section-banners",
  "blocks": [
    { "type": "banner" }
  ],
  "settings": [
    { "type": "header", "content": "t:names.disposition" },
    {
      "type": "setting",
      "setting_type": "radio",
      "id": "format",
      "label": "t:settings.format",
      "options": [
        { "value": "grid",   "label": "t:options.grid" },
        { "value": "slider", "label": "t:options.slider" }
      ],
      "default": "grid"
    }
  ],
  "enabled_on": {
    "page_templates": "all",
    "layout_templates": ["footer"]
  },
  "presets": [
    {
      "name": "t:names.banners",
      "category": "t:categories.media",
      "settings": { "format": "grid" }
    }
  ]
}
{% endschema %}

Chaves de schema para sections:

Chave	O que faz
`name`	Nome da section no editor (chave `t:`).
`wrapper`	Elemento HTML usado como wrapper da section. Por padrão é `section`. Usar `header` ou `footer` para sections em layout templates.
`class`	Classe CSS adicionada ao wrapper.
`icon`	Ícone exibido junto ao nome no editor.
`static`	Se `true`, o usuário não pode remover a section.
`limit`	Quantidade máxima de vezes que essa section pode aparecer em uma página.
`max_blocks`	Quantidade máxima de blocks que o usuário pode adicionar a essa section. Omitir para não limitar.
`enabled_on`	Restringe onde a section pode ser usada. Aceita `page_templates` (`"all"` ou um array como `["home", "product"]`) e/ou `layout_templates` (`["header", "footer"]`).
`blocks`	Tipos de block que a section aceita. Usar `{ "tags": ["general"] }` para aceitar qualquer block com essa tag, ou listar tipos específicos como `[{ "type": "banner" }]`. Cada entrada pode declarar `"limit": N`.
`settings`	Definições de settings, mais separadores `header` que agrupam visualmente os settings no editor.
`presets`	Configurações padrão aplicadas quando o usuário adiciona a section. Podem pré-preencher `settings` e `blocks` iniciais.
`default`	Alternativa a `presets` para sections que sempre são renderizadas com um conjunto fixo de blocks (ex. footer).

Blocks

Ler settings e aplicar block_attributes

Os blocks leem seus settings a partir de block.settings.* e devem aplicar o filtro block_attributes para que o editor possa identificá-los e selecioná-los:

{% set heading_settings = block.settings %}

{% if heading_settings.text %}
  <div class="heading-block {{ heading_settings.size }}" {{ block | block_attributes }} data-store="heading-block-{{ block.id }}">
    {{ heading_settings.text | raw }}
  </div>
{% endif %}

Schema de um block

{% schema %}
{
  "name": "t:names.heading",
  "tags": ["general"],
  "icon": "TextSizeIcon",
  "settings": [
    {
      "type": "setting",
      "setting_type": "richtext",
      "id": "text",
      "label": "t:options.text",
      "default": "t:defaults.heading"
    },
    {
      "type": "setting",
      "setting_type": "select",
      "id": "size",
      "label": "t:settings.size",
      "options": [
        { "value": "h1", "label": "t:options.heading_1" },
        { "value": "h2", "label": "t:options.heading_2" }
      ],
      "default": "h4"
    }
  ],
  "presets": [
    {
      "name": "t:names.heading",
      "category": "t:categories.basic",
      "settings": { "text": "t:defaults.heading" }
    }
  ]
}
{% endschema %}

O campo tags determina quais sections aceitarão esse block: uma section que declare { "tags": ["general"] } em sua chave blocks incluirá automaticamente todos os blocks com a tag "general".

Blocks aninhados

Um block pode conter outros blocks. O schema declara os tipos filho em "blocks": [...] e o markup itera block.blocks:

{% for child_block in block.blocks %}
  {% include 'blocks/' ~ child_block.type ~ '.tpl' with { block: child_block } %}
{% endfor %}

Limitar a quantidade de blocks

A chave max_blocks no schema de uma section limita quantos blocks o usuário pode adicionar. É usada quando o layout quebra visualmente com muitos blocks:

{% schema %}
{
  "name": "t:names.featured_brands",
  "max_blocks": 12,
  "blocks": [
    { "type": "brand-logo" }
  ],
  "settings": [ ... ],
  "presets": [ ... ]
}
{% endschema %}

Se max_blocks for omitido, a section aceita qualquer quantidade de blocks.