In the Anqi CMS, to better organize and display content, we often use document models and custom fields.When you want to provide a more flexible filtering function for documents under a specific model, such as searching by attributes like 'city' or 'education' of a document, you need to know how to obtain these filterable parameter fields.

This is typically a two-step process: first, we need to determine the model ID of the target document (module_id)，This is the key to connecting the document with the model definition; then, use this model ID to query all the filterable parameter fields under the model.

第一步：获取文档所属的模型ID（English）module_id)

要了解一个具体文档的（English）module_idWe can use the 'Get Document Details API'. This interface can provide all basic information of the specified document, including the associated model ID.

You can navigate to{域名地址}/api/archive/detailaGETRequest to call this interface. When making a request, you need to provide the document'sid(Document ID) orfilename(Document URL alias) as a parameter, either one is acceptable.

For example, if you want to get the details of the document with ID 1, the request parameters would beid=1You will find a field namedmodule_idThe field.The value of this field (an integer) is the model ID required for our subsequent query filtering parameters.It is like the 'household register' of a document, recording which content type it belongs to.

Return data example (simplified):

{
  "code": 0,
  "data": {
    "id": 1,
    "title": "欢迎使用AnqiCMS",
    "module_id": 1, // 这就是我们需要的模型ID
    // ... 其他文档详情
  },
  "msg": ""
}

From the above example, we can seemodule_idhas a value of1.

Second step: Utilizemodule_idQuery all filterable parameter fields under this model

Once we have obtainedmodule_idIt can be used to query all the available filter fields and their specific options under the model by using the “Get Document Parameter Filtering Interface” interface.

to{域名地址}/api/archive/filtersaGETRequest, and pass the one obtained in the previous step.module_idasmoduleIdParameter passing.

For example, if yourmodule_idIt is 1, the request parameters will bemoduleId=1. This interface response will clearly list all the fields set as filterable in the model.

Example of returned data:

{
  "code": 0,
  "data": [
    {
      "name": "城市",
      "field_name": "city",
      "items": [
        { "label": "全部", "total": 0 },
        { "label": "北京", "total": 0 },
        { "label": "上海", "total": 0 }
      ]
    },
    {
      "name": "学历",
      "field_name": "certificate",
      "items": [
        { "label": "全部", "total": 0 },
        { "label": "硕士", "total": 0 },
        { "label": "本科", "total": 0 }
      ]
    }
  ],
  "msg": ""
}

In this returned data,dataField is an array, each element of which represents a filterable parameter. Among them:

  • name: is the Chinese name of the filter parameter, convenient for users to understand.
  • field_nameThis is the actual field name used in the interface for this filter parameter, which is the key identifier you need to use when making filter requests in the future.
  • items：is an array that includes all the optional values of the filtering parameter (label), as well as the number of documents corresponding to each option under the current state (total).

Through this method, you can not only know which fields can be filtered, but also understand the specific filtering options provided by each field.

If you want to learn more about the detailed configuration of these filter fields, such as how they are defined in the background or whether they are built-in system fields, you can combine the "Get Model Details Interface" (}]/api/module/detailSearch by this. This interface will have anfieldsarray, listing all the custom fields of this model, each with anis_filterAttributes, explicitly indicating whether the field is set as filterable. This can help you understand the logic of setting filter parameters from the source.

How to apply these filter parameters

Obtained these filterable onesfield_nameEnglish corresponding tolabelAfter that, you can apply it to the “Get Document List Interface”(/api/archive/list) to implement more refined document list filtering functions.

For example, if you getarchive/filtersfrom the interfacefield_nameresponse forcity，anditemscontainslabelif the option is 'Beijing', then in the request/api/archive/listyou can addcity=北京As a query parameter, it retrieves the list of documents related to the model that belong to “Beijing”. This provides a powerful foundation for building dynamic, user-friendly content filtering interfaces.

Through these two-step operations, you can easily achieve the need to dynamically obtain and apply filtering conditions based on the document model, providing users with more flexible and personalized content browsing experiences.

Common Questions and Answers (FAQ)

  1. Q: Why?archive/filtersReturned by the interface.itemsintotalThe value of the field is always 0?

    • A: archive/filtersthe interface'stotalThe field is designed to represent the number of documents corresponding to each option under the current filtering conditions. If you just callarchive/filtersthe interface without cooperationarchive/listThe interface performs an actual document list query, thistotalThe value usually would be 0. It is usually used witharchive/listthe interface combined, when you pass in filtering parameters, archive/listIt will return the number of documents that meet the conditions, and thistotalis inarchive/filtersIn the context, it is more to show the existence of the filtering option rather than the real-time matching number.

  2. Q:moduleDetailin the interfaceis_filterproperties andarchiveFiltersWhat is the difference between the data returned by the interface?

    • A: moduleDetailReturned by the interface.fieldsin an array.is_filterProperty indicating whether the field is configured by the administrator as 'can be used as a filter condition' at the model definition level. It is a boolean value.trueorfalseIt describes the field.Capability.archiveFiltersThe interface returns data, which lists the specific options available for user selection under this model,which actually existand the specific options that users can select to filterlabel), as well as their calling names (field_nameIn short,is_filterIs this field filterable?archiveFiltersWhat specific filter values does this field have?

  3. Q: If my document model has not set any filterable fields, what will the interface return?archive/filters接口会返回什么？

    • A:If a document model indeed has not set any filterable custom fields, or all custom fields areis_filterattributes arefalse, then callingarchive/filtersthe interface,datathe field will return an empty array[]This indicates that there are no parameters available for filtering under the current model.