Widget Development
Widgets are data-driven content blocks rendered inside named widget areas (sidebars, footers, header zones) defined by the active theme. They are the lightest extension type in Pubvana: no PHP class is required. A widget is a JSON manifest plus a .tpl template.
What Widgets Can Do
- Render a list of recent posts, a tag cloud, an author bio, an ad unit, a table of contents
- Pull structured data from any approved
Model.methodpair declared in the manifest - Expose configurable options (title, count, toggle switches, dropdowns) that site owners control in the admin Widgets area
- Respond to page context (e.g. the currently-viewed post ID) via context variables
What Widgets Cannot Do
- Execute arbitrary PHP — no PHP files, no controllers, no custom models outside the approved provider registry
- Define routes or admin pages
- Depend on other widgets
Key Concepts
| Concept | Description |
|---|---|
widget_info.json | Manifest — metadata, admin options schema, data provider declarations |
views/widget.tpl | Jinja-like template rendered by the Pubvana template engine |
| Widget area | Named slot in a theme layout ({% widget_area "sidebar" %}) |
| Widget instance | A placed, configured copy of a widget assigned to an area |
| Data provider | A Model.method call declared in JSON — the engine fetches data for the template |
Subsections
- Getting Started — create your first widget in five minutes
- Widget Structure — directory layout and file responsibilities
- widget_info.json Reference — complete manifest schema
- Widget Views — template variables, filters, and theme-aware class mapping
- Data Providers — how the provider system works and what is available
- Context Variables — page-scoped variables (
@current_post_id) - Options & Admin Forms — auto-generated admin UI from JSON schema