README

tags 扩展

tags 是一个 Contao 扩展，提供了一个架构来为任何 Contao 元素添加标签。它附带了一个通用的数据库结构来保存标签，并且可以用于可视化现有标签。tags 还提供了 Contao 文章、新闻文章和日历事件的预置标签支持。

开发者可以使用标签架构为他们的组件添加标签支持。该模块提供了一个数据容器实际数据容器的输入字段小部件，并支持从数据库中存储和检索标签。当启用 JavaScript 时，您还可以在后台标签输入字段中通过简单的鼠标点击添加和删除标签。

截图显示，标签 URL 的 HTML 标题属性包含标签名称和标记实体的数量，例如 Logging (2) 表示该标签 logging 在所选对象类型（在此例中为新闻文章）已被使用两次。

请注意，您只能在一个数据容器中使用一个标签输入字段，因为标签小部件使用父数据容器的数据源。

在 Contao 前端使用标签

Contao 模块 "标签云" 旨在在 Contao 前端展示标签云。它为给定的一组标签（例如数据容器）生成一个 HTML 列表。要将其作为标签云显示，您需要在您的站点 CSS 文件中定义相关的 CSS 选择器。tags 已经附带两个示例样式表 tags_oxygen.css 和 tags_orange.css，它们位于安装包的 tl_files/tags 目录中（或者如果您通过 Contao 扩展仓库安装了模块，则位于相同的目录中）。请将这些示例文件作为您自己的 CSS 定义的起点，因为在某些情况下，需要定义不可见的样式（例如 "Top 10 tags" 功能）。

数量和大小设置部分允许您定义标签云的一些基本布局设置。您可以通过标签云中显示的标签数量来限制显示的标签数量。0 的值始终显示所有可用的标签，大于 0 的值仅显示最频繁出现的标签。请注意，如果您不显示所有可用的标签，您应该为用户添加一个通知。标签大小数量限制了标签大小的 CSS 类选择器数量。默认值 4 为您的标签生成 4 种不同的 CSS 类样式（根据标签的出现频率）：size1、size2、size3 和 size4。如果您更改此数字，您需要在定义您的 CSS 文件时考虑这一点。使用标签类名添加为每个包含标签名称的标签添加一个额外的 CSS 类（空格被下划线替换）。这允许您使用 CSS 文件单独设置某些标签的样式。例如，标签体育活动将获得一个额外的 CSS 样式 sports_activity，您可以在 CSS 文件中将其更改为一个巨大的大小，如果您想突出显示此特定标签。

使用标签类名复选框为每个包含标签名称（仅将空白转换为下划线）的标签添加一个额外的CSS类名。这为您提供了为所选标签定义单独CSS样式的机会。

对于标签云的HTML代码生成，您可以从标签云模板组合框中选择一个模板。默认情况下这是mod_tagcloud模板。如果您想为标签云创建单独的模板，模板名称应以mod_tagcloud开头，例如mod_tagcloud_mine等。

显示相关标签在选中标签时向前端添加相关标签列表。这显示了与所选标签一起定义的所有标签及其频率。如果您点击相关标签，结果选择将缩小到包含所选标签和所选相关标签的所有数据库条目。相关标签视图仅在标签云模块集成在标签云超链接的目标页面时才有效。通常，您将标签云定位在左侧或右侧的列中，并将结果放在页面主要列中。

前10个标签添加一个包含仅前10个最常用标签的额外标签云。如果您激活了前10个标签，您将看到两个额外的选择

• 展开前10个标签：勾选此框以默认展开前10个标签。这仅在浏览器中启用JavaScript时才有效，否则前10个标签始终展开。
• 展开所有标签：勾选此框以默认展开主标签云。这仅在浏览器中启用JavaScript时才有效，否则主标签云始终展开。

在重定向设置部分，如果您想为标签云中的每个标签使用超链接，请选择一个目标页面。目标页面将通过带有URL参数tag=TAGNAME的URL调用，例如 http://www.mydomain.tld/destination.html?tag=contao 或 http://www.mydomain.tld/destination/tag/contao.html 如果您使用Contao URL重写。

保留URL参数保留新闻存档中的日期特定URL参数（对于实际时间段）。如果您在同一个页面上使用标签云作为新闻存档，所选时间段也将用于标签URL。

在数据源设置中，您需要选择用于生成标签云的Contao源表。如果您想显示新闻文章的标签，应勾选tl_news表。您可以使用仅适用于特定Contao对象的专用标签模块附加组件，例如tags_news、tags_articles或tags_events。使用这些模块，您不需要选择数据源。

专家设置仅在您使用自己的数据源为标签云提供数据时才应更改。如果您使用与标签模块一起提供的默认解决方案，请忽略此设置。开发者可以定义不同的数据库表和数据库表字段作为标签云的源。您还可以为您的标签云定义额外的CSS类或ID，以使用自定义CSS代码进行云样式化。

