IllusionCMS
ES
Manual · 9

Datos: Collections y fuentes REST

Ambos tipos de fuentes de datos se usan igual en el template: data("slug").

9.1 Collections

Una Collection es una estructura de datos propia con campos, p. ej. Blog con título, fecha, imagen y texto.

Crear: Collections → + Nueva → nombre y slug (el slug es el nombre para data("…")). En la pestaña Esquema creas los campos:

Tipo de campo Entrada En el template
Texto, Texto multilínea, URL Campo de texto {{ item.feld }}
Markdown Editor Markdown con vista previa {{ item.feld|markdown }}
HTML Editor de código {{ item.feld|safe }}
Número Campo numérico {{ item.feld }}, {{ item.feld|floatformat:2 }}
Sí/No Casilla {% if item.feld %}…{% endif %}
Fecha Campo de fecha (guardado como AAAA-MM-DD) {{ item.feld }}
Selección Lista de opciones fijas {{ item.feld }}
Imagen Selección de la gestión de archivos {{ image(item.feld) }}
Archivo Selección de la gestión de archivos {{ file(item.feld).url }}
Vínculo (una entrada) Selección de una entrada de otra Collection {{ item.feld.name }}
Vínculos (varias) Añadir, quitar y ordenar entradas {% for x in item.feld %}{{ x.name }}{% endfor %}
Bloques Editor de formularios para bloques hechos de módulos (ver 7.6) {% blocks item.feld %}

El nombre del campo (p. ej. titel) es el nombre en el template; la etiqueta, lo que aparece en el formulario. Obligatorio exige un valor.

Si renombras un campo, las entradas existentes conservan sus valores antiguos solo hasta la próxima vez que se guarde la entrada. Por eso, planifica los nombres de campo lo antes posible.

Idioma de las entradas: En el esquema defines en qué idioma están las entradas de una Collection. Solo entonces se pueden vincular entradas con entradas de otros idiomas – consulta Sitios multilingües.

Vínculos entre Collections: con los tipos de campo Vínculo y Vínculos, una entrada apunta a entradas de otra Collection (o de la misma). La Collection de destino la eliges en el esquema, junto al tipo. Así, un artículo de blog tiene un autor (1:n), y los artículos y las etiquetas pueden asignarse mutuamente de forma múltiple (n:m). Solo se guardan los ID. En data() e item(), los vínculos ya están resueltos:

{% for a in data("blog") %}
  <h2>{{ a.titel }}</h2>
  <p>por {{ a.autor.name }} · {% for t in a.tags %}#{{ t.name }} {% endfor %}</p>
{% endfor %}

En sentido inverso, es decir, «todos los artículos de este autor» o «todos los artículos con esta etiqueta», filtras la otra Collection por el ID. En Vínculos (varias), la comparación significa «contiene», y con __ne, «no contiene»:

{% for x in data("blog", "autor", autor.id) %}…{% endfor %}
{% for x in data("blog", "tags", tag.id, "sort", "-datum") %}…{% endfor %}
  • Se resuelve un nivel: las etiquetas de un artículo son entradas completas, pero sus propios vínculos son solo ID. Así, los vínculos mutuos no forman un bucle. Un nivel más abajo llegas con data() y el filtro.
  • Las entradas eliminadas y, para los visitantes, las no publicadas desaparecen. Un Vínculo queda entonces vacío, y los Vínculos contienen solo las entradas restantes. En la vista previa se incluyen los borradores.
  • En la pestaña Uso hay ejemplos adecuados, también para el sentido inverso («Vinculada desde»). El panel Datos del template del editor de páginas muestra las entradas resueltas.
  • La API REST (/collections/…/items) devuelve los ID. GET /data/{slug} devuelve lo mismo que data() en el template, es decir, resuelto.
  • CSV: la exportación escribe los ID (varios separados por comas). La importación acepta ID o el valor de un campo de texto de la entrada de destino, preferentemente el slug. Así encajan las exportaciones de Webflow, que emiten los vínculos como slugs. Varios valores se separan con coma o punto y coma; lo desconocido se notifica como aviso.

Carpeta: en la pestaña Esquema puedes asignar a una Collection una Carpeta, p. ej. el nombre de un proyecto. La lista de la izquierda se agrupa por ella, y cada carpeta se puede contraer. Las carpetas solo sirven para organizar y no cambian nada en data("…"). Los Snippets y los archivos CSS/JS tienen el mismo campo junto al nombre.

