How to retrieve and flexibly display custom parameter fields in the document model with the `archiveParams` tag?

When managing content in the AnQi CMS, we often encounter situations where it is necessary to add specific attributes for different types of content (such as articles, products).The "Content Model" feature provided by "AnQi CMS" allows us to customize fields according to business needs, greatly enhancing the flexibility and scalability of content.How can we elegantly and flexibly obtain and display these custom parameter fields in the website front-end template?archiveParamsLabel is the key to answering this question.

Understand the custom parameters in the document model.

In-depth explorationarchiveParamsBefore the label, let's review the setting of custom parameters in the Anqi CMS content model.Through the "Content Management" -> "Content Model" feature, we can add unique custom fields for each content model (such as "Article Model" or "Product Model").These fields can contain various types, such as single-line text (author, source), numbers (price, stock), multi-line text (product features), radio/checkboxes (color, size), and so on.These custom fields provide our content management with powerful personalization capabilities.

archiveParamsLabel: The powerful tool for flexibly retrieving custom fields.

When we want to display all or part of a custom parameter of a document on the front-end page,archiveParamsLabels come in handy.It allows us to retrieve all custom parameters of the current document or a specified document, and provides two main ways to organize these data to meet different display requirements.

Get the custom parameters of the current document

archiveParamsLabels are usually used on the document detail page, where it will default to fetching the custom parameters of the currently browsing document. Its basic usage is as follows:

