作为安企CMS的使用者，我们都希望能够高效、灵活地控制网站内容的呈现方式。安企CMS在这方面做得非常出色，它提供了一套既直观又强大的模板引擎语法，让我们可以轻松实现多样化的内容显示需求。

安企CMS模板引擎基础：Django风格，易学易用

安企CMS的模板引擎采用了类似Django语法的标记方式，这使得有其他模板引擎使用经验的朋友能够快速上手。它的设计理念就是力求简洁高效，即便您是第一次接触，也能在短时间内掌握其核心用法。

在安企CMS的模板文件中，有两种主要的语法结构：

  1. 变量输出：{{ 变量名 }} 这是最常见的用法，用于在页面上显示动态数据。比如，您想在网页上展示文章的标题，只需在模板中写入 {{ archive.Title }}。双花括号内放置的是要显示的数据变量，系统会自动将其替换为实际的内容。这种方式直接明了，让数据呈现变得异常简单。

  2. 逻辑控制与标签：{% 标签名 参数 %} 和 {% 结束标签 %} 当我们需要在模板中实现条件判断、循环遍历、数据获取等更复杂的逻辑时，就会用到单花括号和百分号组合的标签语法。这类标签通常成对出现，拥有明确的开始和结束标记，例如 {% if 条件 %}...{% endif %} 用于条件判断，{% for item in 列表 %}...{% endfor %} 用于循环输出列表数据。这种结构清晰地界定了逻辑作用范围，有效避免了混淆。

强大的内置标签：获取各类内容与功能

安企CMS内置了一系列功能丰富的标签，这些标签是实现内容动态显示的核心工具。它们能帮助我们从数据库中获取系统设置、文章列表、分类信息，甚至是用户评论等各种数据，并按照我们设定的规则进行展示。

例如，当您需要在首页展示最新文章列表时，{% archiveList archives with type="list" limit="10" %} 标签就能帮您动态获取并展示这些内容。如果您想构建网站导航菜单，{% navList navs %} 标签能够便捷地拉取后台配置的导航数据。在文章详情页，{% archiveDetail with name="Content" %} 则能轻松调出文章主体内容。

值得一提的是，这些标签往往支持丰富的参数，如 categoryId（分类ID）、moduleId（模型ID）、order（排序方式）、limit（显示数量）等，让我们可以精准地控制数据的来源和呈现规则。此外，{% with 变量名="值" %} 标签还允许您在模板中临时定义变量，这在传递数据给include等辅助标签时非常实用，有助于保持代码的整洁和模块化。

对于日期和时间的显示，安企CMS也提供了便捷的工具。{{ stampToDate(时间戳, "格式") }} 这个函数允许您将数据库中存储的时间戳数据，按照您需要的任何日期时间格式（例如 “2006-01-02 15:04”）进行美化输出，无需手动转换。

灵活的过滤器：美化与处理数据

除了直接输出和逻辑控制，安企CMS的模板引擎还提供了“过滤器”功能，让您能在数据最终显示前对其进行精细化的处理和美化。过滤器通过 | 符号作用于变量之后，可以链式使用，非常灵活。

以下是一些常用的过滤器及其用途：

  • |safe: 当您需要显示包含HTML标签的内容（如文章正文）而不想让这些标签被转义时，|safe 过滤器是您的首选。它会告诉浏览器这部分内容是安全的，可以直接解析为HTML。
  • |truncatechars:数字 或 |truncatewords:数字: 这两个过滤器常用于截断过长的文本，并在末尾添加省略号。前者按字符数截断，后者按单词数截断，非常适合在列表或摘要中显示简介内容。
  • |default:"默认值": 当某个变量可能为空或不存在时，您可以使用 |default 过滤器为其提供一个备用值，避免页面出现空白或错误信息。
  • |join:"分隔符" 和 |split:"分隔符": |join 用于将数组元素用指定的分隔符连接成字符串，而 |split 则能将字符串按分隔符切割成数组，这在处理如标签、关键词等列表数据时非常有用。
  • |date:"格式": 与 stampToDate 类似，|date 过滤器可以将 time.Time 类型的日期对象格式化为指定字符串，同样采用Go语言的时间格式化规则。

