How does the key-value pair structure (`key => item`) in the document details correspond to the backend custom field settings?

When using AnQi CMS to manage website content, the document details or document list interface (such asarchiveDetailandarchiveList) will often return data with a field namedextraThe field. This field is specifically used to carry the custom information we set for the document model. UnderstandextraThe structure of the field and its correspondence with the backend custom fields is crucial for frontend development and content management.

Understanding the custom field mechanism of AnQi CMS.

The AnQi CMS provides powerful custom field functionality, allowing users to flexibly expand their properties based on different types of documents (such as articles, products, etc.).In the background, when you enter "Model Management" and select a specific document model (such as "Article Model" or "Product Model"), you can add or edit custom fields for the model.

Each custom field when set in the background, there are several core properties that need to be paid attention to:

• Field name (field_name)This is the unique identifier for the field within the system, and it is also used in the field when we make API requests, inextrathe field askeyThe identifier. It is usually an English word or pinyin, such as 'author', 'city', 'certificate', etc.
• Field Chinese Name (name): This is a friendly name displayed on the back-end interface for content editors, such as "author", "publishing city", "education", and so on.It helps us intuitively understand the purpose of the field.
• Field Type (type): Determines the data type that the field can store, such as text (text), number (number), radio (radio), checkbox (checkbox), image (image), and so on.
• Is filtering (is_filter): Mark whether this field can be used as a front-end filtering condition.
• Default value (default/content): The initial value set for this field.

It is through these background configurations thatextrathe field is dynamically presented in the API response.

extrathe structure of the field is parsed.

When we go througharchiveDetailorarchiveListWhen the document data is obtained through the interface, if the model associated with the document is configured with custom fields, the data of these fields will be packaged intodataobject underextrain the field.

extraThe structure of the field iskey => itemin the form of:

• keyHere is thekey directly corresponds toYou are in the background custom field settingsThe field name (field_name). This is the unique identifier used by front-end developers to accurately access a custom field value. For example, if you set a custom field in the back end,field_nameWithauthorthen inextraIn the field, you will see a namedauthorkey?
• item: withkeyassociateditemIt is an object that contains detailed information and actual content of the custom field, usually including the following properties:
  • nameThis corresponds to the field Chinese name you set in the background. For example, ifkeyIsauthorthennameit might be 'author'. It is mainly used for display and understanding.
  • valueThis is the actual content filled in or stored in the current document in this custom field. This is the data we most often need to extract and display.
  • defaultThis property displays the default value set for this custom field in the background.

Let us illustrate this with an example:

"extra": {
  "author": {
    "name": "作者",
    "value": "AnqiCMS",
    "default": ""
  },
  "certificate": {
    "name": "学历",
    "value": null,
    "default": null
  },
  "city": {
    "name": "城市",
    "value": "北京\n上海\n重庆",
    "default": "北京\n上海\n重庆"
  }
}

We can clearly see from this returned data thatauthor/certificate/cityThesekeyThey are the field names we define in the background for the custom fields of the model. EachkeybelowitemThe object also lists in detail the Chinese name of the fieldname), and the actual content (value）and \default）。For example, to get the author\'s name, we simply need to accessextra.author.valueJust do it.

Application scenarios in practice

ThisextraThe mechanism of field and custom field correspondence brings great flexibility to the content management and front-end display of the website:

1. Dynamic content display: The front-end can useextrafields inkeyRender page content dynamically without modifying the backend code or database structure. Regardless of how many custom fields are added to the backend, the frontend can access and display them through a unifiedextrastructure.
2. Filter and SearchIf a custom field is marked as “filterable”（is_filter=true），then you will also see it inarchiveFiltersthe interface.field_nameThis allows the front-end to build complex filters, allowing users to retrieve documents based on the values of these custom fields, thereby providing a more refined content navigation experience.
3. Data import and publication: PassedarchivePublishorimportArchiveWhen publishing or importing a document, the data of the custom fields can also be submitted as part of the request parameters. At this time, the name of the request parameter key should also match the "field name" defined on the back-end. ...field_nameKeep consistent.

Through this design, Anqi CMS perfectly combines the flexibility of content management with the standardization of API data transmission, allowing website operators to easily expand the content model and also providing developers with a clear and predictable data structure.

Frequently Asked Questions (FAQ)

1. If I delete a custom field in the background, will it still be included in the API response?extraWill the field still contain it?Answer: No.extraThe field is dynamically generated and it will only contain the custom fields that exist in the current model and have content filled in the document. Once a custom field is deleted from the background or there is no content filled in the field in the document, the field will not be displayed.extraThis value appears in the field.

2.extrafields invalueWithnullWhat does this mean? How should I handle it?Answer:valueWithnullIndicates that the custom field for this document is not filled in on the backend. If a default value is set for this field in the backend,defaultthe property may display the default value, butvalueit will still benullunless the actual content is filled in. When handling on the front end, it should be checked.valueIs itnullto decide whether to display the default value, display empty content, or perform other logical operations.

**3. I can in `