Context Variables

Context variables are page-scoped values injected into the widget render pipeline by the active controller. They allow widgets to scope their data to the current page without requiring the user to configure anything.

Available Context Variables

How to Use Them

Declare a context variable as a provider param value. Prefix the value with @:

"providers": {
    "author": {
        "provider": "AuthorProfileModel.getByUserId",
        "params": {"user_id": "@current_author_id"}
    }
}

At render time, WidgetDataService checks the context bag for current_author_id. If found, it substitutes the value before calling the model method.

Context Availability Guard

If a context variable is referenced but not available on the current page, the entire widget instance is skipped — WidgetService::renderArea() returns an empty string for that instance rather than calling the provider with a null argument. This means you do not need to guard against null in your template when using context providers.

For example, an AuthorBio widget declaring "user_id": "@current_author_id" will only render on pages where @current_author_id has been set. On the homepage or a category page, it renders nothing.

How Controllers Inject Context

Public controllers set context on WidgetDataService before rendering:

// In Blog::post() controller method
service('widgetData')->setContext([
    'current_post_id' => $post->id,
    'current_author_id' => $post->user_id,
]);

Plugin controllers that render full themed pages should follow the same pattern when the page is post-scoped.

Mixing Context and Option Params

A single provider can mix option-key params and context-variable params:

"providers": {
    "related": {
        "provider": "PostModel.getRelated",
        "params": {
            "post_id": "@current_post_id",
            "limit": "count"
        }
    }
}

post_id is resolved from context; limit is resolved from the widget instance option named count.