..  include:: /Includes.rst.txt

..  _content-object:

===================================
`HANDLEBARSTEMPLATE` content object
===================================

:typoscript:`HANDLEBARSTEMPLATE` is a custom content object type provided by
this extension. It compiles and renders a Handlebars template, resolving
template paths, processing variables, and registering assets — all from
TypoScript configuration.

The content object tries to follow the implementation details of TYPO3's
:ref:`FLUIDTEMPLATE <t3tsref:cobj-fluidtemplate>` content object as closely
as possible. Properties such as :typoscript:`templateName`,
:typoscript:`templateRootPaths`, :typoscript:`variables`,
:typoscript:`settings` and :typoscript:`dataProcessing` work the same way,
including the reserved :typoscript:`data` and :typoscript:`current`
variables. Existing :typoscript:`FLUIDTEMPLATE` configuration can therefore
be reused in most cases. The main difference is that there are no
:typoscript:`layoutRootPaths`, since Handlebars layouts are
:ref:`resolved as partials <templates-layouts>`.

..  code-block:: typoscript

    tt_content.header = HANDLEBARSTEMPLATE
    tt_content.header {
        templateName = Header
        templateRootPaths.20 = EXT:my_extension/Resources/Private/Templates
    }

..  contents:: Properties
    :local:
    :depth: 1

----

templateName
============

:aspect:`Type`
    string / stdWrap

:aspect:`Description`
    Name of the template to render. The value is resolved as a filename
    (without the :file:`.hbs` extension) relative to the configured template
    root paths. Prefix the name with :file:`@` to look up the file by its bare
    filename, see :ref:`templates-names`. Exactly one of
    :typoscript:`templateName`, :typoscript:`template`, or :typoscript:`file`
    must be set.

:aspect:`Example`
    ..  code-block:: typoscript

        templateName = Header

        # Flat name
        templateName = @header

        # With stdWrap
        templateName.field = tx_myext_template_name

----

format
======

:aspect:`Type`
    string / stdWrap

:aspect:`Description`
    File extension of the template file. If not set, the file extensions
    :file:`hbs`, :file:`handlebars` and :file:`html` are tried in this order.
    Setting a format restricts the lookup to this file extension. It must be
    one of the supported file extensions.

:aspect:`Example`
    ..  code-block:: typoscript

        format = handlebars

----

template
========

:aspect:`Type`
    string / stdWrap

:aspect:`Description`
    Inline Handlebars source used directly as the template. Useful for short
    or dynamically constructed templates. Cannot be used together with
    :typoscript:`templateName` or :typoscript:`file`.

:aspect:`Example`
    ..  code-block:: typoscript

        template = <h1>{{header}}</h1>

----

file
====

:aspect:`Type`
    string / stdWrap

:aspect:`Description`
    Absolute or :typoscript:`EXT:`-relative path to a Handlebars template
    file. Cannot be used together with :typoscript:`templateName` or
    :typoscript:`template`.

:aspect:`Example`
    ..  code-block:: typoscript

        file = EXT:my_extension/Resources/Private/Templates/Special.hbs

----

templateRootPaths
=================

:aspect:`Type`
    array (numeric keys)

:aspect:`Description`
    Template root paths for this content object. These are added to the
    content object path provider with the highest priority (100), overriding
    any TypoScript or service container paths for this rendering. Higher
    numeric keys take precedence over lower ones.

:aspect:`Example`
    ..  code-block:: typoscript

        templateRootPaths {
            10 = EXT:my_extension/Resources/Private/Templates
            20 = EXT:my_other_extension/Resources/Private/Templates
        }

..  note::

    The shorthand :typoscript:`templateRootPath` (singular) sets a single
    path at key ``0``.

----

partialRootPaths
================

:aspect:`Type`
    array (numeric keys)

:aspect:`Description`
    Partial root paths for this content object. Same priority and override
    rules as :typoscript:`templateRootPaths`.

:aspect:`Example`
    ..  code-block:: typoscript

        partialRootPaths {
            10 = EXT:my_extension/Resources/Private/Partials
        }

..  note::

    The shorthand :typoscript:`partialRootPath` (singular) sets a single
    path at key ``0``.

----

variables
=========

:aspect:`Type`
    array

