Skip to content

Developer documentation · Theme API v1.0 · v1.1

Build a complete company-site template, safely.

Eyivo themes define a finished visual system: page structures, typography, components and styling. A business owner then fills in approved content in the App—without moving blocks, editing code or breaking the design.

Core principle

Liquid decides how the website looks; Eyivo Core decides which company content appears there.

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 }
      }
    }
  }
}
KeyMeaningExample
keyOptional 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
versionYour immutable theme release version (semantic versioning).1.2.0
eyivo_theme_apiThe Eyivo public API contract your package supports.1.0
areasNamed slots that your Liquid page file renders in fixed places.hero, main, bottom
allowed_componentsWhich components the editor may add to one area.["eyivo:hero"]
componentsThe active theme’s custom theme: component definitions. Shared eyivo: definitions stay in theme-core.featured_course
min/maxOptional 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": []
}
KeyPurpose
mediaPublic 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.
companyCompany profile, social links, brand colors, optional logo/favicon asset, and locale-keyed translations.
theme_settingsInitial theme settings, with optional locale-keyed translations.
pagesType, sort order, navigation state, SEO, page settings, components, and locale-keyed content.
catalogCatalog entries with locale-keyed content and an optional cover_asset.
galleriesGallery metadata and image items. Every gallery item needs an asset and non-empty alt_text.
videosAn 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.

ObjectUseful fieldsTypical use
sitename, localeSite-level label and native locale.
companyname, legal_name, description, address, phone, emailHeader, footer and contact information.
pageid, type, title, slug, body, settingsGeneric page content and per-page settings.
seotitle, description, canonical/robots/Open Graph values when suppliedDocument head.
navigation.mainEach item has label, url, activeSite menu.
localecode, name, native_name, direction, is_default, home_url, availableDocument language, RTL direction, localized home links and language selectors.
routeshome, contact, catalog, gallery, videos, blogLocale-correct system URLs; never build prefixes in Liquid.
blogtitle, url, categories, category, posts, post, paginationFree 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.settingsYour manifest settingsUse a configured color, spacing or design option.
products/productTranslated title, URL, summary and bodyProduct listing/detail page types.
galleriesTranslated title and descriptionGallery page type.
videostitle, description, source_type, source_url, playback_url, mediaUse 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.
componentid, type, variant, dataInside 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} and layout-{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 the eyivo-custom-css ID 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} in theme.json, and put each file directly in assets/js/. A package with .js files and no declaration is rejected.
  • Load it: use only <script src="{{ 'js/theme.js' | asset_url }}" defer></script> (or type="module") for a packaged file. Tags run in the order they appear.
  • Several files: each file is reviewed and allowed on its own, so import and export are not allowed. Share code through one global, such as window.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 no eval. Changing a file needs a new version. Images and stylesheets may still load from https:, 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

FieldTypeRequiredTranslatableOptions
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

FieldTypeRequiredTranslatableOptions
eyebrow text No Yes —
heading text No Yes —
body richtext No Yes —

Variants: image_leftimage_rightoverlap

FieldTypeRequiredTranslatableOptions
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

FieldTypeRequiredTranslatableOptions
eyebrow text No Yes —
heading text No Yes —
items repeater No Yes —

Variants: none

FieldTypeRequiredTranslatableOptions
eyebrow text No Yes —
heading text No Yes —
intro textarea No Yes —
items repeater No Yes —

Variants: none

FieldTypeRequiredTranslatableOptions
eyebrow text No Yes —
heading text No Yes —
intro textarea No Yes —
items repeater No Yes —

Variants: none

FieldTypeRequiredTranslatableOptions
eyebrow text No Yes —
heading text No Yes —
intro textarea No Yes —
button_label text No Yes —
button_url url No No —

Variants: none

FieldTypeRequiredTranslatableOptions
eyebrow text No Yes —
heading text No Yes —
text textarea No Yes —
submit_label text No Yes —
form_binding select No No —

Variants: none

FieldTypeRequiredTranslatableOptions
heading text No Yes —
text textarea No Yes —
whatsapp_url url No No —

Variants: none

FieldTypeRequiredTranslatableOptions
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

FieldTypeRequiredTranslatableOptions
heading text No Yes —
items repeater No Yes —

Variants: none

FieldTypeRequiredTranslatableOptions
heading text No Yes —
placeholder text No Yes —
categories repeater No Yes —

Variants: none

