How to get the parameter filter condition list of a specified document model?

In website operation, providing users with a convenient content filtering function can significantly improve user experience and content discovery efficiency.AnQi CMS provides powerful interfaces that allow us to flexibly obtain and utilize these filtering conditions.Today, let's discuss how to get the parameter filter condition list of the specified document model in Anqi CMS.

Understand the importance of filtering conditions

Imagine if your website has many products or articles, and users want to search based on dimensions such as 'city', 'education', or 'product type'.If each filter requires manual input of keywords, the efficiency will be very low.By providing a preset list of filtering conditions, the user can quickly locate the target content by clicking or selecting.These dynamic filtering conditions are the key to improving the interactivity and user-friendliness of the website.

AnQi CMS provides a dedicated interface for us to easily obtain these filter parameters, and then build richly functional filters on the frontend page.

The core interface to get the filtering conditions

To get the parameter filtering conditions list of the specified document model, we need to use AnQi CMS'sarchive/filtersInterface. This interface is designed specifically to retrieve the model's filtering fields and their corresponding options.

API call method

The calling address of this interface is very intuitive:

{域名地址}/api/archive/filters

Remember,{域名地址}Replace with your actual website domain, for examplehttps://en.anqicms.com/api/archive/filters.

This interface usesGETThe method is called, which means you only need to attach the necessary parameters to the request, and do not need to send data in the request body.

Core request parameters:moduleId

The most critical thing is to provide the filtering conditions for a specific document modelmoduleId.moduleIdRepresents the unique identifier of the document model you want to query.For example, the 'Article' model may have an ID (such as 1), and the 'Product' model may have another ID (such as 2).

• How to obtainmoduleId?You can view the IDs of various models through the Anqi CMS backend or callmodule/listInterface to get the list of all models and their corresponding IDs.

When you initiate the request, just specify themoduleIdAttach as a query parameter to the URL. For example, if you want to get the filtering conditions of the document model with ID 1, the request example is as follows:

{域名地址}/api/archive/filters?moduleId=1

Interpretation of the interface returned data

Successfully calledarchive/filtersAfter the interface, you will receive a JSON formatted response.This response contains all the fields and their detailed information available under the document model.

{
  "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 the response ofdataThe field is an array, each element of which represents a filterable field. The structure of each filter field includes the following important parts:

• name(string): This is the display name of the filter condition, for example, "City
• field_name(string): This is the call name of the filter field, for example 'city', 'certificate'.This field is very importantbecause it is called after youarchive/listIt needs to be used as the key name of the request parameter when filtering the actual document list through the interface.
• items(object[]): This is an array that contains all available parameter options for the current filter field. Each option also includes:
  • label(string): Display text of parameter options, such as “Beijing”, “Master”, “All”.
  • total(int): Theoretically represents the number of documents matched under the option.In the current document example, it is displayed as 0, which may indicate that the interface does not directly return the exact count under the filter conditions, or it may need to be effective under specific configurations.labelJust do it.

Apply the filter condition to the document list

After obtaining this list of filter conditions, you can dynamically generate filters on the website front-end. For example, you can create dropdown menus or checkbox groups for "City" and "Education.

When a user selects one or more options in a filter, you can usefield_nameandlabelthe value, combinedarchive/listthe interface to retrieve the list of matching documents.

For example, if the user selects "city" as "Beijing", you can send the following request toarchive/list:

{域名地址}/api/archive/list?moduleId=1&city=北京

HerecityExactlyarchive/filtersThe interface returnsfield_namewhile北京is the user's selectionlabelIn this way, users can perform multi-condition combination filtering, which greatly facilitates the exploration of content.

Tip

• Background configuration is the foundation:Only when a custom field is set to 'filterable' in the document model of AnQi CMS backend, it will be displayed inarchive/filtersAn interface appears. If you find that some filtering conditions are missing, please check the backend model field configuration first.
• Handling of the 'All' option: itemsusually contains an 'All' option.label. When the user selects 'All', it usually means that there is no filtering for this field, so it can be omitted when callingarchive/listit can be omittedfield_nameParameter.
• field_namenaming conventions: field_nameIt is usually English or pinyin, used for interface calls, andnamewhich is Chinese or other languages, used for interface display.

Masterarchive/filtersThe use of the interface will enable you to build a more flexible and user-friendly content filtering feature for your safe CMS website, effectively enhancing the practicality and user experience of the website.

Frequently Asked Questions (FAQ)

1. Why do I callarchive/filtersthe interface returns?dataThe array is empty?This is usually due to the following reasons:

• You providedmoduleIdIncorrect, or no filtering fields are configured under the model corresponding to this ID.
• The document model has custom fields, but these fields are not checked as 'filterable' attributes in the model settings of the Anqi CMS backend.Please log in to the backend and check the field configuration of the corresponding model.

2.field_nameandnameWhat is the difference? Which one should I use? nameIs for user interface display, for example, displayed as "city", "education", which is more readable. Whilefield_nameIt is used for program internal identification and interface calls, for examplecity/certificateWhen you build a frontend filter, you need to send the user's selected conditions toarchive/listwhen usingfield_nameas the key for the request parameters.

3.itemsin.totalDoes the field always display as 0? Is this normal? What is its purpose?Based on the document example you provided,totalThe field is displayed as 0, which is normal. This may mean that in the current interface design,archive/filtersThe interface is mainly used to return a list of selectable options (i.e.,label) without real-time statistics of the number of documents under each option. When building the front-end filter, you mainly focus onlabelGenerate options as needed. If you need to display the number of documents under each filter condition, you may need to call the interface separatelyarchive/listand combine it with different filter conditions to count.