Hello, all website operators and CMS enthusiasts!

Today, we will delve into a practical and flexible tag in the development of the Anqi CMS template.archiveParamsMany people have a question when using custom parameters:archiveParamsWhat is the data structure of the custom parameters returned by the label, is it a fixed array or a variable Map?

In order to make full use of the powerful content model customization capabilities of AnQi CMS, it is crucial to understand this. This article will give you a detailed explanation.archiveParamsThe data structure, and provide practical scenario examples, help you operate the website and design templates with ease.

UnveilingarchiveParams: Flexible data structure for custom parameters

The AnQi CMS is renowned for its high flexibility, especially in the content model, allowing us to customize rich fields for content types such as articles, products, and more.These custom fields, such as article author, product size, and specific attributes, greatly expand the form of content expression.archiveParamsLabels, which are the keys we use to access these valuable custom data from the template.

When we talk aboutarchiveParamsReturns the data structure in which the answer is not either/or. In fact, it combines both "fixed ordered list" (commonly referred to as)SliceorArrayin languages such as Go) and "variable key-value pair set" (i.e.)MapThe characteristics, which depend on how you configure and use this tag.

The core is inarchiveParamstag provides a name ofsortedparameters, which determine the data structure of the returned data.

Scene one: Get the custom parameter of the ordered list (sorted=trueor default)

When you arearchiveParamsthe label usesorted=trueparameter, or not specifysortedparameter (because)trueit is the default value),archiveParamsWill return aList sorted in fixed order (Slice/Array).

Each element in this list is a container that includesName(Field name, i.e., the Chinese name displayed on the back end) andValuethe object of (field data). This structure is especially suitable for:

  1. dynamically displaying all custom fields:For example, you may want to display all product specifications uniformly on a product detail page, and the types of these parameters may increase with the update of the background content model. You can easily do this by using a list.forLoop through all fields without needing to know the specific names of each field.
  2. Maintain the display order of fields:If the order of custom field definitions in the backend is important for the front-end display,sorted=trueThis ensures that the data you receive is sorted in the order defined by the backend.

Example code (returns a sorted list):

Suppose your backend content model defines custom fields such as 'Author', 'Publisher', 'ISBN', etc.

{# 默认或显式指定 sorted=true，返回一个有序的列表 #}
<div>
    <h3>文档自定义参数（有序列表）：</h3>
    {% archiveParams params %} {# sorted=true 是默认行为 #}
    {% for item in params %}
    <div>
        <span>{{item.Name}}：</span> {# 访问字段的显示名称 #}
        <span>{{item.Value}}</span> {# 访问字段的数据值 #}
    </div>
    {% endfor %}
    {% endarchiveParams %}
</div>

{# 如果是特定文档的参数，可以指定id #}
<div>
    <h3>文档ID为1的自定义参数（有序列表）：</h3>
    {% archiveParams params with id="1" %}
    {% for item in params %}
    <div>
        <span>{{item.Name}}：</span>
        <span>{{item.Value}}</span>
    </div>
    {% endfor %}
    {% endarchiveParams %}
</div>

In this code,paramsA variable is a list. ByforLoop, we can iterate over each custom field in the listitemand get its display nameitem.Nameand the corresponding valueitem.Value.

Scenario two: Get the custom parameters of the key-value set (sorted=false)

When you arearchiveParamsspecify in the tag.sorted=falsewhenarchiveParamsWill return aAn unordered set of key-value pairs (Map).

In this mode, the key of Map is the "call field" set when custom fields are defined in the background (usually in lowercase English letters), and the value of Map is also a collection ofNameandValueThe object of.

  1. Accurate access to specific custom fields:If you know the "call field" name of a custom field (for example,author/product_image），and hope to directly obtain its value without having to traverse all fields, then the Map structure provides a more direct and efficient way of access.
  2. Integration with front-end JS frameworks:For front-end applications that need to bind data or perform logic based on a specific field name, the Map structure of data is easier to handle.

Example code (returns a set of key-value pairs):

Assuming your backend content model defines a field namedisbn_numbera custom ISBN field, as well as aauthorauthor field.

{# 显式指定 sorted=false，返回一个无序的Map #}
<div>
    <h3>文档自定义参数（键值对集合）：</h3>
    {% archiveParams params with sorted=false %}
        <div>
            <span>作者名称：</span>
            <span>{{params.author.Value}}</span> {# 通过键名直接访问作者字段的值 #}
        </div>
        <div>
            <span>ISBN：</span>
            <span>{{params.isbn_number.Value}}</span> {# 通过键名直接访问ISBN字段的值 #}
        </div>
        {# 也可以访问Name #}
        <div>
            <span>{{params.isbn_number.Name}}：</span>
            <span>{{params.isbn_number.Value}}</span>
        </div>
    {% endarchiveParams %}
</div>

Here,paramsvariable is a Map. We can access it byparams.author.Valueorparams.isbn_number.ValueThis point operator retrieves the value directly from the calling field name of the custom field, without the need for a loop.

How to choose the data structure suitable for you?

The choice of data structure depends on your specific needs:

  • Choose an ordered list (sorted=true, default):

    • When you needto traverse allCustom field, and display it uniformly on the front end, for example, in a 'specification parameter' block.
    • When the custom fieldDisplay OrderIs important for the front-end presentation.
    • When you are unsure about the names of the calling fields of all custom fields, or when the field types may change dynamically.

  • Select a set of key-value pairs.sorted=false):

    • When you needExactly obtain one or several specificCustom field value, for example, the 'source' link of an article, the 'video introduction' URL of a product.
    • When you want to access data directly through custom field names in the code, which improves the readability and maintainability of the template.
    • When interacting with front-end logic such as JavaScript, the Map structure is usually more convenient.

Summary

archiveParamsTagged throughsortedThe parameter provides flexible data structure selection.Whether it is necessary to display all custom parameters in order or to accurately obtain specific parameter values, Anqi CMS provides an efficient and intuitive solution.Understand and make good use of this feature, which will greatly enhance your development efficiency and content operation capabilities on the AnQi CMS platform.

Common Questions (FAQ)

Q1: How to define custom parameters in the Anqi CMS backend?

A1: Custom parameters are defined inContent Model. You can log in to the Anqi CMS backend, navigate to内容管理-内容模型.Select or create a content model (such as "article model" or "product model"), then click the "Add field" button under the "Content model custom fields" section.Namefor the front-enditem.Name），调用字段（FieldName，用于params.FieldName.ValueofFieldName部分），字段类型、是否必填、默认值等。定义完成后，该模型下的所有文档都将拥有这些自定义参数。

Q2: How can I ensure that the front-end displays my custom parameter content containing HTML tags correctly instead of escaping them?

A2: The template engine of AnQi CMS defaults to HTML escaping for output content for security reasons. If your custom parameters (such as a rich text editor field) contain HTML tags, and you want these tags to be parsed normally by the browser rather than displayed as raw text,<p>or<strong>Text, you need to use this in the output|safefilter. For example:<span>{{item.Value|safe}}</span>or<span>{{params.fieldName.Value|safe}}</span>.

Q3: BesidesarchiveParamsTag, is there another way to directly get the value of a specific custom parameter?