{% archiveParams params %}
    {# 循环遍历所有自定义参数 #}
    {% for item in params %}
    <div>
        <span>{{item.Name}}：</span>
        <span>{{item.Value}}</span>
    </div>
    {% endfor %}
{% endarchiveParams %}

In this code,paramsis the variable name defined for the custom parameter set we obtain. Byforlooping, we can access each custom parameter one by one,item.NameThe parameter name will be displayed (for example, "authoritem.ValueThe parameter value will be displayed. This method is very suitable when you need to list all the custom properties of the document without knowing the specific name of each property.

Specify Document ID Parameter

If we need to get custom parameters of a specific document rather than the document on the current page, we can utilizeidthe parameter to specify the document ID:

{% archiveParams specificParams with id="1" %}
    {# 循环遍历ID为1的文档的所有自定义参数 #}
    {% for item in specificParams %}
    <div>
        <span>{{item.Name}}：</span>
        <span>{{item.Value}}</span>
    </div>
    {% endfor %}
{% endarchiveParams %}

Here,id="1"Will get all custom parameters for the document with ID 1.

Flexible data organization method:sortedThe clever use of parameters

archiveParamsTagssorted参数是其灵活性的关键所在。它决定了获取到的自定义参数是以固定排序的数组形式呈现，还是以无序的键值对（map）形式呈现。

  1. sorted=true(默认行为): 固定排序的数组

    Whensortedparameter settingstrue（这也是默认行为，可以省略不写）时，archiveParams会返回一个数组对象。数组中的每个元素都是一个包含NameandValueThe object of the field.This means you can iterate through and display these parameters in the order defined in the background content model or in the order of the system default.This method is very suitable for scenarios where you want to display all custom fields uniformly, such as the 'Product Specifications' list on the product detail page.

    {# 默认行为，或明确指定 sorted=true，获取一个固定排序的数组 #}
<div>
    <h3>产品规格</h3>
    {% archiveParams productSpecs %}
    {% for spec in productSpecs %}
    <div>
        <strong>{{spec.Name}}：</strong>
        <span>{{spec.Value}}</span>
    </div>
    {% endfor %}
    {% endarchiveParams %}
</div>

  2. sorted=false: An unordered map object, accessed directly

    Whensortedparameter settingsfalsewhenarchiveParamsIt will return a map object. The keys of this map are the "call fields" you set for custom fields in the content model (for exampleauthor/sourceauto，值则是包含NameandValueThe object.The advantage of this method is that you can directly access specific parameters by field names without the need for looping.It is particularly suitable when you only need to display a specific or a few custom fields of a document, and the names of these 'called fields' are known.

    {# 获取一个无序的map对象，直接通过调用字段名访问 #}
{% archiveParams articleInfo with sorted=false %}
    <div>
        <span>作者：</span>
        <span>{{articleInfo.author.Value}}</span> {# 假设调用字段名为 'author' #}
    </div>
    <div>
        <span>来源：</span>
        <span><a href="{{articleInfo.sourceUrl.Value}}" target="_blank">{{articleInfo.source.Value}}</a></span> {# 假设调用字段名为 'source' 和 'sourceUrl' #}
    </div>
{% endarchiveParams %}

    PassarticleInfo.author.ValueThis syntax can directly obtain the value of the custom field "author".This is especially convenient when you need to embed custom fields into specific HTML structures instead of displaying them in a unified list.

auto

auto，如果你的安企CMS部署了多站点功能，并且希望获取非当前站点的文档参数，可以使用siteIdThe parameter is used to specify the site ID. This is very useful when building cross-site content aggregation or display, but is usually not concerned with single-site applications.

archiveParamsWitharchiveDetaildifferences

It is worth mentioning that in the AqieCMS,archiveDetailLabels, although mainly used to obtain basic information of documents (title, content, etc.), it can also directly obtainsingleThe value of custom fields. For example, if you only need to obtain a field namedauthorcustom field, you can use it directly{% archiveDetail with name="author" %}.

When to choosearchiveParamsand when to choosearchiveDetailto get custom fields?

  • when you needto display all or mostcustom fields, or when unsure about which custom fields there are,archiveParamsis the choice (combined withsorted=true).
  • when you needGet and precisely controlthe display position and style of a specific custom fieldarchiveParamswithsorted=falsePerform direct access, or usearchiveDetaildirectly obtain the value of this field, are all good choices.archiveDetailmore concise, butarchiveParams(sorted=false) Can obtain all custom fields' map at once, convenient for subsequent selective use, reducing the number of label calls.

In short,archiveParamsTags provide strong and flexible custom field display capabilities for Anqi CMS users, whether it is a unified list or an accurate call, it can easily handle it, making your website content display richer and more personalized.

Common Questions (FAQ)

1. I have customized an image field in the content model (for example:产品图集The field name used for callingproduct_gallery)archiveParamsHow to get and display it?

答：If your custom image field stores a JSON array of image URLs, then when you usearchiveParamsto get and loop through them,item.ValueThis will be this JSON string. You need to combinesplit/jsonor directly use the specific processing method of the template engine (if it can automatically recognize) to parse it. For example,item.ValueIt is a comma-separated URL string, you can{{ item.Value|split:"," }}Get an array and loop through it. It is more common, if the background storage isjsonThe string, the template may need a special filter or to be processed into a more user-friendly format in the background. In Anqi CMS, if a custom field is designed as a "group image" type,archiveDetailLabel can be processed just likeImagesprocessing fields, whilearchiveParamsThe one obtaineditem.Value可能是JSON字符串，需要您手动解析或依赖框架对自定义字段值的自动解析能力。通常情况下，AnQiCMS会将自定义的组图字段直接渲染成可循环的数组，例如：

{% archiveParams productDetails with sorted=false %}
    {% if productDetails.product_gallery %} {# 检查是否存在此自定义字段 #}
        <h3>产品图集</h3>
        <div class="product-gallery">
            {% for imageUrl in productDetails.product_gallery.Value %} {# 假设 Value 已经是可循环的图片URL数组 #}
                <img src="{{ imageUrl }}" alt="产品图片">
            {% endfor %}
        </div>
    {% endif %}
{% endarchiveParams %}

Please note, here:productDetails.product_gallery.ValueCan directly loop, which depends on the intelligent parsing of specific types of custom fields (such as group images) by AnQiCMS template engine.If your custom field is plain text, even if the content is JSON, you need to parse it manually.

2. 为什么我使用archiveParamsTag getting custom field failed? Some fields are not displayed?

Answer: Please check the following points:

  • Has the document really saved the value of this field?Some custom fields may not have content filled in when adding documents, or the content may be empty.
  • Is the field set to 'Display in list' or 'Filterable'?AlthougharchiveParamsThe fields are usually retrieved, but certain background configurations (such as "Hide on list page" etc.) may affect the frontend display.Ensure that the custom fields you define in the content model are "available for template calls".
  • “Call Field” name is correct?If you usesorted=falseTry to access directly, for example{{articleInfo.author.Value}}, please make sureauthorIs the exact 'call field' name set for this custom field in the content model (usually in lowercase English).
  • Template cache issue:Attempt to clear the security CMS system cache, sometimes old cache after template files or data updates can cause display anomalies.

3. How toarchiveParamsFilter or only display specific types of custom fields?

Answer:archiveParamsThe label itself does not provide direct field type filtering functionality. But you can achieve it in two ways:

  • Backend control:In the content model settings, you can select which custom fields are required, displayed on the publish page, and so on. This will affect the entry of the fields, but usually does not directly filter the front-end display.

  • Template logic judgment:In{% for item in params %}In the loop, you can add conditional judgments to filter the fields to be displayed. For example, if you want to skip displaying the field named 'Internal Note':

    {% archiveParams params %}
    {% for item in params %}
        {% if item.Name != '内部备注' %}
            <div>
                <span>{{item.Name}}：</span>
                <span>{{item.Value}}</span>
            </div>
        {% endif %}
    {% endfor %}
{% endarchiveParams %}

    This way can be controlled to display flexibly according toitem.Name(display name) oritem.FieldName(Call field name, which needs to be obtained or known in a specific way) to flexibly control display.