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

When managing content in AnQi CMS, we often encounter situations where we need 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 I elegantly and flexibly obtain and display these custom parameter fields in the website front-end template?archiveParamsThe tag is the key to solving this problem.

Understand the custom parameters in the document model

Before delving deeperarchiveParamsBefore 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, inventory), multi-line text (product features), radio/checkbox (color, size) etc.These custom fields provide our content management with powerful personalization capabilities.

archiveParamsTag: A powerful tool for flexibly accessing custom fields

When we want to display all or part of the custom parameters of a document on the front-end page,archiveParamsThe tag comes in handy. It allows us to access all custom parameters of the current document or a specified document, and provides two main ways to organize this data to meet different display requirements.

Get the custom parameters of the current document

archiveParamsTags are usually used on the document detail page, at which point it will default to retrieving the custom parameters of the document being viewed. 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 block,paramsThis is the variable name defined for the custom parameter set we have obtained. Byforloop, we can access each custom parameter one by one,item.NameDisplays the parameter name (such as "author", "product number"),item.ValueThe parameter value will be displayed in this way. This is very suitable when you need to list all the custom properties of the document without knowing the specific names of each property.

Specify Document ID for Parameters

If we need to retrieve custom parameters for a specific document instead of the document on the current page, we can utilizeidparameters 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 retrieve all custom parameters for document ID 1.

Flexible data organization method:sortedThe magic of parameters

archiveParamslabel'ssortedThe parameter is the key to its flexibility. It determines whether the obtained custom parameters are presented in a fixed sorted array form or as an unordered key-value pair (map).

  1. sorted=true(Default behavior): A fixed sorted array

    Whensortedthe parameter totrueWhen this is the default behavior,archiveParamsit will return an array object. Each element of the array is an object containingNameandValueThe field object. This means you can iterate and display these parameters in the order defined in the backend content model or in the default order of the system.This method is very suitable for those who want to display all custom fields uniformly, such as the product specifications list on the product details 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

    Whensortedthe parameter tofalsethen,archiveParamsIt 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/sourceAnd, the value is includedNameandValueThe object. This approach has the advantage that you can directly access specific parameters through field names without needing to iterate through a loop.It is especially suitable when you only need to display some or several specific custom fields of a document, and the names of these 'call 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 %}

    ByarticleInfo.author.ValueThis syntax can directly obtain the value of the custom field "author".This is particularly convenient when it is necessary to embed custom fields into a specific HTML structure rather than display them in a unified list.

Application in a multi-site environment

If your Aanqi CMS has multi-site functionality deployed and you want to get the document parameters of a non-current site, you can usesiteIdSpecify the site ID with the parameter. This is very useful when building cross-site content aggregation or display, but it is usually not necessary for single-site applications.

archiveParamswitharchiveDetailDifference

It is worth mentioning that in Anqi CMS,archiveDetailTags, although mainly used to obtain basic document information (title, content, etc.), it can also be directly accesseda singleThe value of a custom field. For example, if you only need to get a field namedauthorThe custom field, can be used directly{% archiveDetail with name="author" %}.

When to choosearchiveParamsWhen to choosearchiveDetailTo get the custom field?

  • When you needTraversal to display all or mostThe custom field, or when unsure about what custom fields there are,archiveParamsIs **selection (withsorted=true)
  • When you needAccurately control the acquisitionWhen displaying the position and style of a specific customized field,archiveParamscooperatesorted=falseDirect access, or usearchiveDetailDirectly obtain the value of this field, it is a good choice.archiveDetailMore concise, butarchiveParams(sorted=false) You can retrieve all custom field maps at once, convenient for subsequent selection as needed, reducing the number of tag calls.

In summary,archiveParamsThe tag provides powerful and flexible custom field display capabilities for Anqi CMS users, whether it is for unified listing or precise invocation, it can easily cope with it, making your website content display richer and more personalized.

Frequently Asked Questions (FAQ)

1. I have customized an image field in the content model (for example:产品图集, called the field nameproduct_gallery)archiveParamsHow to retrieve and display it?

Answer: If your custom image field stores a JSON array of image URLs, then when you usearchiveParamsto retrieve and display in a loop,item.ValueThis will be the 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, ifitem.ValueIt is a comma-separated URL string, you can{{ item.Value|split:"," }}Get an array and loop through it. More commonly, if the backend storesjsonThe string may require a special filter or to be processed in the background to become more user-friendly. In Anqi CMS, if a custom field is designed as a "group image" type,archiveDetailLabel can be processed just likeImagesprocessing a field, andarchiveParamsObtaineditem.ValueIt may be a JSON string, which requires manual parsing or automatic parsing capabilities of the framework for custom field values. In most cases, AnQiCMS will directly render the custom group image field into a recyclable array, such as:

{% 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.ValueIt can be directly cycled and depends on the intelligent parsing of specific types of custom fields (such as group images) by the AnQiCMS template engine.If your custom field is plain text, even if the content is JSON, it needs to be parsed manually.

2. Why do I usearchiveParamsWhen retrieving custom fields by tag, 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 be filled in or may be empty when adding documents.
  • Is the field set to 'Display in list' or 'Filterable'?AlthougharchiveParamsThe fields are usually retrieved, but some backend configurations (such as "Hide on list page" etc.) may affect the display on the front end.Ensure that the custom field you define in the content model is marked as 'available for template calls'.
  • Is the field name called correctly?If you usesorted=falseTry to access directly, for example{{articleInfo.author.Value}}Make sure, pleaseauthorThis is the accurate 'call field' name set by the custom field in the content model (usually in lowercase English).
  • Template caching issue: Try to clear the Anqi CMS system cache, sometimes old caches after template files or data updates can cause display errors.

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

Answer:archiveParamsThe tag itself does not provide direct field type filtering functionality. However, you can achieve this in two ways:

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

  • Logical judgment inside the template: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 according toitem.Name(Display name) oritem.FieldName(Field name to be called, which needs to be obtained or known in a specific way) to flexibly control the display.