Ecosyste.ms: Awesome
An open API service indexing awesome lists of open source software.
https://github.com/heimrichhannot/contao-twig-support-bundle
This bundle adds twig template support to contao.
https://github.com/heimrichhannot/contao-twig-support-bundle
contao twig
Last synced: about 1 month ago
JSON representation
This bundle adds twig template support to contao.
- Host: GitHub
- URL: https://github.com/heimrichhannot/contao-twig-support-bundle
- Owner: heimrichhannot
- License: lgpl-3.0
- Created: 2020-09-15T14:27:00.000Z (over 4 years ago)
- Default Branch: master
- Last Pushed: 2024-10-01T14:22:07.000Z (3 months ago)
- Last Synced: 2024-11-09T14:46:29.550Z (about 2 months ago)
- Topics: contao, twig
- Language: PHP
- Homepage:
- Size: 191 KB
- Stars: 1
- Watchers: 4
- Forks: 2
- Open Issues: 3
-
Metadata Files:
- Readme: README.md
- Changelog: CHANGELOG.md
- License: LICENSE
Awesome Lists containing this project
README
# Contao Twig Support Bundle
[](https://packagist.org/packages/heimrichhannot/contao-twig-support-bundle)
[](https://packagist.org/packages/heimrichhannot/contao-twig-support-bundle)
[](https://github.com/heimrichhannot/contao-twig-support-bundle/actions/workflows/ci.yml)
[](https://coveralls.io/github/heimrichhannot/contao-twig-support-bundle)
A bundle to enable extensive [twig](https://twig.symfony.com/) templates support in contao. Just activate the template loader and you can work with twig templates as they were .html5 templates. This means, you can select twig templates in the custom template select in the contao backend and you can override any template in your project template folder or in a bundle.
As a developer, you can use this bundle to work with twig templates like with contao templates, e.g. use simple template names, template groups and rely on the contao template hierarchy.
## Features
* enable twig support in contao
* use twig to write contao templates
* select twig templates in your module/element custom template selection or override default templates in twig
* support for all types of templates including widgets
* use this bundle as library to work with twig templates in your own bundles with extensive template loader
* uses caching for fast performance (is disabled in dev mode)
* minimal dependencies ;)
## Usage
### Setup
Install via contao manager or composer:
composer require heimrichhannot/contao-twig-support-bundle
### Your first template
1. If you want to use this bundle to enable contao to support twig templates, you need to enable the template loader. You just need to add following configuration entries to your config.yml:
```yaml
# config/config.yml (Contao 4.9) or app/Resources/config/config.yml (Contao 4.4)
huh_twig_support:
enable_template_loader: true
```
1. Now you can create every contao template as twig template. For example create a twig template `ce_text_custom.html.twig` and add it to your projekt `templates` folder (in contao 4.4: `app/Resources/views`). Now you can select the template as custom Template in the text content element (maybe you need to clear the cache before). You can override every core template that is parsed by `parseTemplate` and `parseWidget` hook. You can also add templates from bundles (just place them in `src/Resources/views`).
### Widgets
As already written, this bundle also allows overriding widget templates. Since twig templates are not rendered in the default widget/template scope as contao templates, you can't use `$this` to get variables. Instead, twig support bundle passes the widget instance, so you can use the widget object to get the variable content, for example `{{ widget.name }}` or `{{ widget.class }}`.
### Twig and contao cavets
User input is encoded by contao, so you need to add the raw filter to variables if you need to output html.
### Use project templates folder for twig templates in contao 4.4
If you want to use the project templates folder also in contao 4.4, just add following lines to your config.yml:
```yaml
# app/Ressouces/config/config.yml
twig:
paths:
'%kernel.project_dir%/templates': ~
```
### Skip templates
It may the be case, that other bundle comes with twig templates that are incompatible with core template but have the same name. Or you don't want to process some templates as twig templates. In this case you can add them to the skip templates configuration:
```yaml
huh_twig_support:
skip_templates:
- image
- ce_no_twig
- mod_html5_only
```
There is also a `SkipTemplateException` that could be thrown in the `BeforeParseTwigTemplateEvent` to skip a template.
## Developers
### Events
Event | Description
----- | -----------
BeforeParseTwigTemplateEvent | Dispatched after twig templates was found. Throw a `SkipTemplateException` to skip the curent template to be processed as twig template.
BeforeRenderTwigTemplate | Dispatched before twig templates is rendered.
### Use twig in your bundle
This bundle is a great base if you want to use twig in your own bundles.
#### Template locator
Use the `TwigTemplateLocator` service to load your templates, where you need them while keeping the contao template hierarchy (you can override a bundle template in your project template folder or in another bundle which is loaded after the bundle).
Get all Templates with prefix (like Controller::getTemplateGroup): `TwigTemplateLocator::getTemplateGroup()`
```php
class CustomContainer
{
/**
* @var HeimrichHannot\TwigSupportBundle\Filesystem\TwigTemplateLocator
*/
protected $templateLocator;
public function onTemplateOptionsCallback()
{
return $this->templateLocator->getTemplateGroup('subscribe_button_');
}
}
```
Get the twig path from an template name:
```php
use HeimrichHannot\TwigSupportBundle\Filesystem\TwigTemplateLocator;
use Twig\Environment;
function showTemplateLocatorUsage(TwigTemplateLocator $templateLocator, Environment $twig) {
$twigTemplatePath = $templateLocator->getTemplatePath('my_custom_template');
$buffer = $twig->render($twigTemplatePath, ['foo' => 'bar']);
}
```
#### Template renderer
Use the `TwigTemplateRenderer` service to render a template by template name. The renderer adds template comments in dev mode as contao does for html5 templates. There are additional config options to customize the renderer or render a specific twig template instead of using the template locator to get the correct path to an template name. If you need to add specific logic applied before or after rendering, we recommend to [decorate the service](https://symfony.com/doc/current/service_container/service_decoration.html).
```php
use HeimrichHannot\TwigSupportBundle\Renderer\TwigTemplateRenderer;
use HeimrichHannot\TwigSupportBundle\Renderer\TwigTemplateRendererConfiguration;
class MyCustomController {
/** @var TwigTemplateRenderer */
protected $twigTemplateRenderer;
public function renderAction(string $templateName = 'mod_default', array $templateData = []): string
{
$buffer = $this->twigTemplateRenderer->render($templateName, $templateData);
// Or pass some configuration:
$configuration = (new TwigTemplateRendererConfiguration())
->setShowTemplateComments(false)
->setTemplatePath('@AcmeBundle/module/mod_custom.html.twig')
->setThrowExceptionOnError(false);
return $this->twigTemplateRenderer->render($templateName, $templateData, $configuration);
}
}
```
#### TwigFrontendTemplate
You can use the `TwigFrontendTemplate` class to work with a twig template as it's a normal contao frontend template object. It inherits from the contao FrontendTemplate class and can be used to render twig template in contao context and use all hooks and template class functions.
```php
use HeimrichHannot\TwigSupportBundle\Template\TwigFrontendTemplate;
$template = new TwigFrontendTemplate('my_custom_template');
$template->setData(['foo' => 'bar']);
return $template->getResponse();
```
## Configuration reference
```yaml
# Default configuration for extension with alias: "huh_twig_support"
huh_twig_support:
# Enable twig templates to be loaded by contao (enabled overriding core templates and select twig templates in the contao backend).
enable_template_loader: false
# Template names that should be skipped by the template loader.
skip_templates:
# Examples:
- image
- ce_no_twig
- mod_html5_only
# Template cache lifetime in seconds with a value 0 causing cache to be stored indefinitely (i.e. until the files are deleted).
template_cache_lifetime: 0
```
## Credits
* thanks to [m-vo](https://github.com/m-vo) and his [Twig Bundle](https://github.com/m-vo/contao-twig) which implementation was in inspiration and inital basis for this bundle.