Portada › 4. Componentes

4. Componentes

Introducción

Los componentes son bloques reutilizables que forman las páginas (cabecera, footer, banner, tarjeta…). Cada componente tiene un template HTML con campos editables que el redactor rellena desde el panel sin tocar código.

Esta sección cubre los 4 tipos de componente disponibles en el sistema:

• block: bloque de contenido estático o con campos editables (cabecera, banner, hero).
• collection: lista de items del mismo tipo (noticias, productos, jugadores).
• form: formulario de envío con validación (contacto, inscripción).
• payment: formulario con integración de pago (Stripe).

Acceso rápido

• URL: /components
• Menú lateral: módulo Componentes → entrada Listado.

Pantalla principal (listado)

La tabla de componentes muestra, para cada entrada:

• Nombre: identificador legible del componente.
• Tipo: block, collection, form o payment.
• Idioma: idioma del template (los campos se traducen después campo a campo).
• Estado: activo o borrador.
• Acciones: editar, duplicar, eliminar.

Tareas habituales

4.1 Crear un componente

1. En el listado, pulsa el botón Crear componente (arriba a la derecha).
2. Rellena el nombre interno (slug, en minúsculas y sin espacios, por ejemplo banner_home).
3. Escribe la etiqueta visible para el redactor (por ejemplo Banner Home).
4. Selecciona el tipo (ver 4.2).
5. Opcionalmente, elige un icono y rellena el campo is_global (ver 4.5).
6. Pulsa Guardar para crear el componente en estado borrador.

4.2 Elegir el tipo

El tipo define el comportamiento del componente y no se puede cambiar una vez creado. Si necesitas un tipo distinto, duplica el componente y cambia el tipo en la copia.

4.3 Añadir campos editables

Los campos editables son los datos que el redactor podrá modificar desde el editor. Para cada campo defines:

• name: identificador (se usará como [FIELD_NAME] en el template).
• label: etiqueta visible para el redactor.
• field_type: tipo de dato (ver tabla de tipos de campo más abajo).
• is_translatable: si el campo admite variantes por idioma.

Ejemplo: para un banner necesitas titulo (text, traducible) y imagen (image, no traducible).

4.4 Editar el template HTML

El template HTML es el esqueleto del componente. Mezcla HTML normal con dos tipos de marcadores:

• [FIELD_NOMBRE] → se sustituye por el valor del campo editable definido en 4.3.
• [VAR:clave] → se sustituye por una variable global del sitio (ver sección 11).

Ejemplo de template de un banner:

<section class="banner">
  <h1>[FIELD_TITULO]</h1>
  <a href="[FIELD_ENLACE]" class="btn">Saber más</a>
</section>

4.5 Marcar como global (compartido) o por página

El flag is_global controla dónde se guarda el contenido del componente:

• is_global = 0 (por defecto): el contenido se guarda en component_content, asociado a la página concreta donde se ha añadido el componente. Cada página tiene su propia copia del contenido.
• is_global = 1: el contenido se guarda en component_global_content, compartido por todas las páginas donde se usa el componente. Útil para cabeceras, pies y bloques que deben ser iguales en todo el sitio.

4.6 Importar / exportar un componente

El panel permite exportar un componente como archivo JSON (incluye nombre, tipo, campos y template) y reimportarlo en otra instalación. Esto es útil para:

• Mover componentes entre entornos (local → staging → producción).
• Replicar la definición de un componente en otra web gemela del mismo CMS.
• Hacer copias de seguridad de la definición antes de cambios mayores.

1. En el listado, abre el componente que quieres exportar.
2. Pulsa Exportar. El navegador descargará un archivo .json.
3. Para importarlo, en la pantalla de creación pulsa Importar y selecciona el archivo.

Referencia técnica (webmasters)

Tipos de campo disponibles

Marcadores [FIELD_NAME] y variables [VAR:key]

El parser del motor de plantillas reconoce dos familias de marcadores:

• [FIELD_NOMBRE] → valor del campo editable nombre del componente en la página actual. Si el campo es traducible, se usa la variante del idioma activo.
• [VAR:clave] → valor de la variable global con esa clave (base_path, home_url, etc.).

Para iconos SVG (spritemap) el patrón recomendado es:

<svg aria-hidden="true">
  <use xlink:href="[VAR:base_path]/assets/media/spritemap.svg#sprite-NOMBRE"></use>
</svg>

Rutas internas relevantes

• GET /components — listado de componentes.
• GET /components/create — formulario de creación.
• POST /components — guardar componente nuevo.
• GET /components/{id} — edición de un componente.
• POST /components/{id} — actualizar componente.
• DELETE /components/{id} — eliminar componente.
• GET /components/{id}/export — descargar definición JSON.
• POST /components/import — importar definición JSON.

Errores frecuentes

• El componente no se renderiza en la web pública: revisa que el marcador [FIELD_NOMBRE] está escrito exactamente igual (mayúsculas, guiones bajos) que el name del campo. Un carácter fuera de sitio hace que el motor de plantillas no lo reconozca y deje el marcador tal cual.
• He editado un campo pero no veo los cambios en el sitio: puede ser caché del servidor o del navegador. Recarga la página con Ctrl+F5 para forzar la recarga sin caché. Si persiste, revisa si la web tiene un sistema de caché propio en /variables.
• No puedo borrar un componente: el sistema lo bloquea si está siendo usado por alguna página (existe en component_content o component_global_content). Primero quítalo de todas las páginas (builder → acción eliminar del bloque) y, después, borra el componente del listado.
• El selector de tipo no muestra las 4 opciones: estás viendo la página en un estado anterior a la creación. Recarga con F5; si el problema persiste, limpia la caché del navegador.
• El contenido no se guarda: el componente no tiene is_translatable marcado en el campo, o el valor enviado no pasa la validación del field_type (por ejemplo, un email mal formado). Revisa los mensajes rojos del formulario.