辅助标签：构建模块化与可复用的模板

为了提高模板的可维护性和可复用性，安企CMS引入了几种辅助标签，鼓励模块化开发：

  • {% include "模板文件" %}: 允许您将一个模板文件（例如页头、页脚或侧边栏）的内容嵌入到另一个模板中，避免重复编写代码。
  • {% extends "基础模板" %} 和 {% block 名称 %}: 这是一套强大的模板继承机制。您可以创建一个包含通用页面结构（如页头、页脚、侧边栏）的“基础模板”，然后其他页面通过 {% extends %} 继承它。通过 {% block %} 定义可覆盖的区域，子模板可以重写这些区域，从而在保持整体一致性的同时，实现局部内容的定制。
  • {% macro 名称(参数) %}: 宏（Macro）类似于函数，它允许您定义可重复使用的代码片段。宏可以接受参数，并在模板中像调用函数一样使用，极大地提升了代码的复用性。
  • {% lorem %}: 在模板开发初期，如果缺乏真实数据，{% lorem %} 标签可以快速生成占位文本，帮助您调整页面布局和样式。
  • {%- 和 -%}: 这些特殊的标记用于控制模板渲染时的空白字符。通过在标签的左右加上短横线，可以消除标签本身及其周围产生的多余换行或空格，让生成的HTML代码更加紧凑。

总结

安企CMS的模板引擎语法设计巧妙，兼顾了灵活性和易用性。无论是简单的内容展示，还是复杂的逻辑控制，亦或是高效的模块化开发，它都提供了全面而直观的解决方案。熟悉这些语法和标签，将大大提升您在安企CMS上进行网站内容运营和页面定制的效率，让您的网站内容以最符合预期的形式呈现给用户。

常见问题 (FAQ)

1. 我在模板中使用了 {{ 变量 }} 或 {% 标签 %} 但它没有显示内容，或者显示了错误信息，这是为什么？

遇到这种情况，通常有几个可能的原因：

  • 变量名或标签名拼写错误： 安企CMS的模板引擎对大小写是敏感的，请仔细核对变量名或标签名是否与文档中或后台定义的一致。例如，{{ Archive.Title }} 和 {{ archive.title }} 可能指向不同的数据。
  • 数据未传递到模板： 有些变量或列表数据需要在后端逻辑中显式地传递给模板才能使用。如果您正在自定义模板，请确保相关数据已经从后端控制器正确地传递了过来。
  • 变量值为空： 即使变量名正确，如果该变量在当前上下文中没有值，模板渲染时也可能显示空白。您可以尝试使用 |default:"备用内容" 过滤器来提供一个默认值，便于调试和用户体验。
  • 标签使用方式错误： 特别是逻辑控制标签（如 if 和 for），它们通常需要成对出现，并且参数格式必须正确。例如，for 循环后需要有 {% endfor %}。

2. 我想在模板中显示文章内容，但是 HTML 标签（如 <b>、<p>）被直接显示为文本而不是被浏览器解析，我该怎么做？

这是模板引擎出于安全考虑，默认对所有输出内容进行HTML转义的结果，旨在防止跨站脚本攻击（XSS）。如果您确定要显示的内容是安全的，并且希望浏览器将其解析为HTML，您可以使用 |safe 过滤器。例如，将 {{ archive.Content }} 修改为 {{ archive.Content|safe }} 即可。请务必确认内容来源可靠，以避免引入安全风险。

3. 如何在不同页面使用不同的模板布局，例如有些页面需要侧边栏，有些则不需要？

安企CMS支持模板继承和自定义模板文件。

  • 模板继承： 您可以创建一个名为 base.html 的基础模板，定义网站的通用结构（如页头、页脚），并使用 {% block 内容区域 %}{% endblock %} 标记出可变区域。然后，您的其他页面模板（如 index.html、detail.html）通过 {% extends "base.html" %} 继承它，并只重写（覆盖）那些 block 区域来定义其独特的内容，从而实现不同布局。
  • 自定义模板文件： 对于特定内容模型（如文章、分类、单页面），安企CMS允许您在后台指定使用不同的模板文件。例如，为“关于我们”单页面设置 page/about.html 作为其专属模板