:aspect:`Description`
    Variables passed to the template. Each entry is processed as a content
    object against the current content element's data record. Simple
    string values are passed through as-is; entries with a sub-array are
    rendered via :php:`ContentObjectRenderer::cObjGetSingle()`.

    Two variable names are reserved and always available automatically:

    *   :typoscript:`data` — the full content element data array
    *   :typoscript:`current` — the current field value

:aspect:`Example`
    ..  code-block:: typoscript

        variables {
            header = TEXT
            header.field = header

            bodytext = TEXT
            bodytext.field = bodytext
            bodytext.parseFunc =< lib.parseFunc_RTE

            image = FILES
            image.references.fieldName = image

            # Simple variable (no content object rendering)
            wrapperClass = container
        }

----

settings
========

:aspect:`Type`
    array

:aspect:`Description`
    Arbitrary key-value pairs passed to the template as the :typoscript:`settings`
    variable. Unlike :typoscript:`variables`, entries are not processed as
    content objects — values are used as plain strings.

:aspect:`Example`
    ..  code-block:: typoscript

        settings {
            showDate = 1
        }

    In the template:

    ..  code-block:: handlebars

        {{#if settings.showDate}}
            <time>{{date}}</time>
        {{/if}}

----

dataProcessing
==============

:aspect:`Type`
    array

:aspect:`Description`
    Standard data processors, executed after :typoscript:`variables` are resolved.
    Processors receive and return the :php:`$processedData` array. Any key added
    by a processor is available as a template variable.

    The extension provides additional processors, e.g.
    :typoscript:`process-variables`, :typoscript:`process-each` and
    :typoscript:`media`. See :ref:`data-processors` for the complete list.

:aspect:`Example`
    ..  code-block:: typoscript

        dataProcessing {
            10 = database-query
            10 {
                table = tx_myext_domain_model_item
                as = items
            }

            20 = process-variables
            20 {
                as = items
                merge = 1
                variables {
                    label = TEXT
                    label.field = title
                }
            }
        }

----

preProcessing
=============

:aspect:`Type`
    array

:aspect:`Description`
    :ref:`Data source aware processors <developer-corner-data-source-aware-processor>`
    executed before :typoscript:`variables` are processed. These can read from
    multiple data sources (content element record, processed data, processor
    configuration) and modify the variable set before content object rendering
    begins.

----

postProcessing
==============

:aspect:`Type`
    array

:aspect:`Description`
    :ref:`Data source aware processors <developer-corner-data-source-aware-processor>`
    executed after :typoscript:`variables` have been resolved and data processors
    have run, but before the template is rendered.

----

assets
======

:aspect:`Type`
    array

:aspect:`Description`
    Registers JavaScript and CSS assets via TYPO3's :ref:`Asset collector <t3coreapi:asset-collector>`
    API. Supports four sub-keys: :typoscript:`javaScript`, :typoscript:`inlineJavaScript`,
    :typoscript:`css`, :typoscript:`inlineCss`.

:aspect:`Example`
    ..  code-block:: typoscript

        assets {
            javaScript {
                my-ext-app {
                    source = EXT:my_extension/Resources/Public/JavaScript/app.js
                    attributes.defer = 1
                    options.useNonce = 1
                }
            }
            css {
                my-ext-styles {
                    source = EXT:my_extension/Resources/Public/Css/styles.css
                }
            }
        }

..  seealso::

    :ref:`asset-management` for the complete assets configuration reference.

----

headerAssets
============

:aspect:`Type`
    content object

:aspect:`Description`
    Adds arbitrary markup to the page :html:`<head>`. The value is evaluated
    as a content object and the result is passed to
    :php:`PageRenderer::addHeaderData()`.

:aspect:`Example`
    ..  code-block:: typoscript

        headerAssets = TEXT
        headerAssets.value = <link rel="stylesheet" href="/assets/styles.css">

----

footerAssets
============

:aspect:`Type`
    content object

:aspect:`Description`
    Adds arbitrary markup before the closing :html:`</body>` tag. The value
    is evaluated as a content object and the result is passed to
    :php:`PageRenderer::addFooterData()`.

:aspect:`Example`
    ..  code-block:: typoscript

        footerAssets = TEXT
        footerAssets.value = <script src="/assets/app.js"></script>

----

stdWrap
=======

:aspect:`Type`
    stdWrap

:aspect:`Description`
    Standard TYPO3 stdWrap processing applied to the final rendered output.

:aspect:`Example`
    ..  code-block:: typoscript

        stdWrap.wrap = <div class="handlebars-content">|</div>