Contents 

What does it do? 

The extension provides a full rendering environment for Handlebars templates within TYPO3 CMS. All core features of Handlebars.js are supported by the usage of the third-party library PHP Handlebars.

Its main use is to seamlessly integrate Handlebars templates into TYPO3 without the need to modify these templates again for output in TYPO3.

Features 

• Full rendering environment for Handlebars templates
• Native support for custom Handlebars helpers
• Easy to extend and customize
• Built on dependency injection for better performance and maintainability
• Integration with TYPO3's cache framework for compiled templates

Support 

There are several ways to get support for this extension:

• Slack: https://typo3.slack.com/messages/ext-handlebars
• GitHub: https://github.com/CPS-IT/handlebars/issues

Contributors 

This extension is based on the great work of Digitas Pixelpark GmbH. It was heavily extended and is now maintained by coding. powerful. systems. CPS GmbH.

License 

This extension is licensed under GNU General Public License 2.0 (or later).

Requirements 

• PHP 8.2 - 8.5
• TYPO3 13.4 LTS

Installation 

Require the extension via Composer (recommended):

composer require cpsit/typo3-handlebars

Or download it from TYPO3 extension repository.

# ext_emconf.php

$EM_CONF[$_EXTKEY] = [
    'constraints' => [
        'depends' => [
            'handlebars' => '0.7.0-0.7.99',
        ],
    ],
];

Configuration via service container 

The easiest way to register your template root paths and partial root paths is by using the Services.yaml file:

# Configuration/Services.yaml

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

The HandlebarsExtension takes care of all template paths. They will be merged and then added to the service container resulting in the following parameters:

• %handlebars.templateRootPaths%
• %handlebars.partialRootPaths%

You can reference those parameters in your custom configuration to use the resolved template paths in your services.

The drawback of this configuration is that it is applied to the whole TYPO3 instance since there exists only one service container for the whole system. In case you need different template paths for specific parts of your installation, take a look at the following configuration method that uses TypoScript.

Configuration via TypoScript 

A more flexible configuration method is the usage of TypoScript. This way you can override the configuration from the service container (as described above) which allows you to define different template root paths and partial root paths for specific parts of the system.

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

Configuration 

In your Services.yaml file, add the following lines:

# Configuration/Services.yaml

handlebars:
  variables:
    publicPath: /assets
    # ...

All data will then be available as service parameter %handlebars.variables% within the service container. So you can use it everywhere you need it in your Services.yaml file.

Overwrite default data 

If in certain cases it is necessary to overwrite a value from the default data, it can simply be passed as an additional value in the Presenter:

# Classes/Presenter/MyCustomPresenter.php

namespace Vendor\Extension\Presenter;

use CPSIT\Typo3Handlebars\Data\Response\ProviderResponse;
use CPSIT\Typo3Handlebars\Presenter\AbstractPresenter;

class MyCustomPresenter extends AbstractPresenter
{
    public function present(ProviderResponse $data): string
    {
        $renderData = [
            // ...
        ];

        // Overwrite default data "publicPath"
        $renderData['publicPath'] = '/custom/path/to/assets';

        return $this->renderer->render('path/to/template', $renderData);
    }
}

TypoScript 

# Disable debugging
config.debug = 0

# Enable debugging
config.debug = 1

Local configuration 

// Disable debugging
$GLOBALS['TYPO3_CONF_VARS']['FE']['debug'] = false;

// Enable debugging
$GLOBALS['TYPO3_CONF_VARS']['FE']['debug'] = true;

Example 

1. Preparations

   Before the actual components are created, some preliminary work is necessary.

   1. Installation

      Install the extension using Composer.

   2. Define dependencies

      Add the extension as dependency to your extension as described here.

   3. Services.yaml

      Create a basic Services.yaml file in your extension. Make sure to read and follow the guidelines described at Dependency injection.

   4. TypoScript configuration

      Create a TypoScript configuration file and include it in your site's root template. Make sure to include static TypoScript from EXT:fluid_styled_content.

