Sections y Blocks

Las sections son las unidades de composición de una página y los blocks son sus componentes internos reutilizables. Ambos siguen la misma estructura: markup Twig en la parte superior y un bloque {% schema %} al final que declara sus settings, bloques aceptados y presets para el editor.

Sections

Leer settings

Los settings declarados en el schema se acceden desde section.settings.*:

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

Iterar blocks

Los blocks disponibles en la section se recorren desde 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 una section

El schema se declara entre {% schema %} y {% endschema %} al final del archivo:

{% 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 %}

Claves de schema para sections:

Clave	Qué hace
name	Nombre de la section en el editor (clave t:).
wrapper	Elemento HTML usado como wrapper de la section. Por defecto es section. Usar header o footer para sections en layout templates.
class	Clase CSS agregada al wrapper.
icon	Ícono mostrado junto al nombre en el editor.
static	Si es true, el usuario no puede eliminar la section.
limit	Cantidad máxima de veces que esta section puede aparecer en una página.
max_blocks	Cantidad máxima de blocks que el usuario puede agregar a esta section. Omitir para no limitar.
enabled_on	Restringe dónde puede usarse la section. Acepta page_templates ("all" o un array como ["home", "product"]) y/o layout_templates (["header", "footer"]).
blocks	Tipos de block que acepta la section. Usar { "tags": ["general"] } para aceptar cualquier block con ese tag, o listar tipos específicos como [{ "type": "banner" }]. Cada entrada puede declarar "limit": N.
settings	Definiciones de settings, más separadores header que agrupan visualmente los settings en el editor.
presets	Configuraciones por defecto aplicadas cuando el usuario agrega la section. Pueden pre-poblar settings y blocks iniciales.
default	Alternativa a presets para sections que siempre se renderizan con un conjunto fijo de blocks (ej. footer).

Blocks

Leer settings y aplicar block_attributes

Los blocks leen sus settings desde block.settings.* y deben aplicar el filtro block_attributes para que el editor pueda identificarlos y seleccionarlos:

{% 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 un 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 %}

El campo tags determina qué sections aceptarán este block: una section que declare { "tags": ["general"] } en su clave blocks incluirá automáticamente todos los blocks con el tag "general".

Blocks anidados

Un block puede contener otros blocks. El schema declara los tipos hijo en "blocks": [...] y el markup itera block.blocks:

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

Limitar la cantidad de blocks

La clave max_blocks en el schema de una section limita cuántos blocks puede agregar el usuario. Se usa cuando el layout se rompe visualmente con demasiados blocks:

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

Si max_blocks se omite, la section acepta cualquier cantidad de blocks.