Vartotojo dokumentacija Kūrėjo dokumentacija | |

widget_info.json Reference

The manifest file for every widget. Must be valid JSON. Located at widgets/{slug}/widget_info.json.

Important Changes 2.2.x to 2.3.x Same changes as plugin_info.json above — remove slug, add free field, add required fields note, add URL fields table. Cron registration is plugin-only.

Top-Level Fields

Field Type Required Description
name string yes Display name shown in admin UI
description string no Short description in admin widget list
version string yes Semver version string (e.g. "2.0.0")
min_pubvana_version string no Minimum CMS version required
max_pubvana_version string no Maximum CMS version tested against
update_url string no Endpoint polled for update availability
support_url string no URL linked in admin widget detail
author string no Author name or organisation

admin.options Schema

Defines the configuration form rendered when a site owner places and configures a widget instance. Each key in admin.options becomes a form field.

"admin": {
    "options": {
        "field_key": {
            "type": "text|number|checkbox|select|textarea",
            "label": "Human-Readable Label",
            "default": "default_value",
            "choices": {"value": "Label"}
        }
    }
}

Option Types

Type HTML Control Notes
text <input type="text"> Single-line string
number <input type="number"> Numeric input; stored as string
checkbox <input type="checkbox"> Stored as "1" (checked) or "0" (unchecked)
select <select> Requires choices object ({"value": "Label", ...})
textarea <textarea> Multi-line text, e.g. raw HTML for ad units

All option values are stored JSON-encoded in widget_instances.options_json. Accessed in templates as {{ options.field_key }}.

output Object

"output": {
    "template": "widget.tpl",
    "providers": {
        "variable_name": {
            "provider": "ModelName.methodName",
            "params": {
                "method_param_name": "option_key_or_context_var"
            }
        }
    }
}
  • template — path to the template file, relative to views/ inside the widget directory
  • providers — optional map of variable name → data provider declaration

Full Example — Recent Posts Widget

{
    "name": "Recent Posts",
    "description": "Displays a list of the most recent published posts.",
    "version": "2.0.0",
    "min_pubvana_version": "2.2.3",
    "max_pubvana_version": "2.2.4",
    "update_url": "https://pubvana.net/api/dstore/v1/update/check",
    "support_url": "https://pubvana.net/contact",
    "author": "Pubvana Team",
    "admin": {
        "options": {
            "title": {"type": "text", "label": "Widget Title", "default": "Recent Posts"},
            "count": {"type": "number", "label": "Number of Posts", "default": "5"},
            "show_date": {"type": "checkbox", "label": "Show Date", "default": "1"},
            "show_excerpt": {"type": "checkbox", "label": "Show Excerpt", "default": "0"}
        }
    },
    "output": {
        "template": "widget.tpl",
        "providers": {
            "posts": {
                "provider": "PostModel.getRecent",
                "params": {"limit": "count"}
            }
        }
    }
}

Full Example — Table of Contents (No Providers)

{
    "name": "Table of Contents",
    "admin": {
        "options": {
            "title": {"type": "text", "label": "Widget Title", "default": "Table of Contents"},
            "min_headings": {"type": "number", "label": "Minimum Headings to Show", "default": "2"},
            "max_depth": {
                "type": "select",
                "label": "Max Heading Depth",
                "default": "h3",
                "choices": {"h2": "H2 only", "h3": "H2 + H3", "h4": "H2 + H3 + H4"}
            }
        }
    },
    "output": {"template": "widget.tpl"}
}

Validation Rules

  • version must be parseable as semver (X.Y.Z)
  • type in option definitions must be one of: text, number, checkbox, select, textarea
  • select type without a choices object will render an empty dropdown
  • Provider provider strings must follow the ModelName.methodName format exactly; unrecognised models are blocked by the whitelist