2. Create a new DataProcessor

   Each DataProcessor must implement the CPSIT\Typo3Handlebars\DataProcessing\DataProcessor interface.

   There's already a default DataProcessor in place that provides some basic logic and is required in case you want to develop components like described on this page. Just extend your DataProcessor from CPSIT\Typo3Handlebars\DataProcessing\AbstractDataProcessor and implement the abstract method render():

   # Classes/DataProcessing/HeaderProcessor.php
   
   namespace Vendor\Extension\DataProcessing;
   
   use CPSIT\Typo3Handlebars\DataProcessing\AbstractDataProcessor;
   
   class HeaderProcessor extends AbstractDataProcessor
   {
       protected function render(): string
       {
           $data = $this->provider->get($this->cObj->data);
           return $this->presenter->present($data);
       }
   }
   

   Copied!

   Attention

   Use the correct namespace

   It is very important to create the DataProcessor with the correct namespace, as all other components will be automatically registered based on it.

3. Register DataProcessor as service

   The HeaderProcessor must now be registered in the Services.yaml in the next step:

   # Configuration/Services.yaml
   
   services:
     Vendor\Extension\DataProcessing\HeaderProcessor:
       tags: ['handlebars.processor']

   Copied!

   All related components (DataProvider, Presenter) are now automatically assigned to this DataProcessor and registered accordingly.

   Tip

   If all DataProcessors share the same configuration, they can also be registered all at once with the following configuration:

   # Configuration/Services.yaml
   
   services:
     Vendor\Extension\DataProcessing\:
       resource: '../Classes/DataProcessing/**/*Processor.php'
       tags: ['handlebars.processor']

   Copied!

4. Create a new DataProvider

   Next, a DataProvider must be created that prepares the module's data and makes it available to the DataProcessor again. Each DataProvider must implement the CPSIT\Typo3Handlebars\Data\DataProvider interface.

   # Classes/Data/HeaderProvider.php
   
   namespace Vendor\Extension\Data;
   
   use CPSIT\Typo3Handlebars\Data\DataProvider;
   use CPSIT\Typo3Handlebars\Data\Response\ProviderResponse;
   use Vendor\Extension\Data\Response\HeaderProviderResponse;
   
   class HeaderProvider implements DataProvider
   {
       public function get(array $data): ProviderResponse
       {
           return (new HeaderProviderResponse($data['header']))
               ->setHeaderLayout((int)$data['header_layout'])
               ->setHeaderLink($data['header_link'])
               ->setSubheader($data['subheader']);
       }
   }
   

   Copied!

   As you can see, the DataProvider returns an instance of a so-called ProviderResponse object. This holds the prepared data for higher-level transfer within the rendering process. Create it in the associated namespace:

   # Classes/Data/Response/HeaderProviderResponse.php
   
   namespace Vendor\Extension\Data\Response;
   
   use CPSIT\Typo3Handlebars\Data\Response\ProviderResponse;
   
   class HeaderProviderResponse implements ProviderResponse
   {
       public const LAYOUT_DEFAULT = 0;
   
       private string $header;
       private int $headerLayout = self::LAYOUT_DEFAULT;
       private string $headerLink = '';
       private string $subheader = '';
   
       public function __construct(string $header)
       {
           $this->header = $header;
           $this->validate();
       }
   
       // Getters and setters...
   
       public function toArray(): array
       {
           return [
               'header' => $this->header,
               'headerLayout' => $this->headerLayout,
               'headerLink' => $this->headerLink,
               'subheader' => $this->subheader,
           ];
       }
   
       private function validate(): void
       {
           if ('' === trim($this->header)) {
               throw new \InvalidArgumentException('Header must not be empty.', 1626108393);
           }
       }
   }

   Copied!

