Ir para o conteúdo

Documentação para programadores · Theme API v1.0 · v1.1

Crie um modelo completo de site da empresa com segurança.

Os temas Eyivo definem um sistema visual finalizado: estruturas de página, tipografia, componentes e estilo. O proprietário da empresa preenche o conteúdo aprovado na aplicação, sem mover blocos, editar código ou quebrar o design.

Princípio fundamental

Liquid define como o site aparece; Eyivo Core define qual conteúdo da empresa é exibido.

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 }
      }
    }
  }
}
ChaveSignificadoExemplo
keyEtiqueta 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
versionA versão imutável do lançamento do tema (versionamento semântico).1.2.0
eyivo_theme_apiO 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_componentsQuais componentes o editor pode adicionar a uma área.["eyivo:hero"]
componentsAs definições de componentes theme: personalizados do tema ativo. As definições eyivo: compartilhadas permanecem em theme-core.featured_course
min/maxLimites 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": []
}
ChavePropósito
mediaURLs 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.
companyPerfil da empresa, links sociais, cores da marca, ativo opcional de logotipo/favicon e traduções com chave de localidade.
theme_settingsConfigurações iniciais do tema, com traduções opcionais com chave de localidade.
pagesTipo, ordem de classificação, estado de navegação, SEO, configurações de página, componentes e conteúdo com chave de localidade.
catalogEntradas de catálogo com conteúdo com chave de localidade e um cover_asset opcional.
galleriesMetadados da galeria e itens de imagem. Cada item da galeria precisa de um asset e um alt_text não vazio.
videosUm 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.

ObjetoCampos úteisUso típico
sitename, localeNome do site e idioma principal.
companyname, legal_name, description, address, phone, emailCabeçalho, rodapé e informações de contato.
pageid, type, title, slug, body, settingsConteúdo genérico da página e configurações por página.
seotitle, description e, quando disponíveis, valores de URL canônica, robots e Open GraphSecção head do documento.
navigation.mainCada item tem label, url, activeMenu do site.
localecode, name, native_name, direction, is_default, home_url, availableIdioma do documento, direção RTL, links localizados para a página inicial e seletor de idioma.
routeshome, contact, catalog, gallery, videos, blogURLs do sistema corretas para o idioma atual; nunca monte prefixos em Liquid.
blogtitle, url, categories, category, posts, post, paginationListagem 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.settingsConfigurações definidas no manifestoUse uma opção de cor, espaçamento ou design configurada.
products/productTítulo, URL, resumo e corpo traduzidosPáginas de listagem e detalhes dos produtos.
galleriesTítulo e descrição traduzidosTipo de página da galeria.
videostitle, description, source_type, source_url, playback_url, mediaUse 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.
componentid, type, variant, dataSomente 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} e layout-{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 ID eyivo-custom-css pertencem à 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} em theme.json e coloque cada ficheiro diretamente em assets/js/. Um pacote com ficheiros .js sem a declaração é rejeitado.
  • Carregue-o: use apenas <script src="{{ 'js/theme.js' | asset_url }}" defer></script> (ou type="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 import e export não são permitidos. Partilhe código através de um único global, como window.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…=, URL javascript: 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 sem eval. Alterar um ficheiro exige uma nova versão. Imagens e folhas de estilo ainda podem ser carregadas de https:, 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

CampoTipoObrigatórioTraduzívelOpçõ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

CampoTipoObrigatórioTraduzívelOpções
eyebrow text Não Sim —
heading text Não Sim —
body richtext Não Sim —

Variantes: image_leftimage_rightoverlap

CampoTipoObrigatórioTraduzívelOpçõ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

CampoTipoObrigatórioTraduzívelOpções
eyebrow text Não Sim —
heading text Não Sim —
items repeater Não Sim —

Variantes: nenhuma

CampoTipoObrigatórioTraduzívelOpções
eyebrow text Não Sim —
heading text Não Sim —
intro textarea Não Sim —
items repeater Não Sim —

Variantes: nenhuma

CampoTipoObrigatórioTraduzívelOpções
eyebrow text Não Sim —
heading text Não Sim —
intro textarea Não Sim —
items repeater Não Sim —

Variantes: nenhuma

CampoTipoObrigatórioTraduzívelOpçõ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

CampoTipoObrigatórioTraduzívelOpçõ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

CampoTipoObrigatórioTraduzívelOpções
heading text Não Sim —
text textarea Não Sim —
whatsapp_url url Não Não —

Variantes: nenhuma

CampoTipoObrigatórioTraduzívelOpçõ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

CampoTipoObrigatórioTraduzívelOpções
heading text Não Sim —
items repeater Não Sim —

Variantes: nenhuma

CampoTipoObrigatórioTraduzívelOpções
heading text Não Sim —
placeholder text Não Sim —
categories repeater Não Sim —

Variantes: nenhuma

CampoTipoObrigatórioTraduzívelOpçõ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

CampoTipoObrigatórioTraduzívelOpçõ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

CampoTipoObrigatórioTraduzívelOpçõ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

CampoTipoObrigatórioTraduzívelOpçõ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.

CampoTipoObrigatórioTraduzívelOpções
eyebrow text Não Sim —
heading text Não Sim —
items repeater Não Sim —

Variantes: nenhuma

CampoTipoObrigatórioTraduzívelOpções
eyebrow text Não Sim —
heading text Não Sim —
items repeater Não Sim —

Variantes: nenhuma

CampoTipoObrigatórioTraduzívelOpções
heading text Não Sim —
items repeater Não Sim —

Variantes: nenhuma

CampoTipoObrigatórioTraduzívelOpções
eyebrow text Não Sim —
heading text Não Sim —
items repeater Não Sim —

Variantes: nenhuma

CampoTipoObrigatórioTraduzívelOpções
eyebrow text Não Sim —
heading text Não Sim —
items repeater Não Sim —

Variantes: nenhuma

CampoTipoObrigatórioTraduzívelOpções
eyebrow text Não Sim —
heading text Não Sim —
items repeater Não Sim —

Variantes: nenhuma

CampoTipoObrigatórioTraduzívelOpções
eyebrow text Não Sim —
heading text Não Sim —
items repeater Não Sim —

Variantes: nenhuma

CampoTipoObrigatórioTraduzívelOpções
heading text Não Sim —
items repeater Não Sim —

Variantes: nenhuma

CampoTipoObrigatórioTraduzívelOpções
eyebrow text Não Sim —
heading text Não Sim —
items repeater Não Sim —

Variantes: nenhuma

CampoTipoObrigatórioTraduzívelOpçõ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

CampoTipoObrigatórioTraduzívelOpções
eyebrow text Não Sim —
heading text Não Sim —

Variantes: nenhuma

CampoTipoObrigatórioTraduzívelOpções
heading text Não Sim —
items repeater Não Sim —

Variantes: nenhuma

CampoTipoObrigatórioTraduzívelOpçõ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 sistemaTipo de formulário
eyivo/contactContacto contact
eyivo/quote-requestPedido de orçamento quote_request
eyivo/product-inquiryConsulta de produto product_inquiry
eyivo/appointment-requestPedido de marcação appointment
eyivo/course-applicationCandidatura a curso course_application
eyivo/reservation-requestPedido de reserva reservation
eyivo/property-inquiryConsulta 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}/submissions
GET /__eyivo/forms/{UUID}/challenge

