Implementing dynamic document filtering functionality in the AnQi CMS is a crucial step in enhancing website user experience. This usually involves close collaboration between two core interfaces:archiveFiltersUsed to obtain the conditions available for filtering.archiveListThen it is responsible for retrieving and displaying the corresponding document list based on these conditions.Deeply understanding how they collaborate can help us build flexible and user-friendly content filtering mechanisms for websites.

Understanding the filtering mechanism: from definition to discovery.

Imagine that your website has published a large number of articles, products, or other content, and users may want to search for the information they are interested in according to custom attributes such as 'city', 'education', 'product category', etc.The design philosophy of AnQi CMS is one that allows you to define various custom fields for different content models (such as article models, product models).The better part is, you can set these custom fields to be 'filterable', so they can serve as a basis for users to filter content.

To let the front-end application know which filtering conditions are available, Anqi CMS providesarchiveFiltersInterfaceThis interface plays the role of a "filter condition finder".

When you callarchiveFiltersthe interface, you need to provide it with amoduleIdSpecify the filtering conditions for the content model you want to retrieve. For example, if you have a product model with ID 1, and you want to retrieve the filtering conditions for all products under this model, entermoduleId=1.

The returned data from the interface will show a list, each item in the list represents a filterable dimension. Among them:

  • name：This is the Chinese name of the filter condition, convenient for users to understand, such as “City” or “Education level”.
  • field_name：This is the internal field name of this filter condition in the system (for examplecityorcertificateIt is used as a parameter name in subsequent filtering operations, very critical.
  • items: This is a list containing specific filtering options, each with alabel(such as "Beijing

PassarchiveFiltersYour front-end application can dynamically retrieve all available filter categories and their specific options under the current content model, thus enabling flexible rendering of filter menus, such as dropdowns, checkboxes, or tag clouds.

Apply filter conditions: Convert discovery into filtering

Once your frontend page passesarchiveFiltersThe interface successfully retrieved and displayed all available filter conditions and options, allowing users to make selections from these options. Next, the user's selections need to be applied to the document list, which is wherearchiveListInterface英文版：登上了。

archiveListThe interface is a powerful tool used by Anqi CMS to obtain a list of documents.It supports various parameters to control document retrieval, including by category ID, keywords, sorting methods, etc.archiveList提供了一个名为“Custom Filter Parameters”的灵活机制。

这里的核心操作在于，你需要将archiveFiltersReturned by the interface.field_name[for example]city）作为参数的键（key），并将用户从itemsSelected in the middlelabelThe value (for example, “Beijing”) as the parameter value (value), tokey=valueadded in the form ofarchiveListrequest.

For example, if the user selects "Beijing" as the city on the frontend page, then when constructingarchiveListthe request, you need to add the relevant parameters in the URL query parameter.city=北京If the user also selects 'Education' as 'Bachelor', the request parameters will becomecity=北京&certificate=本科.

At the same time, when callingarchiveListinterface for filtering, it is recommended totypeparameter settingspage. This not only allows you to obtain the total number of documents required for pagination, but also ensures that custom filtering parameters can take effect correctly.

Actual application scenarios and operation steps

In practical project development, this process usually operates like this:

  1. Page initialization loading:When the user first accesses the list page, the front-end calls first:archiveFiltersInterface, input the current list page corresponding tomoduleId.
  2. Dynamic rendering filter:Based onarchiveFiltersThe data returned, the front-end dynamically presents the filtering dimensions such as 'city', 'education' and their options on the page, which may be a sidebar filter menu or a filter bar at the top of the page.
  3. User selects a filter condition:User clicks or selects one or more filter options on the page.
  4. BuildarchiveListRequest:Front-end captures the user's selection, based onfield_nameandlabelConstruct new URL query parameters. For example, if the user selects "Beijing" and "Bachelor's Degree", the request parameters may become?moduleId=1&type=page&page=1&limit=10&city=北京&certificate=本科.
  5. Send request and update the list:Front-end uses these parameters to callarchiveListThe interface. After receiving the request, the backend willmoduleId/type/page/limitas well as the custom filtering parameters we pass in (such ascityandcertificate）To filter documents and return the list of documents that match the criteria and the total count.
  6. Display the filtered results:The front-end receives new data and updates the document list on the page, and may also update the document count next to the filter conditions (if needed).

Through this method, the Aanqi CMS ofarchiveFiltersandarchiveListThe interface协同工作，provides powerful and flexible dynamic filtering capabilities for website content, greatly enhancing the efficiency of users browsing and searching for information.

Common Questions (FAQ)

Q1: Why do I callarchiveFiltersWhen the interface returns,dataIs the array empty or only has a few filtering conditions?A1: This usually has several reasons. First, please make sure you enter themoduleIdIt is correct, and the corresponding content model has indeed been configured with custom fields in the Anqi CMS backend.Next, most importantly, you need to explicitly check the fields you want to use as filtering conditions in the custom field settings of the content model as 'Filterable'.archiveFiltersThe interface will not return them.

Q2: Can I apply multiple filtering conditions at the same time? For example, documents that both have 'City' as 'Beijing' and 'Education' as 'Bachelor'?A2: Absolutely. The Anqi CMS supports receiving multiple custom filter parameters. You just need to specify differentarchiveListinterface supports receiving multiple custom filter parameters. You just need to specify differentfield_name=labelThe key-value pair can be added as an independent query parameter to the request URL. For example:/api/archive/list?moduleId=1&type=page&city=北京&certificate=本科.

Q3:archiveFiltersReturned by the interface.itemsin the listtotalWhat is the use of the field? Why is it always 0 in the example?A3:itemsin the listtotalThe field is designed to represent how many documents meet the conditions under this filter option. However,archiveFiltersThe default implementation of the interface is mainly responsible for providing *available* filtering options itself, and does not count the number of documents under each option in real time, so it is usually set to 0 by default.If you need to display the number of documents corresponding to each filter option on the front end (for example, “Beijing (123)”、“Shanghai (45)”), you may need to perform the count separately on the front end or consider providing these aggregated data through custom development on the back end.