5. Create a new Presenter

   To complete the rendering process, a new Presenter called HeaderPresenter must be created. It must implement the CPSIT\Typo3Handlebars\Presenter\Presenter interface; furthermore, an CPSIT\Typo3Handlebars\Presenter\AbstractPresenter is already available with the default Renderer already specified as a dependency.

   # Classes/Presenter/HeaderPresenter.php
   
   namespace Vendor\Extension\Presenter;
   
   use CPSIT\Typo3Handlebars\Data\Response\ProviderResponse;
   use CPSIT\Typo3Handlebars\Exception\UnableToPresentException;
   use CPSIT\Typo3Handlebars\Presenter\AbstractPresenter;
   
   class HeaderPresenter extends AbstractPresenter
   {
       public function present(ProviderResponse $data): string
       {
           if (!($data instanceof HeaderProviderResponse)) {
               throw new UnableToPresentException(
                   'Received unexpected response from provider.',
                   1613552315
               );
           }
   
           // Use data from ProviderResponse or implement custom logic
           $renderData = $data->toArray();
   
           return $this->renderer->render(
               'Extensions/FluidStyledContent/Header',
               $renderData
           );
       }
   }

   Copied!

6. Set up TypoScript configuration

   Finally, you have to configure via TypoScript that instead of the default Fluid rendering the special Handlebars rendering should be executed for all content elements of the CType header.

   For this purpose, each DataProcessor provides a method process(string $content, array $configuration) as entry point.

   # Configuration/TypoScript/setup.typoscript
   
   tt_content.header = USER
   tt_content.header.userFunc = Vendor\Extension\DataProcessing\HeaderProcessor->process

   Copied!

7. Optional: Create custom Helpers

   If your templates use custom Helpers, you will need to create them additionally. Read Create a custom Helper to learn what options are available for creating your own Helpers.

8. Flush caches

   Changes were made to the service configuration and also the rendering was overwritten using TypoScript. Therefore, it is now necessary to ensure that the caches are flushed and the service container is reconfigured.

Sources 

Usage 

tt_content.tx_myextension_mymodule = USER
tt_content.tx_myextension_mymodule {
    userFunc = CPSIT\Typo3Handlebars\DataProcessing\SimpleProcessor->process
    userFunc.templatePath = Extensions/FluidStyledContent/MyModule
}

As you can see, the SimpleProcessor is directly addressed as userFunc. It already provides the necessary functionality, but can of course also be extended with your own requirements.

Furthermore it is necessary to indicate a template path with (this normally happens in the Presenter). The SimpleProcessor throws an exception, if the template path is not set or invalid.

Sources 

Usage 

1. Transfer of the ContentObjectRenderer

   If the rendering process is triggered via TypoScript, the DataProcessor is automatically assigned the current instance of the ContentObjectRenderer (via the cObj property). It can then pass this to the DataProvider:

   # Classes/DataProcessing/CustomProcessor.php
   
   namespace Vendor\Extension\DataProcessing;
   
   use CPSIT\Typo3Handlebars\DataProcessing\AbstractDataProcessor;
   
   class CustomProcessor extends AbstractDataProcessor
   {
       protected function render(): string
       {
           $this->provider->setContentObjectRenderer($this->cObj);
           // ...
       }
   }

   Copied!

2. Assure ContentObjectRenderer is available

   In the DataProvider, the existence of the ContentObjectRenderer can be easily checked if the associated trait is used:

   # Classes/Data/CustomProvider.php
   
   namespace Vendor\Extension\Data;
   
   use CPSIT\Typo3Handlebars\ContentObjectRendererAware;
   use CPSIT\Typo3Handlebars\Data\DataProvider;
   use CPSIT\Typo3Handlebars\Data\Response\ProviderResponse;
   use CPSIT\Typo3Handlebars\Traits\ContentObjectRendererAwareTrait;
   
   class CustomProvider implements DataProvider, ContentObjectRendererAware
   {
       use ContentObjectRendererAwareTrait;
   
       public function get(array $data): ProviderResponse
       {
           $this->assertContentObjectRendererIsAvailable();
           // ...
       }
   }

   Copied!