Las entradas se gestionan en la pestaña Entradas: + Entrada, editar con doble clic o Editar, orden con las flechas, Publicado por entrada. Las entradas no publicadas solo aparecen en la vista previa.

En la pestaña Uso, la Collection muestra ejemplos listos de template y de API. Con Legible públicamente mediante la API REST, los clientes JavaScript pueden obtener las entradas publicadas sin iniciar sesión, también desde otros dominios (CORS se habilita entonces automáticamente).

Importación y exportación CSV: en la pestaña Entradas, Exportar CSV descarga todas las entradas (también los borradores) como archivo CSV: columnas id, published y después los campos; UTF-8 con BOM, para que Excel muestre bien las diéresis y acentos. Importar CSV acepta un archivo CSV (UTF-8; se reconocen como separadores la coma, el punto y coma o el tabulador) y asigna sus columnas a los campos: automáticamente por nombre de campo o etiqueta, modificable por columna. Una vista previa muestra las primeras entradas tal como se guardarán y lista todos los errores con fila y columna; mientras haya errores, no se importa nada. Se importa todo o nada, y las entradas nuevas se añaden al final; Reemplazar entradas elimina antes todas las existentes.

  • Coincidencia en lugar de añadir: en Coincidencia eliges un campo con valores únicos, normalmente el slug. Si ya existe una entrada con el mismo valor, se actualiza: solo las columnas asignadas; todo lo demás (también el estado, si no hay ninguna columna de estado asignada) se mantiene; si no, se crea una nueva. Con Eliminar las entradas que no están en el archivo se convierte en una sincronización completa: las entradas conservan su ID y solo desaparece lo que falta en el archivo. La vista previa muestra por fila nueva o cambia #ID y, arriba, el resultado (p. ej. «1 nueva · 2 actualizadas · 1 eliminada»). Los valores duplicados en el archivo o en la Collection son errores.

  • Editar en Excel: exporta, edita el archivo (cambia filas, añade filas nuevas con id vacío, borra filas) y vuelve a importarlo: la columna id se reconoce automáticamente como ID de entrada y se propone como coincidencia. Un ID desconocido es un error. Usa para ello una exportación reciente: si se elimina la entrada más nueva, una creada después puede recibir su ID.

  • Nueva Collection desde CSV: Collections → CSV (junto a + Nueva). IllusionCMS propone el nombre, el slug y, para cada columna, el nombre de campo y el tipo (número, sí/no, fecha, URL, HTML, texto …); todo se puede cambiar antes de importar, y las columnas se pueden ignorar.

  • Exportaciones de Webflow: las columnas de gestión (Collection ID, Item ID, Created On …) se ignoran; Draft y Archived determinan el estado (true = borrador). Para otros archivos puedes usar tú mismo una columna con sí/no como Estado: online o Estado: borrador; sin una columna así, todas las entradas se publican.

  • Valores: los números pueden escribirse en formato alemán (1.234,50) o inglés (1,234.50); 1,5 se interpreta como 1,5. Sí/No entiende ja/nein, true/false, 1/0, x. Las fechas se convierten a AAAA-MM-DD desde 2025-10-02, 02.10.2025, marcas de tiempo ISO y el formato de Webflow. Los valores con cero inicial (códigos postales) la importación los propone como texto, no como número.

  • Imágenes y archivos: una columna de imagen o archivo contiene o bien el ID de un archivo o bien la dirección de un archivo ya adoptado mediante importación de sitios web: así, las URL de imagen de una exportación de Webflow encuentran las imágenes importadas. Las demás direcciones quedan vacías (la vista previa las muestra como aviso); si quieres conservar la dirección, usa el tipo URL.

  • La importación no dispara eventos de Workflow: con mil filas serían, si no, mil ejecuciones de Workflow (p. ej. notificaciones).

Datos en vivo: algunas Collections se llenan solas en el servidor en producción, p. ej. las solicitudes de contacto de un Workflow. Si marcas en el esquema la casilla Datos en vivo, sus entradas se conservan en el destino cuando subes un Bundle desde local; las entradas de prueba de tu instancia local no se transfieren. El esquema (campos, nombre) sigue viniendo igualmente del estado local. En la lista, esas Collections llevan la insignia Live.

