Sections y Blocks | Documentación para Diseñadores

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.