3. Use the ContentObjectRenderer

   If successful, the ContentObjectRenderer can then be used, for example, to parse database content generated using RTE:

    # Classes/Data/CustomProvider.php
   
    namespace Vendor\Extension\Data;
   
    use CPSIT\Typo3Handlebars\ContentObjectRendererAware;
    use CPSIT\Typo3Handlebars\Data\DataProvider;
    use CPSIT\Typo3Handlebars\Data\Response\ProviderResponse;
    use CPSIT\Typo3Handlebars\Traits\ContentObjectRendererAwareTrait;
   +use Vendor\Extension\Data\Response\CustomProviderResponse;
   
    class CustomProvider implements DataProvider, ContentObjectRendererAware
    {
        use ContentObjectRendererAwareTrait;
   
        public function get(array $data): ProviderResponse
        {
            $this->assertContentObjectRendererIsAvailable();
   -        // ...
   +
   +        $text = $this->parseText($data);
   +
   +        return new CustomProviderResponse($text);
       }
   +
   +    private function parseText(string $plaintext): string
   +    {
   +        return $this->contentObjectRenderer->parseFunc($plaintext, [], '< lib.parseFunc_RTE');
   +    }
    }

   Copied!

Sources 

Example 1: Shared Presenter 

Assume that there are two modules Highlight Box and Highlight Text, which are both rendered using the same Handlebars template. The data provision is still done via two separate DataProviders.

In the Services.yaml file, we register both DataProcessors, but specify a concrete method call setPresenter(). This is normally called automatically if it is not set manually.

# Configuration/Services.yaml

services:
  Vendor\Extension\DataProcessing\HighlightBoxProcessor:
    tags: ['handlebars.processor']
    calls:
      - setPresenter: ['@Vendor\Extension\Presenter\HighlightPresenter']
  Vendor\Extension\DataProcessing\HighlightTextProcessor:
    tags: ['handlebars.processor']
    calls:
      - setPresenter: ['@Vendor\Extension\Presenter\HighlightPresenter']

Both DataProcessors are now injected with the same Presenter, while all other components continue to act independently.

Example 2: Shared DataProvider 

The same procedure can be used if a common DataProvider is to be used instead of a common Presenter. In this case the method call must be setProvider():

# Configuration/Services.yaml

services:
  Vendor\Extension\DataProcessing\HighlightBoxProcessor:
    tags: ['handlebars.processor']
    calls:
      - setProvider: ['@Vendor\Extension\Data\HighlightProvider']
  Vendor\Extension\DataProcessing\HighlightTextProcessor:
    tags: ['handlebars.processor']
    calls:
      - setProvider: ['@Vendor\Extension\Data\HighlightProvider']

Sources 

Custom Renderer 

The CPSIT\Typo3Handlebars\Renderer\Renderer interface describes a Renderer. A distinction must be made as to whether the custom Renderer is to be used for all components or only for individual variants.

# Configuration/Services.yaml

services:
  CPSIT\Typo3Handlebars\Renderer\Renderer:
    alias: 'Vendor\Extension\Renderer\AlternativeRenderer'

# Configuration/Services.yaml

services:
  Vendor\Extension\Presenter\MyCustomPresenter:
    arguments:
      $renderer: ['@Vendor\Extension\Renderer\AlternativeRenderer']

Custom TemplateResolver 

A standard TemplateResolver exists for resolving template paths for templates and partials. This is used in the default Renderer, but a custom TemplateResolver can also be used for specific purposes.

To use a custom TemplateResolver, a corresponding class is created that implements the CPSIT\Typo3Handlebars\Renderer\Template\TemplateResolver interface:

# Classes/Renderer/Template/AlternativeTemplateResolver.php

namespace Vendor\Extension\Renderer\Template;

