README

此插件提供了一种通用的列表模块，可用于任意contao实体，包含标准列表处理，如分页、排序和筛选。

它可以使您生成列表，不仅限于事件、新闻或常见问题，还可以是您喜欢的任何DCA。

特性

• 用于任意contao实体的通用列表模块
• 支持所有形式的标准列表处理，如分页、排序、筛选
• 与筛选插件协同工作
• 可继承的列表配置
• 模板使用twig构建
• 支持Encore Bundle

使用方法

安装

1. 通过composer (composer require heimrichhannot/contao-list-bundle) 或 contao管理器安装
2. 更新您的数据库

建议

• 建议与Reader Bundle一起使用。
• 使用Encore Bundle来管理您的前端资源

使用方法

提示：您也可以在交互式命令中执行以下步骤来设置基本列表。只需在contao根目录中运行vendor/bin/contao-console huh-list:make即可。

1. 设置一个筛选器（参见Filter Bundle设置）
2. 创建一个列表配置（系统 -> 列表配置）
   • 要添加如图片、视频、滑块等列表元素，请添加列表配置元素（参见概念 -> 列表配置元素以获取解释）
   • 建议：为了提高性能，请检查您的列表配置中的“限制格式化字段”并仅选择您确实需要格式化的字段
3. 创建一个列表前端模块并在您想要的位置输出它

概念

可继承的列表配置

由于列表配置有时可能包含大量数据，我们决定将其外包到专门的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）。

文档

开发者文档