1. Modelo conceptual
Hay tres responsabilidades distintas. Separarlas ayuda a entender la versión 1.
Eyivo Core
Almacena detalles de la empresa, páginas, medios, SEO, navegación y estado de publicación. Es la fuente de verdad del contenido.
Paquete del tema
Define formas de página fijas, secciones permitidas, esquemas de componentes personalizados y CSS. Nunca consulta datos ni ejecuta código de aplicación.
Editor de la aplicación
Genera formularios seguros a partir del esquema. Los propietarios pueden actualizar el texto, las imágenes, las páginas y el orden de las secciones dentro de un área.
No es un constructor de páginas: el propietario puede añadir una sección permitida a main y elegir su posición numérica. No puede crear un área nueva, mover un hero al pie de página ni cambiar los archivos de tu tema. Puede añadir su propio CSS del sitio, que se carga después de tus hojas de estilo, y dar nombres de clase a las secciones (consulta CSS personalizado del sitio).
2. Inicio rápido: una plantilla mínima y utilizable
Cada tema v1 incluye su propio diseño completo, estilos y scripts, y puede organizarlos como decida su autor. Un tema nunca hereda el diseño ni los recursos de otro. Los componentes eyivo: compartidos y los siete tipos de página de reserva proceden de theme-core; el tema solo almacena los tipos que sustituye y los componentes que declara en el espacio de nombres theme:.
Cada tema v1 necesita un archivo de diseño predeterminado. Tanto page-types/ como components/ son opcionales si el paquete usa únicamente los recursos de reserva de Core:
acme-industrial/
├── theme.json
├── layouts/default.liquid
├── page-types/
│ └── home.liquid # optional override
├── components/
│ └── featured_course.liquid
├── locales/
│ ├── en.json
│ └── tr.json
├── screenshots/
│ └── home-desktop.png # demo-data screenshot
└── assets/
├── css/theme.css
└── js/theme.js # Theme API 1.1, reviewed
layouts/default.liquid siempre pertenece al tema activo y define todo el documento público. Eyivo busca primero el tipo de página solicitado en ese tema y, si no existe, usa theme-core/page-types. Core nunca aporta un diseño ni recursos; incluso el contenido de reserva se muestra con el diseño y los estilos del tema activo.
3. Describe la plantilla en theme.json
El manifiesto declara las capacidades del tema y define el contrato con el que se generan los formularios de la aplicación. Responde a tres preguntas: qué tipos de página existen, qué áreas contiene cada uno y qué componentes puede incluir cada área. Los temas integrados declaran explícitamente los diez tipos de página estándar e incluyen sus archivos Liquid correspondientes. Los temas personalizados pueden seguir usando las plantillas de respaldo del núcleo para tipos no declarados.
{
"name": "Acme Industrial",
"version": "1.0.0",
"eyivo_theme_api": "1.0",
"settings": {
"primary_color": { "type": "color" },
"button_radius": { "type": "number" }
},
"page_types": {
"home": {
"areas": {
"hero": {
"allowed_components": ["eyivo:hero"],
"min": 0,
"max": 1
},
"main": {
"allowed_components": ["eyivo:rich_text", "eyivo:image_text", "theme:featured_course"]
}
}
},
"page": { "areas": { "main": { "allowed_components": ["eyivo:rich_text"] } } }
},
"components": {
"featured_course": {
"variants": ["card", "compact"],
"schema": {
"heading": { "type": "text", "required": true, "translatable": true },
"summary": { "type": "textarea", "translatable": true }
}
}
}
}
| Clave | Significado | Ejemplo |
|---|---|---|
key | Etiqueta opcional para tu propia referencia. Eyivo asigna a cada tema subido su propio ID, así que la clave nunca decide a qué tema pertenece una subida. | acme-industrial |
version | La versión inmutable de la publicación del tema, con numeración semántica. | 1.2.0 |
eyivo_theme_api | El contrato de la API pública de Eyivo que admite el paquete. | 1.0 |
areas | Espacios con nombre que el archivo de página Liquid muestra en lugares fijos. | hero, main, bottom |
allowed_components | Qué componentes el editor puede agregar a un área. | ["eyivo:hero"] |
components | Definiciones de componentes theme: propias del tema activo. Las definiciones eyivo: compartidas permanecen en theme-core. | featured_course |
min/max | Límites opcionales sobre el número de secciones en esa área. | max: 1 |
Tipos de página de reserva: los tipos integrados son home, page, gallery, contact, products, product y videos. Si omites uno, se usa su definición y su archivo Liquid de theme-core. Declara un tipo solo si el tema aporta también su archivo de sustitución page-types/<type>.liquid.
El editor recibe la API combinada de tipos de página: las definiciones del tema activo sustituyen a las equivalentes de Core, y los tipos omitidos siguen disponibles desde Core.
4. Completa el contenido de demostración en demo.json
Cada paquete debe incluir un archivo demo.json portátil cuyo contenido sea solo borrador y al menos una captura de pantalla tomada con esos datos cargados. Los temas integrados usan el mismo esquema. No incluyas ID de base de datos, dominios de clientes ni credenciales de ningún tipo, incluidas las de almacenamiento de objetos.
{
"schema_version": 2,
"default_locale": "en",
"label": "Northline Build Co.",
"summary": "Thoughtful construction for the way life happens.",
"media": {
"media/hero.jpg": {
"public_url": "https://cdn.eyivo.com/demo/hero.jpg",
"mime_type": "image/jpeg",
"original_name": "hero.jpg",
"bytes": 184000,
"width": 1600,
"height": 900
},
"assets/images/team.jpg": {
"mime_type": "image/jpeg",
"original_name": "team.jpg"
}
},
"company": { "display_name": "Northline Build Co.", "logo_asset": "media/hero.jpg" },
"theme_settings": { "settings": { "header_cta_url": "/contact" } },
"pages": [],
"catalog": [],
"galleries": [],
"videos": []
}
| Clave | Propósito |
|---|---|
media | URL pública de origen y metadatos asociados a identificadores portátiles de recursos. Reutiliza el identificador en hero_asset, cover_asset, media_asset, el campo asset de una galería, logo_asset y favicon_asset. |
company | Perfil de la empresa, enlaces sociales, colores de la marca, logotipo o favicon opcional y traducciones organizadas por idioma. |
theme_settings | Configuración inicial del tema, con traducciones opcionales organizadas por idioma. |
pages | Tipo, orden de clasificación, estado de navegación, SEO, configuración de página, componentes y contenido organizado por idioma. |
catalog | Entradas de catálogo con contenido organizado por idioma y un cover_asset opcional. |
galleries | Metadatos de la galería y sus imágenes. Cada elemento necesita un asset y un alt_text que no esté vacío. |
videos | Un source_url externo o un media_asset, modo de presentación y contenido por idioma. |
Cada entrada de media necesita una public_url con https en un host permitido (el host de medios de demostración de Eyivo cdn.eyivo.com o images.pexels.com), o un archivo incluido en el tema dentro de assets/, identificado por su ruta y sin public_url. Otros hosts, http, direcciones IP, otros puertos y redirecciones se rechazan con el diagnóstico de carga demo_media_url. mime_type, width y height son solo indicaciones: Eyivo detecta el tipo real a partir del contenido descargado, que debe ser una imagen o un vídeo permitidos de 20 MB como máximo.
Los formularios de la demo usan enlaces de formulario portables, que Eyivo resuelve por separado para cada sitio que importa la demo. Las imágenes de la demo importadas se convierten en referencias de medios normales de ese sitio; eliminarlas allí nunca elimina el original compartido.
Páginas y componentes
{
"type": "home",
"sort_order": 0,
"navigation_visible": true,
"hero_asset": "media/hero.jpg",
"translations": {
"en": { "slug": "home", "title": "Home", "meta_title": "Home | Northline" },
"tr": { "slug": "ana-sayfa", "title": "Ana sayfa", "meta_title": "Ana sayfa | Northline" }
},
"components": [{
"component_type": "eyivo:hero",
"area": "hero",
"position": 100,
"variant": "split",
"data": { "primary_url": "/contact" },
"translations": {
"en": { "heading": "Built for real life", "primary_label": "Contact us" },
"tr": { "heading": "Gerçek yaşam için tasarlandı", "primary_label": "Bize ulaşın" }
}
}]
}
Los tipos y áreas de componentes deben estar declarados en el manifiesto del tema activo o en theme-core. Usa rutas relativas como /contact para los enlaces dentro del mismo sitio. Las demos de inicio incluidas usan su imagen de cabecera existente como fondo a todo el ancho, con una capa para facilitar la lectura y texto adaptable: immersive en la mayoría de los temas y centered con imagen en Compact. Las demás variantes conservan sus propios diseños.
Idiomas de demostración y alternativa
El inglés es el idioma base obligatorio: establece default_locale en en. Si falta en datos antiguos, también significa inglés. Los demás idiomas admitidos son opcionales; no presentes copias del inglés como traducciones.
Incluye translations.en y objetos de idioma opcionales para empresa, ajustes del tema, páginas, componentes, productos, galerías, pies y textos alternativos de imágenes, vídeos y artículos. Los campos antiguos en inglés sin clave de idioma siguen siendo válidos. Al crear el sitio se elige su idioma principal y cada campo ausente usa el inglés. Los arrays sustituyen al array inglés completo; los valores vacíos explícitos se conservan. Solo se importa el idioma elegido, sin activar otros automáticamente.
Usa slugs fuente en inglés en enlaces internos y entradas de menú portátiles. La importación los convierte al slug traducido, incluidos los enlaces de texto enriquecido y artículos. Las entradas de menú pueden incluir mapas explícitos slugs y labels. Las etiquetas ausentes usan el inglés. Las URL externas no cambian.
{
"company": {
"translations": {
"en": { "display_name": "Northline", "description": "Built around your needs." },
"tr": { "display_name": "Northline", "description": "İhtiyaçlarınıza göre tasarlandı." }
}
},
"theme_settings": {
"settings": { "header_cta_url": "/contact" },
"translations": {
"en": { "header_cta_label": "Contact us" },
"tr": { "header_cta_label": "Bize ulaşın" }
}
},
"menus": {
"footer": [{ "type": "page", "slug": "contact",
"slugs": { "en": "contact", "tr": "iletisim" },
"labels": { "en": "Contact us", "tr": "Bize ulaşın" }
}]
}
}
Importación y seguridad de los medios
Los sitios nuevos del panel incluyen datos de demostración por defecto y publican inmediatamente el idioma elegido; el propietario puede desmarcar la opción. Cargar una demo desde Marca en un sitio existente sigue creando borradores y conserva el contenido publicado. La App central copia las imágenes a la biblioteca del nuevo sitio y envía referencias mediante la API interna. Los masters y los temas nunca reciben credenciales de almacenamiento de objetos. Los temas usan el valor media.public_url proporcionado.
Declara las capturas de pantalla en theme.json.preview con data_source: "demo_data". El paquete debe contener cada imagen preview declarada.
5. Escribe el diseño que necesite tu tema
El diseño predeterminado controla todo el documento HTML. Nada fuera del tema activo aporta su cabecera, pie, hoja de estilos o estructura visual. La plataforma solo añade sus propios scripts para formularios, verificación humana, consentimiento y la insignia de Eyivo; los scripts de temas requieren Theme API 1.1.
<!doctype html>
<html lang="{{ locale.code }}" dir="{{ locale.direction }}">
<head>
<meta charset="utf-8">
<meta name="viewport" content="width=device-width, initial-scale=1">
{% eyivo_head %}
<link rel="stylesheet" href="{{ 'css/theme.css' | asset_url }}">
</head>
<body>
<header class="site-header">
<a href="{{ locale.home_url }}">{{ company.name }}</a>
<nav>
{% for item in navigation.main %}
<a href="{{ item.url }}">{{ item.label }}</a>
{% endfor %}
</nav>
</header>
{{ content | raw }}
</body>
</html>
Cada archivo de tipo de página determina dónde aparecen sus áreas dinámicas. Los componentes del área ya son cadenas HTML renderizadas: insértalas con | raw. Los valores normales se escapan de forma predeterminada.
<main class="home-layout">
<section class="home-layout__hero">{{ areas.hero | raw }}</section>
<div class="home-layout__content">{{ areas.main | raw }}</div>
<aside class="home-layout__footer-cta">{{ areas.bottom | raw }}</aside>
</main>
Renderizar un componente directamente
Un diseñador puede colocar un componente registrado directamente en un diseño o archivo de tipo de página. Esa posición queda fijada por el tema y el propietario no puede reordenarla ni eliminarla desde el panel. Pasa un objeto mediante data:, campos individuales del esquema o ambos; los campos con nombre prevalecen sobre las claves equivalentes de data:.
{% eyivo_component "eyivo:cta",
eyebrow: "Let’s talk",
heading: page.title,
text: company.description,
button_label: "Contact us",
button_url: routes.contact
%}
{% eyivo_component "theme:featured_course",
data: page.settings.featured_course,
variant: "compact"
%}
El tipo debe ser un literal entre comillas con espacio de nombres. La renderización directa usa el mismo esquema, variantes, archivo de componente y objeto component normalizado que una instancia de área. Un archivo de componente no puede renderizar otros componentes.
Recursos: usa siempre {{ 'css/theme.css' | asset_url }}. Eyivo lo sirve desde el paquete activo como /theme-assets/<theme>/css/theme.css; no fijes en el código el nombre de otro tema ni una ruta del sistema de archivos.
Metadatos, rutas y diccionarios de interfaz
Cada diseño debe renderizar {% eyivo_head %} exactamente una vez. Eyivo genera el título, la descripción, robots, canonical, hreflang, Open Graph y los datos estructurados. Usa routes.home, routes.contact, routes.catalog, routes.gallery y routes.videos en vez de fijar rutas públicas en el código. Pasa las URL editables por | localized_url: las rutas internas conocidas reciben el prefijo del idioma activo y las URL externas no cambian.
{{ 'Menu' | t }}
{{ theme.settings.header_cta_url | localized_url }}
Puedes crear archivos opcionales locales/<locale>.json para las etiquetas de interfaz que añada el tema. El orden de búsqueda es: inglés de Core, idioma de Core, inglés del tema e idioma del tema. Las etiquetas compartidas de theme-core funcionan sin copiar archivos. Los textos comerciales pertenecen al contenido traducible, a los campos de componentes o a la configuración del tema; no a los diccionarios de interfaz.
Un archivo de componente personalizado
<article class="featured-course featured-course--{{ component.variant }}">
<div class="featured-course__content">
<h1>{{ component.data.heading }}</h1>
{% if component.data.summary %}<p>{{ component.data.summary }}</p>{% endif %}
</div>
</article>
En los campos traducibles, Eyivo elige el idioma del visitante antes de renderizar. Así, un visitante turco y otro inglés ven la misma estructura de componentes con distintos valores de component.data.heading.
7. Los datos seguros de Liquid que puedes utilizar
Liquid recibe datos simples y normalizados, no modelos de Laravel ni de la base de datos. Si un valor no aparece en esta tabla, considéralo no disponible en v1.
| Objeto | Campos útiles | Uso típico |
|---|---|---|
site | name, locale | Etiqueta a nivel de sitio y configuración regional nativa. |
company | name, legal_name, description, address, phone, email | Encabezado, pie de página e información de contacto. |
page | id, type, title, slug, body, settings | Contenido de página genérico y configuración por página. |
seo | title, description, valores canónicos/robots/Open Graph cuando se suministran | Metadatos del documento. |
navigation.main | Cada artículo tiene label, url, active | Menú del sitio. |
locale | code, name, native_name, direction, is_default, home_url, available | Idioma del documento, dirección RTL, enlaces de inicio localizados y selectores de idioma. |
routes | home, contact, catalog, gallery, videos, blog | URL del sistema adaptadas al idioma; nunca construyas prefijos en Liquid. |
blog | title, url, categories, category, posts, post, pagination | Listado del blog, archivos de categorías y artículos gratuitos. Cada publicación incluye título, resumen, URL, fechas, categorías e imagen de portada. Solo blog.post.body_html contiene HTML seguro del artículo generado por el servidor y debe renderizarse con raw. La paginación proporciona previous_url y next_url. |
theme.settings | Tu configuración de manifiesto | Usa una opción configurada de color, espaciado o diseño. |
products/product | Título, URL, resumen y cuerpo traducidos | Listado de productos/tipos de páginas de detalles. |
galleries | Título y descripción traducidos. | Tipo de página de galería. |
videos | title, description, source_type, source_url, playback_url, media | Use playback_url para archivos de vídeo subidos y source_url para vídeos HTTP(S) externos, según source_type. Las imágenes adjuntas nunca son fuentes de vídeo. No use el propio archivo de vídeo como imagen de portada. |
component | id, type, variant, data | Solo dentro de un archivo de componente. |
Ejemplo de diseño adaptado al idioma
<html lang="{{ locale.code }}" dir="{{ locale.direction }}">
<a href="{{ locale.home_url }}">{{ company.name }}</a>
{% if locale.available.size > 1 %}
<nav aria-label="Language">
{% for language in locale.available %}
<a href="{{ language.url }}" lang="{{ language.code }}"
{% if language.current %}aria-current="page"{% endif %}>
{{ language.native_name }}
</a>
{% endfor %}
</nav>
{% endif %}
Cada idioma disponible incluye además label, direction, is_default, current y has_translation. Eyivo solo proporciona traducciones publicadas equivalentes, por lo que los temas deben usar language.url en vez de construir /en u otro prefijo.
Ejemplo de un token basado en configuración: style="--brand: {{ theme.settings.primary_color }}". Primero se debe declarar el ajuste en theme.json.
8. Componentes: directos y dinámicos
Los componentes tienen un contrato de renderización con dos formas de colocación. El diseñador controla los componentes directos en un diseño o tipo de página. Los componentes dinámicos se guardan como instancias de un área y se gestionan desde el editor. Cada instancia dinámica tiene un ID estable, tipo con espacio de nombres, área, posición, variante opcional, datos y traducciones. La posición determina el orden, no la identidad.
Tipos de campo
text, textarea, richtext, number, boolean, select, url, email, image, video, file, color, icon, page, product y repeater.
Espacios de nombres
eyivo: se carga desde theme-core/components; theme:, desde el tema activo; y plugin: queda reservado para futuros plugins. Usa el tipo completo con espacio de nombres en un área o en la etiqueta eyivo_component.
Componente universal: establece "universal": true en su definición para permitirlo en todas las áreas de los tipos de página compatibles. Aun así, necesita un esquema válido y un archivo Liquid.
Los enlaces de acción compartidos adaptan las rutas internas conocidas al idioma activo y conservan los parámetros de consulta y los fragmentos. El texto enriquecido conserva el formato seguro dentro de contenedores anidados del editor. Se omiten las imágenes de galería vacías, las imágenes de mapa sin destino no son enlaces y las etiquetas de diapositivas y búsqueda usan el idioma de interfaz del visitante.
9. CSS personalizado del sitio y clases de sección
Los propietarios pueden añadir su propio CSS a un sitio y dar nombres de clase a las secciones (Diseño → CSS personalizado). Escribe los temas para que esto funcione bien:
- Orden de carga: el CSS del sitio se añade como
<style id="eyivo-custom-css">justo antes de</head>, después de todas las hojas de estilo del tema. Mantén</head>en tus layouts y no dependas de que tu CSS sea el último. - Clases de sección: el renderizador añade los nombres de clase de una sección al primer elemento de la salida del componente, así que da a cada plantilla de componente un único elemento raíz. Los nombres también están disponibles como
{{ component.css_class }}si quieres colocarlos en otro sitio. - Selectores estables: conserva las clases
body.theme-{key}ylayout-{name}y una clase raíz estable por componente, para que el CSS de los propietarios siga funcionando entre versiones. Indica cualquier cambio de nombre en las notas de la versión. - Temas subidos: también admiten CSS personalizado del sitio. Todas las versiones de un tema subido comparten una hoja de estilos por sitio, que se elimina cuando la última versión del tema en un sitio se retira o se elimina.
- Nombres reservados: el prefijo de clase
eyivo-y el IDeyivo-custom-csspertenecen a la plataforma.
10. Scripts de temas (Theme API 1.1)
Un tema puede incluir su propio JavaScript para menús, carruseles, pestañas, filtros y funciones similares. Los scripts son opcionales: todo tema debe funcionar sin ellos, y los paquetes Theme API 1.0 siguen funcionando igual, sin scripts.
- Decláralo: define
"eyivo_theme_api": "1.1"y"capabilities": {"custom_javascript": true}entheme.json, y coloca cada archivo directamente enassets/js/. Un paquete con archivos.jssin la declaración se rechaza. - Cárgalo: usa solo
<script src="{{ 'js/theme.js' | asset_url }}" defer></script>(otype="module") para un archivo del paquete. Las etiquetas se ejecutan en el orden en que aparecen. - Varios archivos: cada archivo se revisa y se permite por separado, así que no se permiten
importniexport. Comparte código mediante un único global, comowindow.AcmeTheme, y carga primero el archivo que lo define. - Límites: como máximo 20 archivos, 100 KB por archivo y 300 KB en total, solo texto UTF-8.
- Rechazado en plantillas: scripts en línea, fuentes de script externas, atributos de eventos
on…=, URLjavascript:y los elementos<iframe>,<object>,<embed>y<base>. - Solo código legible: sube el código fuente, no código minificado, empaquetado ni codificado. Los empaquetadores pueden generar salida sin minificar.
- Estados: una versión nueva está Pendiente de revisión hasta que terminan las comprobaciones, y luego pasa a Aprobada o Rechazada. Solo una versión aprobada se puede previsualizar o usar. Una versión aprobada puede quedar Bloqueada más tarde: los sitios conservan el tema sin sus scripts.
- Tres comprobaciones automáticas, en orden: código legible; reglas de código (sin
eval,new Function,document.write, redirecciones de página,window.open, cookies ni almacenamiento del navegador, WebAssembly, temporizadores con cadenas, elementos script o frame creados, ni valores de formularios enviados por la red); y una revisión de seguridad con IA. Para esa revisión, los scripts y las líneas de plantilla que los cargan se envían a un servicio de IA. Cualquier hallazgo rechaza la versión, con el archivo y la línea.
Aprobado: un botón de menú
(function () {
document.querySelectorAll('[data-menu-toggle]').forEach(function (button) {
button.addEventListener('click', function () {
document.body.classList.toggle('menu-open');
});
});
})();
Rechazado: envía valores del formulario fuera
form.addEventListener('submit', function () {
fetch('/collect', { method: 'POST', body: form.elements.email.value });
});
- Solo el propietario: los scripts aprobados solo se ejecutan en sitios de la cuenta que subió el tema, y solo mientras la plataforma y el propietario del sitio lo permitan.
- Política de seguridad: las páginas que ejecutan scripts de temas permiten exactamente los archivos revisados, fijados por sus hashes SHA-256, con
connect-src 'self', sin frames ni workers y sineval. Cambiar un archivo requiere una versión nueva. Las imágenes y hojas de estilo aún pueden cargarse desdehttps:, por lo que la revisión también rechaza datos enviados mediante URL de imágenes u hojas de estilo. - Tras la aprobación: los navegadores informan de intentos de infringir la política. Los informes de tres visitantes en 24 horas bloquean la versión; las denuncias de abuso de tres visitantes en 7 días desactivan los scripts en ese sitio y vuelven a revisar la versión. Los propietarios reciben un correo cuando una versión se aprueba, se rechaza o se bloquea.
- Funciones de la plataforma: los scripts no deben sustituir, envolver ni ocultar los formularios y sus campos ocultos, la verificación humana, el banner de consentimiento, la insignia de Eyivo ni la barra del propietario.
11. Catálogo de componentes disponibles
Estos 30 componentes eyivo: compartidos forman la biblioteca completa de v1 y se cargan desde theme-core. Un tema también puede declarar e implementar sus propios componentes theme:.
Variantes: spliteditorialcenteredimmersive
| Campo | Tipo | Requerido | Traducible | Opciones |
|---|---|---|---|---|
eyebrow |
text |
No | Sí | — |
heading |
text |
Sí | Sí | — |
summary |
textarea |
No | Sí | — |
image_url |
url |
No | No | — |
image_alt |
text |
No | Sí | — |
primary_label |
text |
No | Sí | — |
primary_url |
url |
No | No | — |
secondary_label |
text |
No | Sí | — |
secondary_url |
url |
No | No | — |
Variantes: ninguna
| Campo | Tipo | Requerido | Traducible | Opciones |
|---|---|---|---|---|
eyebrow |
text |
No | Sí | — |
heading |
text |
No | Sí | — |
body |
richtext |
No | Sí | — |
Variantes: image_leftimage_rightoverlap
| Campo | Tipo | Requerido | Traducible | Opciones |
|---|---|---|---|---|
eyebrow |
text |
No | Sí | — |
heading |
text |
No | Sí | — |
body |
richtext |
No | Sí | — |
image_url |
url |
No | No | — |
image_alt |
text |
No | Sí | — |
badge |
text |
No | Sí | — |
button_label |
text |
No | Sí | — |
button_url |
url |
No | No | — |
Variantes: ninguna
| Campo | Tipo | Requerido | Traducible | Opciones |
|---|---|---|---|---|
eyebrow |
text |
No | Sí | — |
heading |
text |
No | Sí | — |
items |
repeater |
No | Sí | — |
Variantes: ninguna
| Campo | Tipo | Requerido | Traducible | Opciones |
|---|---|---|---|---|
eyebrow |
text |
No | Sí | — |
heading |
text |
No | Sí | — |
intro |
textarea |
No | Sí | — |
items |
repeater |
No | Sí | — |
Variantes: ninguna
| Campo | Tipo | Requerido | Traducible | Opciones |
|---|---|---|---|---|
eyebrow |
text |
No | Sí | — |
heading |
text |
No | Sí | — |
intro |
textarea |
No | Sí | — |
items |
repeater |
No | Sí | — |
Variantes: ninguna
| Campo | Tipo | Requerido | Traducible | Opciones |
|---|---|---|---|---|
eyebrow |
text |
No | Sí | — |
heading |
text |
No | Sí | — |
intro |
textarea |
No | Sí | — |
button_label |
text |
No | Sí | — |
button_url |
url |
No | No | — |
Variantes: ninguna
| Campo | Tipo | Requerido | Traducible | Opciones |
|---|---|---|---|---|
eyebrow |
text |
No | Sí | — |
heading |
text |
No | Sí | — |
items |
repeater |
No | Sí | — |
Variantes: ninguna
| Campo | Tipo | Requerido | Traducible | Opciones |
|---|---|---|---|---|
eyebrow |
text |
No | Sí | — |
heading |
text |
No | Sí | — |
text |
textarea |
No | Sí | — |
submit_label |
text |
No | Sí | — |
form_binding |
select |
No | No | — |
Variantes: ninguna
| Campo | Tipo | Requerido | Traducible | Opciones |
|---|---|---|---|---|
heading |
text |
No | Sí | — |
text |
textarea |
No | Sí | — |
whatsapp_url |
url |
No | No | — |
Variantes: ninguna
| Campo | Tipo | Requerido | Traducible | Opciones |
|---|---|---|---|---|
eyebrow |
text |
No | Sí | — |
heading |
text |
No | Sí | — |
address |
textarea |
No | Sí | — |
map_url |
url |
No | No | — |
image_url |
url |
No | No | — |
image_alt |
text |
No | Sí | — |
Variantes: ninguna
| Campo | Tipo | Requerido | Traducible | Opciones |
|---|---|---|---|---|
heading |
text |
No | Sí | — |
items |
repeater |
No | Sí | — |
Variantes: ninguna
| Campo | Tipo | Requerido | Traducible | Opciones |
|---|---|---|---|---|
heading |
text |
No | Sí | — |
placeholder |
text |
No | Sí | — |
categories |
repeater |
No | Sí | — |
Variantes: ninguna
| Campo | Tipo | Requerido | Traducible | Opciones |
|---|---|---|---|---|
eyebrow |
text |
No | Sí | — |
heading |
text |
No | Sí | — |
summary |
textarea |
No | Sí | — |
video_url |
url |
No | No | — |
poster_url |
url |
No | No | — |
Variantes: ninguna
| Campo | Tipo | Requerido | Traducible | Opciones |
|---|---|---|---|---|
eyebrow |
text |
No | Sí | — |
heading |
text |
No | Sí | — |
price |
text |
No | Sí | — |
period |
text |
No | Sí | — |
features |
repeater |
No | Sí | — |
button_label |
text |
No | Sí | — |
button_url |
url |
No | No | — |
Variantes: ninguna
| Campo | Tipo | Requerido | Traducible | Opciones |
|---|---|---|---|---|
label |
text |
No | Sí | — |
heading |
text |
No | Sí | — |
body |
textarea |
No | Sí | — |
button_label |
text |
No | Sí | — |
button_url |
url |
No | No | — |
Variantes: ninguna
| Campo | Tipo | Requerido | Traducible | Opciones |
|---|---|---|---|---|
eyebrow |
text |
No | Sí | — |
heading |
text |
No | Sí | — |
items |
repeater |
No | Sí | — |
Variantes: ninguna
El componente compartido eyivo:faq conserva los mismos campos y el mismo marcado en cada tema. Cada tema lo presenta con su propia tipografía, espaciado y color.
| Campo | Tipo | Requerido | Traducible | Opciones |
|---|---|---|---|---|
eyebrow |
text |
No | Sí | — |
heading |
text |
No | Sí | — |
items |
repeater |
No | Sí | — |
Variantes: ninguna
| Campo | Tipo | Requerido | Traducible | Opciones |
|---|---|---|---|---|
eyebrow |
text |
No | Sí | — |
heading |
text |
No | Sí | — |
items |
repeater |
No | Sí | — |
Variantes: ninguna
| Campo | Tipo | Requerido | Traducible | Opciones |
|---|---|---|---|---|
heading |
text |
No | Sí | — |
items |
repeater |
No | Sí | — |
Variantes: ninguna
| Campo | Tipo | Requerido | Traducible | Opciones |
|---|---|---|---|---|
eyebrow |
text |
No | Sí | — |
heading |
text |
No | Sí | — |
items |
repeater |
No | Sí | — |
Variantes: ninguna
| Campo | Tipo | Requerido | Traducible | Opciones |
|---|---|---|---|---|
eyebrow |
text |
No | Sí | — |
heading |
text |
No | Sí | — |
items |
repeater |
No | Sí | — |
Variantes: ninguna
| Campo | Tipo | Requerido | Traducible | Opciones |
|---|---|---|---|---|
eyebrow |
text |
No | Sí | — |
heading |
text |
No | Sí | — |
items |
repeater |
No | Sí | — |
Variantes: ninguna
| Campo | Tipo | Requerido | Traducible | Opciones |
|---|---|---|---|---|
eyebrow |
text |
No | Sí | — |
heading |
text |
No | Sí | — |
items |
repeater |
No | Sí | — |
Variantes: ninguna
| Campo | Tipo | Requerido | Traducible | Opciones |
|---|---|---|---|---|
heading |
text |
No | Sí | — |
items |
repeater |
No | Sí | — |
Variantes: ninguna
| Campo | Tipo | Requerido | Traducible | Opciones |
|---|---|---|---|---|
eyebrow |
text |
No | Sí | — |
heading |
text |
No | Sí | — |
items |
repeater |
No | Sí | — |
Variantes: ninguna
| Campo | Tipo | Requerido | Traducible | Opciones |
|---|---|---|---|---|
eyebrow |
text |
No | Sí | — |
heading |
text |
No | Sí | — |
text |
textarea |
No | Sí | — |
button_label |
text |
No | Sí | — |
button_url |
url |
No | No | — |
Variantes: ninguna
| Campo | Tipo | Requerido | Traducible | Opciones |
|---|---|---|---|---|
eyebrow |
text |
No | Sí | — |
heading |
text |
No | Sí | — |
Variantes: ninguna
| Campo | Tipo | Requerido | Traducible | Opciones |
|---|---|---|---|---|
heading |
text |
No | Sí | — |
items |
repeater |
No | Sí | — |
Variantes: ninguna
| Campo | Tipo | Requerido | Traducible | Opciones |
|---|---|---|---|---|
eyebrow |
text |
No | Sí | — |
heading |
text |
No | Sí | — |
intro |
textarea |
No | Sí | — |
items |
repeater |
No | Sí | — |
12. Formularios e historial de solicitudes
Forms API 1 incluye siete procesadores aprobados. Los temas controlan diseño y estilo; los plugins definen esquema, validación y flujo. La plataforma guarda, verifica y notifica.
| Plugin del sistema | Tipo de formulario |
|---|---|
eyivo/contact | Contacto contact |
eyivo/quote-request | Solicitud de presupuesto quote_request |
eyivo/product-inquiry | Consulta de producto product_inquiry |
eyivo/appointment-request | Solicitud de cita appointment |
eyivo/course-application | Solicitud de curso course_application |
eyivo/reservation-request | Solicitud de reserva reservation |
eyivo/property-inquiry | Consulta inmobiliaria property_inquiry |
Un formulario, varias ubicaciones
La configuración crea un UUID predeterminado estable por sitio/plugin/tipo. Reutilizar una ubicación conserva esa identidad; un formulario nuevo con nombre recibe otro UUID. Cambiar de tema o reinstalar conserva el historial. Los temas usan alias portables y el editor permite seleccionar formularios guardados sin introducir UUIDs.
{
"plugins": ["eyivo/contact", "eyivo/quote-request"],
"forms": {
"contact": {"plugin":"eyivo/contact","type":"contact","schema_version":1,"instance":"default"},
"quote": {"plugin":"eyivo/quote-request","type":"quote_request","schema_version":1,"instance":"default"}
}
}
Usa forms.contact en contacto y component.form en secciones de formulario. Sustituye form_preset por form_binding. Renderiza campos, ayuda, action, CSRF, form_context firmado y verification_html suministrados. Solo se aceptan cambios de presentación declarados y campos adicionales permitidos; no se debilita la validación obligatoria.
forms.contact · component.form · form_binding · form.fields · form.action · form.csrf_token · form.context · form.verification_html
Dos vistas, un registro
La bandeja compartida y las páginas de lista/detalle del plugin muestran los mismos registros. Cada formulario requiere Panel API 2, submission-list/submission-detail y un enlace de menú plano. Panel API 1 sigue admitido. Ver no marca como leído; lectura, archivo y flujo son independientes y usan record_revision al editar. Desactivar elimina las páginas del plugin, pero conserva el historial en la bandeja compartida.
{"components":[{"type":"submission-list","form_type":"contact","detail_page":"submission"}]}
{"components":[{"type":"submission-detail","form_type":"contact","list_page":"submissions"}]}
Datos y permisos
Los registros usan la base de contenido del sitio y el límite de paquete max_db_bytes existente. No hay cuotas adicionales de cantidad o retención. La configuración sigue en el master con 50 campos, 32 KB y tres niveles. Los miembros pueden ver; modificar requiere propietario/gestión. Los plugins no acceden directamente a la base y no envían PHP/Blade a la app.
Guardado verificado y notificación
La plataforma valida contexto, respuestas y Human Verification y guarda registro, uso y trabajo de notificación juntos. El mismo intento y contenido se recuperan durante 24 horas sin duplicados. SMTP se ejecuta después y puede reintentar; un fallo de correo no borra el registro. Sin destinatario del formulario se usa el correo de la empresa; si ninguna dirección es válida, se guarda sin correo.
Todos los temas incluidos usan este contrato. Los antiguos POST de contact devuelven 410; los enlaces GET de contacto funcionan. Las solicitudes de cita o reserva no confirman reservas. No se incluyen procesadores de terceros, archivos ni destinos externos arbitrarios.
POST /__eyivo/forms/{UUID}/submissionsGET /__eyivo/forms/{UUID}/challenge
15. Plantillas de página y plantillas base de reserva
Hay diez tipos de página estándar: home, page, contact, products, product, gallery, videos, blog, blog_category y blog_post. Un tema puede aportar los diez o solo algunos; theme-core ofrece una plantilla funcional para cada tipo que el tema no declare. Conserva los nombres de área y los enlaces de formularios de los tipos base al sustituirlos, para que el contenido existente y los formularios registrados sigan funcionando tras un cambio de tema.
16. Cabeceras de página
Las cabeceras de subpágina tienen dos formas. Sin imagen, usa una franja compacta con migas de pan, un antetítulo opcional y el título de la página. Con imagen, coloca el título, las migas de pan y el resumen sobre la imagen y una capa de contraste, para que el texto se lea sobre cualquier foto, y refleja la dirección de la capa en diseños de derecha a izquierda.
17. Imágenes, galerías y vídeo
Mantén las imágenes subidas dentro de marcos acotados: las imágenes del catálogo conservan sus proporciones y las fotos de detalle pueden llenar el marco con un recorte centrado. Las galerías pueden abrir la imagen original en un diálogo que se cierra con Escape y devuelve el foco al enlace de la imagen; sin scripts, enlaza el original para que se abra en una pestaña nueva. Los carruseles de imágenes deben admitir gestos táctiles, botones, teclado y movimiento reducido.
18. Texto enriquecido y reglas de visualización comunes
El componente común eyivo:rich_text acepta cuerpos marcados por el editor y cuerpos HTML antiguos. Ambos pasan por la lista de formato permitido de la plataforma: los párrafos, títulos, listas y enlaces seguros se muestran como contenido, y se eliminan los scripts, los controladores de eventos y los enlaces inseguros. Los demás campos de texto siguen escapados. Muestra el texto enriquecido con los filtros proporcionados, no con tu propio tratamiento de HTML.
19. Introducciones, áreas de orientación y páginas largas
Un tipo de página puede combinar la cabecera con un área de orientación opcional para enlaces rápidos o datos clave; si esa área está vacía, la introducción debe usar todo el ancho. Las páginas editoriales largas deben mantener una longitud de línea legible y un espaciado claro de títulos, y pueden colocar secciones de apoyo, como una lista de comprobación o una nota, junto al artículo en pantallas anchas y después en pantallas pequeñas. Todo diseño debe leerse bien sin scripts.
20. Movimiento y movimiento reducido
El movimiento decorativo es opcional. Respeta prefers-reduced-motion en transiciones, carruseles y secciones animadas, y pausa el contenido en movimiento mientras el visitante pasa el cursor por encima o tiene el foco dentro.
21. Lista de comprobación de un tema completo
Un tema completo aporta las diez plantillas de página, da estilo a todos los componentes comunes eyivo:, admite todos los enlaces de formulario portables mediante los plugins de formulario existentes y la verificación humana, y funciona en escritorio, móvil y diseños de derecha a izquierda. El filtrado del catálogo, las pestañas, los carruseles y los desplegables de navegación son mejoras opcionales sobre un contenido que funciona sin ellas.
22. ¿Qué sucede desde la activación de la plantilla hasta la publicación?
- Instala o activa la plantilla. Eyivo valida el paquete, registra su clave y versión, y muestra sus opciones y esquemas de componentes en la aplicación.
- Elige un tipo de página. Eyivo usa el archivo Liquid y la definición de áreas del tema activo cuando existen; de lo contrario, usa los correspondientes de
theme-core. - Añade secciones permitidas. La aplicación solo ofrece los tipos enumerados en
allowed_components. Guarda el texto, las referencias multimedia y las traducciones en la instancia seleccionada. - Renderiza de forma segura. Eyivo resuelve los datos de empresa, página, SEO y navegación; renderiza los componentes de área guardados y los componentes directos situados por el diseñador; después renderiza el tipo de página y el diseño del tema activo.
- Publica. El visitante recibe el HTML y CSS del tema, pero nunca credenciales de base de datos, modelos internos ni código de aplicación.
- Actualiza con una versión nueva. Subir un ZIP en Temas personalizados crea un tema nuevo. Para cambiar un tema existente, ábrelo, aumenta
versionentheme.jsony sube una versión nueva. Cada sitio cambia cuando usas la versión nueva como borrador y la publicas; la versión anterior sigue disponible para revertir durante 30 días.
23. Validación y errores comunes
| Si ves… | Comprueba esto primero |
|---|---|
| “Versión API del tema Eyivo no compatible” | Establece "eyivo_theme_api": "1.0". |
| Error de tipo/diseño/componente de página faltante | Cada tipo de página o componente declarado por el tema necesita su archivo .liquid correspondiente. El tema activo siempre debe aportar layouts/default.liquid; los tipos de página integrados que se omitan usan los archivos de Core. |
| Componente no disponible en el editor | Añade el tipo con espacio de nombres a la lista allowed_components del área o marca su definición como universal. |
| Componente directo desconocido | Usa un tipo eyivo: del catálogo compartido entre comillas o declara la definición theme: y el archivo Liquid correspondiente en el tema activo. |
| El campo es rechazado | Declara el campo en el esquema del componente y usa un tipo de campo compatible. Usa translatable: true para el texto específico de cada idioma. |
| La plantilla aparece sin estilo | Usa el filtro asset_url para el CSS y comprueba que el archivo exista en assets/. |
| El paquete se rechaza por sintaxis insegura | Elimina PHP/Blade, env, config, llamadas a bases de datos o HTTP y acceso al sistema de archivos. Liquid solo se usa para la presentación. |
Reglas de scripts: custom_javascript_declaration, script_file, script_tag, script_import, script_size | Sigue Scripts de temas. Los hallazgos de la revisión aparecen en la página de la versión con su archivo y línea; corrígelos y sube una versión nueva. |
24. Preguntas frecuentes
¿Puede un cliente crear otro diseño o mover una sección principal al pie de página?
No. Puede cambiar contenido aprobado y ordenar componentes permitidos dentro de un área. El tipo de página Liquid define el diseño.
¿Puede un diseñador utilizar un componente sin un área editable?
Sí. Usa eyivo_component en un diseño o tipo de página. Usa un área cuando el propietario deba controlar la instancia y su orden.
¿Debe un tema implementar todos los tipos de página?
Todos los temas deben admitir el blog. Los tipos integrados blog, blog_category y blog_post pueden usar las definiciones y archivos Liquid correspondientes de theme-core dentro del diseño del tema activo. Declara un tipo solo si aportas su archivo de sustitución correspondiente. Los paquetes de temas existentes siguen siendo compatibles. Las rutas del blog son /blog, /blog/category/{slug} y /blog/{slug}, con el prefijo de idioma de Eyivo cuando corresponda. Conserva eyivo_head para metadatos seguros, estilos adaptables del blog y tarjetas de imagen con dimensiones limitadas.
¿Puede un tema consultar una página, llamar a una API o leer una variable de entorno?
No. Los datos se transmiten deliberadamente como objetos seguros. Esto mantiene los temas portátiles, seguros y predecibles.
¿Cómo publico una actualización?
Publica una nueva versión semántica del tema. No modifiques silenciosamente una versión publicada; los sitios deben pasar expresamente a la nueva versión.
¿Dónde deberían vivir las imágenes?
Usa una URL multimedia de Eyivo en los datos del componente o un recurso del paquete referenciado mediante asset_url. No uses rutas arbitrarias del sistema de archivos del servidor.
25. Registro de cambios
- 31 de octubre de 2026. Theme API 1.1: los temas pueden incluir JavaScript revisado en
assets/js/con la capacidadcustom_javascript. Las versiones nuevas se revisan automáticamente y muestran Pendiente de revisión, Aprobada, Rechazada o Bloqueada. Los paquetes Theme API 1.0 no cambian. - 31 de octubre de 2026. Los propietarios pueden añadir CSS personalizado del sitio, cargado después de tus hojas de estilo, y dar nombres de clase a las secciones, que se añaden al primer elemento de cada componente y están disponibles como
{{ component.css_class }}. Consulta CSS personalizado del sitio y clases de sección. - 31 de octubre de 2026. Los medios de demostración de
demo.jsondeben usar un hosthttpspermitido (cdn.eyivo.comoimages.pexels.com) o un archivo incluido enassets/. Eyivo detecta el tipo de cada archivo a partir de su contenido. Es una corrección de seguridad; la Theme API sigue en la 1.0. - 30 de octubre de 2026. Eyivo asigna a cada tema subido su propio ID, y
keyentheme.jsones opcional. Sube los cambios como una versión nueva desde la página del tema. El repositorio de ejemplo guarda el tema en su carpetasample-theme/, que comprimes y subes. El ejemplo de paquete ya no muestraassets/js/, porque las subidas con Theme API 1.0 no pueden incluir archivos JavaScript.