use CPSIT\Typo3Handlebars\Renderer\Template\TemplateResolver;

class AlternativeTemplateResolver implements TemplateResolver
{
    /**
     * @var list<string>
     */
    private array $supportedFileExtensions = ['hbs', 'hbs.html'];

    public function getSupportedFileExtensions(): array
    {
        return $this->supportedFileExtensions;
    }

    public function supports(string $fileExtension): bool
    {
        return in_array(strtolower($fileExtension), $this->supportedFileExtensions, true);
    }

    public function resolveTemplatePath(string $templatePath): string
    {
        // ...
    }
}

This is then used in the Services.yaml file instead of the standard TemplateResolver:

# Configuration/Services.yaml

services:
  CPSIT\Typo3Handlebars\Renderer\Template\TemplateResolver:
    alias: 'Vendor\Extension\Renderer\Template\AlternativeTemplateResolver'

Sources 

Implementation options 

There are several ways to implement Helpers. To understand how Helpers are resolved in the Renderer, it is worth taking a look at the responsible Trait.

Basically every registered Helper must be callable. This means that both globally defined functions and invokable classes as well as class methods are possible. See what options are available in the following examples.

function greet(array $context): string
{
    return sprintf('Hello, %s!', $context['hash']['name']);
}

# Classes/Renderer/Helper/GreetHelper.php

namespace Vendor\Extension\Renderer\Helper;

use CPSIT\Typo3Handlebars\Renderer\Helper\Helper;

class GreetHelper implements Helper
{
    public function __invoke(array $context): string
    {
        return sprintf('Hello, %s!', $context['hash']['name']);
    }
}

# Classes/Renderer/Helper/GreetHelper.php

namespace Vendor\Extension\Renderer\Helper;

use CPSIT\Typo3Handlebars\Renderer\Helper\Helper;
use Vendor\Extension\Domain\Repository\PersonRepository;

class GreetHelper implements Helper
{
    private PersonRepository $repository;

    public function __construct(PersonRepository $repository)
    {
        $this->repository = $repository;
    }

    public function greetById(array $context): string
    {
        $name = (int)$this->getNameById($context['hash']['userId']);

        return sprintf('Hello, %s!', $name);
    }

    private function getNameById(int $userId): string
    {
        return $this->repository->findByUid($userId)->getName();
    }
}

Registration 

Helpers can be registered either via configuration in the Services.yaml file or directly via the Renderer (if the default Renderer is used).

# Configuration/Services.yaml

services:
  Vendor\Extension\Renderer\Helper\GreetHelper:
    tags:
      - name: handlebars.helper
        identifier: 'greet'
        method: 'greetById'

# Configuration/Services.yaml

services:
  handlebars.renderer_extended:
    parent: handlebars.renderer
    calls:
      # Global function
      - registerHelper: ['greet', 'greet']
      # or invokable class
      - registerHelper: ['greet', '@Vendor\Extension\Renderer\Helper\GreetHelper']

  CPSIT\Typo3Handlebars\Renderer\Renderer:
    alias: 'handlebars.renderer_extended'

{{ greet id=1 }}

$renderer->registerHelper(
    'greet',
    \Vendor\Extension\Renderer\Helper\GreetHelper::class . '::greetById'
);

Sources 

BeforeRenderingEvent 

This event is triggered directly before the compiled template is rendered along with the provided data. This allows the data to be manipulated once again before it is passed to the Renderer.

Example:

# Classes/EventListener/BeforeRenderingListener.php

namespace Vendor\Extension\EventListener;

use CPSIT\Typo3Handlebars\Event\BeforeRenderingEvent;

class BeforeRenderingListener
{
    public function modifyRenderData(BeforeRenderingEvent $event): void
    {
        $data = $event->getData();

        // Do anything...

        $event->setData($data);
    }
}

AfterRenderingEvent 

After the Renderer has completely rendered the template using the provided data, the AfterRenderingEvent is triggered. This can be used to subsequently influence the rendering result.

