template.json

Every template directory may include a template.json manifest alongside index.html. It defines the template's display name and its editable fields. When a template is synced from GitHub, the name becomes the template's title and each field becomes an editable input.

Templates built in Allegro have one too: open the template's Options tab and click Edit template.json to view or edit it, or read template_json from the REST API's get template endpoint. See Editing template.json.

A machine-readable JSON Schema is published for editor autocompletion and validation. Reference it from your file with $schema:

{
    "$schema": "https://docs.allegroaudience.com/template.schema.json",
    "name": "Newsletter Signup",
    "fields": [
        {
            "slug": "headline",
            "type": "text",
            "label": "Headline",
            "default_value": "Stay in the know"
        }
    ]
}

Top-level properties

Property	Type	Required	Description
name	string	Yes	Display name (title) of the template. Used as the template title on sync.
fields	array	Yes	The editable fields exposed by the template. May be empty.
supports	array	No	Capabilities the template declares. See Supports.
plans	array	No	Preview only. Sample plans for the local preview. Ignored on sync.

Field properties

Property	Type	Required	Description
slug	string	Yes	Placeholder identifier. Lowercase letters, numbers, -, and _ only (^[a-z0-9_-]+$).
type	string	Yes	One of text, textarea, richtext, number, checkbox, enum, group.
label	string	No	Name shown to editors. Defaults to the slug in words (faq_sections → "Faq sections").
description	string	No	Help text shown under the label.
tab	string	No	Top-level fields only. The tab the field appears in when editors fill it in; fields without one appear under "General".
formats	array	No	richtext only. Any of bold, italic, link, bulleted_list, numbered_list; all five when omitted.
repeatable	boolean	No	Lets editors enter a list of values instead of one. A group is always repeatable.
options	array	For enum	The choices of an enum field: a string (used as both value and label) or { "value", "label" }.
fields	array	For group	The subfields of a group. Subfields take every property except tab and default_value, and can be groups themselves up to three levels deep.
default_value	any	No	Value an interaction uses until it saves its own, and the preview editor's initial value. Use an array for a repeatable field.

Default values on interactions

An interaction action that uses the template renders default_value for any field it has no saved value for, including fields added to the template later. A saved value wins, even an empty one. A checkbox default of true or false is stored as the text "true" or "false", and a default that doesn't match the field's shape (an array on a single field, or text on a repeatable one) is dropped on sync.

Field types

Type	Editors see	Value
text	Single-line text input	The text
textarea	Multi-line text input	The text
richtext	Editor with the field's formats	Cleaned HTML
number	Number input	The number, as text
checkbox	Toggle	"true" or "false"
enum	Select of the field's options	The chosen option's value
group	A list of items, each with one input per subfield	A list of objects keyed by subfield slug

text, number, checkbox, and enum values are limited to 200 characters; textarea and richtext values to 10,000. A repeatable field holds up to 50 items. Every value except richtext is inserted into the page as escaped text. A richtext value keeps only paragraphs, line breaks, and its allowed formats, and links must use http, https, or mailto.

Repeatable fields and groups

Mark a field repeatable to let editors add as many values as they need, such as a list of links. Use a group when each item needs several values, such as newsletters that each have a title, image, and ID. A group's subfields can be repeatable, and can be groups themselves, up to three levels deep (a top-level field, a group inside it, and a group inside that).

{
    "fields": [
        {
            "slug": "links",
            "type": "text",
            "label": "Links",
            "repeatable": true
        },
        {
            "slug": "newsletters",
            "type": "group",
            "label": "Newsletters",
            "fields": [
                { "slug": "id", "type": "text", "label": "List ID" },
                { "slug": "title", "type": "text", "label": "Title" },
                { "slug": "image", "type": "text", "label": "Image URL" },
                {
                    "slug": "frequency",
                    "type": "enum",
                    "options": ["daily", "weekly"]
                }
            ]
        }
    ]
}

Loop over a repeatable field in the template HTML with {% for item in slug %}…{% endfor %}. See Repeatable fields for the full syntax.

Supports

supports lists the capabilities a template declares. plans is the only one today: it marks the template as showing plans from an offer.

{
    "name": "Plan Picker",
    "supports": ["plans"],
    "fields": []
}

When a template supports plans:

• Every interaction that uses the template must choose an offer. The interaction editor shows an Offer picker for it, and saving without one fails.
• No field may use the slug plans. The sync skips a field with that slug and records a warning in the sync log.

Values other than plans are ignored on sync and recorded as warnings, so a typo doesn't stop the rest of the template from syncing.

See Plans for how the template renders the offer's plans in HTML, Alpine.js, and index.js.

In local preview

Local Template Preview reads template.json and renders an editor input per field in its sidebar, seeded with default_value. Repeatable fields and groups get Add item, reorder, and Remove buttons. Seed them with an array:

{
    "slug": "newsletters",
    "type": "group",
    "fields": [{ "slug": "title", "type": "text" }],
    "default_value": [
        { "title": "Morning Briefing" },
        { "title": "Weekend Reads" }
    ]
}

The local preview renders a plans template with two sample plans. To preview your own, add a top-level plans list in the shape a template receives. The sync ignores it. See Previewing Plans.

{
    "name": "Plan Picker",
    "supports": ["plans"],
    "fields": [],
    "plans": [
        {
            "id": "annual",
            "name": "Annual",
            "formatted_price": "$99.00",
            "duration_label": "1 year",
            "fields": { "badge": "Best value" }
        }
    ]
}

Complete example

{
    "$schema": "https://docs.allegroaudience.com/template.schema.json",
    "name": "Newsletter Signup",
    "fields": [
        {
            "slug": "headline",
            "type": "text",
            "label": "Headline",
            "default_value": "Stay in the know"
        },
        { "slug": "intro", "type": "textarea", "label": "Intro" },
        {
            "slug": "theme",
            "type": "enum",
            "label": "Theme",
            "options": [
                { "value": "light", "label": "Light" },
                { "value": "dark", "label": "Dark" }
            ],
            "default_value": "light"
        },
        {
            "slug": "newsletters",
            "type": "group",
            "label": "Newsletters",
            "fields": [
                { "slug": "id", "type": "text", "label": "List ID" },
                { "slug": "title", "type": "text", "label": "Title" }
            ],
            "default_value": [{ "id": "morning", "title": "Morning Briefing" }]
        },
        {
            "slug": "show_privacy_note",
            "type": "checkbox",
            "label": "Show privacy note"
        }
    ]
}