README

一个扩展包，用于在contao中启用广泛的twig模板支持。只需激活模板加载器，您就可以像处理.html5模板一样处理twig模板。这意味着，您可以在contao后端的自定义模板选择中选中twig模板，并且可以覆盖项目模板文件夹或扩展包中的任何模板。作为开发者，您可以使用此扩展包像处理contao模板一样处理twig模板，例如使用简单的模板名称、模板组和依赖contao模板层次。

特性

在contao中启用twig支持
- 使用twig编写contao模板
- 在模块/元素自定义模板选择中选中twig模板，或在twig中覆盖默认模板
- 支持所有类型的模板，包括小工具
将此扩展包作为库使用，在您的扩展包中与twig模板一起使用广泛的模板加载器
使用缓存以实现快速性能（在开发模式下禁用）
最小依赖；)

使用说明

设置

通过contao管理器或composer安装

composer require heimrichhannot/contao-twig-support-bundle

您的第一个模板

如果您想使用此扩展包来启用contao以支持twig模板，您需要启用模板加载器。您只需将以下配置条目添加到您的config.yml中
```
# config/config.yml (Contao 4.9) or app/Resources/config/config.yml (Contao 4.4)
huh_twig_support:
    enable_template_loader: true
```
现在您可以将每个contao模板都创建为twig模板。例如，创建一个twig模板ce_text_custom.html.twig并将其添加到您的项目templates文件夹中（在contao 4.4中：app/Resources/views）。现在您可以在文本内容元素中选择该模板作为自定义模板（可能需要先清除缓存）。您还可以覆盖由parseTemplate和parseWidget钩子解析的任何核心模板。您还可以添加来自扩展包的模板（只需将它们放置在src/Resources/views中）。

小工具

如前所述，此扩展包还允许覆盖小工具模板。由于twig模板不是在默认的小工具/模板作用域中渲染的，因此您不能使用$this来获取变量。相反，twig支持扩展包传递小工具实例，因此您可以使用小工具对象来获取变量内容，例如{{ widget.name }}或{{ widget.class }}。

twig和contao注意事项

用户输入由contao编码，因此如果您需要输出HTML，您需要在变量中添加原始过滤器。

在contao 4.4中使用项目模板文件夹

如果您想在contao 4.4中也将项目模板文件夹用于，只需将以下行添加到您的config.yml中

# app/Ressouces/config/config.yml
twig:
  paths:
    '%kernel.project_dir%/templates': ~

跳过模板

可能存在其他扩展包带有与核心模板不兼容但具有相同名称的twig模板的情况。或者您可能不希望将某些模板作为twig模板处理。在这种情况下，您可以将它们添加到跳过模板配置中

huh_twig_support:
    skip_templates:
        - image
        - ce_no_twig
        - mod_html5_only

还有可能在BeforeParseTwigTemplateEvent中抛出SkipTemplateException以跳过模板。

开发者

事件

在您的扩展包中使用twig

如果您想在您的扩展包中使用twig，此扩展包是一个很好的基础。

模板定位器

使用TwigTemplateLocator服务来加载您的模板，您需要在的地方保留contao模板层次结构（您可以在项目模板文件夹中或在其他加载在该包之后的包中覆盖一个包模板）。

获取所有带有前缀的模板（如Controller::getTemplateGroup）：TwigTemplateLocator::getTemplateGroup()

class CustomContainer
{
    /**
     * @var HeimrichHannot\TwigSupportBundle\Filesystem\TwigTemplateLocator
     */
    protected $templateLocator;

    public function onTemplateOptionsCallback()
    {
        return $this->templateLocator->getTemplateGroup('subscribe_button_');
    }
}

从模板名称获取twig路径

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']);
}

模板渲染器

使用TwigTemplateRenderer服务通过模板名称渲染模板。渲染器在开发模式下添加模板注释，就像contao为html5模板所做的那样。有额外的配置选项可以自定义渲染器或渲染特定的twig模板，而不是使用模板定位器来获取模板名称的正确路径。如果您需要在渲染前后添加特定的逻辑，我们建议装饰服务。

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

您可以使用TwigFrontendTemplate类来处理twig模板，因为它是一个正常的contao前端模板对象。它继承自contao FrontendTemplate类，可以用于在contao上下文中渲染twig模板并使用所有钩子和模板类函数。

use HeimrichHannot\TwigSupportBundle\Template\TwigFrontendTemplate;

$template = new TwigFrontendTemplate('my_custom_template');
$template->setData(['foo' => 'bar']);
return $template->getResponse();

配置参考

# 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

致谢

感谢m-vo和他的Twig Bundle，该包的实现是本包的灵感和初始基础。

heimrichhannot / contao-twig-support-bundle

维护者

详细信息