Example:

# Classes/EventListener/AfterRenderingListener.php

namespace Vendor\Extension\EventListener;

use CPSIT\Typo3Handlebars\Event\AfterRenderingEvent;

class AfterRenderingListener
{
    public function modifyRenderedContent(AfterRenderingEvent $event): void
    {
        $content = $event->getContent();

        // Do anything...

        $event->setContent($content);
    }
}

Sources 

Overview 

TYPO3 13+ provides the AssetCollector service as the recommended way to register frontend assets. The Handlebars extension fully supports this API through the assets configuration in HANDLEBARSTEMPLATE content objects.

Asset Types 

The AssetCollector API supports four distinct asset types, all fully supported by this extension:

1. External JavaScript Files - Link to external .js files
2. Inline JavaScript Code - Embed JavaScript directly in the page
3. External CSS Files - Link to external .css files
4. Inline CSS Code - Embed styles directly in the page

10 = HANDLEBARSTEMPLATE
10 {
    templateName = MyTemplate

    assets {
        javaScript {
            my-app-script {
                source = EXT:myext/Resources/Public/JavaScript/app.js
                attributes {
                    async = 1
                    defer = 1
                    crossorigin = anonymous
                }
                options {
                    priority = 1
                    useNonce = 1
                }
            }
        }
    }
}

assets {
    inlineJavaScript {
        my-inline-script {
            source = console.log('Hello from Handlebars'); initMyApp();
            attributes {
                type = module
            }
            options {
                priority = 1
            }
        }
    }
}

assets {
    css {
        my-styles {
            source = EXT:myext/Resources/Public/Css/styles.css
            attributes {
                media = screen and (max-width: 768px)
            }
            options {
                priority = 1
            }
        }
    }
}

assets {
    inlineCss {
        critical-css {
            source = body { margin: 0; padding: 0; } .container { max-width: 1200px; }
        }
    }
}

Configuration Reference 

Complete Examples 

page.20 = HANDLEBARSTEMPLATE
page.20 {
    templateName = MyPage

    variables {
        title = TEXT
        title.data = page:title
    }

    assets {
        # External JavaScript
        javaScript {
            app-script {
                source = EXT:myext/Resources/Public/JavaScript/app.js
                attributes {
                    defer = 1
                }
            }
        }

        # External CSS
        css {
            main-styles {
                source = EXT:myext/Resources/Public/Css/main.css
            }
        }
    }
}

page.20 = HANDLEBARSTEMPLATE
page.20 {
    templateName = MyPage

    assets {
        # High-priority critical CSS
        css {
            critical-styles {
                source = EXT:myext/Resources/Public/Css/critical.css
                options {
                    priority = 1
                }
            }
        }

        # Regular stylesheet with media query
        css {
            responsive-styles {
                source = EXT:myext/Resources/Public/Css/responsive.css
                attributes {
                    media = screen and (min-width: 768px)
                }
            }
        }

        # Inline critical CSS (highest priority)
        inlineCss {
            above-the-fold {
                source = body { font-family: sans-serif; } h1 { font-size: 2em; }
                options {
                    priority = 1
                }
            }
        }

        # Modern JavaScript module
        javaScript {
            app-module {
                source = EXT:myext/Resources/Public/JavaScript/app.js
                attributes {
                    type = module
                }
                options {
                    useNonce = 1
                }
            }
        }

        # Legacy fallback for older browsers
        javaScript {
            app-legacy {
                source = EXT:myext/Resources/Public/JavaScript/app.legacy.js
                attributes {
                    nomodule = 1
                    defer = 1
                }
            }
        }

        # Inline initialization code
        inlineJavaScript {
            app-init {
                source = window.APP_CONFIG = { apiUrl: '/api' };
                options {
                    priority = 1
                }
            }
        }
    }
}

