How to use the `archiveParams` tag to retrieve custom fields and include them in Json-LD?

As an experienced website operation expert, I know the importance of structured data in search engine optimization today.Make good use of structured data, not only can it help search engines better understand your content, but also help you get richer display opportunities in search results.AnQiCMS (AnQiCMS) is a powerful and flexible content management system that provides excellent support in this regard.archiveParamsLabel retrieves custom fields and cleverly integrates them into the Json-LD structured data.

Why is the combination of custom fields and Json-LD so important?

In AnQi CMS, you can add rich custom fields for content models such as articles, products, and (Archive) to meet the personalized needs of different business scenarios.For example, add fields such as 'SKU', 'Brand', 'Stock quantity', etc. to products, or add 'Author biography', 'Estimated reading time', etc. to articles.These custom fields contain the core information of the website content, but by default, search engines may not understand these non-standardized data directly.

At this moment, Json-LD (JavaScript Object Notation for Linked Data) comes into play.It is a data format based on JSON that can clearly describe entities and their properties on web pages to search engines.By mapping custom fields in AnQi CMS to specific attributes in Json-LD, we can provide search engines with more accurate and rich structured information, thereby effectively improving the SEO performance of website content and even getting the opportunity to display rich text snippets (Rich Snippets) in search results.

Understand the custom fields of AnQi CMSarchiveParamsTag

In the AnQi CMS backend, you can flexibly create custom fields for different document types (such as article models, product models) through the "Content Management" "Content Model" feature.These fields can be single-line text, numbers, multi-line text, or even single-choice, multi-choice, or drop-down selections in various forms, greatly enhancing the expressive power of the content.

And to display these valuable custom fields on the frontend template,archiveParamsThe tag is your helpful assistant. This tag is specifically used to retrieve all custom parameters associated with the current document (or specified document). Its basic usage is:

{% archiveParams params with id="[文档ID]" sorted="true/false" %}
    {# 循环或直接访问自定义字段 #}
{% endarchiveParams %}

Here are two key parameters to note:

• id: If you want to get the custom fields of the current page document, you can omit this parameter; if you want to get the fields of a specific document, you need to specify its ID.
• sortedThis parameter determines the organization form of the custom fields you obtain.
  • Whensortedis set totrueWhen set to the default value,paramsit will be an array of objects sorted by the background order. You need to use{% for item in params %}Loop through and pass throughitem.NameGet the field name,item.ValueGet the field value.
  • Whensortedis set tofalsethen,paramsIt will be an unordered Map object, the key name directly corresponds to the 'call field' you set in the background. This method is more suitable when you know which specific field you want to retrieve, you can directly access it throughparams.你的调用字段名.ValueVisit. For example, if you have a custom field namedproduct_skuThe field can be used directly{{ params.product_sku.Value }}To get its value. For scenarios where we need to accurately map to Json-LD,sorted=falseit is usually more convenient.

steps to integrate custom fields into Json-LD practice

Now, let's take a specific scenario as an example: Suppose we have a 'product model' where there are two custom fields, their 'access fields' are respectivelyproduct_sku(Single line text) andbrand_name(Single line text). We hope to add these values to the product's Json-LD structured data.

Step 1: Define custom fields in the Anqi CMS backend

First, make sure you have selected or created your "product model" in the "content management" -> "content model" of the Anqi CMS background, and added a namedproduct_skuandbrand_nameCustom field (ensure that the field name is accurate). Then, when publishing the product, fill in the corresponding values for these fields.

Step two: Get the custom field in the template.

Generally, you will operate on the product detail page (such asproduct/detail.html). First, we need to usearchiveParamstags to obtain these custom fields in the form of a Map.

{# 在产品详情页的适当位置（例如顶部）获取自定义字段 #}
{% archiveParams productCustomFields with sorted=false %}
    {# 现在 productCustomFields 是一个Map，我们可以直接通过键名访问 #}
    {% set sku = productCustomFields.product_sku.Value %}
    {% set brand = productCustomFields.brand_name.Value %}
{% endarchiveParams %}

{# 你也可以在这里输出这些变量进行调试，例如：#}
{# <p>SKU: {{ sku }}</p> #}
{# <p>Brand: {{ brand }}</p> #}

Here, we usewith sorted=falseRetrieve custom fields as a Map and then use{% set %}Labels willproduct_skuandbrand_nameassign their values toskuandbrandThese are the two new template variables. The benefit of this is that the variable names are more concise, which is convenient for subsequent use in Json-LD.

Third step: usejsonLdThe tag embeds custom fields into Json-LD.

AnQi CMS providesjsonLdLabel to manage the Json-LD data on the page.The power of this tag lies in the fact that it allows you to override or supplement the Json-LD data generated by the system default.You only need to write JSON code that conforms to Json-LD syntax within it, and the system will automatically merge it with default data.

Now, let's insertskuandbrandthe variable into Json-LD. We assume that we want to add aProducttype Schema.

{% jsonLd %}
<script type="application/ld+json">
{
    "@context": "https://schema.org/",
    "@type": "Product",
    "name": "{% archiveDetail with name='Title' %}", {# 获取产品标题 #}
    "sku": "{{ sku }}", {# 插入自定义的SKU #}
    "brand": {
        "@type": "Brand",
        "name": "{{ brand }}" {# 插入自定义的品牌名称 #}
    },
    "description": "{% archiveDetail with name='Description' %}", {# 获取产品简介 #}
    "image": "{% archiveDetail with name='Logo' %}", {# 获取产品主图 #}
    "offers": {
        "@type": "Offer",
        "url": "{% archiveDetail with name='Link' %}",
        "priceCurrency": "USD", {# 假设币种是美元 #}
        "price": "{% archiveDetail with name='Price' %}", {# 假设产品价格存储在内置Price字段 #}
        "availability": "https://schema.org/InStock"
    }
}
</script>
{% endjsonLd %}

In this example:

• We first use{% archiveDetail %}The tag gets built-in fields of the product, such asTitle/Description/LogoandLinkThese are the basic information for building product Json-LD.
• Then, we cleverly embed the variable obtained in the second step.skuandbrandby using the form of the variable,{{ sku }}and{{ brand }}into the corresponding position."sku"and"brand".
• Please note the syntax of Json-LD,brandIt is an object, so we need to specify@typeandnameProperty.
• pricefields we assume use the built-in AnqicmsPricefield.

By following these steps, when your product detail page is visited, the page source code will generate a rich and accurate Json-LD structured data containing these custom fields.This will greatly help search engines understand your product information, thereby providing more attractive displays in search results.

**Practical Tips and Warnings

1. verification is critical: After completing the Json-LD code, it is imperative to use Google's Rich Results Test (Rich Text Results Test tool) or Schema.org's Schema Markup Validator for validation.This can help you check for grammatical errors and ensure that the data structure conforms to specifications.
2. Handle null valuesYour custom field may not always be filled in.Inserting null directly in Json-LD may lead to structured data errors.{% if sku %}Set a default value for the variable{% set sku = productCustomFields.product_sku.Value|default:'' %}To avoid outputting an empty string.
3. Understand Schema types: Schema.org defines a large number of Schema types (such asProduct/Article/OrganizationChoose the most suitable Schema for your content type and map your custom fields according to its property specifications.
4. Placement location:jsonLdTags are usually placed in the HTML's<head>or<body>Tag inside, the specific position does not affect search engine parsing, but it is recommended to place them uniformly for management.

by masteringarchiveParamswithjsonLdThe combination of these powerful tags allows you to fully unleash the potential of Anqi CMS, injecting new vitality into the website's SEO performance.

Frequently Asked Questions (FAQ)

Q1: Why did I addarchiveParamsandjsonLdThe label is not displayed in Json-LD but the custom field is?

A1: This could be caused by several reasons. First, please check if the 'call field' name of the custom field matches the one youarchiveParamsinsorted=falseThe key names accessed in the mode are identical, including case. Secondly, ensure that the custom fields are filled in when publishing documents in the background, if they are empty,{{ variable }}May not output anything.Finally, check if the JSON syntax of Json-LD is correct; a tiny comma or quote error can cause the entire Json-LD block to fail to parse.Suggest using Google's Rich Results Test tool for real-time validation, it will point out the specific error location.

Q2:archiveParamsCan I get custom fields from other documents except the current document?

A2: Yes.archiveParamsTag supportidParameters. You can go through any page toid="[文档ID]"specify getting custom fields from any document. For example,{% archiveParams relatedProductFields with id="123" sorted=false %}You can obtain the custom field of the document with ID 123. This is very useful when you need to aggregate related information or build a complex page layout.

Q3: If I have many custom fields and want to dynamically include some of them in Json-LD, is there a more flexible method?

A3: Of course, you can combinearchiveParamsofsorted=truePatterns and templates offorLoop as wellifTo judge and implement. First, get all custom fields in array form:{% archiveParams allCustomFields %}Then, in the Json-LD JSON structure, you can dynamically construct part of the JSON content using template logic:

<script type="application/ld+json">
{
    "@context": "https://schema.org/",
    "@type": "Product",
    "name": "{% archiveDetail with name='Title' %}",
    {% for field in allCustomFields %}
        {% if field.Name == "产品SKU" %}
            "sku": "{{ field.Value }}",
        {% elif field.Name == "品牌名称" %}
            "brand": { "@type": "Brand", "name": "{{ field.Value }}" },
        {% endif %}
    {% endfor %}
    "description": "{% archiveDetail with name='Description' %}"
    {# ... 其他字段 ... #}
}
</script>

This method allows you to base onfield.Name(Custom field display name) orfield.FieldName(Field name if used)sorted=falseIt is more convenient to judge whether a field is included and flexibly build Json-LD, especially suitable for conditional display or variable field names.However, pay attention to the strict correctness of the generated JSON format, avoiding extra commas and such issues.