13. Navegação secundária e barras laterais

Registe em theme.json os menus header, secondary, sidebar, footer e useful_links de que precisar. Mostre navigation.secondary numa barra utilitária e navigation.sidebar ao lado das páginas normais. Os proprietários editam e publicam cada menu no editor de menus padrão. Mantenha o menu principal curto; em ecrãs pequenos, a barra lateral deve passar para baixo do conteúdo.

Uma barra lateral é uma área de layout, não um componente. Declare uma área sidebar em cada tipo de página que a use, com os seus allowed_components (por exemplo rich_text, announcement, download_list e contact_actions) e um max, e mostre areas.sidebar dentro de um <aside> ao lado de navigation.sidebar:

{% if navigation.secondary.size > 0 %}
<nav aria-label="{{ 'Useful information' | t }}">
  {% for item in navigation.secondary %}
    <a href="{{ item.url }}"{% if item.active %} aria-current="page"{% endif %}>{{ item.label }}</a>
  {% endfor %}
</nav>
{% endif %}
<aside aria-label="{{ 'More information' | t }}">
  {% for item in navigation.sidebar %}
    <a href="{{ item.url }}">{{ item.label }}</a>
  {% endfor %}
  {{ areas.sidebar | raw }}
</aside>

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?

  1. 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.
  2. 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.
  3. 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.
  4. 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.
  5. Publique. O visitante recebe HTML e CSS, mas não credenciais da base de dados, modelos internos ou código da aplicação.
  6. Atualize com uma nova versão. Carregar um ZIP em Temas personalizados cria um novo tema. Para alterar um tema existente, abra-o, aumente version no theme.json e 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 ausenteCada 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 editorO tipo com espaço de nomes deve constar da lista allowed_components dessa área ou ter uma definição universal.
Componente direto desconhecidoUse um tipo eyivo: do catálogo partilhado ou declare uma definição theme: e um ficheiro Liquid correspondentes no tema ativo.
O campo foi rejeitadoDeclare-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 estiloUse o filtro asset_url para CSS e confirme se o ficheiro está em assets/.
O pacote foi rejeitado por sintaxe inseguraRemova 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_sizeSiga 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 capacidade custom_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.json tem de usar um anfitrião https permitido (cdn.eyivo.com ou images.pexels.com) ou um ficheiro incluído em assets/. 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 key no theme.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 pasta sample-theme/, que comprime e carrega. O exemplo de pacote já não mostra assets/js/, porque os carregamentos com Theme API 1.0 não podem incluir ficheiros JavaScript.