README

此包提供了一个通用的阅读器模块，可用于任意contao实体，并包含标准阅读器特定功能，如字段输出、图片和自动项目处理。

这使得除了事件、新闻或常见问题之外，还可以为每个DCA生成阅读器。

功能

• 通用阅读器模块：输出任意DCA实体的实体
• 专用且可继承的阅读器配置实体，可以分配给一个或多个模块
• 支持模板的twig
• Head Bundle 支持

提示：此模块可以与 heimrichhannot/contao-list-bundle 一起使用，后者可以显示任意DCA实体的列表

印象

阅读器配置

概念

可继承的阅读器配置

由于有时读者配置可能会包含大量数据，我们决定将其外包到专用的DCA实体中。这些实体可以以可重用的方式分配给一个或多个阅读器模块。

此外，还可以创建继承自其他读者配置的读者配置。因此，在保持其他一切不变的情况下，可以覆盖单个选项。

项目类

在阅读器中输出的每个数据库记录（例如事件）都由 Item 类建模和包装。具体类是 DefaultItem。您可以将项目想象为一种ORM（对象关系映射）。

项目最重要的属性是 raw 和 formatted 数组，这些数组也可以在阅读器项目模板中迭代

• raw：包含原始数据库值
• formatted：包含原始值的格式化表示

示例：假设一个数据库记录有一个字段 startDate，它包含在后台选择日期的Unix时间戳。那么 raw 包含这个Unix时间戳，而 formatted 包含根据contao设置中设置的 dateFormat 美化打印的日期，即 "2020-09-12"。

阅读器包使用 heimrichhannot/contao-utils-bundle 中的 FormUtil::prepareSpecialValueForOutput() 方法来处理特殊值。它支持广泛的特殊值类型

• 日期/时间字段
• 数组
• 具有 options、options_callback 和 DCA 的 reference 键中的条目的字段
• 二进制字段（文件、图像等）
• ...

您可以在您的阅读器项目twig模板中以通常的方式访问这两个数组

{% for field, value in raw %}
{% endfor %}

{% for field, value in formatted %}
{% endfor %}

注意：默认情况下，数据库记录的所有值都进行了格式化并可在项目模板中访问。如您所想，如果某些字段有数千个选项，则格式化过程可能需要一些时间，并可能降低您网站的性能。因此，您始终应限制格式化字段，并且仅格式化您真正需要的字段。您可以在阅读器配置（字段 limitFormattedFields）中调整此设置。

为了方便起见，您还可以在您的twig模板中像这样访问字段值

{{ fieldname }}

如果您配置了字段 fieldname 以进行格式化，则它将包含格式化值。如果没有，则包含原始值。如果它已格式化，您还可以使用以下方式访问其原始值

{{ raw.fieldname }}

阅读器配置元素

每个读者配置可以包含一个或多个读者配置元素。这些元素旨在指定可能多次发生的事情（例如，因为存在许多同一类型的字段）。

当前内置的读者配置元素类型

其他包也可以添加读者配置元素。以下是一些示例

• 通过聚合类型包进行聚合
• 通过视频包增强视频

图像

您可以将图像作为格式化值添加，如果您还希望具有图像大小处理或未设置图像时的自动占位符等附加功能，您可以使用图像读取配置元素。

配置完成后，您可以在项目模板中按如下方式输出

{% if images|default and images.myImage|default %}
    {{ include('@HeimrichHannotContaoUtils/image.html.twig', images.myImage) }}
{% endif %}

重要：请注意，默认情况下，生成的图像元素被添加到名为images的数组中。如果您的DCA包含具有相同名称的字段，您需要指定不同的容器名称，例如resizedImages（使用overrideTemplateContainerVariable）。

模板

定义模板有两种方式。

1. 通过前缀

第一种方式是在任何templates或包的views目录中简单地部署twig模板，以下为前缀

• reader_item_
• item_
• news_
• event_

可以定义更多前缀，请参见第二种方式。

2. 通过config.yml

第二种方式是扩展config.yml并定义一个严格的模板

Plugin.php

<?php

class Plugin implements BundlePluginInterface, ExtensionPluginInterface
{
    /**
     * {@inheritdoc}
     */
    public function getBundles(ParserInterface $parser)
    {
        …
    }

    /**
     * {@inheritdoc}
     */
    public function getExtensionConfig($extensionName, array $extensionConfigs, ContainerBuilder $container)
    {
        return ContainerUtil::mergeConfigFile(
            'huh_reader',
            $extensionName,
            $extensionConfigs,
            __DIR__ .'/../Resources/config/config.yml'
        );
    }
}

config.yml

huh:
    reader:
        templates:
            item:
                - { name: default, template: "@HeimrichHannotContaoReader/reader_item_default.html.twig" }
            item_prefixes:
                - reader_item_
                - item_
                - news_
                - event_

开发者

事件

阅读器配置元素

添加新的读者配置元素很容易。

1. 创建一个实现了HeimrichHannot\ConfigElementTypeBundle\ConfigElementType\ConfigElementTypeInterface的类

2. 将类作为具有服务标签huh.reader.config_element_type的服务进行注册

3. 将友好的类型名称（翻译）添加到$GLOBALS['TL_LANG']['tl_reader_config_element']['reference']变量中

   $lang['reference'][\HeimrichHannot\ReaderBundle\ConfigElementType\CommentConfigElementType::getType()] = 'Comment';