1. Il modello mentale
Ci sono tre responsabilità distinte. Tenerle separate è fondamentale per comprendere la versione v1.
Eyivo Core
Conserva dati aziendali, pagine, media, SEO, navigazione e stato di pubblicazione. È la fonte autorevole dei contenuti.
Pacchetto del tema
Definisce forme di pagina fisse, sezioni consentite, schemi di componenti personalizzati e CSS. Non interroga mai i dati né esegue il codice dell'applicazione.
Editor dell'app
Genera moduli sicuri dallo schema. I proprietari possono aggiornare testo, immagini, pagine e ordine delle sezioni all'interno di un'area.
Non è un page builder: il proprietario può aggiungere una sezione consentita a main e sceglierne la posizione numerica. Non può creare una nuova area, spostare un hero nel footer né modificare i file del tuo tema. Può aggiungere il proprio CSS del sito, caricato dopo i tuoi fogli di stile, e assegnare nomi di classe alle sezioni (vedi CSS personalizzato del sito).
2. Guida rapida: un tema minimo e funzionante
Ogni tema v1 controlla l’intero layout, gli stili e gli script e può organizzarli secondo il design scelto dall’autore. Un tema non eredita layout o risorse da altri temi. I componenti condivisi eyivo: e i sette tipi di pagina predefiniti provengono da theme-core; il tema include solo i tipi di pagina che sostituisce e i componenti che dichiara nello spazio dei nomi theme:.
Ogni tema v1 necessita di un file di layout predefinito. Sia page-types/ che components/ sono opzionali quando il pacchetto utilizza solo fallback 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 proviene sempre dal tema attivo e possiede il documento pubblico completo. Eyivo cerca prima il tipo di pagina richiesto in quel tema, quindi torna a theme-core/page-types. Core non fornisce mai un layout o risorse, quindi il contenuto della pagina di fallback è ancora racchiuso e stilizzato dal tema attivo.
3. Descrivere il modello in theme.json
Il manifest è sia una dichiarazione di capacità che il contratto utilizzato per generare moduli dell'app. Risponde a tre domande: quali strutture di pagina esistono, quali aree ha ciascuna struttura e cosa un componente può memorizzare. I temi integrati dichiarano esplicitamente tutti i dieci tipi di pagina standard e includono i relativi file Liquid. I temi personalizzati possono continuare a usare i modelli di fallback del core per i tipi non dichiarati.
{
"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 }
}
}
}
}
| Chiave | Significato | Esempio |
|---|---|---|
key | Etichetta facoltativa per tuo riferimento. Eyivo assegna a ogni tema caricato un proprio ID, quindi la chiave non decide mai a quale tema appartiene un caricamento. | acme-industrial |
version | La versione immutabile della release del tema (versionamento semantico). | 1.2.0 |
eyivo_theme_api | Il contratto API pubblico Eyivo supportato dal tuo pacchetto. | 1.0 |
areas | Slot denominati di cui il file di pagina Liquid esegue il rendering in posizioni fisse. | hero, main, bottom |
allowed_components | Quali componenti l'editor può aggiungere a un'area. | ["eyivo:hero"] |
components | Le definizioni dei componenti theme: personalizzati del tema attivo. Le definizioni eyivo: condivise rimangono in theme-core. | featured_course |
min/max | Limiti facoltativi al numero di sezioni in quell'area. | max: 1 |
Fallback dei tipi di pagina: i tipi integrati sono home, page, gallery, contact, products, product e videos. Ometti un tipo per usare la definizione e il file Liquid di theme-core. Dichiaralo solo se il tema fornisce anche il file sostitutivo page-types/<type>.liquid.
L’editor riceve l’API combinata dei tipi di pagina: le definizioni del tema attivo sostituiscono quelle corrispondenti di core, mentre i tipi omessi restano disponibili da core.
4. Completa il contenuto demo in demo.json
Ogni caricamento deve includere un file demo.json portabile, usato solo come bozza, e almeno uno screenshot acquisito con quei dati demo. I temi integrati usano lo stesso schema. Non includere ID del database, domini dei clienti, credenziali o chiavi dello storage a oggetti.
{
"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": []
}
| Chiave | Scopo |
|---|---|
media | URL pubblici di origine e metadati indicizzati tramite identificatori portabili delle risorse. Riutilizza l’identificatore per hero_asset, cover_asset, media_asset, asset degli elementi della galleria, logo_asset e favicon_asset. |
company | Profilo aziendale, collegamenti social, colori del marchio, risorse logo/favicon opzionali e traduzioni con chiave locale. |
theme_settings | Impostazioni iniziali del tema, con traduzioni opzionali con chiave locale. |
pages | Tipo, ordinamento, stato di navigazione, SEO, impostazioni della pagina, componenti e contenuto con chiave locale. |
catalog | Voci di catalogo con contenuto con chiave locale e cover_asset opzionale. |
galleries | Metadati della galleria e immagini. Ogni elemento richiede un asset e un alt_text non vuoto. |
videos | Uno source_url esterno o uno media_asset, modalità di presentazione e contenuto con chiave locale. |
Ogni voce di media richiede una public_url in https su un host consentito (l’host dei media demo di Eyivo cdn.eyivo.com o images.pexels.com), oppure un file incluso nel tema sotto assets/, indicato dal suo percorso e senza public_url. Altri host, http, indirizzi IP, altre porte e reindirizzamenti vengono rifiutati con la diagnostica di caricamento demo_media_url. mime_type, width e height sono solo indicazioni: Eyivo rileva il tipo reale dal contenuto scaricato, che deve essere un’immagine o un video consentiti di al massimo 20 MB.
I moduli demo usano collegamenti di modulo portabili, che Eyivo risolve separatamente per ogni sito che importa la demo. Le immagini demo importate diventano normali riferimenti multimediali su quel sito; rimuoverle lì non rimuove mai l’originale condiviso.
Pagine e componenti
{
"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" }
}
}]
}
I tipi e le aree dei componenti devono essere dichiarati nel manifest del tema attivo o in theme-core. Utilizza percorsi relativi come /contact per i collegamenti allo stesso sito. Le demo della home incluse usano la loro immagine hero esistente come sfondo a tutta larghezza, con una sovrapposizione leggibile e testo adattivo: immersive nella maggior parte dei temi e centered con immagine in Compact. Le altre varianti mantengono i propri layout.
Lingue demo e lingua di riserva
L’inglese è la lingua di base obbligatoria: imposta default_locale su en. Se manca nei dati precedenti, si intende comunque inglese. Le altre lingue supportate sono facoltative; non presentare copie inglesi come traduzioni.
Fornisci translations.en e oggetti lingua facoltativi per azienda, impostazioni, pagine, componenti, prodotti, gallerie, didascalie e testi alternativi, video e articoli. I vecchi campi inglesi senza chiave lingua restano validi. La creazione sceglie la lingua principale del sito e usa l’inglese per ogni campo mancante. Gli array sostituiscono l’intero array inglese; i valori esplicitamente vuoti vengono conservati. Si importa solo la lingua scelta, senza attivarne altre automaticamente.
Usa gli slug sorgente inglesi nei link interni e nei menu portabili. L’importazione li converte negli slug tradotti, anche nel testo formattato e negli articoli. I menu possono indicare mappe esplicite slugs e labels. Le etichette mancanti usano l’inglese. Gli URL esterni restano invariati.
{
"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" }
}]
}
}
Importazione e sicurezza dei media
I nuovi siti dalla dashboard includono i dati demo per impostazione predefinita e pubblicano subito la lingua scelta; il proprietario può deselezionare l’opzione. Su un sito esistente, il caricamento da Branding crea ancora bozze e conserva i contenuti pubblicati. L’App centrale copia le immagini nella libreria del nuovo sito e invia riferimenti tramite l’API interna. Master e temi non ricevono credenziali per lo storage di oggetti. I temi usano il valore media.public_url fornito.
Dichiara gli screenshot in theme.json.preview con data_source: "demo_data". Il pacchetto deve contenere ogni immagine preview dichiarata.
5. Scrivi qualsiasi layout di cui il tuo tema ha bisogno
Il layout predefinito possiede l’intero documento HTML. Nulla al di fuori del tema attivo fornisce intestazione, piè di pagina, foglio di stile o struttura visiva. La piattaforma aggiunge solo i propri script per moduli, verifica umana, consenso e badge Eyivo; gli script dei temi richiedono 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>
Un file di tipo pagina decide quindi esattamente dove appaiono le sue aree dinamiche. I componenti dell'area sono già stringhe HTML sottoposte a rendering, quindi inseriscili con | raw. Per impostazione predefinita, i valori ordinari vengono sottoposti a escape.
<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>
Eseguire il rendering di un componente direttamente
Un progettista può inserire un componente registrato direttamente in un file di layout o di tipo pagina. Questo posizionamento è fissato dal tema e non viene riordinato o rimosso nel pannello. Passa un oggetto attraverso data:, singoli campi dello schema o entrambi; i campi denominati sovrascrivono le chiavi corrispondenti da 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"
%}
Il tipo deve essere un valore letterale con spazio dei nomi tra virgolette. Il rendering diretto utilizza lo stesso schema, varianti, file di componenti e oggetto component normalizzato come istanza di area. I file dei componenti non possono eseguire il rendering di altri componenti.
Asset: utilizza sempre {{ 'css/theme.css' | asset_url }}. Eyivo lo serve dal pacchetto attivo come /theme-assets/<theme>/css/theme.css; non codificare un altro nome di tema o percorso di filesystem.
Head, percorsi e dizionari dell’interfaccia
Ogni layout deve eseguire il rendering di {% eyivo_head %} esattamente una volta. Eyivo possiede quindi il titolo, la descrizione, i robot, il canonical, l'hreflang, l'Open Graph e l'output dei dati strutturati. Utilizza routes.home, routes.contact, routes.catalog, routes.gallery e routes.videos invece dei percorsi pubblici codificati. Passa le impostazioni URL modificabili tramite | localized_url in modo che i percorsi interni noti ottengano il prefisso locale attivo mentre gli URL esterni rimangano invariati.
{{ 'Menu' | t }}
{{ theme.settings.header_cta_url | localized_url }}
Puoi creare file locales/<locale>.json per le etichette dell’interfaccia introdotte dal tema. L’ordine di ricerca è: inglese di core, lingua corrente di core, inglese del tema e lingua corrente del tema. Le etichette condivise di theme-core funzionano senza copiare file. Il testo dell’azienda va nei contenuti traducibili, nei campi dei componenti o nelle impostazioni del tema, non nei dizionari.
Un file del componente personalizzato
<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>
Per i campi traducibili, Eyivo seleziona la lingua del visitatore prima del rendering. Un visitatore turco e un visitatore inglese vedono quindi la stessa struttura dei componenti con valori component.data.heading diversi.
7. I dati Liquid sicuri che puoi utilizzare
Liquid riceve dati semplici e normalizzati, non Laravel o modelli di database. Se un valore non è presente in questa tabella, consideralo non disponibile nella versione v1.
| Oggetto | Campi utili | Utilizzo tipico |
|---|---|---|
site | name, locale | Nome del sito e lingua principale. |
company | name, legal_name, description, address, phone, email | Intestazione, piè di pagina e informazioni di contatto. |
page | id, type, title, slug, body, settings | Contenuti generici della pagina e impostazioni per pagina. |
seo | title, description e, se disponibili, valori canonical, robots e Open Graph | Sezione head del documento. |
navigation.main | Ogni voce contiene label, url e active | Menù del sito. |
locale | code, name, native_name, direction, is_default, home_url, available | Lingua del documento, direzione RTL, collegamenti alla home localizzati e selettore della lingua. |
routes | home, contact, catalog, gallery, videos, blog | URL di sistema corretti per la lingua corrente; non costruire prefissi in Liquid. |
blog | title, url, categories, category, posts, post, pagination | Elenco del blog gratuito, archivio delle categorie e pagine degli articoli. I post espongono titolo, riepilogo, URL, date, categorie e immagine di copertina. Solo blog.post.body_html contiene HTML sicuro degli articoli generato dal server e richiede raw. La paginazione fornisce previous_url e next_url. |
theme.settings | Impostazioni definite nel manifest | Utilizza un'opzione di colore, spaziatura o design configurata. |
products/product | Titolo, URL, riepilogo e corpo tradotti | Pagine elenco e dettaglio dei prodotti. |
galleries | Titolo e descrizione tradotti | Tipo di pagina della galleria. |
videos | title, description, source_type, source_url, playback_url, media | Usa playback_url per i file video caricati e source_url per i video HTTP(S) esterni, secondo source_type. Le immagini allegate non sono mai sorgenti video. Non usare il file video stesso come immagine di anteprima. |
component | id, type, variant, data | Solo all'interno di un file componente. |
Esempio di layout corretto per ogni lingua
<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 %}
Ciascun elemento della lingua disponibile espone anche label, direction, is_default, current e has_translation. Eyivo fornisce solo traduzioni pubblicate equivalenti, quindi i temi devono utilizzare language.url invece di costruire /en o qualsiasi altro prefisso.
Esempio di token basato sulle impostazioni: style="--brand: {{ theme.settings.primary_color }}". L'impostazione deve essere prima dichiarata in theme.json.
8. Componenti diretti e dinamici
I componenti condividono un unico contratto di rendering e hanno due modalità di posizionamento. Un componente diretto è fissato dal designer nel layout o nel tipo di pagina. Un componente dinamico è salvato come istanza di un’area della pagina e gestito nell’editor. Le istanze dinamiche hanno un ID stabile, tipo con spazio dei nomi, area, posizione, variante facoltativa, dati e traduzioni. La posizione determina solo l’ordine, non l’identità.
Tipi di campo
text, textarea, richtext, number, boolean, select, url, email, image, video, file, color, icon, page, product e repeater.
Spazi dei nomi
eyivo: si risolve da theme-core/components, theme: si risolve dal tema attivo e plugin: è riservato per plugin futuri. Utilizza il tipo esatto dello spazio dei nomi in un'area o in un tag eyivo_component.
Componente universale: imposta "universal": true su una definizione del componente per consentirlo in tutte le aree dei tipi di pagina compatibili. Deve comunque avere uno schema valido e un file Liquid.
I collegamenti di azione condivisi adattano i percorsi interni noti alla lingua attiva, mantenendo i parametri di query e i frammenti. Il testo formattato conserva la formattazione sicura nei contenitori annidati dell’editor. Le immagini vuote della galleria vengono omesse, le immagini della mappa senza destinazione non sono collegamenti e le etichette delle diapositive e della ricerca usano la lingua dell’interfaccia del visitatore.
9. CSS personalizzato del sito e classi di sezione
I proprietari possono aggiungere il proprio CSS a un sito e assegnare nomi di classe alle sezioni (Design → CSS personalizzato). Scrivi i temi in modo che funzioni bene:
- Ordine di caricamento: il CSS del sito viene aggiunto come
<style id="eyivo-custom-css">subito prima di</head>, dopo tutti i fogli di stile del tema. Mantieni</head>nei layout e non contare sul fatto che il tuo CSS sia l’ultimo. - Classi di sezione: il renderer aggiunge i nomi di classe di una sezione al primo elemento dell’output del componente, quindi dai a ogni template di componente un unico elemento radice. I nomi sono disponibili anche come
{{ component.css_class }}se vuoi inserirli altrove. - Riferimenti stabili: mantieni le classi
body.theme-{key}elayout-{name}e una classe radice stabile per componente, così il CSS dei proprietari continua a funzionare tra le versioni. Indica ogni rinomina nelle note di rilascio. - Temi caricati: supportano anch’essi il CSS personalizzato del sito. Tutte le versioni di un tema caricato condividono un foglio di stile per sito, che viene eliminato quando l’ultima versione del tema su un sito viene ritirata o eliminata.
- Nomi riservati: il prefisso di classe
eyivo-e l’IDeyivo-custom-cssappartengono alla piattaforma.
10. Script dei temi (Theme API 1.1)
Un tema può includere il proprio JavaScript per menu, slider, schede, filtri e funzioni simili. Gli script sono facoltativi: ogni tema deve funzionare anche senza, e i pacchetti Theme API 1.0 continuano a funzionare invariati, senza script.
- Dichiaralo: imposta
"eyivo_theme_api": "1.1"e"capabilities": {"custom_javascript": true}intheme.jsone metti ogni file direttamente inassets/js/. Un pacchetto con file.jssenza dichiarazione viene rifiutato. - Caricalo: usa solo
<script src="{{ 'js/theme.js' | asset_url }}" defer></script>(otype="module") per un file del pacchetto. I tag vengono eseguiti nell’ordine in cui compaiono. - Più file: ogni file viene revisionato e autorizzato singolarmente, quindi
importedexportnon sono consentiti. Condividi il codice tramite un’unica variabile globale, comewindow.AcmeTheme, e carica per primo il file che la definisce. - Limiti: al massimo 20 file, 100 KB per file e 300 KB in totale, solo testo UTF-8.
- Rifiutati nei template: script inline, sorgenti di script esterne, attributi di gestione eventi
on…=, URLjavascript:ed elementi<iframe>,<object>,<embed>e<base>. - Solo codice leggibile: carica il sorgente, non codice minificato, compresso o codificato. I bundler possono generare output non minificato.
- Stati: una nuova versione è In attesa di revisione finché i controlli non terminano, poi diventa Approvata o Rifiutata. Solo una versione approvata può essere visualizzata in anteprima o usata. Una versione approvata può essere in seguito Bloccata: i siti mantengono il tema senza i suoi script.
- Tre controlli automatici, in ordine: codice leggibile; regole del codice (niente
eval,new Function,document.write, reindirizzamenti di pagina,window.open, cookie o archiviazione del browser, WebAssembly, timer con stringhe, elementi script o frame creati, né valori dei moduli inviati in rete); e una revisione di sicurezza con IA. Per questa revisione, gli script e le righe di template che li caricano vengono inviati a un servizio di IA. Qualsiasi problema rifiuta la versione, con file e riga.
Approvato: un pulsante del menu
(function () {
document.querySelectorAll('[data-menu-toggle]').forEach(function (button) {
button.addEventListener('click', function () {
document.body.classList.toggle('menu-open');
});
});
})();
Rifiutato: invia altrove i valori del modulo
form.addEventListener('submit', function () {
fetch('/collect', { method: 'POST', body: form.elements.email.value });
});
- Solo il proprietario: gli script approvati vengono eseguiti solo sui siti dell’account che ha caricato il tema, e solo finché la piattaforma e il proprietario del sito li consentono.
- Criteri di sicurezza: le pagine che eseguono script dei temi consentono esattamente i file revisionati, fissati dai loro hash SHA-256, con
connect-src 'self', senza frame o worker e senzaeval. Modificare un file richiede una nuova versione. Immagini e fogli di stile possono ancora essere caricati dahttps:, perciò la revisione rifiuta anche i dati inviati tramite URL di immagini o fogli di stile. - Dopo l’approvazione: i browser segnalano i tentativi di violare i criteri. Le segnalazioni di tre visitatori entro 24 ore bloccano la versione; le segnalazioni di abuso di tre visitatori entro 7 giorni disattivano gli script su quel sito e ricontrollano la versione. I proprietari ricevono un’email quando una versione viene approvata, rifiutata o bloccata.
- Funzioni della piattaforma: gli script non devono sostituire, racchiudere o nascondere i moduli e i loro campi nascosti, la verifica umana, il banner del consenso, il badge Eyivo o la barra del proprietario.
11. Catalogo dei componenti disponibili
Questi 30 componenti condivisi eyivo: costituiscono l’intera libreria v1 e provengono da theme-core. Un tema può inoltre dichiarare e implementare i propri componenti theme:.
Varianti: spliteditorialcenteredimmersive
| Campo | Tipo | Necessario | Traducibile | Opzioni |
|---|---|---|---|---|
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 | — |
Varianti: nessuna
| Campo | Tipo | Necessario | Traducibile | Opzioni |
|---|---|---|---|---|
eyebrow |
text |
No | Sì | — |
heading |
text |
No | Sì | — |
body |
richtext |
No | Sì | — |
Varianti: image_leftimage_rightoverlap
| Campo | Tipo | Necessario | Traducibile | Opzioni |
|---|---|---|---|---|
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 | — |
Varianti: nessuna
| Campo | Tipo | Necessario | Traducibile | Opzioni |
|---|---|---|---|---|
eyebrow |
text |
No | Sì | — |
heading |
text |
No | Sì | — |
items |
repeater |
No | Sì | — |
Varianti: nessuna
| Campo | Tipo | Necessario | Traducibile | Opzioni |
|---|---|---|---|---|
eyebrow |
text |
No | Sì | — |
heading |
text |
No | Sì | — |
intro |
textarea |
No | Sì | — |
items |
repeater |
No | Sì | — |
Varianti: nessuna
| Campo | Tipo | Necessario | Traducibile | Opzioni |
|---|---|---|---|---|
eyebrow |
text |
No | Sì | — |
heading |
text |
No | Sì | — |
intro |
textarea |
No | Sì | — |
items |
repeater |
No | Sì | — |
Varianti: nessuna
| Campo | Tipo | Necessario | Traducibile | Opzioni |
|---|---|---|---|---|
eyebrow |
text |
No | Sì | — |
heading |
text |
No | Sì | — |
intro |
textarea |
No | Sì | — |
button_label |
text |
No | Sì | — |
button_url |
url |
No | No | — |
Varianti: nessuna
| Campo | Tipo | Necessario | Traducibile | Opzioni |
|---|---|---|---|---|
eyebrow |
text |
No | Sì | — |
heading |
text |
No | Sì | — |
items |
repeater |
No | Sì | — |
Varianti: nessuna
| Campo | Tipo | Necessario | Traducibile | Opzioni |
|---|---|---|---|---|
eyebrow |
text |
No | Sì | — |
heading |
text |
No | Sì | — |
text |
textarea |
No | Sì | — |
submit_label |
text |
No | Sì | — |
form_binding |
select |
No | No | — |
Varianti: nessuna
| Campo | Tipo | Necessario | Traducibile | Opzioni |
|---|---|---|---|---|
heading |
text |
No | Sì | — |
text |
textarea |
No | Sì | — |
whatsapp_url |
url |
No | No | — |
Varianti: nessuna
| Campo | Tipo | Necessario | Traducibile | Opzioni |
|---|---|---|---|---|
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ì | — |
Varianti: nessuna
| Campo | Tipo | Necessario | Traducibile | Opzioni |
|---|---|---|---|---|
heading |
text |
No | Sì | — |
items |
repeater |
No | Sì | — |
Varianti: nessuna
| Campo | Tipo | Necessario | Traducibile | Opzioni |
|---|---|---|---|---|
heading |
text |
No | Sì | — |
placeholder |
text |
No | Sì | — |
categories |
repeater |
No | Sì | — |
Varianti: nessuna
| Campo | Tipo | Necessario | Traducibile | Opzioni |
|---|---|---|---|---|
eyebrow |
text |
No | Sì | — |
heading |
text |
No | Sì | — |
summary |
textarea |
No | Sì | — |
video_url |
url |
No | No | — |
poster_url |
url |
No | No | — |
Varianti: nessuna
| Campo | Tipo | Necessario | Traducibile | Opzioni |
|---|---|---|---|---|
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 | — |
Varianti: nessuna
| Campo | Tipo | Necessario | Traducibile | Opzioni |
|---|---|---|---|---|
label |
text |
No | Sì | — |
heading |
text |
No | Sì | — |
body |
textarea |
No | Sì | — |
button_label |
text |
No | Sì | — |
button_url |
url |
No | No | — |
Varianti: nessuna
| Campo | Tipo | Necessario | Traducibile | Opzioni |
|---|---|---|---|---|
eyebrow |
text |
No | Sì | — |
heading |
text |
No | Sì | — |
items |
repeater |
No | Sì | — |
Varianti: nessuna
Il componente condiviso eyivo:faq mantiene gli stessi campi e lo stesso markup in ogni tema. Ogni tema lo presenta con il proprio carattere, la propria spaziatura e il proprio colore.
| Campo | Tipo | Necessario | Traducibile | Opzioni |
|---|---|---|---|---|
eyebrow |
text |
No | Sì | — |
heading |
text |
No | Sì | — |
items |
repeater |
No | Sì | — |
Varianti: nessuna
| Campo | Tipo | Necessario | Traducibile | Opzioni |
|---|---|---|---|---|
eyebrow |
text |
No | Sì | — |
heading |
text |
No | Sì | — |
items |
repeater |
No | Sì | — |
Varianti: nessuna
| Campo | Tipo | Necessario | Traducibile | Opzioni |
|---|---|---|---|---|
heading |
text |
No | Sì | — |
items |
repeater |
No | Sì | — |
Varianti: nessuna
| Campo | Tipo | Necessario | Traducibile | Opzioni |
|---|---|---|---|---|
eyebrow |
text |
No | Sì | — |
heading |
text |
No | Sì | — |
items |
repeater |
No | Sì | — |
Varianti: nessuna
| Campo | Tipo | Necessario | Traducibile | Opzioni |
|---|---|---|---|---|
eyebrow |
text |
No | Sì | — |
heading |
text |
No | Sì | — |
items |
repeater |
No | Sì | — |
Varianti: nessuna
| Campo | Tipo | Necessario | Traducibile | Opzioni |
|---|---|---|---|---|
eyebrow |
text |
No | Sì | — |
heading |
text |
No | Sì | — |
items |
repeater |
No | Sì | — |
Varianti: nessuna
| Campo | Tipo | Necessario | Traducibile | Opzioni |
|---|---|---|---|---|
eyebrow |
text |
No | Sì | — |
heading |
text |
No | Sì | — |
items |
repeater |
No | Sì | — |
Varianti: nessuna
| Campo | Tipo | Necessario | Traducibile | Opzioni |
|---|---|---|---|---|
heading |
text |
No | Sì | — |
items |
repeater |
No | Sì | — |
Varianti: nessuna
| Campo | Tipo | Necessario | Traducibile | Opzioni |
|---|---|---|---|---|
eyebrow |
text |
No | Sì | — |
heading |
text |
No | Sì | — |
items |
repeater |
No | Sì | — |
Varianti: nessuna
| Campo | Tipo | Necessario | Traducibile | Opzioni |
|---|---|---|---|---|
eyebrow |
text |
No | Sì | — |
heading |
text |
No | Sì | — |
text |
textarea |
No | Sì | — |
button_label |
text |
No | Sì | — |
button_url |
url |
No | No | — |
Varianti: nessuna
| Campo | Tipo | Necessario | Traducibile | Opzioni |
|---|---|---|---|---|
eyebrow |
text |
No | Sì | — |
heading |
text |
No | Sì | — |
Varianti: nessuna
| Campo | Tipo | Necessario | Traducibile | Opzioni |
|---|---|---|---|---|
heading |
text |
No | Sì | — |
items |
repeater |
No | Sì | — |
Varianti: nessuna
| Campo | Tipo | Necessario | Traducibile | Opzioni |
|---|---|---|---|---|
eyebrow |
text |
No | Sì | — |
heading |
text |
No | Sì | — |
intro |
textarea |
No | Sì | — |
items |
repeater |
No | Sì | — |
12. Moduli e storico delle richieste
Forms API 1 offre sette processori approvati. I temi gestiscono layout e stile; i plugin definiscono schema, validazione e flusso. La piattaforma gestisce persistenza, verifica e notifiche.
| Plugin di sistema | Tipo di modulo |
|---|---|
eyivo/contact | Contatto contact |
eyivo/quote-request | Richiesta di preventivo quote_request |
eyivo/product-inquiry | Informazioni prodotto product_inquiry |
eyivo/appointment-request | Richiesta di appuntamento appointment |
eyivo/course-application | Domanda per un corso course_application |
eyivo/reservation-request | Richiesta di prenotazione reservation |
eyivo/property-inquiry | Informazioni immobiliari property_inquiry |
Un modulo, più posizioni
La configurazione crea un UUID predefinito stabile per sito/plugin/tipo. Riutilizzare una posizione conserva l’identità; creare un modulo con nome genera un altro UUID. Cambi di tema e reinstallazione conservano lo storico. I temi usano alias portabili; l’editor seleziona i moduli salvati senza inserire UUID.
{
"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 nei contatti e component.form nelle sezioni modulo. Sostituisci form_preset con form_binding. Renderizza campi, aiuti, action, CSRF, form_context firmato e verification_html forniti. Sono ammesse solo modifiche di presentazione dichiarate e campi aggiuntivi consentiti; la validazione obbligatoria resta attiva.
forms.contact · component.form · form_binding · form.fields · form.action · form.csrf_token · form.context · form.verification_html
Due viste, un record
La casella condivisa e le pagine elenco/dettaglio del plugin mostrano gli stessi record. I moduli richiedono Panel API 2, submission-list/submission-detail e un collegamento di menu senza sottolivelli. Panel API 1 resta supportata. Aprire non segna come letto; lettura, archivio e flusso sono separati e le modifiche usano record_revision. Disabilitare rimuove le pagine del plugin; la casella condivisa conserva gli snapshot storici.
{"components":[{"type":"submission-list","form_type":"contact","detail_page":"submission"}]}
{"components":[{"type":"submission-detail","form_type":"contact","list_page":"submissions"}]}
Dati e autorizzazioni
I record usano il database dei contenuti del sito e il limite max_db_bytes del pacchetto. Nessuna quota separata per numero o conservazione. La configurazione resta sul master con 50 campi, 32 KB e tre livelli. I membri visualizzano; modificare richiede proprietario/gestione. Nessun accesso diretto al database dei plugin o trasferimento di PHP/Blade all’app.
Salvataggio verificato e notifica
La piattaforma convalida contesto, risposte e Human Verification, poi salva record, utilizzo e notifica insieme. Lo stesso tentativo si recupera per 24 ore senza duplicati. SMTP interviene dopo con possibili tentativi successivi; un errore email non elimina il record. Senza destinatario del modulo si usa l’email aziendale; se nessun indirizzo è valido, il record viene salvato senza email.
Tutti i temi inclusi usano questo contratto. I vecchi POST contact restituiscono 410; le pagine GET dei contatti funzionano. Le richieste di appuntamento o prenotazione non confermano prenotazioni. Processori di terzi, caricamenti e destinazioni esterne arbitrarie sono esclusi.
POST /__eyivo/forms/{UUID}/submissionsGET /__eyivo/forms/{UUID}/challenge
15. Template di pagina e template di base di riserva
Esistono dieci tipi di pagina standard: home, page, contact, products, product, gallery, videos, blog, blog_category e blog_post. Un tema può fornirli tutti o solo alcuni; theme-core fornisce un template funzionante per ogni tipo che il tema non dichiara. Mantieni i nomi delle aree e i collegamenti dei moduli dei tipi di base quando li sostituisci, così contenuti esistenti e moduli registrati continuano a funzionare dopo un cambio di tema.
16. Intestazioni di pagina
Le intestazioni delle sottopagine hanno due forme. Senza immagine, usa una fascia compatta con breadcrumb, un occhiello facoltativo e il titolo della pagina. Con un’immagine, posiziona titolo, breadcrumb e riepilogo sopra l’immagine e un livello di contrasto, così il testo resta leggibile su qualsiasi foto, e rispecchia la direzione del livello nei layout da destra a sinistra.
17. Immagini, gallerie e video
Mantieni le immagini caricate in cornici delimitate: le immagini del catalogo conservano le proporzioni e le foto di dettaglio possono riempire la cornice con un ritaglio centrato. Le gallerie possono aprire l’immagine originale in una finestra di dialogo che si chiude con Esc e riporta il focus al link dell’immagine; senza script, collega l’originale perché si apra in una nuova scheda. Gli slider di immagini devono supportare tocco, pulsanti, tastiera e movimento ridotto.
18. Testo formattato e regole di visualizzazione comuni
Il componente comune eyivo:rich_text accetta contenuti marcati dall’editor e contenuti HTML meno recenti. Entrambi passano dall’elenco di formattazione consentita della piattaforma: paragrafi, titoli, elenchi e link sicuri appaiono come contenuto, mentre script, gestori di eventi e link non sicuri vengono rimossi. Gli altri campi di testo restano con escape. Mostra il testo formattato con i filtri forniti, non con una tua gestione dell’HTML.
19. Introduzioni, aree di orientamento e pagine lunghe
Un tipo di pagina può affiancare all’intestazione un’area di orientamento facoltativa per link rapidi o informazioni chiave; se l’area è vuota, l’introduzione deve usare tutta la larghezza. Le pagine editoriali lunghe devono mantenere una lunghezza di riga leggibile e spaziature chiare tra i titoli, e possono collocare sezioni di supporto, come una checklist o una nota, accanto all’articolo sugli schermi ampi e dopo di esso su quelli piccoli. Ogni layout deve restare leggibile senza script.
20. Movimento e movimento ridotto
Il movimento decorativo è facoltativo. Rispetta prefers-reduced-motion per transizioni, slider e sezioni animate, e metti in pausa i contenuti in movimento mentre il visitatore ci passa sopra con il mouse o vi sposta il focus.
21. Checklist di un tema completo
Un tema completo fornisce tutti e dieci i template di pagina, dà stile a tutti i componenti comuni eyivo:, supporta ogni collegamento di modulo portabile tramite i plugin di modulo esistenti e la verifica umana, e funziona su desktop, mobile e layout da destra a sinistra. Filtri del catalogo, schede, slider e menu espandibili sono miglioramenti facoltativi su contenuti che funzionano anche senza.
22. Cosa succede dall'attivazione del modello alla pubblicazione?
- Installa/attiva il modello. Eyivo convalida il pacchetto, registra la sua chiave/versione ed espone le sue impostazioni e gli schemi dei componenti nell'app.
- Scegli un tipo di pagina. Eyivo utilizza il file Liquid corrispondente e la definizione dell'area del tema attivo quando presente, altrimenti il fallback
theme-corecorrispondente. - Aggiungi sezioni consentite. L'App offre solo le tipologie elencate in
allowed_components. Memorizza testo, riferimenti multimediali e traduzioni rispetto all'istanza del componente selezionato. - Rendering sicuro. Eyivo prepara i dati di azienda, pagina, SEO e navigazione; genera i componenti salvati nelle aree e quelli diretti nelle posizioni fissate dal designer; infine genera il tipo di pagina e il layout del tema attivo.
- Pubblica. Il visitatore riceve HTML e CSS, ma non credenziali del database, modelli interni o codice dell’applicazione.
- Aggiorna con una nuova versione. Caricare uno ZIP in Temi personalizzati crea un nuovo tema. Per modificare un tema esistente, aprilo, aumenta
versionintheme.jsone carica una nuova versione. Ogni sito passa alla nuova versione quando la usi come bozza e la pubblichi; la versione precedente resta disponibile per il ripristino per 30 giorni.
23. Validazione ed errori comuni
| Se vedi... | Controlla prima questo |
|---|---|
| “Versione Eyivo Theme API non supportata” | Imposta "eyivo_theme_api": "1.0". |
| Errore di tipo/layout/componente di pagina mancante | Ogni tipo di pagina o componente dichiarato dal tema necessita del file .liquid corrispondente. Il tema attivo deve sempre fornire layouts/default.liquid; i tipi di pagina incorporati omessi ricadono nel core. |
| Componente non disponibile nell'editor | Il suo tipo con spazio dei nomi deve trovarsi nell'elenco allowed_components di quell'area oppure la definizione deve essere universale. |
| Componente diretto sconosciuto | Usa un tipo eyivo: tra virgolette del catalogo condiviso oppure dichiara nel tema attivo una definizione theme: e il file Liquid corrispondente. |
| Il campo è rifiutato | Dichiararlo nello schema del componente e utilizzare un tipo di campo supportato. Utilizzare translatable: true per il testo specifico della locale. |
| Il modello appare senza stile | Utilizza il filtro asset_url per CSS e conferma che il file si trova in assets/. |
| Il pacchetto è stato rifiutato per sintassi non sicura | Rimuovi le chiamate PHP/Blade, env, config, DB/HTTP e l'accesso al filesystem. Liquid è di sola presentazione. |
Regole degli script: custom_javascript_declaration, script_file, script_tag, script_import, script_size | Segui Script dei temi. I problemi della revisione compaiono nella pagina della versione con file e riga; correggili e carica una nuova versione. |
24. Domande frequenti
Un cliente può creare un nuovo layout o spostare una sezione hero sotto il piè di pagina?
No. Possono modificare i contenuti approvati e ordinare componenti approvati all'interno di un'area. Il tipo di pagina Liquid possiede il layout.
Un progettista può utilizzare un componente senza un'area modificabile?
Sì. Usa eyivo_component nel layout o nel tipo di pagina. Usa un’area quando il titolare del sito deve controllare l’istanza del componente e il suo ordine.
Un tema deve implementare ogni tipo di pagina?
Ogni tema deve supportare il blog. I tipi integrati blog, blog_category e blog_post possono usare le definizioni e i file Liquid di theme-core nel layout del tema attivo. Dichiara un tipo solo se fornisci il relativo file sostitutivo. I pacchetti di temi esistenti restano compatibili. I percorsi del blog sono /blog, /blog/category/{slug} e /blog/{slug}, con il prefisso della lingua quando necessario. Mantieni eyivo_head per metadati sicuri, stili responsive e schede con immagini di dimensioni contenute.
Un tema può eseguire query su una pagina, chiamare un'API o leggere una variabile di ambiente?
No. I dati vengono deliberatamente trasmessi come oggetti sicuri. Ciò mantiene i temi portatili, sicuri e prevedibili.
Come posso rilasciare un aggiornamento?
Pubblica una nuova versione del tema con numerazione semantica. Non modificare una release già pubblicata senza cambiare versione: i siti devono passare esplicitamente alla nuova versione.
Dove dovrebbero vivere le immagini?
Utilizza un URL multimediale Eyivo nei dati del componente o una risorsa del pacchetto a cui si fa riferimento tramite asset_url. Non utilizzare percorsi arbitrari del file system del server.
25. Registro delle modifiche
- 31 ottobre 2026. Theme API 1.1: i temi possono includere JavaScript revisionato in
assets/js/con la funzionalitàcustom_javascript. Le nuove versioni vengono revisionate automaticamente e mostrano In attesa di revisione, Approvata, Rifiutata o Bloccata. I pacchetti Theme API 1.0 non cambiano. - 31 ottobre 2026. I proprietari possono aggiungere CSS personalizzato del sito, caricato dopo i tuoi fogli di stile, e assegnare nomi di classe alle sezioni, aggiunti al primo elemento di ogni componente e disponibili come
{{ component.css_class }}. Vedi CSS personalizzato del sito e classi di sezione. - 31 ottobre 2026. I media demo in
demo.jsondevono usare un hosthttpsconsentito (cdn.eyivo.comoimages.pexels.com) o un file incluso sottoassets/. Eyivo rileva il tipo di ogni file dal suo contenuto. È una correzione di sicurezza; la Theme API resta alla 1.0. - 30 ottobre 2026. Eyivo assegna a ogni tema caricato un proprio ID e
keyintheme.jsonè facoltativo. Carica le modifiche come nuova versione dalla pagina del tema. Il repository di esempio tiene il tema nella cartellasample-theme/, che comprimi e carichi. L’esempio di pacchetto non mostra piùassets/js/, perché i caricamenti con Theme API 1.0 non possono includere file JavaScript.