1. The mental model
There are three separate responsibilities. Keeping them separate is the key to understanding v1.
Eyivo Core
Stores company details, pages, media, SEO, navigation and publishing state. It is the source of truth for content.
Theme package
Defines fixed page shapes, allowed sections, custom component schemas and CSS. It never queries data or executes application code.
App editor
Generates safe forms from the schema. Owners may update text, images, pages and section order inside an area.
Not a page builder: an owner can add a permitted section to main and choose its numeric position. They cannot create a new area, drag a hero into the footer or change your theme’s files. They can add their own site CSS, loaded after your stylesheets, and give sections class names (see Site custom CSS).
2. Quick start: a minimal, usable template
Every v1 theme owns its complete layout, styles and scripts, and may arrange them in any design its author chooses. Themes never inherit a layout or asset from another theme. Common eyivo: components and the seven fallback page types come from theme-core; a theme only stores the page types it overrides and components it declares in the theme: namespace.
Every v1 theme needs a default layout file. Both page-types/ and components/ are optional when the package uses only core fallbacks:
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 always comes from the active theme and owns the complete public document. Eyivo first looks for the requested page type in that theme, then falls back to theme-core/page-types. Core never supplies a layout or assets, so the fallback page content is still wrapped and styled by the active theme.
3. Describe the template in theme.json
The manifest is both a capability declaration and the contract used to generate App forms. It answers three questions: which page structures exist, which areas each structure has, and what a component is allowed to store. Built-in themes explicitly declare all ten standard page types and include their corresponding Liquid files. Custom themes can continue to use core fallbacks for undeclared page types.
{
"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 }
}
}
}
}
| Key | Meaning | Example |
|---|---|---|
key | Optional label for your own reference. Eyivo gives every uploaded theme its own ID, so the key never decides which theme an upload belongs to. | acme-industrial |
version | Your immutable theme release version (semantic versioning). | 1.2.0 |
eyivo_theme_api | The Eyivo public API contract your package supports. | 1.0 |
areas | Named slots that your Liquid page file renders in fixed places. | hero, main, bottom |
allowed_components | Which components the editor may add to one area. | ["eyivo:hero"] |
components | The active theme’s custom theme: component definitions. Shared eyivo: definitions stay in theme-core. | featured_course |
min/max | Optional limits on the number of sections in that area. | max: 1 |
Page-type fallback: the built-in types are home, page, gallery, contact, products, product and videos. Omit any of them to use its definition and Liquid file from theme-core. Declare a type only when the theme also supplies its matching page-types/<type>.liquid override.
The editor receives the merged page-type API: active-theme definitions replace matching core definitions, while every omitted type remains available from core.
4. Complete demo content in demo.json
Every upload must include a portable, draft-only demo.json fixture and at least one screenshot captured with that fixture loaded. Built-in themes use the same schema. Do not include database IDs, tenant domains, credentials, or object-storage credentials.
{
"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": []
}
| Key | Purpose |
|---|---|
media | Public source URLs and metadata keyed by portable asset identifiers. Reuse the identifier for hero_asset, cover_asset, media_asset, gallery-item asset, logo_asset, and favicon_asset. |
company | Company profile, social links, brand colors, optional logo/favicon asset, and locale-keyed translations. |
theme_settings | Initial theme settings, with optional locale-keyed translations. |
pages | Type, sort order, navigation state, SEO, page settings, components, and locale-keyed content. |
catalog | Catalog entries with locale-keyed content and an optional cover_asset. |
galleries | Gallery metadata and image items. Every gallery item needs an asset and non-empty alt_text. |
videos | An external source_url or a media_asset, presentation mode, and locale-keyed content. |
Every media entry needs either a public_url on https at an allowed host (the Eyivo demo media host cdn.eyivo.com or images.pexels.com), or a file packaged in the theme under assets/, keyed by its path and given without public_url. Other hosts, http, IP addresses, other ports and redirects are rejected with the demo_media_url upload diagnostic. mime_type, width and height are only hints: Eyivo detects the real type from the downloaded file, which must be an allowed image or video of at most 20 MB.
Demo forms use portable form bindings, which Eyivo resolves separately for every site that imports the demo. Imported demo images become ordinary media references on that site; removing them there never removes the shared original.
Pages and components
{
"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" }
}
}]
}
Component types and areas must be declared in the active theme manifest or theme-core. Use relative paths such as /contact for same-site links. Bundled homepage demos use their existing hero image as a full-width background with a readable overlay and responsive text: immersive in most themes, and image-backed centered in Compact. Other hero variants retain their own layouts.
Demo languages and fallback
English is the required base language: set default_locale to en. Omitted values in older fixtures also mean English. Every other supported site language is optional; do not copy English text into another locale and present it as a translation.
Provide translations.en and optional locale objects for company copy, theme settings, pages, components, products, galleries, gallery-item captions and alt text, videos, and blog posts. Legacy unkeyed English fields remain supported. Creation selects the site’s native language and falls back to English for each missing field. Arrays replace the entire English array; explicit empty values are preserved. Only the selected site language is imported, without automatically enabling English or other locales.
Use English source slugs in same-site links and portable menu entries. Import maps them to the selected translation’s slug, including links in rich text and blog documents. Menu entries may supply explicit slugs and labels maps. Missing label overrides fall back to English. External URLs are unchanged.
{
"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" }
}]
}
}
Import and media safety
New dashboard sites include demo data by default and immediately publish the selected language; owners can uncheck this option. Loading a demo from Branding on an existing site still creates drafts and preserves published content. The central App copies images into the new site’s media library and sends references through the Internal API. Masters and themes never receive object-storage credentials. Themes render the supplied media.public_url.
Declare screenshots in theme.json.preview with data_source: "demo_data". The package must contain every declared preview image.
5. Write any layout your theme needs
The default layout owns the complete HTML document. Nothing outside the active theme supplies its header, footer, stylesheet or visual structure. The platform adds only its own scripts for forms, human verification, consent and the Eyivo badge; theme scripts need 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>
A page-type file then decides exactly where its dynamic areas appear. Area components are already rendered HTML strings, so insert them with | raw. Ordinary values are escaped by default.
<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>
Render a component directly
A designer may place a registered component directly in a layout or page-type file. This placement is fixed by the theme and is not reordered or removed in the panel. Pass an object through data:, individual schema fields, or both; named fields override matching keys from 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"
%}
The type must be a quoted namespaced literal. Direct rendering uses the same schema, variants, component file and normalized component object as an area instance. Component files cannot render other components.
Assets: always use {{ 'css/theme.css' | asset_url }}. Eyivo serves it from the active package as /theme-assets/<theme>/css/theme.css; do not hard-code another theme name or filesystem path.
Head, routes and interface dictionaries
Every layout must render {% eyivo_head %} exactly once. Eyivo then owns the title, description, robots, canonical, hreflang, Open Graph and structured-data output. Use routes.home, routes.contact, routes.catalog, routes.gallery and routes.videos instead of hardcoded public paths. Pass editable URL settings through | localized_url so known internal paths gain the active locale prefix while external URLs remain unchanged.
{{ 'Menu' | t }}
{{ theme.settings.header_cta_url | localized_url }}
Create optional locales/<locale>.json files for interface labels introduced by the theme. Lookup order is core English, core locale, theme English, then theme locale. Shared labels from theme-core therefore work without copying files. Business copy belongs in translatable content, component fields, or theme-setting fields—not dictionaries.
A custom component file
<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>
For translatable fields, Eyivo selects the visitor’s locale before rendering. A Turkish visitor and an English visitor therefore see the same component structure with different component.data.heading values.
7. The safe Liquid data you can use
Liquid receives plain, normalized data—not Laravel or database models. If a value is not in this table, treat it as unavailable in v1.
| Object | Useful fields | Typical use |
|---|---|---|
site | name, locale | Site-level label and native locale. |
company | name, legal_name, description, address, phone, email | Header, footer and contact information. |
page | id, type, title, slug, body, settings | Generic page content and per-page settings. |
seo | title, description, canonical/robots/Open Graph values when supplied | Document head. |
navigation.main | Each item has label, url, active | Site menu. |
locale | code, name, native_name, direction, is_default, home_url, available | Document language, RTL direction, localized home links and language selectors. |
routes | home, contact, catalog, gallery, videos, blog | Locale-correct system URLs; never build prefixes in Liquid. |
blog | title, url, categories, category, posts, post, pagination | Free blog listing, category archive, and article pages. Posts expose title, summary, URL, dates, categories, and cover media. Only blog.post.body_html contains server-generated safe article HTML and should use raw. Pagination supplies previous_url and next_url. |
theme.settings | Your manifest settings | Use a configured color, spacing or design option. |
products/product | Translated title, URL, summary and body | Product listing/detail page types. |
galleries | Translated title and description | Gallery page type. |
videos | title, description, source_type, source_url, playback_url, media | Use playback_url for uploaded video files and source_url for external HTTP(S) videos, according to source_type. Attached images are never video sources. Do not use the video file itself as a poster image. |
component | id, type, variant, data | Inside a component file only. |
Locale-safe layout example
<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 %}
Each available-language item also exposes label, direction, is_default, current, and has_translation. Eyivo supplies only equivalent published translations, so themes must use language.url instead of constructing /en or any other prefix.
Example of a settings-driven token: style="--brand: {{ theme.settings.primary_color }}". The setting must first be declared in theme.json.
8. Components: direct and dynamic
Components have one rendering contract with two placement choices. A direct component is controlled by the designer in a layout or page type. A dynamic component is stored as a page-area instance and controlled through the editor. Dynamic instances have a stable ID, namespaced type, area, position, optional variant, data and translations. Position is only ordering—not identity.
Field types
text, textarea, richtext, number, boolean, select, url, email, image, video, file, color, icon, page, product and repeater.
Namespaces
eyivo: resolves from theme-core/components, theme: resolves from the active theme, and plugin: is reserved for future plugins. Use the exact namespaced type in an area or eyivo_component tag.
Universal component: set "universal": true on a component definition to allow it in all areas of compatible page types. It still must have a valid schema and Liquid file.
Shared action links localize known internal paths while preserving query strings and fragments. Rich text retains safe formatting inside nested editor containers. Empty gallery images are omitted, map images without a destination are not links, and slider and search labels use the visitor's interface language.
9. Site custom CSS and section classes
Owners can add their own CSS to a site and give sections class names (Design → Custom CSS). Write themes so this works well:
- Load order: the site’s CSS is added as
<style id="eyivo-custom-css">just before</head>, after every theme stylesheet. Keep</head>in your layouts, and don’t depend on your CSS being last. - Section classes: the renderer adds a section’s class names to the first element of the component’s output, so give each component template one root element. The names are also available as
{{ component.css_class }}if you want to place them elsewhere. - Stable hooks: keep the
body.theme-{key}andlayout-{name}classes and one stable root class per component, so owners’ CSS keeps working across your versions. List any rename in the version’s release notes. - Uploaded themes: get site custom CSS too. All versions of one uploaded theme share one stylesheet per site, and it is deleted when the theme’s last version on a site is retired or deleted.
- Reserved names: the
eyivo-class prefix and theeyivo-custom-cssID belong to the platform.
10. Theme scripts (Theme API 1.1)
A theme can ship its own JavaScript for menus, sliders, tabs, filters and similar features. Scripts are optional: every theme must still work without them, and Theme API 1.0 packages keep working unchanged without scripts.
- Declare it: set
"eyivo_theme_api": "1.1"and"capabilities": {"custom_javascript": true}intheme.json, and put each file directly inassets/js/. A package with.jsfiles and no declaration is rejected. - Load it: use only
<script src="{{ 'js/theme.js' | asset_url }}" defer></script>(ortype="module") for a packaged file. Tags run in the order they appear. - Several files: each file is reviewed and allowed on its own, so
importandexportare not allowed. Share code through one global, such aswindow.AcmeTheme, and load the file that defines it first. - Limits: at most 20 files, 100 KB per file and 300 KB in total, UTF-8 text only.
- Rejected in templates: inline scripts, external script sources,
on…=event-handler attributes,javascript:URLs, and<iframe>,<object>,<embed>and<base>elements. - Readable code only: upload source, not minified, packed or encoded code. Bundlers can write unminified output.
- Statuses: a new version is Pending review until the checks finish, then Approved or Rejected. Only an Approved version can be previewed or used. An Approved version can later be Blocked: websites keep the theme without its scripts.
- Three automatic checks, in order: readable code; code rules (no
eval,new Function,document.write, page redirects,window.open, cookies or browser storage, WebAssembly, string timers, created script or frame elements, or form values sent over the network); and an AI security review. The scripts and the template lines that load them are sent to an AI service for that review. Any finding rejects the version, with the file and line.
Passes: a menu toggle
(function () {
document.querySelectorAll('[data-menu-toggle]').forEach(function (button) {
button.addEventListener('click', function () {
document.body.classList.toggle('menu-open');
});
});
})();
Rejected: sends form values away
form.addEventListener('submit', function () {
fetch('/collect', { method: 'POST', body: form.elements.email.value });
});
- Owner only: approved scripts run only on websites owned by the account that uploaded the theme, and only while the platform and the website’s owner allow them.
- Security policy: pages that run theme scripts allow exactly the reviewed files, pinned by their SHA-256 hashes, with
connect-src 'self', no frames or workers, and noeval. Changing a file needs a new version. Images and stylesheets may still load fromhttps:, so the review also rejects data sent through image or stylesheet URLs. - After approval: browsers report attempts to break the policy. Reports from three visitors within 24 hours block the version; abuse reports from three visitors within 7 days switch scripts off on that website and recheck the version. Owners get an email when a version is approved, rejected or blocked.
- Platform features: scripts must not replace, wrap or hide forms and their hidden fields, human verification, the consent banner, the Eyivo badge or the owner bar.
11. Available component catalog
These 30 shared eyivo: components form the complete v1 library and resolve from theme-core. A theme may additionally declare and implement its own theme: components.
Variants: spliteditorialcenteredimmersive
| Field | Type | Required | Translatable | Options |
|---|---|---|---|---|
eyebrow |
text |
No | Yes | — |
heading |
text |
Yes | Yes | — |
summary |
textarea |
No | Yes | — |
image_url |
url |
No | No | — |
image_alt |
text |
No | Yes | — |
primary_label |
text |
No | Yes | — |
primary_url |
url |
No | No | — |
secondary_label |
text |
No | Yes | — |
secondary_url |
url |
No | No | — |
Variants: none
| Field | Type | Required | Translatable | Options |
|---|---|---|---|---|
eyebrow |
text |
No | Yes | — |
heading |
text |
No | Yes | — |
body |
richtext |
No | Yes | — |
Variants: image_leftimage_rightoverlap
| Field | Type | Required | Translatable | Options |
|---|---|---|---|---|
eyebrow |
text |
No | Yes | — |
heading |
text |
No | Yes | — |
body |
richtext |
No | Yes | — |
image_url |
url |
No | No | — |
image_alt |
text |
No | Yes | — |
badge |
text |
No | Yes | — |
button_label |
text |
No | Yes | — |
button_url |
url |
No | No | — |
Variants: none
| Field | Type | Required | Translatable | Options |
|---|---|---|---|---|
eyebrow |
text |
No | Yes | — |
heading |
text |
No | Yes | — |
items |
repeater |
No | Yes | — |
Variants: none
| Field | Type | Required | Translatable | Options |
|---|---|---|---|---|
eyebrow |
text |
No | Yes | — |
heading |
text |
No | Yes | — |
intro |
textarea |
No | Yes | — |
items |
repeater |
No | Yes | — |
Variants: none
| Field | Type | Required | Translatable | Options |
|---|---|---|---|---|
eyebrow |
text |
No | Yes | — |
heading |
text |
No | Yes | — |
intro |
textarea |
No | Yes | — |
items |
repeater |
No | Yes | — |
Variants: none
| Field | Type | Required | Translatable | Options |
|---|---|---|---|---|
eyebrow |
text |
No | Yes | — |
heading |
text |
No | Yes | — |
intro |
textarea |
No | Yes | — |
button_label |
text |
No | Yes | — |
button_url |
url |
No | No | — |
Variants: none
| Field | Type | Required | Translatable | Options |
|---|---|---|---|---|
eyebrow |
text |
No | Yes | — |
heading |
text |
No | Yes | — |
items |
repeater |
No | Yes | — |
Variants: none
| Field | Type | Required | Translatable | Options |
|---|---|---|---|---|
eyebrow |
text |
No | Yes | — |
heading |
text |
No | Yes | — |
text |
textarea |
No | Yes | — |
submit_label |
text |
No | Yes | — |
form_binding |
select |
No | No | — |
Variants: none
| Field | Type | Required | Translatable | Options |
|---|---|---|---|---|
heading |
text |
No | Yes | — |
text |
textarea |
No | Yes | — |
whatsapp_url |
url |
No | No | — |
Variants: none
| Field | Type | Required | Translatable | Options |
|---|---|---|---|---|
eyebrow |
text |
No | Yes | — |
heading |
text |
No | Yes | — |
address |
textarea |
No | Yes | — |
map_url |
url |
No | No | — |
image_url |
url |
No | No | — |
image_alt |
text |
No | Yes | — |
Variants: none
| Field | Type | Required | Translatable | Options |
|---|---|---|---|---|
heading |
text |
No | Yes | — |
items |
repeater |
No | Yes | — |
Variants: none
| Field | Type | Required | Translatable | Options |
|---|---|---|---|---|
heading |
text |
No | Yes | — |
placeholder |
text |
No | Yes | — |
categories |
repeater |
No | Yes | — |
Variants: none
| Field | Type | Required | Translatable | Options |
|---|---|---|---|---|
eyebrow |
text |
No | Yes | — |
heading |
text |
No | Yes | — |
summary |
textarea |
No | Yes | — |
video_url |
url |
No | No | — |
poster_url |
url |
No | No | — |
Variants: none
| Field | Type | Required | Translatable | Options |
|---|---|---|---|---|
eyebrow |
text |
No | Yes | — |
heading |
text |
No | Yes | — |
price |
text |
No | Yes | — |
period |
text |
No | Yes | — |
features |
repeater |
No | Yes | — |
button_label |
text |
No | Yes | — |
button_url |
url |
No | No | — |
Variants: none
| Field | Type | Required | Translatable | Options |
|---|---|---|---|---|
label |
text |
No | Yes | — |
heading |
text |
No | Yes | — |
body |
textarea |
No | Yes | — |
button_label |
text |
No | Yes | — |
button_url |
url |
No | No | — |
Variants: none
| Field | Type | Required | Translatable | Options |
|---|---|---|---|---|
eyebrow |
text |
No | Yes | — |
heading |
text |
No | Yes | — |
items |
repeater |
No | Yes | — |
Variants: none
The shared eyivo:faq component keeps the same fields and markup in every theme. Each theme presents it in that theme’s own type, spacing, and color.
| Field | Type | Required | Translatable | Options |
|---|---|---|---|---|
eyebrow |
text |
No | Yes | — |
heading |
text |
No | Yes | — |
items |
repeater |
No | Yes | — |
Variants: none
| Field | Type | Required | Translatable | Options |
|---|---|---|---|---|
eyebrow |
text |
No | Yes | — |
heading |
text |
No | Yes | — |
items |
repeater |
No | Yes | — |
Variants: none
| Field | Type | Required | Translatable | Options |
|---|---|---|---|---|
heading |
text |
No | Yes | — |
items |
repeater |
No | Yes | — |
Variants: none
| Field | Type | Required | Translatable | Options |
|---|---|---|---|---|
eyebrow |
text |
No | Yes | — |
heading |
text |
No | Yes | — |
items |
repeater |
No | Yes | — |
Variants: none
| Field | Type | Required | Translatable | Options |
|---|---|---|---|---|
eyebrow |
text |
No | Yes | — |
heading |
text |
No | Yes | — |
items |
repeater |
No | Yes | — |
Variants: none
| Field | Type | Required | Translatable | Options |
|---|---|---|---|---|
eyebrow |
text |
No | Yes | — |
heading |
text |
No | Yes | — |
items |
repeater |
No | Yes | — |
Variants: none
| Field | Type | Required | Translatable | Options |
|---|---|---|---|---|
eyebrow |
text |
No | Yes | — |
heading |
text |
No | Yes | — |
items |
repeater |
No | Yes | — |
Variants: none
| Field | Type | Required | Translatable | Options |
|---|---|---|---|---|
heading |
text |
No | Yes | — |
items |
repeater |
No | Yes | — |
Variants: none
| Field | Type | Required | Translatable | Options |
|---|---|---|---|---|
eyebrow |
text |
No | Yes | — |
heading |
text |
No | Yes | — |
items |
repeater |
No | Yes | — |
Variants: none
| Field | Type | Required | Translatable | Options |
|---|---|---|---|---|
eyebrow |
text |
No | Yes | — |
heading |
text |
No | Yes | — |
text |
textarea |
No | Yes | — |
button_label |
text |
No | Yes | — |
button_url |
url |
No | No | — |
Variants: none
| Field | Type | Required | Translatable | Options |
|---|---|---|---|---|
eyebrow |
text |
No | Yes | — |
heading |
text |
No | Yes | — |
Variants: none
| Field | Type | Required | Translatable | Options |
|---|---|---|---|---|
heading |
text |
No | Yes | — |
items |
repeater |
No | Yes | — |
Variants: none
| Field | Type | Required | Translatable | Options |
|---|---|---|---|---|
eyebrow |
text |
No | Yes | — |
heading |
text |
No | Yes | — |
intro |
textarea |
No | Yes | — |
items |
repeater |
No | Yes | — |
12. Forms and submission history
Forms API 1 provides seven approved processors. Themes own layout and styling; plugins own schemas, validation and workflow. The host handles persistence, verification and notifications.
| System plugin | Form type |
|---|---|
eyivo/contact | Contact contact |
eyivo/quote-request | Quote request quote_request |
eyivo/product-inquiry | Product inquiry product_inquiry |
eyivo/appointment-request | Appointment request appointment |
eyivo/course-application | Course application course_application |
eyivo/reservation-request | Reservation request reservation |
eyivo/property-inquiry | Property inquiry property_inquiry |
One form, reusable placements
Setup creates a retained default UUID per site/plugin/type. Reusing a placement keeps that identity; creating a named form gives a separate UUID. Theme changes and plugin reinstall preserve history. Themes declare portable aliases; the editor selects saved forms without asking customers to type 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 in contact templates and component.form in lead sections. Replace form_preset with form_binding. Render supplied fields and guidance, action, CSRF, signed form_context and verification_html. Only declared presentation overrides and permitted additional fields are accepted; required validation cannot be weakened.
forms.contact · component.form · form_binding · form.fields · form.action · form.csrf_token · form.context · form.verification_html
Two inbox views, one record
The shared site inbox and each form plugin’s own list/detail pages show the same records. Form packages require Panel API 2 submission-list/submission-detail components and a flat menu link. Panel API 1 remains supported. Viewing does not mark records read; read/archive/workflow states are separate and edits use record_revision. Disabled plugins lose menus/pages, while the shared inbox retains historical snapshots.
{"components":[{"type":"submission-list","form_type":"contact","detail_page":"submission"}]}
{"components":[{"type":"submission-detail","form_type":"contact","list_page":"submissions"}]}
Customer data and permissions
Form records stay in the assigned site content database and share the existing package max_db_bytes allowance with other content. No separate submission-count or retention quota is added. Configuration remains in the master database with limits of 50 fields, 32 KB and three levels. Members can view; owner/manage permissions govern changes. Plugins receive no direct database access, and PHP/Blade never moves to the app.
Verified saving and notification
The host validates signed context, declared answers and required Human Verification, then commits the record, usage and notification work together. Identical attempts and payloads recover for 24 hours without saving twice. SMTP delivery runs afterward and may retry; an email failure does not undo a saved record. An unset form recipient falls back to the company email; if neither address is valid, the submission is saved without email.
All shipped themes use this contract. Legacy contact POSTs return 410; contact-page GET links still work. Appointment and reservation requests do not confirm bookings. Third-party form processors, file uploads and arbitrary external actions are not included.
POST /__eyivo/forms/{UUID}/submissionsGET /__eyivo/forms/{UUID}/challenge
15. Page templates and core fallbacks
There are ten standard page types: home, page, contact, products, product, gallery, videos, blog, blog_category and blog_post. A theme may provide all ten or only some; theme-core supplies a working template for every type the theme does not declare. Keep the area names and form bindings of the core page types when you override them, so existing content and registered forms keep working after a theme change.
16. Page heroes
Subpage heroes come in two forms. Without an image, use a compact banner with breadcrumbs, an optional eyebrow and the page title. With an image, layer the title, breadcrumbs and summary above the image and a contrasting overlay, so text stays readable on any photograph, and mirror the overlay direction in right-to-left layouts.
17. Images, galleries and video
Keep uploaded images inside bounded frames: catalog images keep their proportions, and detail photographs may fill the frame with a centered cover crop. Galleries may open the original image in a dialog that closes on Escape and returns focus to the image link; without scripts, link the original so it opens in a new tab. Image sliders should support touch, buttons, the keyboard and reduced motion.
18. Rich text and shared rendering rules
The shared eyivo:rich_text component accepts editor-marked and older HTML bodies. Both pass through the platform’s formatting allow-list: paragraphs, headings, lists and safe links display as content, while scripts, event handlers and unsafe links are removed. Other text fields stay escaped. Render rich text with the provided filters instead of your own HTML handling.
19. Introductions, orientation areas and long-form pages
A page type may pair the hero with an optional orientation area for quick links or key facts; when that area is empty, let the introduction use the full width. Long editorial pages should keep a readable line length and clear heading spacing, and may place supporting sections, such as a checklist or note, beside the article on wide screens and after it on small screens. Keep every layout readable without scripts.
20. Motion and reduced motion
Decorative motion is optional. Respect prefers-reduced-motion for transitions, sliders and animated sections, and pause moving content while the visitor hovers over it or focuses inside it.
21. A complete theme checklist
A complete theme provides all ten page templates, styles all shared eyivo: components, supports every portable form binding through the existing form plugins and Human Verification, and works on desktop, mobile and right-to-left layouts. Catalog filtering, tabs, sliders and navigation disclosures are optional enhancements on top of content that works without them.
22. What happens from template activation to publishing?
- Install/activate the template. Eyivo validates the package, records its key/version and exposes its settings and component schemas in the App.
- Choose a page type. Eyivo uses the active theme’s matching Liquid file and area definition when present, otherwise the matching
theme-corefallback. - Add permitted sections. The App only offers the types listed in
allowed_components. It stores text, media references and translations against the selected component instance. - Render safely. Eyivo resolves company/page/SEO/navigation data, renders saved area components, renders direct components where the designer placed them, then renders the active theme’s page type and layout.
- Publish. The visitor receives your HTML and CSS, but no database credentials, internal models or application code.
- Update with a new version. Uploading a zip under Custom themes creates a new theme. To change an existing theme, open it, raise
versionintheme.jsonand upload a new version. Each site switches when you use the new version as a draft and publish; the previous version stays available as a rollback for 30 days.
23. Validation and common mistakes
| If you see… | Check this first |
|---|---|
| “Unsupported Eyivo Theme API version” | Set "eyivo_theme_api": "1.0". |
| Missing page type/layout/component error | Every page type or component declared by the theme needs its matching .liquid file. The active theme must always provide layouts/default.liquid; omitted built-in page types fall back to core. |
| Component unavailable in the editor | Its namespaced type must be in that area’s allowed_components list, or the definition must be universal. |
| Unknown direct component | Use a quoted eyivo: type from the shared catalog or declare a matching theme: definition and Liquid file in the active theme. |
| Field is rejected | Declare it in the component schema and use one supported field type. Use translatable: true for locale-specific text. |
| Template appears unstyled | Use the asset_url filter for CSS and confirm the file is under assets/. |
| Package is rejected for unsafe syntax | Remove PHP/Blade, env, config, DB/HTTP calls and filesystem access. Liquid is presentation-only. |
Script rules: custom_javascript_declaration, script_file, script_tag, script_import, script_size | Follow Theme scripts. Review findings appear on the version’s page with their file and line; fix them and upload a new version. |
24. FAQ
Can a customer create a new layout or move a hero below the footer?
No. They can change approved content and order approved components within an area. The Liquid page type owns layout.
Can a designer use a component without an editable area?
Yes. Use eyivo_component in a layout or page type. Use an area when the site owner should control the component instance and its order.
Must a theme implement every page type?
Blog support is required for every theme. The built-in types blog, blog_category, and blog_post can use the matching definitions and Liquid files from theme-core, inside the active theme’s layout. Declare a type only when supplying its matching override file. Existing theme packages remain compatible. Blog routes use /blog, /blog/category/{slug}, and /blog/{slug}, with Eyivo’s locale prefix where required. Preserve eyivo_head for safe metadata, responsive blog styles, and bounded image cards.
Can a theme query a page, call an API or read an environment variable?
No. Data is deliberately passed in as safe objects. This keeps themes portable, secure and predictable.
How do I release an update?
Publish a new semantic theme version. Do not silently mutate a published release; sites should move to a new version explicitly.
Where should images live?
Use an Eyivo media URL in component data, or a package asset referenced through asset_url. Do not use arbitrary server filesystem paths.
25. Changelog
- 31 October 2026. Theme API 1.1: themes can ship reviewed JavaScript in
assets/js/with thecustom_javascriptcapability. New versions are reviewed automatically and show Pending review, Approved, Rejected or Blocked. Theme API 1.0 packages are unchanged. - 31 October 2026. Owners can add site custom CSS, loaded after your stylesheets, and give sections class names, added to each component’s first element and available as
{{ component.css_class }}. See Site custom CSS and section classes. - 31 October 2026. Demo media in
demo.jsonmust use an allowedhttpshost (cdn.eyivo.comorimages.pexels.com) or a file packaged underassets/. Eyivo detects each file’s type from its content. This is a security fix; the Theme API stays at 1.0. - 30 October 2026. Eyivo gives every uploaded theme its own ID, and
keyintheme.jsonis optional. Upload changes as a new version from the theme’s page. The sample repository keeps the theme in itssample-theme/folder, which you zip and upload. The package example no longer showsassets/js/, because Theme API 1.0 uploads can’t include JavaScript files.