Widget Areas

Widget areas are named slots in a theme where widgets can be placed. Declared in theme_info.json, rendered in templates with a single tag function call.

Declaring Widget Areas

"widget_areas": {
    "sidebar":        "Main Sidebar",
    "footer-1":       "Footer Column 1",
    "footer-2":       "Footer Column 2",
    "footer-3":       "Footer Column 3",
    "before-content": "Before Content"
}

Rendering a Widget Area

{! widget_area "sidebar" !}
{! widget_area "footer-1" !}

Renders all widgets assigned to that area in configured sort order. Outputs nothing if no widgets are assigned.

Typical Usage

Sidebar

<div class="row">
    <div class="col-lg-8">{% block content %}{% endblock %}</div>
    {% if theme_options.show_sidebar %}
    <div class="col-lg-4">{! widget_area "sidebar" !}</div>
    {% endif %}
</div>

Footer columns

<div class="row">
    <div class="col-md-4">{! widget_area "footer-1" !}</div>
    <div class="col-md-4">{! widget_area "footer-2" !}</div>
    <div class="col-md-4">{! widget_area "footer-3" !}</div>
</div>

Widget Area Synchronisation

On theme activation, ThemeService syncs the manifest to the widget_areas DB table. Areas from a previous theme that are no longer in the new manifest become orphaned (kept in DB but not rendered). Widget assignments are preserved when switching themes if area slugs match.

Standard Area Slugs