..  include:: /Includes.rst.txt

..  _template-paths:

==============
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.

..  contents::
    :local:
    :depth: 2

..  _template-paths-priority:

Priority order
==============

+-------------------------------------------------+----------+
| Source                                          | Priority |
+=================================================+==========+
| Per-content-object TypoScript                   | 100      |
+-------------------------------------------------+----------+
| :typoscript:`plugin.tx_handlebars.view`         | 50       |
+-------------------------------------------------+----------+
| Service container (e.g. :file:`Services.yaml`)  | 0        |
+-------------------------------------------------+----------+

..  _template-paths-per-content-object:

Per-content-object (priority 100)
---------------------------------

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

..  code-block:: typoscript

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

..  seealso::

    :ref:`content-object` for the full :typoscript:`HANDLEBARSTEMPLATE`
    property reference.

..  _template-paths-typoscript:

TypoScript (priority 50)
------------------------

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

..  code-block:: typoscript

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

The :typoscript:`cpsit/handlebars` site set also populates these paths
from the site settings :typoscript:`{$handlebars.view.templateRootPath}` and
:typoscript:`{$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.

..  _template-paths-service-container:

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.

..  code-block:: yaml
    :caption: Configuration/Services.yaml

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

..  _template-paths-resolution:

Template name resolution
========================

Once the root paths are collected, template and partial names are resolved
against them. Next to directory-relative names, flat :file:`@`-prefixed names
are supported, see :ref:`templates-names`.