Options & Admin Forms

The admin configuration form for a widget instance is auto-generated from the admin.options schema in widget_info.json. You do not write any PHP or HTML for the form.

How It Works

When a site administrator opens a widget instance for editing in Appearance → Widgets, Pubvana reads the widget's admin.options schema and renders a form field for each option. On save, the form values are merged with the schema defaults and stored JSON-encoded in widget_instances.options_json.

Storage Format

Options are stored as a JSON object in widget_instances.options_json:

{
    "title": "My Recent Posts",
    "count": "5",
    "show_date": "1",
    "show_excerpt": "0"
}

All values are stored as strings, including numbers and checkbox states. The template engine and WidgetDataService handle type coercion as needed.

Accessing Options in Templates

Use dot notation on the options variable:

{{ options.title }}
{{ options.count }}
{% if options.show_date == "1" %}...{% endif %}

Option Type Reference

text

"title": {"type": "text", "label": "Widget Title", "default": "Recent Posts"}

Renders as <input type="text">. Suitable for short strings: titles, CSS classes, URLs.

number

"count": {"type": "number", "label": "Number of Posts", "default": "5"}

Renders as <input type="number">. Value stored as string; cast to int by WidgetDataService when used as a provider param.

checkbox

"show_date": {"type": "checkbox", "label": "Show Date", "default": "1"}

Renders as a toggle checkbox. Stored as "1" (checked) or "0" (unchecked). Default "1" means checked by default.

select

"layout": {
    "type": "select",
    "label": "Display Layout",
    "default": "list",
    "choices": {
        "list": "Vertical List",
        "grid": "Grid",
        "compact": "Compact"
    }
}

Renders as <select>. The choices object keys are stored values; values are display labels.

textarea

"custom_html": {"type": "textarea", "label": "Custom HTML / Ad Code", "default": ""}

Renders as <textarea>. Used for raw HTML content like ad unit embed codes. In the template, output with {! !} to avoid double-escaping:

{! options.custom_html !}

Defaults and Merging

When a widget instance is created, its stored options begin as the schema defaults. When the admin saves the form, only keys present in the form are updated. The merge priority is:

1. Instance-stored value (highest)
2. Schema default value
3. Empty string (fallback)

This means adding a new option to an existing widget's schema (after instances are already created) will correctly fall back to the default for existing instances until they are re-saved.