如何获取和显示指定文档的自定义参数（如作者、来源）？

在使用安企CMS管理您的网站内容时，您可能会发现仅仅依靠默认的标题、内容、摘要等字段无法完全满足个性化的展示需求。例如，您希望在文章详情页显示“作者”和“来源”信息，或者在产品页面展示“材质”和“尺寸”等特定参数。安企CMS提供了强大的自定义参数功能，让您可以轻松地为不同类型的文档（如文章、产品）添加、管理并显示这些个性化信息。

本文将详细介绍如何在安企CMS中获取和显示指定文档的自定义参数，如作者、来源等，帮助您打造更加丰富和定制化的内容展示。

一、在后台配置自定义参数并录入内容

要获取并显示自定义参数，首先需要在安企CMS后台进行配置。这个过程分为两步：定义参数，然后为文档录入这些参数的值。

1. 定义内容模型的自定义字段

自定义参数是与“内容模型”相关联的。每个内容模型（例如“文章模型”、“产品模型”）都可以拥有自己独特的自定义字段。

• 进入内容模型管理： 登录安企CMS后台，导航到 “内容管理” 菜单，然后点击 “内容模型”。
• 选择或新建模型： 在这里，您可以选择编辑现有的内容模型（如“文章模型”）来添加新的字段，也可以创建一个全新的内容模型。
• 添加自定义字段： 在选定的内容模型编辑页面中，找到 “内容模型自定义字段” 区域，点击“添加字段”。您会看到以下几个关键设置项：
  • 参数名： 这是在后台界面显示给运营者看的中文名称，例如“文章作者”、“内容来源”。
  • 调用字段： 这是在前端模板中用来调用该参数的唯一标识符，必须使用英文字母，建议采用驼峰命名或小写下划线命名，例如author、source、material。这个字段名至关重要，前端调用时会用到它。
  • 字段类型： 根据您需要存储的数据类型选择合适的字段，例如“单行文本”（适用于作者、来源）、“多行文本”（适用于较长的介绍）、“数字”、“单项选择”、“多项选择”或“下拉选择”等。
  • 是否必填： 根据业务需求，决定该字段是否为必填项。
  • 默认值： 如果该字段有常用值，可以设置默认值。
• 保存配置： 完成字段设置后，务必点击保存按钮，使更改生效。

2. 为文档录入自定义参数值

定义好内容模型的自定义字段后，在发布或编辑相应模型的文档时，就可以为这些字段填入具体内容了。

• 进入文档编辑界面： 导航到 “内容管理”，点击 “发布文档” 或编辑现有文档。
• 填写自定义参数： 在文档编辑页面的下方，会有一个 “其他参数” 的折叠区域。展开这个区域，您会看到刚刚为该内容模型定义的自定义字段，以及对应的输入框或选择项。在这里，您可以为当前文档填写“文章作者”、“内容来源”等信息。
• 保存文档： 填写完毕后，保存文档。这些自定义参数的值就会与该文档一同存储。

二、在前端模板中获取和显示自定义参数

配置和录入完成后，接下来就是如何在网站的前端页面（通常是文档详情页）上展示这些自定义参数了。安企CMS提供了强大的模板标签，让这一过程变得非常灵活。

通常，您需要在您模板目录下的 {模型table}/detail.html（例如article/detail.html或product/detail.html）文件中添加以下代码。

1. 直接调用指定自定义参数（推荐简单场景）

对于像“作者”、“来源”这样在页面上只显示一次的特定字段，最直接的方法是使用 archiveDetail 标签。

假设您在内容模型中定义了“作者”（调用字段为author）和“来源”（调用字段为source）两个自定义字段。

{# 在文档详情页，您可以直接使用 archive 对象来调用自定义字段 #}
<p>作者：{{ archive.author }}</p>
<p>来源：{{ archive.source }}</p>

{# 或者，使用 archiveDetail 标签，这在当前页面不是文档详情页，但您知道文档ID时非常有用 #}
<p>作者：{% archiveDetail with name="author" %}</p>
<p>来源：{% archiveDetail with name="source" %}</p>

{# 如果自定义参数的内容是富文本或 Markdown 格式，需要加上 |safe 过滤器，Markdown 内容还需 |render 过滤器 #}
<div class="introduction">
    产品简介：{{ archive.introduction|render|safe }}
</div>

说明：

• 在文档详情页中，系统通常会自动提供一个名为 archive 的变量，其中包含了当前文档的所有信息，包括自定义参数。您可以通过 {{ archive.调用字段名 }} 的形式直接访问。
• {% archiveDetail with name="调用字段名" %} 这种方式则更具通用性，无论当前页面是否直接是文档详情页，只要系统能识别当前文档上下文或您指定了文档ID，它就能获取到数据。
• |render|safe：如果您的自定义字段类型是富文本编辑器，并且内容可能包含HTML标签或Markdown语法，为了让这些内容正确显示而不是作为纯文本输出，您需要加上 |safe 过滤器。如果同时启用了Markdown编辑器，那么就需要先|render再|safe。

2. 循环遍历所有自定义参数（适用于动态展示）

如果您希望在一个区域动态地展示某个文档的所有自定义参数，例如在一个产品详情页统一展示所有规格参数，那么 archiveParams 标签会非常方便。它会返回一个自定义参数的列表，您可以循环遍历并显示它们的名称和值。

<div class="custom-parameters">
    <h3>详细参数</h3>
    {% archiveParams params %}
    {% for item in params %}
        <p><strong>{{ item.Name }}：</strong> {{ item.Value|safe }}</p>
    {% endfor %}
    {% endarchiveParams %}
</div>

说明：

• {% archiveParams params %} 会获取当前文档所有已定义的自定义参数，并将其赋值给 params 变量。
• params 是一个数组对象，每个元素都包含 Name（参数名，如“文章作者”）和 Value（参数值）。
• 通过 {% for item in params %} 循环，您可以依次取出每个参数的名称和值进行显示。
• 同样，|safe 过滤器在这里也很重要，以防参数值中包含需要解析的HTML内容。

三、使用技巧与注意事项

• 调用字段名一致性： 确保在后台定义“调用字段”时使用的名称，与您在模板中调用时使用的名称完全一致（包括大小写）。
• 数据类型匹配： 在后台定义字段类型时，请根据实际内容选择。例如，如果自定义字段是多选类型，那么在前端 item.Value 可能会是逗号分隔的字符串，您可能需要进行额外的处理（如使用 |split:"," 过滤器将其转换成数组再遍历）。
• 模板缓存： 修改模板文件后，如果页面没有立即更新，请尝试清除安企CMS的系统缓存或浏览器缓存。
• 样式美化： 上述代码仅为功能实现，实际应用中，您还需要通过CSS来对这些自定义参数进行美化，使其与网站整体风格保持一致。

通过上述方法，您可以充分利用安企CMS的自定义参数功能，为您的网站内容增加更多维度和个性化展示，从而提升用户体验和内容价值。

常见问题解答 (FAQ)

Q1: 我在后台设置了自定义参数，但为什么在文档编辑页面“其他参数”中没有看到它？ A1: 请检查您是否为当前文档所属的内容模型添加了自定义参数。例如，如果您编辑的是一篇“文章”，那么自定义参数必须是在“文章模型”下定义的。另外，请确保在定义完自定义字段后，点击了保存按钮，并可能需要刷新页面才能显示。

**Q2: 我在模板中调用自定义参数时，显示的是纯文本，没有解析HTML标签，或者Markdown内容