Edge Templates: visao geral

Overview: what an Edge Template is and how it works

Um Edge Template e uma pequena aplicacao web autocontida (HTML + CSS + JS) que pode ser configurada via querystring e exibida em diversos hospedeiros: o editor da Insyde, paineis embutidos por iframe (CEP do Premiere, UXP, NRCS como ENPS/Octopus) ou diretamente em um navegador.

An Edge Template is a small self-contained web app (HTML + CSS + JS) that gets configured via the URL querystring and rendered in a variety of hosts: the Insyde editor, embedded iframe panels (Premiere CEP, UXP, NRCS like ENPS/Octopus), or a plain browser.

1. Modelo mental / Mental model

Cada template e descrito por um config.json. Esse arquivo declara quais campos o template aceita, e o editor da Insyde gera automaticamente um formulario para preencher cada campo. A saida e uma URL com querystring; o template, ao ser aberto nessa URL, le os parametros e se renderiza.

Each template is described by a config.json. That file declares which fields the template accepts, and the Insyde editor automatically generates a form to fill each field. The output is a URL with a querystring; when the template is opened at that URL, it reads the params and renders itself. 

// pipeline:

config.json   →   Insyde editor   →   ?key=value&...   →   index.html
(schema)        (form UI)           (querystring)        (renders widget)

Tres arquivos minimos compoem um template:

A template needs three minimum files:

Templates que precisam de play/stop, seek, ou exportacao de video adotam o canal flow-bridge — um wrapper postMessage que padroniza o lifecycle entre template e host. Ele substitui padroes ad-hoc como window.__template ou ?record=1.

Templates that need play/stop, seek, or video export adopt the flow-bridge channel — a postMessage wrapper that standardizes the lifecycle between template and host. It replaces ad-hoc patterns like window.__template or ?record=1.

2. Hello world

O template mais simples possivel: uma headline com cor de fundo configuravel.

The simplest possible template: a headline with a configurable background color.

index.html

<!DOCTYPE html>
<html><head><meta charset="utf-8"></head><body>
  <div id="root"></div>
  <script>
    const p = new URLSearchParams(location.search);
    const root = document.getElementById('root');
    root.style.background = p.get('bg') || '#000';
    root.style.color = '#fff';
    root.style.padding = '40px';
    root.style.fontFamily = 'sans-serif';
    root.textContent = p.get('t') || 'Hello';
  </script>
</body></html>

config.json

{
  "fields": [
    {
      "key": "t",
      "name": "title",
      "label": "Title",
      "type": "text",
      "default": "Hello world"
    },
    {
      "key": "bg",
      "name": "bgColor",
      "label": "Background",
      "type": "color",
      "default": "#1a1a2e"
    }
  ],
  "meta": {
    "version": "1.0.0",
    "widget": "HelloWorld",
    "name": "Hello world",
    "resolution": { "width": 1920, "height": 1080 }
  }
}

O editor le esse config.json e mostra dois campos: um input de texto e um seletor de cor. Cada vez que o usuario edita, o editor atualiza a URL de preview:

The editor reads this config.json and shows two inputs: a text field and a color picker. Each edit updates the preview URL: 

./index.html?t=Breaking%20News&bg=%23ff3300

3. Anatomia do config.json / Anatomy of config.json

{
  "fields": [   // array de campos editaveis / array of editable fields
    { ... },
    { ... }
  ],
  "meta": {     // metadata para o editor (galeria, canvas) / editor metadata
    "version":  "2.0.0",
    "widget":   "WidgetClassName",
    "name":     "Display name",
    "category": "taxonomy-slug",
    "resolution": { "width": 1920, "height": 1080 }
  }
}

O bloco fields declara o que o usuario edita. O bloco meta e usado somente pelo editor (o template em runtime nao precisa ler nada de meta).

The fields block declares what the user edits. The meta block is used by the editor only (the template at runtime never needs to read anything from meta).

4. Estrutura comum de um campo / Common field shape

Todo campo, independentemente do tipo, segue a mesma forma base:

Every field, regardless of type, follows the same base shape:

Property Required Description
key Yes Sigla curta usada na querystring / Short prefix used in the querystring (ex: t, bg)
name Yes Nome completo em camelCase / Full camelCase name (ex: title, bgColor)
label Yes Rotulo exibido no editor / Display label in the editor
type Yes Tipo do campo (ver referencia) / Field type (see reference)
default Yes Valor inicial / Initial value
tip No Texto de ajuda mostrado no editor / Help text shown in the editor

5. Como o template e empacotado / How a template is packaged

Um template deve ser entregue como um arquivo ZIP contendo, na raiz:

A template should be delivered as a ZIP file containing, at the root: 

my-template/
├── index.html         // entry point
├── app.js             // logic (or inline in index.html)
├── style.css          // styles (or inline)
├── config.json        // schema + metadata
├── img/               // optional default assets
├── fonts/             // optional embedded fonts
└── vendor/            // optional third-party libs

O ZIP e enviado pelo editor ao backend; o backend extrai e publica os arquivos em uma CDN. A partir dai, o template e acessivel via uma URL fixa, e o editor gera previews ao adicionar a querystring.

The ZIP is uploaded by the editor to the backend; the backend extracts and publishes the files to a CDN. From then on the template is accessible at a fixed URL, and the editor builds previews by appending the querystring.

Importante / Important: O template deve funcionar em modo standalone (apenas com a querystring, sem nenhuma API extra). Isso garante que rode em qualquer hospedeiro: editor, embed iframe, plug-in NLE.
The template must work in standalone mode (just the querystring, no extra API). That guarantees it runs in any host: editor, embed iframe, NLE plug-in.

6. Validacao com JSON Schema / JSON Schema validation

O config.json tem um schema canonico publicado em https://docs.insyde.one/edge-template.schema.json. Use ele para autocomplete e validacao em tempo real no editor.

The config.json has a canonical schema published at https://docs.insyde.one/edge-template.schema.json. Use it for autocomplete and real-time validation in your editor.

1) Inline no proprio arquivo / Inline in the file itself

VS Code (com a extensao JSON nativa) le o campo $schema e ativa autocomplete + erros automaticamente:

VS Code (with the built-in JSON extension) reads the $schema field and enables autocomplete + errors automatically:

{
  "$schema": "https://docs.insyde.one/edge-template.schema.json",
  "fields": [
    { "key": "t", "name": "title", "label": "Title", "type": "text", "default": "Hello" }
  ],
  "meta": { "version": "1.0.0", "widget": "MyWidget" }
}

2) Linha de comando com ajv / Command line with ajv

npm install -g ajv-cli ajv-formats

ajv validate \
  -s https://docs.insyde.one/edge-template.schema.json \
  -d config.json \
  --spec=draft2020 -c ajv-formats

3) Em CI / In CI

Adicione o comando acima como step do pipeline para barrar PRs com config.json invalido. O schema e versionado junto com a documentacao — mudancas que quebram entram com novo $id.

Add the command above as a pipeline step to block PRs with invalid config.json. The schema is versioned alongside the documentation — breaking changes ship under a new $id.

7. Proximos passos / Next steps

Back to docs index