assets {
    javaScript {
        cdn-library {
            source = https://cdn.example.com/library.js
            attributes {
                crossorigin = anonymous
                integrity = sha384-oqVuAfXRKap7fdgcCY5uykM6+R9GqQ8K/uxy9rx7HNQlGYl1kPzQho1wx4JwY8wC
                defer = 1
            }
        }
    }

    css {
        cdn-styles {
            source = https://cdn.example.com/styles.css
            attributes {
                crossorigin = anonymous
                integrity = sha384-T3c6CoIi6uLrA9TneNEoa7RxnatzjcDSCmG1MXxSR1GAsXEV/Dwwykc2MPK8M2HN
            }
        }
    }
}

Migration from Legacy Methods 

If you're using the legacy headerAssets or footerAssets configuration, consider migrating to the modern assets approach:

10 = HANDLEBARSTEMPLATE
10 {
    templateName = MyTemplate

    headerAssets = TEXT
    headerAssets.value = <script src="path/to/script.js"></script>

    footerAssets = TEXT
    footerAssets.value = <script>console.log('footer');</script>
}

10 = HANDLEBARSTEMPLATE
10 {
    templateName = MyTemplate

    assets {
        javaScript {
            my-script {
                source = EXT:myext/Resources/Public/JavaScript/script.js
            }
        }

        inlineJavaScript {
            footer-script {
                source = console.log('footer');
            }
        }
    }
}

Best Practices 

# Good: Namespaced identifier
my-extension-app-script {
    source = ...
}

# Bad: Generic identifier (may conflict with other extensions)
app {
    source = ...
}

# Critical inline CSS should have priority
inlineCss {
    critical {
        source = ...
        options.priority = 1
    }
}

# Regular stylesheets can have normal priority
css {
    theme {
        source = ...
        # No priority option = loaded after priority assets
    }
}

inlineJavaScript {
    inline-config {
        source = window.config = { /* ... */ };
        options.useNonce = 1
    }
}

# Modern browsers
javaScript {
    app-module {
        source = EXT:myext/Resources/Public/JavaScript/app.module.js
        attributes.type = module
    }
}

# Legacy browsers
javaScript {
    app-legacy {
        source = EXT:myext/Resources/Public/JavaScript/app.legacy.js
        attributes.nomodule = 1
    }
}

Troubleshooting 

# Use extension prefix to avoid conflicts
my-ext-my-script {
    source = ...
}

# Correct
attributes {
    async = 1        # Will output: async="async"
    defer = 1        # Will output: defer="defer"
}

# Incorrect - will not be output
attributes {
    async = 0        # Omitted from output
    defer =          # Omitted from output
}

See Also 

• TYPO3 AssetCollector Documentation
• TYPO3 AssetCollector API
• Using the Content Object Renderer

DataProvider (Model) 

• DataProvider

DataProviders are used to provide relevant data for processing by a DataProcessor. The data source is irrelevant: data can be provided both from local sources such as the TYPO3 database and from external sources such as APIs.

Thus, DataProviders fulfill the part of the Model in the MVC pattern. The data supplied is not necessarily only applicable to a specific template, but serves the general usability of all components involved in the rendering process of a parent module.

DataProcessor (Controller) 

• DataProcessor
• AbstractDataProcessor

DataProcessors are the entry point into the entire rendering process. They fetch the data from the DataProvider, process it and pass it on to the Presenter.

This is where the entire processing logic takes place. Thus, DataProcessors fulfill the part of the Controller in the MVC pattern. They are usually addressed directly via TypoScript.

Presenter (View transition) 

• Presenter
• AbstractPresenter

In Presenter, the supplied data is prepared for rendering a specific Handlebars template. Dependent templates can also be selected based on the supplied data if multiple template variants are possible.

In the MVC pattern, the Presenter takes on a transitional role between the DataProcessor (Controller) and the Renderer (View).

Renderer (View) 

• Renderer
• HandlebarsRenderer

The template is finally rendered in the Renderer. For this purpose, the template is compiled and filled with data from the Presenter. The resulting output is returned and completes the rendering process.