FieldTypeRequiredTranslatableOptions
eyebrow text No Yes —
heading text No Yes —
summary textarea No Yes —
video_url url No No —
poster_url url No No —

Variants: none

FieldTypeRequiredTranslatableOptions
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

FieldTypeRequiredTranslatableOptions
label text No Yes —
heading text No Yes —
body textarea No Yes —
button_label text No Yes —
button_url url No No —

Variants: none

FieldTypeRequiredTranslatableOptions
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.

FieldTypeRequiredTranslatableOptions
eyebrow text No Yes —
heading text No Yes —
items repeater No Yes —

Variants: none

FieldTypeRequiredTranslatableOptions
eyebrow text No Yes —
heading text No Yes —
items repeater No Yes —

Variants: none

FieldTypeRequiredTranslatableOptions
heading text No Yes —
items repeater No Yes —

Variants: none

FieldTypeRequiredTranslatableOptions
eyebrow text No Yes —
heading text No Yes —
items repeater No Yes —

Variants: none

FieldTypeRequiredTranslatableOptions
eyebrow text No Yes —
heading text No Yes —
items repeater No Yes —

Variants: none

FieldTypeRequiredTranslatableOptions
eyebrow text No Yes —
heading text No Yes —
items repeater No Yes —

Variants: none

FieldTypeRequiredTranslatableOptions
eyebrow text No Yes —
heading text No Yes —
items repeater No Yes —

Variants: none

FieldTypeRequiredTranslatableOptions
heading text No Yes —
items repeater No Yes —

Variants: none

FieldTypeRequiredTranslatableOptions
eyebrow text No Yes —
heading text No Yes —
items repeater No Yes —

Variants: none

FieldTypeRequiredTranslatableOptions
eyebrow text No Yes —
heading text No Yes —
text textarea No Yes —
button_label text No Yes —
button_url url No No —

Variants: none

FieldTypeRequiredTranslatableOptions
eyebrow text No Yes —
heading text No Yes —

Variants: none

FieldTypeRequiredTranslatableOptions
heading text No Yes —
items repeater No Yes —

Variants: none

FieldTypeRequiredTranslatableOptions
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 pluginForm type
eyivo/contactContact contact
eyivo/quote-requestQuote request quote_request
eyivo/product-inquiryProduct inquiry product_inquiry
eyivo/appointment-requestAppointment request appointment
eyivo/course-applicationCourse application course_application
eyivo/reservation-requestReservation request reservation
eyivo/property-inquiryProperty 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}/submissions
GET /__eyivo/forms/{UUID}/challenge

13. Secondary navigation and sidebars

Register header, secondary, sidebar, footer and useful_links menus in theme.json as needed. Render navigation.secondary in a utility bar and navigation.sidebar beside ordinary pages. Owners edit and publish every menu through the standard menu editor. Keep the primary menu short; on small screens the sidebar should move below the page content.

A sidebar is a layout area, not a component. Declare a sidebar area on each page type that uses it, with its allowed_components (for example rich_text, announcement, download_list and contact_actions) and a max, then render areas.sidebar inside an <aside> next to 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. 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?

  1. Install/activate the template. Eyivo validates the package, records its key/version and exposes its settings and component schemas in the App.
  2. Choose a page type. Eyivo uses the active theme’s matching Liquid file and area definition when present, otherwise the matching theme-core fallback.
  3. 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.
  4. 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.
  5. Publish. The visitor receives your HTML and CSS, but no database credentials, internal models or application code.
  6. Update with a new version. Uploading a zip under Custom themes creates a new theme. To change an existing theme, open it, raise version in theme.json and 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 errorEvery 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 editorIts namespaced type must be in that area’s allowed_components list, or the definition must be universal.
Unknown direct componentUse a quoted eyivo: type from the shared catalog or declare a matching theme: definition and Liquid file in the active theme.
Field is rejectedDeclare it in the component schema and use one supported field type. Use translatable: true for locale-specific text.
Template appears unstyledUse the asset_url filter for CSS and confirm the file is under assets/.
Package is rejected for unsafe syntaxRemove 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_sizeFollow 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 the custom_javascript capability. 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.json must use an allowed https host (cdn.eyivo.com or images.pexels.com) or a file packaged under assets/. 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 key in theme.json is optional. Upload changes as a new version from the theme’s page. The sample repository keeps the theme in its sample-theme/ folder, which you zip and upload. The package example no longer shows assets/js/, because Theme API 1.0 uploads can’t include JavaScript files.