1. O modelo mental
Há três responsabilidades distintas. Mantê-las separadas é essencial para entender a v1.
Eyivo Core
Armazena detalhes da empresa, páginas, multimédia, SEO, navegação e estado de publicação. É a fonte da verdade para o conteúdo.
Pacote do tema
Define estruturas de página fixas, secções permitidas, esquemas de componentes personalizados e CSS. Nunca consulta dados nem executa código da aplicação.
Editor da aplicação
Gera formulários seguros a partir do esquema. Os titulares podem atualizar texto, imagens, páginas e a ordem das secções dentro de uma área.
Não é um construtor de páginas: o proprietário pode adicionar uma secção permitida a main e escolher a sua posição numérica. Não pode criar uma nova área, arrastar um hero para o rodapé nem alterar os ficheiros do seu tema. Pode adicionar o seu próprio CSS do site, carregado depois das suas folhas de estilos, e dar nomes de classe às secções (veja CSS personalizado do site).
2. Início rápido: um modelo mínimo e utilizável
Cada tema v1 controla todo o seu layout, estilos e scripts e pode organizá-los segundo o design escolhido pelo autor. Um tema não herda layouts nem ficheiros de outro tema. Os componentes partilhados eyivo: e os sete tipos de página de reserva vêm de theme-core; o tema guarda apenas os tipos de página que substitui e os componentes que declara no espaço de nomes theme:.
Cada tema v1 precisa de um ficheiro de layout predefinido. As pastas page-types/ e components/ são opcionais quando o pacote usa apenas os 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 sempre vem do tema ativo e controla todo o documento público. Eyivo procura o tipo de página solicitado primeiro no tema e depois em theme-core/page-types. Core nunca fornece layout nem ficheiros visuais; por isso, mesmo o conteúdo de fallback usa o layout e o estilo do tema ativo.
3. Descreva o tema em theme.json
O manifesto declara as capacidades do tema e define o contrato usado para gerar os formulários da aplicação. Ele responde a três perguntas: quais estruturas de página existem, quais áreas cada estrutura contém e quais dados cada componente pode armazenar. Os temas integrados declaram explicitamente os dez tipos de página padrão e incluem os arquivos Liquid correspondentes. Temas personalizados podem continuar usando os modelos de fallback do núcleo para tipos não 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 }
}
}
}
}
| Chave | Significado | Exemplo |
|---|---|---|
key | Etiqueta opcional para referência própria. A Eyivo atribui a cada tema carregado o seu próprio ID, por isso a chave nunca decide a que tema pertence um carregamento. | acme-industrial |
version | A versão imutável do lançamento do tema (versionamento semântico). | 1.2.0 |
eyivo_theme_api | O contrato da API pública Eyivo suportado pelo seu pacote. | 1.0 |
areas | Áreas identificadas que o ficheiro de página Liquid apresenta em locais fixos. | hero, main, bottom |
allowed_components | Quais componentes o editor pode adicionar a uma área. | ["eyivo:hero"] |
components | As definições de componentes theme: personalizados do tema ativo. As definições eyivo: compartilhadas permanecem em theme-core. | featured_course |
min/max | Limites opcionais para o número de secções nessa área. | max: 1 |
Tipos de página de reserva: os tipos integrados são home, page, gallery, contact, products, product e videos. Omita um tipo para usar a definição e o ficheiro Liquid de theme-core. Declare-o apenas quando o tema fornecer o ficheiro substituto page-types/<type>.liquid.
O editor recebe a API combinada dos tipos de página: as definições do tema ativo substituem as correspondentes de core, enquanto os tipos omitidos continuam disponíveis em core.
4. Conteúdo de demonstração completo em demo.json
Cada pacote enviado deve incluir um ficheiro demo.json portátil, cujo conteúdo serve apenas de rascunho, e pelo menos uma captura de ecrã feita com esses dados de demonstração. Os temas integrados usam o mesmo esquema. Não inclua IDs da base de dados, domínios de clientes, credenciais nem chaves de armazenamento 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": []
}
| Chave | Propósito |
|---|---|
media | URLs públicas de origem e metadados associados a identificadores portáteis de recursos. Reutilize o identificador em hero_asset, cover_asset, media_asset, no asset dos itens da galeria, em logo_asset e favicon_asset. |
company | Perfil da empresa, links sociais, cores da marca, ativo opcional de logotipo/favicon e traduções com chave de localidade. |
theme_settings | Configurações iniciais do tema, com traduções opcionais com chave de localidade. |
pages | Tipo, ordem de classificação, estado de navegação, SEO, configurações de página, componentes e conteúdo com chave de localidade. |
catalog | Entradas de catálogo com conteúdo com chave de localidade e um cover_asset opcional. |
galleries | Metadados da galeria e itens de imagem. Cada item da galeria precisa de um asset e um alt_text não vazio. |
videos | Um source_url externo ou media_asset, modo de apresentação e conteúdo com chave de localidade. |
Cada entrada de media precisa de uma public_url em https num anfitrião permitido (o anfitrião de multimédia de demonstração da Eyivo cdn.eyivo.com ou images.pexels.com), ou de um ficheiro incluído no tema em assets/, identificado pelo seu caminho e sem public_url. Outros anfitriões, http, endereços IP, outras portas e redirecionamentos são rejeitados com o diagnóstico de envio demo_media_url. mime_type, width e height são apenas indicações: a Eyivo deteta o tipo real a partir do conteúdo transferido, que tem de ser uma imagem ou um vídeo permitidos com 20 MB no máximo.
Os formulários da demo usam associações de formulário portáteis, que a Eyivo resolve separadamente para cada site que importa a demo. As imagens da demo importadas tornam-se referências de multimédia normais nesse site; removê-las lá nunca remove o original partilhado.
Páginas e 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" }
}
}]
}
Os tipos e áreas de componentes devem ser declarados no manifesto do tema ativo ou theme-core. Use caminhos relativos, como /contact, para links do mesmo site. As demonstrações de início incluídas usam a imagem hero existente como fundo de largura total, com uma camada para facilitar a leitura e texto responsivo: immersive na maioria dos temas e centered com imagem no Compact. As outras variantes mantêm seus próprios layouts.
Idiomas de demonstração e alternativa
O inglês é o idioma base obrigatório: defina default_locale como en. A ausência em dados antigos também significa inglês. Os outros idiomas suportados são opcionais; não apresente cópias em inglês como traduções.
Forneça translations.en e objetos de idioma opcionais para empresa, definições, páginas, componentes, produtos, galerias, legendas e textos alternativos, vídeos e artigos. Os campos antigos em inglês sem chave de idioma continuam válidos. A criação escolhe o idioma principal do site e usa inglês em cada campo em falta. Os arrays substituem todo o array inglês; valores explicitamente vazios são preservados. Apenas o idioma escolhido é importado, sem ativar outros automaticamente.
Use slugs de origem em inglês nos links internos e menus portáteis. A importação converte-os nos slugs traduzidos, incluindo links em texto formatado e artigos. Os menus podem fornecer mapas explícitos slugs e labels. Etiquetas em falta usam inglês. Os URLs externos não são alterados.
{
"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" }
}]
}
}
Importação e segurança de multimédia
Os novos sites no painel incluem dados de demonstração por predefinição e publicam imediatamente o idioma escolhido; o proprietário pode desmarcar a opção. Num site existente, importar a partir de Marca continua a criar rascunhos e preserva o conteúdo publicado. A App central copia imagens para a biblioteca do novo site e envia referências pela API interna. Masters e temas nunca recebem credenciais do armazenamento de objetos. Os temas usam o valor media.public_url fornecido.
Declare as capturas de ecrã em theme.json.preview com data_source: "demo_data". O pacote deve conter todas as imagens preview declaradas.
5. Crie o layout de que o seu tema precisa
O layout predefinido controla todo o documento HTML. Nada fora do tema ativo fornece o cabeçalho, o rodapé, a folha de estilos ou a estrutura visual. A plataforma só acrescenta os seus próprios scripts para formulários, verificação humana, consentimento e o selo Eyivo; os scripts de temas exigem 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>
O ficheiro de tipo de página determina onde aparecem as suas áreas dinâmicas. Os componentes das áreas já são cadeias HTML geradas; insira-as com | raw. Os valores comuns são escapados por predefinição.
<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 um componente diretamente
Um designer pode colocar um componente registado diretamente num ficheiro de layout ou de tipo de página. A posição fica definida pelo tema e não pode ser alterada nem removida no painel. Passe um objeto através de data:, campos individuais do esquema ou ambos; os campos identificados prevalecem sobre as chaves correspondentes 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"
%}
O tipo deve ser um literal entre aspas com namespace. A renderização direta usa o mesmo esquema, variantes, ficheiro de componente e objeto component normalizado de uma instância de área. Um ficheiro de componente não pode renderizar outros componentes.
Ficheiros do tema: use sempre {{ 'css/theme.css' | asset_url }}. Eyivo entrega o ficheiro do pacote ativo em /theme-assets/<theme>/css/theme.css; não fixe outro nome de tema nem um caminho do sistema de ficheiros.
Cabeçalho, rotas e dicionários de interface
Cada layout deve renderizar {% eyivo_head %} exatamente uma vez. Eyivo controla o título, a descrição, as diretivas robots, a URL canônica, hreflang, Open Graph e os dados estruturados. Use routes.home, routes.contact, routes.catalog, routes.gallery e routes.videos em vez de caminhos públicos fixos. Passe URLs editáveis pelo filtro | localized_url, que adiciona o prefixo do idioma aos caminhos internos conhecidos e mantém URLs externas inalteradas.
{{ 'Menu' | t }}
{{ theme.settings.header_cta_url | localized_url }}
Pode criar ficheiros locales/<locale>.json para os rótulos de interface introduzidos pelo tema. A ordem de procura é: inglês de core, idioma atual de core, inglês do tema e idioma atual do tema. Os rótulos partilhados de theme-core funcionam sem copiar ficheiros. Os textos da empresa devem estar no conteúdo traduzível, nos campos dos componentes ou nas definições do tema, não nos dicionários.
Um ficheiro 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>
Para campos traduzíveis, o Eyivo seleciona a localidade do visitante antes da renderização. Portanto, um visitante turco e um visitante inglês veem a mesma estrutura de componentes com valores component.data.heading diferentes.
7. Dados Liquid seguros que pode utilizar
Liquid recebe dados simples e normalizados – não Laravel ou modelos de banco de dados. Se um valor não estiver nesta tabela, trate-o como indisponível na v1.
| Objeto | Campos úteis | Uso típico |
|---|---|---|
site | name, locale | Nome do site e idioma principal. |
company | name, legal_name, description, address, phone, email | Cabeçalho, rodapé e informações de contato. |
page | id, type, title, slug, body, settings | Conteúdo genérico da página e configurações por página. |
seo | title, description e, quando disponíveis, valores de URL canônica, robots e Open Graph | Secção head do documento. |
navigation.main | Cada item tem label, url, active | Menu do site. |
locale | code, name, native_name, direction, is_default, home_url, available | Idioma do documento, direção RTL, links localizados para a página inicial e seletor de idioma. |
routes | home, contact, catalog, gallery, videos, blog | URLs do sistema corretas para o idioma atual; nunca monte prefixos em Liquid. |
blog | title, url, categories, category, posts, post, pagination | Listagem do blog gratuito, arquivos de categorias e páginas de artigos. Os artigos incluem título, resumo, URL, datas, categorias e imagem de capa. Apenas blog.post.body_html contém HTML seguro gerado pelo servidor para o artigo e deve usar raw. A paginação fornece previous_url e next_url. |
theme.settings | Configurações definidas no manifesto | Use uma opção de cor, espaçamento ou design configurada. |
products/product | Título, URL, resumo e corpo traduzidos | Páginas de listagem e detalhes dos produtos. |
galleries | Título e descrição traduzidos | Tipo de página da galeria. |
videos | title, description, source_type, source_url, playback_url, media | Use playback_url para ficheiros de vídeo carregados e source_url para vídeos HTTP(S) externos, conforme source_type. As imagens anexadas nunca são fontes de vídeo. Não use o próprio ficheiro de vídeo como imagem de capa. |
component | id, type, variant, data | Somente dentro de um ficheiro de componente. |
Exemplo de layout correto para cada 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 item de idioma disponível também expõe label, direction, is_default, current e has_translation. A Eyivo fornece apenas traduções publicadas equivalentes, portanto os temas devem usar language.url em vez de construir /en ou qualquer outro prefixo.
Exemplo de token orientado por configurações: style="--brand: {{ theme.settings.primary_color }}". A configuração deve primeiro ser declarada em theme.json.
8. Componentes: diretos e dinâmicos
Os componentes seguem um contrato de apresentação com duas formas de posicionamento. Um componente direto é controlado pelo designer num layout ou tipo de página. Um componente dinâmico é guardado como instância de uma área de página e controlado pelo editor. As instâncias dinâmicas têm um ID estável, tipo com espaço de nomes, área, posição, variante opcional, dados e traduções. A posição indica apenas a ordem, não a identidade.
Tipos de campo
text, textarea, richtext, number, boolean, select, url, email, image, video, file, color, icon, page, product e repeater.
Namespaces
eyivo: é resolvido a partir de theme-core/components, theme: a partir do tema ativo e plugin: fica reservado para futuros plug-ins. Use o tipo exato com espaço de nomes numa área ou numa tag eyivo_component.
Componente universal: defina "universal": true na definição do componente para o permitir em todas as áreas de tipos de página compatíveis. Continua a precisar de um esquema válido e de um ficheiro Liquid.
Os links de ação partilhados adaptam os caminhos internos conhecidos ao idioma ativo, preservando os parâmetros de consulta e os fragmentos. O texto formatado mantém a formatação segura em contentores aninhados do editor. As imagens de galeria vazias são omitidas, as imagens de mapa sem destino não são links e as etiquetas de slides e pesquisa usam o idioma da interface do visitante.
9. CSS personalizado do site e classes de secção
Os proprietários podem adicionar o seu próprio CSS a um site e dar nomes de classe às secções (Design → CSS personalizado). Escreva os temas para que isto funcione bem:
- Ordem de carregamento: o CSS do site é adicionado como
<style id="eyivo-custom-css">mesmo antes de</head>, depois de todas as folhas de estilos do tema. Mantenha</head>nos layouts e não dependa de o seu CSS ser o último. - Classes de secção: o renderizador adiciona os nomes de classe de uma secção ao primeiro elemento da saída do componente, por isso dê a cada modelo de componente um único elemento raiz. Os nomes também estão disponíveis como
{{ component.css_class }}se os quiser colocar noutro sítio. - Pontos de ligação estáveis: mantenha as classes
body.theme-{key}elayout-{name}e uma classe raiz estável por componente, para que o CSS dos proprietários continue a funcionar entre versões. Indique qualquer mudança de nome nas notas da versão. - Temas carregados: também têm CSS personalizado do site. Todas as versões de um tema carregado partilham uma folha de estilos por site, que é eliminada quando a última versão do tema num site é retirada ou eliminada.
- Nomes reservados: o prefixo de classe
eyivo-e o IDeyivo-custom-csspertencem à plataforma.
10. Scripts de temas (Theme API 1.1)
Um tema pode incluir o seu próprio JavaScript para menus, carrosséis, separadores, filtros e funcionalidades semelhantes. Os scripts são opcionais: todos os temas têm de funcionar sem eles, e os pacotes Theme API 1.0 continuam a funcionar sem alterações, sem scripts.
- Declare-o: defina
"eyivo_theme_api": "1.1"e"capabilities": {"custom_javascript": true}emtheme.jsone coloque cada ficheiro diretamente emassets/js/. Um pacote com ficheiros.jssem a declaração é rejeitado. - Carregue-o: use apenas
<script src="{{ 'js/theme.js' | asset_url }}" defer></script>(outype="module") para um ficheiro do pacote. As etiquetas são executadas pela ordem em que aparecem. - Vários ficheiros: cada ficheiro é revisto e autorizado separadamente, por isso
importeexportnão são permitidos. Partilhe código através de um único global, comowindow.AcmeTheme, e carregue primeiro o ficheiro que o define. - Limites: no máximo 20 ficheiros, 100 KB por ficheiro e 300 KB no total, apenas texto UTF-8.
- Rejeitado nos modelos: scripts inline, fontes de script externas, atributos de eventos
on…=, URLjavascript:e os elementos<iframe>,<object>,<embed>e<base>. - Apenas código legível: carregue o código-fonte, não código minificado, compactado ou codificado. Os bundlers podem gerar saída não minificada.
- Estados: uma nova versão fica A aguardar revisão até as verificações terminarem e depois passa a Aprovada ou Rejeitada. Só uma versão aprovada pode ser pré-visualizada ou usada. Uma versão aprovada pode mais tarde ficar Bloqueada: os sites mantêm o tema sem os scripts.
- Três verificações automáticas, por ordem: código legível; regras de código (sem
eval,new Function,document.write, redirecionamentos de página,window.open, cookies ou armazenamento do navegador, WebAssembly, temporizadores com cadeias de texto, elementos script ou frame criados, nem valores de formulários enviados pela rede); e uma revisão de segurança por IA. Para essa revisão, os scripts e as linhas de modelo que os carregam são enviados a um serviço de IA. Qualquer problema rejeita a versão, com o ficheiro e a linha.
Aprovado: um botão de menu
(function () {
document.querySelectorAll('[data-menu-toggle]').forEach(function (button) {
button.addEventListener('click', function () {
document.body.classList.toggle('menu-open');
});
});
})();
Rejeitado: envia valores do formulário para fora
form.addEventListener('submit', function () {
fetch('/collect', { method: 'POST', body: form.elements.email.value });
});
- Só o proprietário: os scripts aprovados só são executados em sites da conta que carregou o tema, e apenas enquanto a plataforma e o proprietário do site o permitirem.
- Política de segurança: as páginas que executam scripts de temas permitem exatamente os ficheiros revistos, fixados pelos seus hashes SHA-256, com
connect-src 'self', sem frames nem workers e semeval. Alterar um ficheiro exige uma nova versão. Imagens e folhas de estilo ainda podem ser carregadas dehttps:, por isso a revisão também rejeita dados enviados através de URL de imagens ou folhas de estilo. - Após a aprovação: os navegadores comunicam tentativas de violar a política. As comunicações de três visitantes em 24 horas bloqueiam a versão; as denúncias de abuso de três visitantes em 7 dias desativam os scripts nesse site e voltam a verificar a versão. Os proprietários recebem um email quando uma versão é aprovada, rejeitada ou bloqueada.
- Funcionalidades da plataforma: os scripts não podem substituir, envolver nem ocultar os formulários e os seus campos ocultos, a verificação humana, a faixa de consentimento, o selo Eyivo ou a barra do proprietário.
11. Catálogo de componentes disponíveis
Esses 30 componentes compartilhados eyivo: formam a biblioteca completa da v1 e vêm de theme-core. Um tema também pode declarar e implementar seus próprios componentes theme:.
Variantes: spliteditorialcenteredimmersive
| Campo | Tipo | Obrigatório | Traduzível | Opções |
|---|---|---|---|---|
eyebrow |
text |
Não | Sim | — |
heading |
text |
Sim | Sim | — |
summary |
textarea |
Não | Sim | — |
image_url |
url |
Não | Não | — |
image_alt |
text |
Não | Sim | — |
primary_label |
text |
Não | Sim | — |
primary_url |
url |
Não | Não | — |
secondary_label |
text |
Não | Sim | — |
secondary_url |
url |
Não | Não | — |
Variantes: nenhuma
| Campo | Tipo | Obrigatório | Traduzível | Opções |
|---|---|---|---|---|
eyebrow |
text |
Não | Sim | — |
heading |
text |
Não | Sim | — |
body |
richtext |
Não | Sim | — |
Variantes: image_leftimage_rightoverlap
| Campo | Tipo | Obrigatório | Traduzível | Opções |
|---|---|---|---|---|
eyebrow |
text |
Não | Sim | — |
heading |
text |
Não | Sim | — |
body |
richtext |
Não | Sim | — |
image_url |
url |
Não | Não | — |
image_alt |
text |
Não | Sim | — |
badge |
text |
Não | Sim | — |
button_label |
text |
Não | Sim | — |
button_url |
url |
Não | Não | — |
Variantes: nenhuma
| Campo | Tipo | Obrigatório | Traduzível | Opções |
|---|---|---|---|---|
eyebrow |
text |
Não | Sim | — |
heading |
text |
Não | Sim | — |
items |
repeater |
Não | Sim | — |
Variantes: nenhuma
| Campo | Tipo | Obrigatório | Traduzível | Opções |
|---|---|---|---|---|
eyebrow |
text |
Não | Sim | — |
heading |
text |
Não | Sim | — |
intro |
textarea |
Não | Sim | — |
items |
repeater |
Não | Sim | — |
Variantes: nenhuma
| Campo | Tipo | Obrigatório | Traduzível | Opções |
|---|---|---|---|---|
eyebrow |
text |
Não | Sim | — |
heading |
text |
Não | Sim | — |
intro |
textarea |
Não | Sim | — |
items |
repeater |
Não | Sim | — |
Variantes: nenhuma
| Campo | Tipo | Obrigatório | Traduzível | Opções |
|---|---|---|---|---|
eyebrow |
text |
Não | Sim | — |
heading |
text |
Não | Sim | — |
intro |
textarea |
Não | Sim | — |
button_label |
text |
Não | Sim | — |
button_url |
url |
Não | Não | — |
Variantes: nenhuma
| Campo | Tipo | Obrigatório | Traduzível | Opções |
|---|---|---|---|---|
eyebrow |
text |
Não | Sim | — |
heading |
text |
Não | Sim | — |
items |
repeater |
Não | Sim | — |
Variantes: nenhuma
| Campo | Tipo | Obrigatório | Traduzível | Opções |
|---|---|---|---|---|
eyebrow |
text |
Não | Sim | — |
heading |
text |
Não | Sim | — |
text |
textarea |
Não | Sim | — |
submit_label |
text |
Não | Sim | — |
form_binding |
select |
Não | Não | — |
Variantes: nenhuma
| Campo | Tipo | Obrigatório | Traduzível | Opções |
|---|---|---|---|---|
heading |
text |
Não | Sim | — |
text |
textarea |
Não | Sim | — |
whatsapp_url |
url |
Não | Não | — |
Variantes: nenhuma
| Campo | Tipo | Obrigatório | Traduzível | Opções |
|---|---|---|---|---|
eyebrow |
text |
Não | Sim | — |
heading |
text |
Não | Sim | — |
address |
textarea |
Não | Sim | — |
map_url |
url |
Não | Não | — |
image_url |
url |
Não | Não | — |
image_alt |
text |
Não | Sim | — |
Variantes: nenhuma
| Campo | Tipo | Obrigatório | Traduzível | Opções |
|---|---|---|---|---|
heading |
text |
Não | Sim | — |
items |
repeater |
Não | Sim | — |
Variantes: nenhuma
| Campo | Tipo | Obrigatório | Traduzível | Opções |
|---|---|---|---|---|
heading |
text |
Não | Sim | — |
placeholder |
text |
Não | Sim | — |
categories |
repeater |
Não | Sim | — |
Variantes: nenhuma
| Campo | Tipo | Obrigatório | Traduzível | Opções |
|---|---|---|---|---|
eyebrow |
text |
Não | Sim | — |
heading |
text |
Não | Sim | — |
summary |
textarea |
Não | Sim | — |
video_url |
url |
Não | Não | — |
poster_url |
url |
Não | Não | — |
Variantes: nenhuma
| Campo | Tipo | Obrigatório | Traduzível | Opções |
|---|---|---|---|---|
eyebrow |
text |
Não | Sim | — |
heading |
text |
Não | Sim | — |
price |
text |
Não | Sim | — |
period |
text |
Não | Sim | — |
features |
repeater |
Não | Sim | — |
button_label |
text |
Não | Sim | — |
button_url |
url |
Não | Não | — |
Variantes: nenhuma
| Campo | Tipo | Obrigatório | Traduzível | Opções |
|---|---|---|---|---|
label |
text |
Não | Sim | — |
heading |
text |
Não | Sim | — |
body |
textarea |
Não | Sim | — |
button_label |
text |
Não | Sim | — |
button_url |
url |
Não | Não | — |
Variantes: nenhuma
| Campo | Tipo | Obrigatório | Traduzível | Opções |
|---|---|---|---|---|
eyebrow |
text |
Não | Sim | — |
heading |
text |
Não | Sim | — |
items |
repeater |
Não | Sim | — |
Variantes: nenhuma
O componente partilhado eyivo:faq mantém os mesmos campos e a mesma marcação em cada tema. Cada tema apresenta-o com a sua tipografia, o seu espaçamento e a sua cor.
| Campo | Tipo | Obrigatório | Traduzível | Opções |
|---|---|---|---|---|
eyebrow |
text |
Não | Sim | — |
heading |
text |
Não | Sim | — |
items |
repeater |
Não | Sim | — |
Variantes: nenhuma
| Campo | Tipo | Obrigatório | Traduzível | Opções |
|---|---|---|---|---|
eyebrow |
text |
Não | Sim | — |
heading |
text |
Não | Sim | — |
items |
repeater |
Não | Sim | — |
Variantes: nenhuma
| Campo | Tipo | Obrigatório | Traduzível | Opções |
|---|---|---|---|---|
heading |
text |
Não | Sim | — |
items |
repeater |
Não | Sim | — |
Variantes: nenhuma
| Campo | Tipo | Obrigatório | Traduzível | Opções |
|---|---|---|---|---|
eyebrow |
text |
Não | Sim | — |
heading |
text |
Não | Sim | — |
items |
repeater |
Não | Sim | — |
Variantes: nenhuma
| Campo | Tipo | Obrigatório | Traduzível | Opções |
|---|---|---|---|---|
eyebrow |
text |
Não | Sim | — |
heading |
text |
Não | Sim | — |
items |
repeater |
Não | Sim | — |
Variantes: nenhuma
| Campo | Tipo | Obrigatório | Traduzível | Opções |
|---|---|---|---|---|
eyebrow |
text |
Não | Sim | — |
heading |
text |
Não | Sim | — |
items |
repeater |
Não | Sim | — |
Variantes: nenhuma
| Campo | Tipo | Obrigatório | Traduzível | Opções |
|---|---|---|---|---|
eyebrow |
text |
Não | Sim | — |
heading |
text |
Não | Sim | — |
items |
repeater |
Não | Sim | — |
Variantes: nenhuma
| Campo | Tipo | Obrigatório | Traduzível | Opções |
|---|---|---|---|---|
heading |
text |
Não | Sim | — |
items |
repeater |
Não | Sim | — |
Variantes: nenhuma
| Campo | Tipo | Obrigatório | Traduzível | Opções |
|---|---|---|---|---|
eyebrow |
text |
Não | Sim | — |
heading |
text |
Não | Sim | — |
items |
repeater |
Não | Sim | — |
Variantes: nenhuma
| Campo | Tipo | Obrigatório | Traduzível | Opções |
|---|---|---|---|---|
eyebrow |
text |
Não | Sim | — |
heading |
text |
Não | Sim | — |
text |
textarea |
Não | Sim | — |
button_label |
text |
Não | Sim | — |
button_url |
url |
Não | Não | — |
Variantes: nenhuma
| Campo | Tipo | Obrigatório | Traduzível | Opções |
|---|---|---|---|---|
eyebrow |
text |
Não | Sim | — |
heading |
text |
Não | Sim | — |
Variantes: nenhuma
| Campo | Tipo | Obrigatório | Traduzível | Opções |
|---|---|---|---|---|
heading |
text |
Não | Sim | — |
items |
repeater |
Não | Sim | — |
Variantes: nenhuma
| Campo | Tipo | Obrigatório | Traduzível | Opções |
|---|---|---|---|---|
eyebrow |
text |
Não | Sim | — |
heading |
text |
Não | Sim | — |
intro |
textarea |
Não | Sim | — |
items |
repeater |
Não | Sim | — |
12. Formulários e histórico de pedidos
Forms API 1 fornece sete processadores aprovados. Os temas controlam disposição e estilo; os plugins definem esquema, validação e fluxo. A plataforma guarda, verifica e notifica.
| Plugin do sistema | Tipo de formulário |
|---|---|
eyivo/contact | Contacto contact |
eyivo/quote-request | Pedido de orçamento quote_request |
eyivo/product-inquiry | Consulta de produto product_inquiry |
eyivo/appointment-request | Pedido de marcação appointment |
eyivo/course-application | Candidatura a curso course_application |
eyivo/reservation-request | Pedido de reserva reservation |
eyivo/property-inquiry | Consulta imobiliária property_inquiry |
Um formulário, várias posições
A configuração cria um UUID predefinido permanente por site/plugin/tipo. Reutilizar uma posição conserva a identidade; criar um formulário com nome gera outro UUID. Mudar de tema ou reinstalar preserva o histórico. Os temas usam nomes portáteis; o editor seleciona formulários guardados sem introduzir 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"}
}
}
Use forms.contact nos contactos e component.form nas secções de formulário. Substitua form_preset por form_binding. Renderize campos, ajuda, action, CSRF, form_context assinado e verification_html fornecidos. Só são permitidas alterações de apresentação declaradas e campos adicionais autorizados; a validação obrigatória mantém-se.
forms.contact · component.form · form_binding · form.fields · form.action · form.csrf_token · form.context · form.verification_html
Duas vistas, um registo
A caixa partilhada e as páginas de lista/detalhe do plugin mostram os mesmos registos. Formulários exigem Panel API 2, submission-list/submission-detail e um link de menu sem subníveis. Panel API 1 continua suportada. Ver não marca como lido; leitura, arquivo e fluxo são separados e alterações usam record_revision. Desativar remove as páginas do plugin; a caixa partilhada mantém o histórico.
{"components":[{"type":"submission-list","form_type":"contact","detail_page":"submission"}]}
{"components":[{"type":"submission-detail","form_type":"contact","list_page":"submissions"}]}
Dados e permissões
Os registos usam a base de conteúdo do site e o limite max_db_bytes do pacote existente. Não há quota adicional de quantidade ou retenção. A configuração continua no master com 50 campos, 32 KB e três níveis. Membros podem ver; alterações exigem proprietário/gestão. Plugins não têm acesso direto à base nem enviam PHP/Blade para a app.
Gravação verificada e notificação
A plataforma valida contexto, respostas e Human Verification e guarda registo, utilização e trabalho de notificação juntos. A mesma tentativa pode ser recuperada durante 24 horas sem duplicação. SMTP executa depois e pode repetir; uma falha de email não apaga o registo. Sem destinatário no formulário, usa-se o email da empresa; se nenhum endereço for válido, o registo é guardado sem email.
Todos os temas incluídos usam este contrato. POST contact antigos devolvem 410; as páginas GET de contacto funcionam. Pedidos de marcação ou reserva não confirmam reservas. Processadores de terceiros, ficheiros e destinos externos arbitrários estão excluídos.
POST /__eyivo/forms/{UUID}/submissionsGET /__eyivo/forms/{UUID}/challenge
15. Modelos de página e modelos base de reserva
Existem dez tipos de página padrão: home, page, contact, products, product, gallery, videos, blog, blog_category e blog_post. Um tema pode fornecer os dez ou só alguns; theme-core fornece um modelo funcional para cada tipo que o tema não declarar. Mantenha os nomes das áreas e as associações de formulários dos tipos base ao substituí-los, para que o conteúdo existente e os formulários registados continuem a funcionar após uma mudança de tema.
16. Cabeçalhos de página
Os cabeçalhos de subpágina têm duas formas. Sem imagem, use uma faixa compacta com navegação estrutural, um pré-título opcional e o título da página. Com imagem, coloque o título, a navegação estrutural e o resumo sobre a imagem e uma camada de contraste, para que o texto se leia em qualquer fotografia, e espelhe a direção da camada em layouts da direita para a esquerda.
17. Imagens, galerias e vídeo
Mantenha as imagens carregadas dentro de molduras delimitadas: as imagens do catálogo mantêm as proporções e as fotografias de detalhe podem preencher a moldura com um recorte centrado. As galerias podem abrir a imagem original numa caixa de diálogo que fecha com Escape e devolve o foco à ligação da imagem; sem scripts, ligue a original para abrir num novo separador. Os carrosséis de imagens devem suportar toque, botões, teclado e movimento reduzido.
18. Texto formatado e regras de apresentação comuns
O componente comum eyivo:rich_text aceita conteúdos marcados pelo editor e conteúdos HTML antigos. Ambos passam pela lista de formatação permitida da plataforma: parágrafos, títulos, listas e ligações seguras aparecem como conteúdo, enquanto scripts, manipuladores de eventos e ligações inseguras são removidos. Os outros campos de texto continuam escapados. Apresente texto formatado com os filtros fornecidos, e não com o seu próprio tratamento de HTML.
19. Introduções, áreas de orientação e páginas longas
Um tipo de página pode juntar ao cabeçalho uma área de orientação opcional para ligações rápidas ou factos principais; se essa área estiver vazia, a introdução deve usar toda a largura. As páginas editoriais longas devem manter um comprimento de linha legível e espaçamento claro entre títulos, e podem colocar secções de apoio, como uma lista de verificação ou uma nota, ao lado do artigo em ecrãs largos e depois dele em ecrãs pequenos. Todos os layouts devem continuar legíveis sem scripts.
20. Movimento e movimento reduzido
O movimento decorativo é opcional. Respeite prefers-reduced-motion em transições, carrosséis e secções animadas, e pause o conteúdo em movimento enquanto o visitante passa o rato por cima ou tem o foco no seu interior.
21. Lista de verificação de um tema completo
Um tema completo fornece os dez modelos de página, estiliza todos os componentes comuns eyivo:, suporta todas as associações de formulário portáteis através dos plugins de formulário existentes e da verificação humana, e funciona em computador, telemóvel e layouts da direita para a esquerda. Filtros de catálogo, separadores, carrosséis e menus expansíveis são melhorias opcionais sobre conteúdo que funciona sem eles.
22. O que acontece entre a ativação do tema e a publicação?
- Instale e ative o tema. A Eyivo valida o pacote, regista a sua chave e versão e disponibiliza as definições e os esquemas de componentes na aplicação.
- Escolha um tipo de página. Eyivo usa o ficheiro Liquid e a definição de área do tema ativo, quando existirem; caso contrário, usa o fallback correspondente de
theme-core. - Adicione secções permitidas. A aplicação oferece apenas os tipos listados em
allowed_components. Guarda texto, referências multimédia e traduções na instância do componente selecionado. - Renderize com segurança. Eyivo resolve dados de empresa/página/SEO/navegação, renderiza componentes de área salvos, renderiza componentes diretos onde o designer os colocou e, em seguida, renderiza o tipo de página e layout do tema ativo.
- Publique. O visitante recebe HTML e CSS, mas não credenciais da base de dados, modelos internos ou código da aplicação.
- Atualize com uma nova versão. Carregar um ZIP em Temas personalizados cria um novo tema. Para alterar um tema existente, abra-o, aumente
versionnotheme.jsone carregue uma nova versão. Cada site muda quando usa a nova versão como rascunho e a publica; a versão anterior fica disponível para reverter durante 30 dias.
23. Validação e erros comuns
| Se vir… | Verifique isso primeiro |
|---|---|
| “Versão Eyivo Theme API não suportada” | Defina "eyivo_theme_api": "1.0". |
| Erro de tipo/layout/componente de página ausente | Cada tipo de página ou componente declarado pelo tema precisa de seu ficheiro .liquid correspondente. O tema ativo deve sempre fornecer layouts/default.liquid; os tipos de página integrados omitidos voltam ao núcleo. |
| Componente indisponível no editor | O tipo com espaço de nomes deve constar da lista allowed_components dessa área ou ter uma definição universal. |
| Componente direto desconhecido | Use um tipo eyivo: do catálogo partilhado ou declare uma definição theme: e um ficheiro Liquid correspondentes no tema ativo. |
| O campo foi rejeitado | Declare-o no esquema do componente e use um tipo de campo compatível. Use translatable: true para texto específico de localidade. |
| O tema aparece sem estilo | Use o filtro asset_url para CSS e confirme se o ficheiro está em assets/. |
| O pacote foi rejeitado por sintaxe insegura | Remova chamadas PHP/Blade, env, config, DB/HTTP e acesso ao sistema de ficheiros. Liquid é apenas para apresentação. |
Regras de scripts: custom_javascript_declaration, script_file, script_tag, script_import, script_size | Siga Scripts de temas. Os problemas da revisão aparecem na página da versão com o ficheiro e a linha; corrija-os e carregue uma nova versão. |
24. Perguntas frequentes
Um cliente pode criar outro layout ou mover uma secção hero para baixo do rodapé?
Não. O cliente pode alterar conteúdos permitidos e ordenar componentes aprovados dentro de uma área. O tipo de página Liquid define o layout.
Um designer pode usar um componente sem área editável?
Sim. Use eyivo_component em um layout ou tipo de página. Use uma área quando o proprietário do site deve controlar a instância do componente e sua ordem.
Um tema deve implementar todos os tipos de página?
Todo tema deve oferecer suporte ao blog. Os tipos integrados blog, blog_category e blog_post podem usar as definições e os ficheiros Liquid de theme-core dentro do layout do tema ativo. Declare um tipo apenas quando fornecer o ficheiro substituto correspondente. Os pacotes de temas existentes continuam compatíveis. As rotas do blog são /blog, /blog/category/{slug} e /blog/{slug}, com o prefixo do idioma quando necessário. Mantenha eyivo_head para metadados seguros, estilos responsivos e cartões de imagem com altura limitada.
Um tema pode consultar uma página, chamar uma API ou ler uma variável de ambiente?
Não. Os dados são deliberadamente transmitidos como objetos seguros. Isso mantém os temas portáteis, seguros e previsíveis.
Como faço para lançar uma atualização?
Publique uma nova versão do tema com numeração semântica. Não altere uma versão publicada sem mudar seu número; os sites devem migrar explicitamente para a nova versão.
Onde devem ficar as imagens?
Use um URL de multimédia Eyivo nos dados do componente ou um ativo de pacote referenciado por meio de asset_url. Não use caminhos arbitrários do sistema de ficheiros do servidor.
25. Registo de alterações
- 31 de outubro de 2026. Theme API 1.1: os temas podem incluir JavaScript revisto em
assets/js/com a capacidadecustom_javascript. As novas versões são revistas automaticamente e mostram A aguardar revisão, Aprovada, Rejeitada ou Bloqueada. Os pacotes Theme API 1.0 não mudam. - 31 de outubro de 2026. Os proprietários podem adicionar CSS personalizado do site, carregado depois das suas folhas de estilos, e dar nomes de classe às secções, adicionados ao primeiro elemento de cada componente e disponíveis como
{{ component.css_class }}. Veja CSS personalizado do site e classes de secção. - 31 de outubro de 2026. A multimédia de demonstração em
demo.jsontem de usar um anfitriãohttpspermitido (cdn.eyivo.comouimages.pexels.com) ou um ficheiro incluído emassets/. A Eyivo deteta o tipo de cada ficheiro a partir do conteúdo. É uma correção de segurança; a Theme API continua na 1.0. - 30 de outubro de 2026. A Eyivo atribui a cada tema carregado o seu próprio ID, e
keynotheme.jsoné opcional. Carregue alterações como uma nova versão a partir da página do tema. O repositório de exemplo guarda o tema na pastasample-theme/, que comprime e carrega. O exemplo de pacote já não mostraassets/js/, porque os carregamentos com Theme API 1.0 não podem incluir ficheiros JavaScript.