How to handle the `extra` field returned by the `archive/list` interface to obtain custom field information?

When using AnQi CMS for website content management, we often need to display more personalized data in addition to the conventional information such as title, introduction, thumbnail, etc.This additional information, such as the author of the article, the model of the product, the release location, etc., is achieved through the powerful custom field function of Anqicms.So, when we go through the front-endarchive/listHow can you elegantly extract and utilize these custom fields when fetching the document list through the interface? The answer is hidden in the returned data.extrathe field.

Inarchive/listIn each document returned by the interface (or called an article) data, you will find a field namedextraThe field. This field is like a treasure chest, containing all the custom field information you have carefully set for the document.extraThe field itself is an object (or sometimes called an associative array), the key (key) is the form field call name you set in the Anqi CMS background content model, and the value corresponding to each key is another object containingname/valueanddefaultAn object with three properties.

Let us understand through a specific example. Suppose you add a custom field named "author" in the "article" content model in the Anqi CMS background, and it internally calls a named author. When you pass througharchive/listWhen you retrieve the list of articles through the interface, if an article has filled in author information, then in itsextrafield, you will see a structure similar to this:

"extra": {
  "author": {
    "name": "作者",
    "value": "AnqiCMS编辑部",
    "default": ""
  },
  "publish_city": {
    "name": "发布城市",
    "value": "上海",
    "default": "北京"
  }
}

Here, authorandpublish_cityIs the name of the custom field call. They each contain:

• name: The Chinese display name of the field, convenient for understanding.
• value: This document is the actual content filled in for this custom field.
• defaultIf:valueIf left blank, this default value will be used.

It is very intuitive to obtain the values of these custom fields. You just need to use the "call name" of the field (that is,extraTo access it, then retrieve thevalueproperty. For example, if you have already obtained a single document object in your frontend codedocumentThe way to get the author's name isdocument.extra.author.valueTo get the publishing city isdocument.extra.publish_city.value.

This feature greatly enhances the flexibility and scalability of content. By customizing fields, you can add exclusive attributes that fully meet the business needs of different content models (such as articles, products, cases, etc.) andextraThe field is the key to passing these exclusive attributes from the backend to the frontend.This means you can design highly customized display pages based on the content model, without changing the core code to adapt to diverse content structures.

In actual development, there are several points to pay special attention to. First, be sure to checkextraWhether the field itself and its internal custom fields exist. Some documents may not have filled in a certain custom field, or the field may not be defined at all in the content model, in which case it is accessed directly.document.extra.someField.valueIt may cause the program to crash. A robust approach is to first determineextrawhether it exists, then determine whether the specific custom field exists, and finally try to retrieve itsvalueFor example, conditional statements can be usedif (document.extra && document.extra.author) { /* 使用 document.extra.author.value */ }to ensure the robustness of the code. Secondly, whenvaluethe field is empty, consider usingdefaultthe field as a backup display content to enhance user experience.

Furthermore, if you not only need to get the value of a custom field, but also want to know its type (such as text, number, or image), or whether it is a filterable field and other metadata information, then you can further utilize the services provided by Anqi CMS.module/detailThe interface can return the detailed definitions of all custom fields of the specified content model, including theirfield_name/name/type/is_filterProperties such as this are very useful for front-end dynamic form rendering or different handling based on field type.

In summary,archive/listThe interface returnsextraThe field provides a unified and flexible mechanism for handling custom field information in Anqi CMS.Understand and make good use of this mechanism, it will make your website content display more depth and personalization, thereby better meeting user needs.

Frequently Asked Questions (FAQ)

1.extraWhy are fields sometimes empty(null)?When you do not set any custom fields for the document type in the Anqi CMS backend content model, or although fields are set, all custom fields in the document instance are not filled in with any values (including default values), thenarchive/listThe interface returnsextraField may display asnullIt is recommended to check in the frontendextraWhether the field isnullTo avoid errors caused by attempting to access the properties of an empty object.

2. How to know the 'calling name' of a custom field （field_name)?The "display name" of a custom field is the unique identifier you set when creating or editing the content model in Anqicms background.If you forget the name of a field's call, you can enter the corresponding content model management interface in the background to view it.Furthermore, you can also callmodule/detailinterface (pass the corresponding model ID) to get the detailed definitions of all custom fields under the model, includingfield_nameProperty.

3.extrafields indefaultWhat is the value for? defaultThe value is in the custom field.valueA placeholder value provided when nothing is specified. For example, if you set up a "author" field and specify the default value "anonymous", then when a document does not explicitly fill in the author,extra.author.valueMay be empty, butextra.author.defaultWill still be "Anonymous". This can be used as a fallback option when displaying content, ensuring that even if no specific information is filled in, there is a friendly prompt or preset content.