AnQiCMS模板中如何正确使用双花括号`{{}}`和百分号`{% %}`标签控制内容的显示逻辑？

在使用安企CMS（AnQiCMS）构建和管理网站时，灵活运用模板语言是提升效率和实现个性化展示的关键。其中，双花括号 {{}} 和百分号标签 {% %} 是模板文件中控制内容显示逻辑的两位核心“角色”。它们各自承担着不同的职责，理解并正确使用它们，能帮助您轻松驾驭AnQiCMS的强大模板功能。

一、内容的“发声筒”：双花括号 {{}} 的妙用

双花括号 {{}} 的主要作用是输出变量的内容。当您需要在网页上直接展示来自后台数据或模板中定义的变量时，{{}} 就派上了用场。它们就像一个传声筒，将变量所承载的信息原封不动地“喊”出来。

最常见的用法是输出页面的标题、文章内容或系统设置：

<title>{{tdk.Title}}</title>
<h1>{{archive.Title}}</h1>
<img src="{{system.SiteLogo}}" alt="{{system.SiteName}}" />

在这里，tdk.Title、archive.Title、system.SiteLogo 和 system.SiteName 都是从AnQiCMS后台获取的变量。

更强大的是，{{}} 可以与过滤器（Filters）结合使用，对输出内容进行格式化和处理。例如，您可能需要格式化日期、截断过长的文本，或者进行大小写转换：

<span>发布日期：{{item.CreatedTime | stampToDate("2006-01-02")}}</span>
<p>{{item.Description | truncatechars:100}}</p>
<div>{{item.Title | upper}}</div>
  • stampToDate("2006-01-02") 过滤器将时间戳 item.CreatedTime 格式化为“年-月-日”的字符串。
  • truncatechars:100 过滤器会将 item.Description 截断为最多100个字符，并附加省略号。
  • upper 过滤器则将 item.Title 中的所有英文字母转换为大写。

需要特别注意的是，出于安全考虑，{{}} 默认会自动转义 HTML 标签和 JavaScript 代码，以防止跨站脚本攻击（XSS）。如果您确定某个变量的内容是安全的HTML，并且希望它能被浏览器解析而不是作为纯文本显示，可以使用 |safe 过滤器：

<div>{{archive.Content | safe}}</div>

这在显示文章详情、富文本编辑器内容等场景中非常有用。

二、逻辑的“指挥棒”：百分号标签 {% %} 的艺术

与用于内容输出的 {{}} 不同，百分号标签 {% %} 主要用于控制模板的逻辑流和行为。它们不会直接输出内容，而是执行一系列指令，如条件判断、循环遍历、引入其他模板文件或调用AnQiCMS提供的各种数据标签。所有 {% %} 标签都需要成对出现，即有一个起始标签和一个对应的结束标签（如 {% if %} 对应 {% endif %}）。

  1. 条件判断：{% if %} 掌控内容的显示逻辑 当您需要根据特定条件来决定是否显示某段内容时，{% if %} 标签是您的首选。它支持 elif（否则如果）和 else（否则）结构，让逻辑判断更加灵活。

    {% if item.Thumb %}
    <img src="{{item.Thumb}}" alt="{{item.Title}}" />
{% else %}
    <img src="/static/images/default-thumb.png" alt="无缩略图" />
{% endif %}

    这段代码判断如果 item.Thumb 变量存在，就显示对应的缩略图；否则，显示一张默认的图片。

  2. 循环遍历：{% for %} 动态生成列表 对于列表数据（如文章列表、分类列表、导航菜单），{% for %} 标签能够遍历数组或集合，为每个元素生成重复的HTML结构。它还可以与 {% empty %} 结合，处理列表为空的情况。

    {% archiveList archives with type="page" limit="10" %}
    {% for item in archives %}
    <li>
        <a href="{{item.Link}}">{{item.Title}}</a>
        <span>浏览量：{{item.Views}}</span>
    </li>
    {% empty %}
    <li>目前还没有任何文章发布。</li>
    {% endfor %}
{% endarchiveList %}

    这里，archiveList 是一个AnQiCMS的自定义标签，用于获取文章列表。{% for item in archives %} 则遍历这个列表，生成每个文章的链接和标题。如果 archives 为空，则显示 {% empty %} 中的内容。

  3. 自定义标签：AnQiCMS 强大功能的入口 AnQiCMS提供了丰富的自定义标签，让您无需编写复杂的数据库查询，即可轻松获取各种数据。这些自定义标签都是通过 {% %} 来调用的，例如：

    • 获取分类列表：{% categoryList %}

      {% categoryList categories with moduleId="1" parentId="0" %}
    <ul>
        {% for category in categories %}
            <li><a href="{{category.Link}}">{{category.Title}}</a></li>
        {% endfor %}
    </ul>
{% endcategoryList %}

      这段代码会获取文章模型（moduleId=1）下的所有顶级分类（parentId=0），并循环显示它们的名称和链接。

    • 获取系统配置：{% system %}

      <p>版权所有：{% system with name="SiteCopyright" %}</p>

      直接获取后台配置的版权信息。

  4. 变量声明：{% with %} 和 {% set %} 简化模板 当您需要在模板中定义临时变量来存储数据或简化表达式时，可以使用 {% with %} 或 {% set %}。

    {% with greeting="你好，世界！" %}
    <p>{{greeting}}</p>
{% endwith %}