如果您一切都按照规定操作，您应该在您的页面上看到类似的输出

或者激活了前10个标签

或者激活了前10个标签和相关标签

如果显示多个标签云（前10个标签和所有标签），Contao会添加一个JavaScript，允许您展开或折叠标签云。如果没有JavaScript支持，标签始终展开。要使JavaScript工作，您必须使用示例CSS文件tags_oxygen.css或tags_orange.css中的CSS样式定义。

除了通用标签云模块之外，标签还包含五个其他专用标签云模块

• 标签云（文章）
• 标签云（新闻）
• 标签云（事件）
• 标签云（成员）
• 标签云（内容元素）

例如，在标签云（事件）中，您可以使用仅选定的日历来生成标签云，从而过滤标签。

标签扩展为以下Contao元素提供了默认标签支持：

• 新闻文章
• 文章
• 内容元素
• 日历事件
• 成员

使用标签云跳转到其他Contao模块

为了有效地使用标签云，您应该在标签云模块的重定向设置中输入目标页面。目标页面应包含标签云模块（如果您想使用相关标签）以及以下经过标签扩展修改的Contao模块之一：

• 模块新闻存档：显示所有带有选定标签的新闻文章。新闻存档的标题将显示选定的标签和选择数量。
• 模块新闻列表：显示所有带有选定标签的新闻文章。新闻存档的标题将显示选定的标签和选择数量。
• 模块全局文章列表：显示带有选定标签的文章列表。文章列表的标题将显示选定的标签和选择数量。
• 模块事件列表：显示所有选中日历的带有选定标签的事件。事件列表的标题将显示选定的标签和选择数量。
• 模块日历：显示所有带有选定标签的事件。当您更改默认日历模板时，输出事件的标签。
• 模块标签对象列表：显示带有指定标签的内容元素（页面、文章、内容元素）列表。

在前端显示分配的标签

对于新闻文章和文章，您可以在内容的底部显示分配的标签。因此，您可以在特定模块中检查“显示文章标签”或“显示新闻标签”选项，并选择标签超链接的目标页面。

忽略标签设置会忽略所有与标签相关的URL参数。这意味着使用此设置的新闻列表或其他模块不能按标签过滤。如果您在同一页面上有多个列表，但只想使特定列表按标签过滤，这将很有帮助。

这些标签设置适用于新闻阅读器、新闻存档和文章列表（标签）模块。文章列表（标签）模块仅在安装附加扩展标签_articles时才可用。

只有当您使用能够评估标签列表模板变量的模板时，才会显示额外的标签列表。您可以检查模板news_full_tags以获取更多详细信息。如果您将相关代码复制并粘贴到模板中，您可以将任何其他模板准备为使用此功能。

<?php if ($this->showTags): ?>
 
<?php if (count($this->taglist)): ?>
<ul class="tag-chain">
<?php $counter = 0; foreach ($this->taglist as $tag): ?>
<li class="tag-chain-item<?php if ($counter == 0) echo ' first'; ?>
<?php if ($counter == count($this->taglist)-1) echo ' last'; ?>
<?php if ($this->showTagClass) echo ' ' . $tag['class']; ?>"><?php echo $tag['url']; ?></li>
<?php $counter++; endforeach; ?>
</ul>
<?php endif; ?>
<?php endif; ?>

此输出的CSS样式已在示例CSS文件tags_orange.css和tags_oxygen.css中定义。您可以使用这些文件作为您自己的样式定义的基础。带有分配标签的新闻条目将如下所示：

对于日历模块，是否要在日历中显示事件的标签取决于您。要这样做，您需要修改默认日历模板cal_default或创建基于cal_default的模板。要显示标签，您可以访问相应事件的tags或字段，例如：

          <?php foreach ($day['events'] as $event): ?>
            <div class="event cal_<?= $event['parent'] ?><?= $event['class'] ?>">
              <a href="<?= $event['href'] ?>" title="<?= $event['title'] ?> (<?php if ($event['day']) echo $event['day'] . ', '; ?><?= $event['date'] ?><?php if ($event['time']) echo ', ' .  $event['time']; ?>)"<?= $event['target'] ?>><?= $event['link'] ?></a>
              <div>
              	<?php foreach ($event['taglist'] as $tagdata): ?>
              		<div class="<?= $tagdata['class'] ?>"><?= $tagdata['url'] ?></div>
              	<?php endforeach; ?>
              </div>
            </div>
          <?php endforeach; ?>

tags字段包含一个数组，其中包含事件的全部可用标签，例如：

Array(
  [0] => conference
  [1] => meeting
)

