In AnQi CMS, to better organize and display content, we often use document models and custom fields.When you want to provide more flexible filtering functions for documents under a specific model, for example, to search according to certain attributes of a document such as 'city' or 'education', you need to know how to obtain these filterable parameter fields.

This is usually a two-step process: first, we need to determine the model ID of the target document (module_idThis 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.

First step: Get the model ID of the document (module_id)

To understand a specific document'smodule_idWe can use the 'Get Document Details API'. This API can provide all basic information about a specified document, including the associated model ID.

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

For example, if you want to get the details of the document with ID 1, the request parameters would beid=1In the data returned by the interface, you will find a field namedmodule_idThe field. The value of this field (an integer) is the model ID required for subsequent query filtering parameters.It is like a 'residence register' of the 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_idThe value is1.

Second step: usemodule_idQuery all the filterable parameter fields under the model

Once we have obtainedmodule_idYou can use the 'Get Document Parameter Filter Interface' to query all the fields and their specific options available for filtering under the model.

To{域名地址}/api/archive/filtersSend aGETRequest, and take the previous step obtainedmodule_idasmoduleIda parameter.

For example, if yourmodule_idIs 1, the request parameters will bemoduleId=1. This interface response will clearly list all 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,dataThe field is an array, where each element 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 for the filtering parameter in the interface, it is the key identifier you need to use for subsequent filtering requests.
  • itemsA list containing all the selectable values for the filtering parameter (label), as well as the number of documents corresponding to each option in the current state (total)

In this way, you can not only know which fields can be filtered, but also understand what specific filtering options each field provides.

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 system built-in fields, you can combine the "Get Model Details Interface" (}/api/module/detail) Query. This interface will have one in the returned model details,fieldsan array listing all the custom fields of the model, where each field has oneis_filterThe attribute explicitly indicates whether the field is set as filterable. This can help you understand the logic of setting the filter parameters from the source.

How to apply these filter parameters

Obtain these filterable onesfield_nameand the correspondinglabelAfter that, you can apply it to the "Get Document List Interface" (/api/archive/list) to achieve more refined document list filtering.

For example, if you get fromarchive/filtersinterfacefield_nameWithcityanditemscontainslabelIf the option for 'Beijing' is selected, then you can add in the request/api/archive/listat that timecity=北京As a query parameter, to retrieve all documents related to the model and belonging to "Beijing". This provides a powerful foundation for building dynamic, user-friendly content filtering interfaces.

By performing these two steps, you can easily implement the need to dynamically obtain and apply filtering conditions based on the document model, providing users with more flexible and personalized content browsing experiences.

Frequently Asked Questions (FAQ)

  1. Q: Why?archive/filtersThe interface returnsitemsintotalIs the value of the field always 0?

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

  2. Q:moduleDetailthe interface inis_filterattributes andarchiveFiltersWhat are the differences in the data returned by the interface

    • A: moduleDetailThe interface returnsfieldsin the array,is_filterAn attribute indicating whether the field is configured by the administrator at the model definition level as 'Can be used as a filter condition'. It is a boolean value (trueorfalse), which explains theabilityHoweverarchiveFiltersData returned by the interface, which lists the specific options available for users to select and filter under this model,actually existof,label), and their calling names (field_nameIn short,is_filterCan this field be filtered?archiveFiltersWhat specific filtering values does this field have?

  3. Q: If my document model has not set any filterable fields, callingarchive/filtersWhat will the interface return?

    • A:If a document model indeed has not set any filterable custom fields, or all custom fieldis_filterproperties 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.