In AnQi CMS, the custom fields of documents are a reflection of its powerful flexibility, allowing us to add various unique attributes to content, thereby enabling more refined management and display of information.But for many developers and operations personnel, how to accurately obtain the values of these custom fields through the API is often a clear issue.Don't worry, Anqi CMS provides a clear path in API design, throughextraField, you can easily master this additional data.

UnderstandingextraField: treasure house of custom data.

When you make an API request to the Anqi CMS for details of a single document or a list of documents, the returned data will usually include a field namedextraa field that containsextraThe field, as the name implies, is a collection of 'additional' information, specifically used to store all the custom fields and their corresponding values that you configure for the document model in the background.It is an object type, whose internal structure is very intuitive and convenient for programming access.

To be specific,extraEach key inside the object corresponds to the form field name you set when creating custom fields in the AnQi CMS backend (field_name)。This key corresponds to a small object that contains three properties:

  • name：This is the Chinese name of the custom field for easy understanding.
  • valueThis is the actual content of the custom field filled in, which is the data you hope to obtain the most.
  • defaultIf the user does not fill in this field, it will display the default value set in the background.

How to get the value of a specific custom field? For example, 'author'

Assuming we are now to retrieve the author information of a document. In the Anqi CMS backend, you may have already added a named "author" to the article model, with the form field name ofauthorcustom field.

To obtain detailed information about this document, we usually usearchive/detailan interface. You can access the document throughIDor itsURL 别名（filename）to request this interface. For example, to request a document with ID 1:

GET {域名地址}/api/archive/detail?id=1

The data returned by the interface will be a JSON structure, wheredatathe object contains all the detailed properties of the document. Insidedatayou will findextrafields, which may look like this:

{
  "code": 0,
  "data": {
    "id": 1,
    "title": "欢迎使用AnqiCMS",
    // ... 其他常规字段 ...
    "extra": {
      "author": {
        "name": "作者",
        "value": "AnqiCMS",
        "default": ""
      },
      "certificate": {
        "name": "学历",
        "value": null,
        "default": null
      },
      "city": {
        "name": "城市",
        "value": "北京上海重庆广州天津",
        "default": "北京上海重庆广州天津"
      }
    },
    // ... 其他字段 ...
    "link": ""
  },
  "msg": ""
}

From the above example, we can clearly seeextrathere is aauthorkey. To get the actual name of the author, you just need to follow the data pathdata.extra.author.valueIt can be. In your programming language, it usually looks like thisresponse.data.extra.author.valueFor example, ifresponseIs the parsed JSON object, thenresponse.data.extra.author.valueIt will return"AnqiCMS".

Custom fields for document lists get applied

It is not only the details of a single document, when you accessarchive/listthrough an interface to obtain a list of document items, eachextraThe field will also contain its custom field information. This means you can easily display author, source, specific attributes, and other custom information directly in places like article lists, product display pages, etc., without needing to request details for each list item individually.

the way to access is witharchive/detailThe interface is completely the same. When traversing the document list, for each document object, you still access it according to the custom field name "form field call name".extraThe corresponding in the object.value.

Useful tips and precautions

  1. The field name is crucial: Be sure to remember the 'form field name' you defined in the backend custom field settings (field_nameThis is the unique identifier obtained through API programming. If forgotten, it can be obtained throughapi/module/detailinterface to get model details, which will list all custom fieldsfield_name.
  2. handle empty value situations: Not all documents will fill in all custom fields, or a field may not exist at all in some document models. Be sure to handle this in your code.extraCheck for null values in objects and their nested custom fields to avoid runtime errors. For example, before accessingdata.extra.author.valuefirst verifydata.extraDoes it exist anddata.extra.authorwhether it exists.
  3. Differentiatenameandvalue:extraEach custom field object under the field hasnameandvaluetwo properties.nameis the display name of the field (such as “author”), whereasvalueis the actual content you need (such as “AnqiCMS”).

By understanding and making good use ofextraField, Anqi CMS provides an extremely convenient way to manage and display a variety of content attributes, making your website or application content more profound and flexible.

Frequently Asked Questions (FAQ)

Q1: How do I know the form field name of a custom field if I don't know it?A1: You can confirm in two ways: first, log in to the Anqi CMS backend, go to “Content Management” -> “Model Management”, find the corresponding document model and click edit, where all custom fields and their “form field call names” under the model will be listed. Second, you can also callapi/module/detailInterface, pass in the model ID and find the custom field you want in the returneddata.fieldsarray, whose property is the corresponding call name.field_name.

Q2: Why is the one I getextraThe field is empty or does not contain the custom field I want?A2: This usually has several reasons:

1.  **文档未填写该字段**：如果该文档在编辑时，您在对应的自定义字段中留空了，那么 `extra` 中该字段的 `value` 就会是 `null`。
2.  **字段不属于该文档模型**：您可能试图获取的自定义字段并不属于当前文档所使用的模型。请检查后台模型配置。
3.  **接口类型**：只有 `archive/detail` 和 `archive/list` 这两个接口会在 `data` 中返回 `extra` 字段，其他接口如 `archive/prev` 或 `archive/next` 通常不包含此信息。

Q3:data.extra.your_field.nameanddata.extra.your_field.valueWhat is the difference? Which one should I use?A3:data.extra.your_field.nameThe one you set for this custom field in the background is returneddisplay name(for example, “author”)). Anddata.extra.your_field.valueThe field returned is the one that the user enters while editing the documentThe content actually filled in(For example "AnqiCMS"). In most cases, you would want to retrieve and display the content filled in by the user, so you should usedata.extra.your_field.value.