Variables

Template variables are available at two scopes: globally for every rendering, and locally for a single content object rendering.

Global variables

Global variables are merged into every template rendering automatically. They can be defined through TypoScript or the service container.

Via TypoScript

Use plugin.tx_handlebars.variables to define variables available on every page where the TypoScript is active. This is best suited for dynamic variables that depend on the current request context, since the underlying provider can only resolve them once a request is available (see the tip below):

plugin.tx_handlebars {
    variables {
        pageTitle = TEXT
        pageTitle.data = page:title

        campaign = TEXT
        campaign.field = campaign
    }
}

Via service container

Variables can also be defined instance-wide through Services.yaml. These apply regardless of TypoScript configuration:

Configuration/Services.yaml

handlebars:
  variables:
    publicPath: /assets
    apiEndpoint: https://api.example.com

Note

When the same key is defined in both sources, the TypoScript value takes precedence.

Tip

Prefer the service container for static variables. The underlying GlobalVariableProvider is always cacheable, so its variables are resolved once and reused across renderings.

plugin.tx_handlebars.variables is backed by TypoScriptVariableProvider, which cannot resolve variables until a request with a ContentObjectRenderer attached is available — this may not yet be the case during early bootstrapping. Because of this, it reports itself as non-cacheable until a request has been resolved, which disables caching of the merged variable set for that rendering. Reserve plugin.tx_handlebars.variables for dynamic variables that genuinely depend on the current request context, for example a TEXT content object reading a GET parameter or the current page record.

Per-rendering variables

Variables scoped to a single rendering are declared in the variables property of a HANDLEBARSTEMPLATE content object. Each entry is processed as a standard content object against the current record's data:

tt_content.header = HANDLEBARSTEMPLATE
tt_content.header {
    templateName = Header

    variables {
        header = TEXT
        header.field = header

        subheader = TEXT
        subheader.field = subheader

        link = TEXT
        link.typolink.parameter.field = header_link
    }
}

Entries with no sub-configuration are treated as simple variables and passed to the template as-is, without invoking ContentObjectRenderer:

variables {
    # Content object — field value is rendered via cObjGetSingle
    header = TEXT
    header.field = header

    # Simple variables — values are passed through directly
    cssClass = my-element
    theme = dark
}

Two variables are always injected automatically and cannot be overridden (this reflects the same behavior as in FLUIDTEMPLATE):

data: The full data array of the current content element record.
current: The value of the current field ($cObj->currentValKey).

Warning

Declaring data or current in variables is not allowed and raises an exception.