taglist字段包含一个数组，该数组包含标签的URL、标签名称和标签类，例如：

Array(
  [0] => Array(
    [url] => <a href=".../tags/conference.html">conference</a>
    [tag] => conference
    [class] => conference
  )
  [1] => Array(
    [url] => <a href=".../tags/meeting.html">meeting</a>
    [tag] => meeting
    [class] => meeting
  )
)

内容元素

标签扩展扩展了Contao的内容元素标题，并在专家设置中引入了额外的参数“仅显示带有标签的标题”。如果您选中此选项，Contao仅在内容页使用了至少一个标签时显示标题，例如如果页面是从标签云打开的。

您可以将此元素与插入标签{{tags_used}}结合使用，以显示针对您内容的具体标签标题，例如选定的参与者 {{tags_used}} => 选定的参与者 (国会+十月+纽约)

插入标签

tags向Contao添加以下插入标签：

• {{tags_used}}: 将被替换为使用的标签列表，例如 (Contao+Extension+tags)
• {{tags_news::news_id}}: 将被替换为分配给给定新闻文章的标签列表，例如 {{tags_news:1}} 显示ID为1的新闻文章的标签。
• {{tags_event::event_id}}: 将被替换为分配给给定日历事件的标签列表，例如 {{tags_event:1}} 显示ID为1的日历事件的标签。
• {{tags_article::article_id}}: 将被替换为分配给给定文章的标签列表，例如 {{tags_article:1}} 显示ID为1的文章的标签。
• {{tags_article_url::article_id}}: 将被替换为分配给给定文章的链接标签列表，例如 {{tags_article_url:1}} 显示ID为1的文章的标签，并将每个标签链接到包含文章的页面。
• {{tags_content::content_id}}: 将被替换为分配给给定内容元素的标签列表，例如 {{tags_content:1}} 显示ID为1的内容元素的标签。

额外的Contao模块

标签扩展包含以下新的Contao模块：

全局文章列表

全局文章列表显示给定选定标签的所有可用文章列表。

新闻模块的特殊设置

新闻模块新闻阅读器、新闻存档和新闻列表使用一个额外的参数来忽略所有标签设置。如果您页面上有多个模块，并且只想让一个模块能够通过选定的标签过滤其内容，这可能很有用。如果您在标签设置部分选中“忽略标签”选项，则模块将忽略任何与标签相关的操作。

新闻模块还包含一个标签过滤器，您可以在其中添加以逗号分隔的标签列表。默认情况下，模块的内容将通过输入的标签进行过滤。如果您只想显示带有特定标签的列表，这可能很有用。

标签对象列表

前端模块标签对象列表可以创建基于给定标签过滤的内容元素列表。可用的对象类型是三种内容元素类型：页面、文章和内容元素。如果存在标签，对象类型是将在生成的列表中显示和链接的元素，例如，对象类型页面创建指向Contao页面的URL列表，对象类型文章显示指向Contao文章的链接。

标签源定义了用于生成列表的标签源。例如，如果您选择tl_article，则仅考虑文章标签。

页面选择用于定义可用内容元素链接的根页面。只有指向此页面及其子页面的链接将被考虑在列表中。

示例

• 对象类型：页面
• 标签源：tl_article
• 页面：网站根目录

这会创建一个来自文章标签的页面链接列表。仅考虑所选网站上的链接。

扩展开发者提示

只想使用标签扩展的用户可以跳过以下段落。

为Contao数据容器添加标签支持

要在Contao后端添加标签支持，您需要完成以下步骤

1. 要显示标签输入字段，您必须在数据容器中创建一个数据库字段。由于标签保存在单独的表中，您只需要一个小数据库字段，但是您需要该字段将输入字段嵌入到数据容器中。所有标签都将保存在由标签扩展提供的数据库表tl_tag中。
2. 您需要在模块的DCA配置数组中嵌入输入字段

$GLOBALS['TL_DCA']['tl_literature']['palettes']['default'] = 'title,author,description,tags,content';

$GLOBALS['TL_DCA']['tl_literature']['fields']['tags'] = array
(
	'label'                   => &$GLOBALS['TL_LANG']['MSC']['tags'],
	'inputType'               => 'tag',
	'eval'                    => array('tl_class'=>'clr long'),
	'sql'                     => "char(1) NOT NULL default ''"
);

标签扩展已经提供了语言变量$GLOBALS['TL_LANG']['MSC']['tags']作为标签字段的默认标识符。当然，您可以将其更改为其他值。

在保存过程中的验证过程中，标签模块会自动将输入的标签保存到数据库表tl_tag中。对于每个标签，它存储实际数据容器的ID（表字段" id"）、数据容器的名称（表字段" from_table"）以及标签值（表字段" tag"）。

标签小部件eval数组的选项