Singleton: para cosas que existen exactamente una vez (ajustes del sitio web, códigos de color, datos de contacto, horarios), marca Singleton en el esquema. La Collection contiene entonces exactamente una entrada; en lugar de una lista, en Contenido ves directamente el formulario. En el template, data() devuelve la entrada directamente como objeto:

{% set s = data("einstellungen") %}
<header style="--primaer: {{ s.primaerfarbe }}">{{ s.firmenname }} · {{ s.telefon }}</header>

También la API (GET /api/v1/collections/einstellungen/items, /api/v1/data/einstellungen) devuelve un objeto; se modifica con PUT /api/v1/collections/einstellungen/item. No es posible una segunda entrada, ni tampoco la importación CSV. Solo se puede cambiar el modo mientras la Collection tenga como máximo una entrada.

Página de detalle y vista previa: si las entradas aparecen en una página Catch-All (p. ej. /blog/<slug>), elígela en el esquema en Página de detalle, junto con el campo que contiene la parte de la URL (normalmente slug). Al editar una entrada aparece entonces a la derecha la vista previa de esa página, con el estado aún sin guardar, es decir, en vivo mientras escribes, y conmutable entre escritorio, tableta y móvil; Abrir ↗ muestra la entrada guardada en el sitio web.

9.2 data() e item()

{% for post in data("blog") %}…{% endfor %}

Los parámetros van a continuación como pares de nombre y valor:

Parámetro Efecto Ejemplo
sort Ordenar, - = descendente data("blog", "sort", "-datum")
limit Como máximo n entradas data("blog", "limit", 3)
offset Saltar las n primeras data("blog", "offset", 10, "limit", 10)
cualquier campo Filtrar por igualdad data("produkte", "kategorie", "schuhe")
feld__gt, __gte, __lt, __lte Mayor / mayor o igual / menor / menor o igual. Los números se comparan como números y los campos de fecha (AAAA-MM-DD), cronológicamente; las entradas sin valor quedan fuera data("events", "datum__gte", today)
feld__ne Distinto data("blog", "kategorie__ne", "intern")

Además existen los campos id, _created y _updated (tiempo Unix), p. ej. "sort", "-_created" para «los más nuevos primero». Los valores de variables funcionan igual: data("produkte", "kategorie", route.query.kat).

Una entrada individual la encuentras con item():

{% with p=item("produkte", "slug", "sneaker-weiss") %}{{ p.name }}{% endwith %}

9.3 Fuentes REST

Las fuentes REST conectan cualquier API JSON: tienda, CRM, sistema de tickets, CMS headless, servicios propios. El CMS consulta la API al renderizar, extrae la lista y guarda el resultado en caché durante un tiempo.

Crear: Fuentes REST → + Nueva:

Campo Significado
Nombre / Slug El slug es el nombre para data("…")
Método / URL GET o POST, URL http(s) absoluta
Cabecera p. ej. Authorization: Bearer …
Body JSON en POST
Ruta de la lista Dónde está la lista en la respuesta, p. ej. data.items (vacío = respuesta completa)
Caché Durante cuánto tiempo se reutiliza el resultado (segundos, 0 = nunca)
Tiempo límite Tiempo máximo de espera (1–60 segundos)

Los marcadores hacen flexibles las consultas:

  • {name} en la URL, el body o la cabecera se rellena desde el template: URL https://shop.example.com/api/products?cat={kat} → data("produkte", "kat", "schuhe").
  • {env.NAME} lee una variable de entorno del servidor. Así, las credenciales no van en la base de datos: cabecera Authorization: Bearer {env.SHOP_TOKEN}, servidor arrancado con SHOP_TOKEN=… ./illusioncms.

Probar: a la derecha, Probar consulta muestra el estado, la duración y los datos. En Listas en el resultado aparecen todos los lugares en los que la respuesta contiene listas; un clic adopta la ruta. Debajo hay un ejemplo de template listo con los campos encontrados.

Conviene saber:

  • Si una consulta falla (estado de error, tiempo límite, JSON no válido), la página no se puede renderizar. Con la sesión iniciada ves la causa exacta.
  • Una página con datos REST permanece en la caché de páginas como máximo durante la duración de caché de la fuente.
  • Quien puede crear fuentes REST puede hacer que el servidor consulte cualquier dirección, también en la red interna.