> ## Documentation Index
> Fetch the complete documentation index at: https://docs.riqra.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Secciones y schema

> La gramática de {% schema %}: tipos de setting, bloques, presets, ubicaciones y settings_schema.json.

Cada sección declara su superficie editable en un bloque `{% schema %}` con JSON, al final del archivo. Es lo que el personalizador le muestra al comerciante y lo que la validación de subida verifica. Un ejemplo real de Origin:

```liquid theme={null}
{% schema %}
{
  "name": "Barra de anuncios",
  "enabled_on": { "groups": ["header"] },
  "limit": 1,
  "settings": [
    { "type": "text", "id": "message", "label": "Mensaje", "default": "" },
    { "type": "url", "id": "link", "label": "Enlace" },
    { "type": "checkbox", "id": "open_in_new_tab", "label": "Abrir en nueva pestaña", "default": false }
  ]
}
{% endschema %}
```

En el Liquid de la sección lees los valores con `section.settings.<id>`; los settings globales de `settings_schema.json` con `settings.<id>`.

## Tipos de setting

Cada setting lleva `type`, `id` y `label`, más `default`, `info` y `placeholder` opcionales. Los tipos soportados son exactamente estos (cualquier otro es un error de validación):

| Tipo                 | Guarda          | Notas                                                                                  |
| -------------------- | --------------- | -------------------------------------------------------------------------------------- |
| `text`               | string          | Texto de una línea.                                                                    |
| `textarea`           | string          | Texto de varias líneas.                                                                |
| `richtext`           | string (HTML)   | Texto enriquecido; el HTML se sanitiza en el servidor antes de llegar al drop.         |
| `color`              | string          | Color en hex, p. ej. `#407EFF`.                                                        |
| `url`                | string          | URL escrita o elegida con el selector de recursos (colecciones, productos, páginas).   |
| `image_picker`       | string (URL)    | Imagen de la biblioteca de archivos del comercio; úsala con `image_url`.               |
| `number`             | number          | Número libre.                                                                          |
| `range`              | number          | Número acotado con `min`, `max` y `step`.                                              |
| `checkbox`           | boolean         | Casilla.                                                                               |
| `select`             | string          | Una opción de `options: [{ "value", "label" }]`.                                       |
| `font_picker`        | string          | Familia tipográfica del catálogo de fuentes.                                           |
| `collection`         | string (handle) | Referencia a una colección; resuélvela con `collections[section.settings.<id>]`.       |
| `link_list`          | string (handle) | Referencia a un menú de navegación; resuélvela con `linklists[section.settings.<id>]`. |
| `color_scheme`       | string (id)     | Referencia a un esquema de color del tema. Solo en secciones.                          |
| `color_scheme_group` | —               | La lista editable de esquemas de color. Solo en `settings_schema.json`.                |
| `header`             | —               | Encabezado no editable que agrupa settings. Lleva `content` en vez de `id`/`label`.    |

```json theme={null}
{ "type": "header", "content": "Barra de contacto" },
{ "type": "checkbox", "id": "show_contact_bar", "label": "Mostrar barra de contacto", "default": true }
```

## Bloques

`blocks` declara los elementos repetibles de la sección; el comerciante los agrega, reordena y elimina. En Liquid se iteran con `section.blocks` y cada uno expone `block.type`, `block.settings` y `block.shopify_attributes` (atributos para el resaltado en el personalizador).

```json theme={null}
"blocks": [
  {
    "type": "slide",
    "name": "Banner",
    "settings": [
      { "type": "image_picker", "id": "image", "label": "Imagen" },
      { "type": "url", "id": "link", "label": "Enlace" }
    ]
  }
]
```

```liquid theme={null}
{%- for block in section.blocks -%}
  <div data-slide {{ block.shopify_attributes }}>…</div>
{%- endfor -%}
```

* `limit` en un bloque acota cuántas instancias de ese tipo se pueden agregar.
* `max_blocks` en la raíz del schema acota el total de bloques de la sección.
* `"static": true` (extensión de Riqra) marca un bloque fijo: existe exactamente una vez, se crea solo y queda anclado en el editor — el comerciante edita sus settings pero no puede quitarlo ni duplicarlo.

## Presets

`presets` define las variantes con las que la sección aparece en el panel "Agregar sección", con settings y bloques iniciales:

```json theme={null}
"presets": [
  {
    "name": "Carrusel de banners",
    "settings": { "autoplay": true },
    "blocks": [{ "type": "slide" }, { "type": "slide" }]
  }
]
```

## Ubicaciones y límites

* `limit` (raíz): máximo de instancias de la sección por plantilla, p. ej. `"limit": 1` para un encabezado único.
* `enabled_on` / `disabled_on`: restringen dónde puede agregarse la sección, por plantilla (`templates: ["index", "collection", …]`) o por grupo (`groups: ["header", "footer"]`). Usa uno u otro, no ambos.

```json theme={null}
"enabled_on": { "templates": ["index", "page"] }
```

* `tag` y `class` se aceptan por compatibilidad con Shopify pero se ignoran: el framework es dueño del wrapper `riqra-section-{id}`.

## `config/settings_schema.json`

Los settings globales del tema — la pestaña "Configuración del tema" del personalizador — se declaran como un arreglo de grupos con nombre. La entrada `theme_info` es obligatoria:

```json theme={null}
[
  {
    "name": "theme_info",
    "theme_name": "Origin",
    "theme_author": "Riqra",
    "color_scheme": "only light"
  },
  {
    "name": "Tipografía",
    "settings": [
      { "type": "font_picker", "id": "body_font", "label": "Fuente del cuerpo", "default": "Open Sans" }
    ]
  }
]
```

`theme_info` acepta además `theme_version`, `theme_documentation_url` y `theme_support_url`. `color_scheme` (extensión de Riqra) declara el esquema CSS del tema: `"light"`, `"dark"`, `"light dark"`, `"dark light"` u `"only light"`.