{% set todayDate = now("2006-01-02") %}
<p>今天是：{{todayDate}}</p>

  5. 模板组织：{% include %} 和 {% extends %} 提升可维护性 为了提高模板的可重用性和可维护性，AnQiCMS支持模板的拆分和继承。

    • {% include "partial/header.html" %}：将一个公共的模板片段（如头部导航、页脚）引入到当前模板中。
    • {% extends 'base.html' %}：允许您定义一个基础布局（骨架模板），其他页面模板通过继承它并重写特定区块（{% block %}）来构建页面，避免重复编写大量代码。
    <!-- base.html (骨架模板) -->
<!DOCTYPE html>
<html>
<head>
    <title>{% block title %}默认标题{% endblock %}</title>
</head>
<body>
    {% include "partial/header.html" %}
    <div id="content">
        {% block content %}
            <!-- 页面内容将在此处插入 -->
        {% endblock %}
    </div>
    {% include "partial/footer.html" %}
</body>
</html>


<!-- index.html (继承 base.html) -->
{% extends 'base.html' %}


{% block title %}首页 - 我的网站{% endblock %}


{% block content %}
    <h1>欢迎来到我的首页！</h1>
    <p>这是首页的专属内容。</p>
{% endblock %}

三、使用这些标签的黄金法则

掌握 AnQiCMS 模板标签，除了了解其功能外，还需要注意一些通用的原则：

  1. 严格区分大小写：AnQiCMS 的模板变量和标签名都是大小写敏感的。item.Title 和 item.title 会被视为两个不同的变量。
  2. 标签成对出现：所有 {% %} 标签，如 {% if %}、{% for %}、{% with %} 等，都需要有对应的结束标签，如 {% endif %}、{% endfor %}、{% endwith %}。
  3. 清理空白行：默认情况下，模板引擎在解析 {% %} 逻辑标签时，可能会输出标签所在行产生的空白符。为了避免不必要的空白行影响页面布局，可以在标签内部的前后使用 - 符号，如 {%- if %} 或 {% endif -%}。
  4. 理解上下文：不同的页面（如首页、文章详情页、分类列表页）或不同的自定义标签（如 archiveList、categoryList）会提供不同的变量上下文。确保您在当前语境中访问的变量是存在的。

通过深入理解 {{}} 和 {% %} 这两种核心标签，您将能够更高效、更灵活地使用AnQiCMS来构建和维护您的网站模板，实现丰富多样的内容展示和功能。

常见问题 (FAQ)

  1. 为什么我的 {{变量}} 输出的是 HTML 代码而不是解析后的内容？ 这是AnQiCMS模板引擎的默认安全机制，为了防止XSS攻击，它会自动转义HTML标签。如果您确定要输出的HTML内容是安全的，并且希望浏览器将其解析渲染，您需要使用 |safe 过滤器。例如：{{ archive.Content | safe }}。

  2. 为什么我在模板中引用 {{变量}} 时，有时会显示空白，而不是我期望的内容？ 这通常有几个原因：

    • 变量名拼写错误：请仔细检查变量名是否与文档或实际数据结构中的一致，包括大小写。
    • 变量在当前上下文中不存在：某些变量只在特定页面类型或特定自定义标签的循环中可用。例如，item.Title 仅在 {% for item in list %} 循环中有效