The `archiveParams` tag returns custom parameters, is the data structure a fixed array or a variable Map?

Hello, all website operators and AnQi CMS enthusiasts!

Today, we will delve into a practical and flexible tag in AnQi CMS template development -archiveParamsMany times, when using custom parameters, there is a question:archiveParamsThe custom parameters returned by the tag, is its data structure a fixed array or a variable Map?

To better utilize the powerful content model customization capabilities of Anqi CMS, it is crucial to understand this point. This article will provide you with a detailed explanation.archiveParamsData structure, and provides practical scenarios to help you operate websites and design templates with ease.

RevelationarchiveParams: A flexible data structure for custom parameters

AnQi CMS is known 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 authors, product dimensions, and specific properties, greatly expand the expression form of content. AndarchiveParamsThe label, which is the key to accessing these valuable custom data from the template.

When we talk aboutarchiveParamsWhen returning a data structure, the answer is not either/or. In fact, it combines a "fixed ordered list" (commonly referred to as in Go language) and a "variable key-value set" (that isSliceorArray)MapThe characteristics, which depend on how you configure and use this tag.

Its core lies inarchiveParamsthe label provides a namedsortedThe parameter, which is exactly what determines the data structure returned.

Scenario one: Retrieve the custom parameters of the ordered list (sorted=trueor default)

when you arearchiveParamsUsed in tagssorted=trueparameters, or do not specifysortedparameters (becausetrueit is the default value) when,archiveParamsWill return oneA fixed sorted list (Slice/Array).

Each element in this list is a container that includesName(field name, that is, the Chinese name displayed in the background) andValue(Data field) object. This structure is especially suitable for:

1. Dynamically display all custom fields:For example, you may want to display all product specifications uniformly on a product detail page, and 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 knowing the specific names of each field.
2. Maintain the display order of fields:If the order of custom field definitions on the backend is important for front-end display, thensorted=trueIt can ensure that the data you get is sorted according to the backend definition.

Example code (returns an ordered list):

Assuming 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 block,paramsA variable is a list. By usingforWe 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 arearchiveParamsExplicitly specify in the tagsorted=falsethen,archiveParamsWill return oneAn unordered collection 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 container that includesNameandValueThe object. This structure is very suitable for:

1. Accurately access a specific custom field:If you know the 'call field' name of a custom field (for example,author/product_image), and if you want to directly access its value without traversing 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, data in Map structure is easier to handle.

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

Assuming your backend content model defines a field calledisbn_numbera custom ISBN field, as well as oneauthoran author 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, paramsa variable is a Map. We can access it byparams.author.Valueorparams.isbn_number.ValueThis dot operator, gets the value of the field by calling the field name of the custom field directly, without looping.

How to choose the data structure suitable for you?

Choose which data structure depends on your specific needs:

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

  • when you needto traverse allCustom field, and displayed uniformly on the front end, for example, in a 'specification parameters' block.
  • When the custom fieldDisplay orderIs very important for front-end presentation.
  • When you are not sure about the names of all the custom field names called, or the field types may change dynamically.

• Select a key-value pair set (sorted=false):

  • when you needAccurately obtain one or more specificThe value of the custom field, such as the source link of the article, the video introduction URL of the product.
  • When you want to access data directly through custom field names in the code, it improves the readability and maintainability of the template.
  • When interacting with front-end logic like JavaScript, the Map structure is usually more convenient.

Summary

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

Frequently Asked 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 and navigate to内容管理-u003e内容模型. Select or create a content model (such as "article model" or "product model"), and then click the "Add field" button under the "Content model custom fields" section.Here, you can set the Chinese name of the field (Name, used for the frontenditem.Name），Call Field（）FieldName，Used Forparams.FieldName.ValueofFieldNamePart），Field Type, Whether Required, Default Value, etc. After definition, all documents under this model will have these custom parameters.

Q2: How can I ensure that HTML tags within my custom parameter content are displayed correctly on the front end and not escaped?

A2: The template engine of AnQiCMS defaults to escaping 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 instead of being displayed as raw HTML,<p>or<strong>Text, you need to use it in the output|safea filter. For example:<span>{{item.Value|safe}}</span>or<span>{{params.fieldName.Value|safe}}</span>.

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