Template paths

Template and partial root paths are collected from various sources, each with a distinct priority. Higher-priority sources win over lower-priority ones. Within a single source, higher numeric keys override lower ones.

Priority order

Source	Priority	Cacheable
Per-content-object TypoScript	100	No
`plugin.tx_handlebars.view`	50	Yes
Service container (e.g. `Services.yaml`)	0	Yes

Per-content-object (priority 100)

Template and partial root paths can be set directly inside a HANDLEBARSTEMPLATE content object. These paths apply only to that specific rendering, including any nested partial lookups triggered by it.

tt_content.textmedia = HANDLEBARSTEMPLATE
tt_content.textmedia {
    templateRootPaths {
        10 = EXT:my_extension/Resources/Private/Templates
    }
    partialRootPaths {
        10 = EXT:my_extension/Resources/Private/Partials
    }
}

TypoScript (priority 50)

Global paths for all renderings on the current page can be configured under plugin.tx_handlebars.view:

plugin.tx_handlebars {
    view {
        templateRootPaths {
            10 = EXT:my_extension/Resources/Private/Templates
        }
        partialRootPaths {
            10 = EXT:my_extension/Resources/Private/Partials
        }
    }
}

The cpsit/handlebars site set also populates these paths from the site settings {$handlebars.view.templateRootPath} and {$handlebars.view.partialRootPath}.

Note

When multiple extensions declare paths under the same numeric key, the last one loaded wins. Use distinct keys (e.g., 10, 20, 30) to ensure all paths are registered.

Service container (priority 0)

The lowest-priority source is the service container. Paths registered here apply instance-wide, regardless of the current page or content object, and serve as the global fallback.

Configuration/Services.yaml

handlebars:
  view:
    templateRootPaths:
      10: EXT:my_extension/Resources/Private/Templates
    partialRootPaths:
      10: EXT:my_extension/Resources/Private/Partials

The HandlebarsExtension DI extension merges all paths declared this way into the container parameters %handlebars.templateRootPaths% and %handlebars.partialRootPaths%.

Template name resolution

Once the root paths are collected, the active TemplateResolver turns a template or partial name into an absolute file path. The default resolver supports two addressing styles: directory-relative paths and flat @-prefixed names.

Flat template names

The default template resolver lets you reference any template or partial by its bare filename rather than a directory-relative path. Prefix the name with @ to use this addressing:

tt_content.tx_myext_teaser = HANDLEBARSTEMPLATE
tt_content.tx_myext_teaser {
    templateName = @teaser
}

{{> @card}}

The resolver scans all configured root paths and finds the file by name regardless of its subdirectory. If the same filename exists in multiple root paths, the higher-priority root path wins. This matches the Fractal template resolution convention, making it straightforward to use a Fractal component library as the template source.

Appending --<variant> selects a named variant and falls back to the base name automatically if no dedicated file exists:

{{> @card--highlighted}}   {{!-- falls back to @card if not found --}}

Names without the @ prefix are resolved as directory-relative paths in the usual way.