The Renderer is thus responsible for the View in the context of the MVC pattern. The compiled templates used for this are usually cached.

Helper (optional) 

• Helper

Helpers describe a simple way to bring custom PHP functionality to Handlebars templates. They are similar to ViewHelpers used in Fluid templates.

The default Renderer is able to handle various Helpers. There are few limitations to the successful use of Helpers:

• The associated callable (class method/function) must be publicly callable
• If the callable is a class method, it must be loadable by the registered PHP class autoloader

Helpers play a rather subordinate role in the MVC pattern, since they are not explicitly involved. However, since they are implicitly involved in the output of a template, they most likely take the role of the View.

TemplateResolver 

• TemplateResolver
• HandlebarsTemplateResolver

Whenever a template is rendered by the Renderer, it must first be resolved, e.g. by looking it up in all defined template root paths. It is necessary to define a TemplateResolver for each Renderer, because the Renderer itself is not able to resolve template paths.

The TemplateResolver is also used for resolving partials. However, since partials do not necessarily have to be used, defining a TemplateResolver for them is optional.

Configuration 

Tag each DataProcessor with handlebars.compatibility_layer within your Services.yaml file and provide additional information about the target extbase controller and actions supported by it.

# Configuration/Services.yaml

services:
  Vendor\Extension\DataProcessing\MyProcessor:
    tags:
      - name: handlebars.processor
      - name: handlebars.compatibility_layer
        type: 'extbase_controller'
        controller: 'Vendor\Extension\Controller\MyController'
        actions: 'dummy'

The action configuration can be either empty (= NULL) or set to a comma-separated list of action names that are supported by the configured DataProcessor. If you leave it empty, the DataProcessor is used for all controller actions.

Usage 

Once the HandlebarsViewResolver is triggered to render a specific "view", it creates an array of information and passes it to the configured DataProcessor. You can then take further steps based on the provided configuration.

When accessing the $configuration property inside your DataProcessor, you should see the following properties:

$configuration = [
    'extbaseViewConfiguration' => [
        'controller' => '<controller class>',
        'action' => '<controller action>',
        'request' => '<original extbase request>',
        'variables' => '<template variables>',
    ],
];

Sources 

Usage 

 # Classes/DataProcessing/HeaderProcessor.php

 namespace Vendor\Extension\DataProcessing;

 use CPSIT\Typo3Handlebars\DataProcessing\AbstractDataProcessor;

 class HeaderProcessor extends AbstractDataProcessor
 {
     protected function render(): string
     {
+        $this->initializeConfigurationManager();
         $data = $this->provider->get($this->cObj->data);
         return $this->presenter->present($data);
     }
 }

Sources 

Create an issue first 

Before you start working on the extension, please create an issue on GitHub: https://github.com/CPS-IT/handlebars/issues

Also, please check if there is already an issue on the topic you want to address.

Contribution workflow 

git clone https://github.com/CPS-IT/handlebars.git
cd handlebars

composer install

# All analyzers
composer analyze

# Specific analyzers
composer analyze:dependencies

# Run all linters
composer lint

# Run specific linters
composer lint:composer
composer lint:editorconfig
composer lint:php
composer lint:typoscript

# Fix all CGL issues
composer fix

# Fix specific CGL issues
composer fix:composer
composer fix:editorconfig
composer fix:php

# Run all static code analyzers
composer sca

# Run specific static code analyzers
composer sca:php

# All tests
composer test

# Specific tests
composer test:functional
composer test:unit

# All tests with code coverage
composer test:coverage

# Specific tests with code coverage
composer test:coverage:functional
composer test:coverage:unit

# Merge code coverage of all test suites
composer test:coverage:merge

open .Build/coverage/html/_merged/index.html

# Rebuild and open documentation
composer docs

# Build documentation (from cache)
composer docs:build

# Open rendered documentation
composer docs:open