In AnQi CMS, implementing the dynamic filtering function of documents is a key step to improve the user experience of the website. This usually involves close collaboration between two core interfaces:archiveFiltersUsed to obtain the available filtering conditions andarchiveListIt is responsible for retrieving and displaying the corresponding document list based on these conditions.A deep understanding of how they work together can help us build a flexible and user-friendly content filtering mechanism for the website.

Understand the filtering mechanism: from definition to discovery

Imagine, your website has published a large amount of articles, products, or other content, and users may want to search for information of interest based on custom attributes such as 'city', 'education', 'product category', and so on.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).Even better, you can set these custom fields to 'filterable', so they can serve as a basis for users to filter content.

So that the front-end application knows what filtering conditions are available, Anqi CMS providesarchiveFiltersInterfaceThis interface plays the role of a "filter condition discoverer".

When you callarchiveFiltersthe interface, you need to provide it with amoduleIdClarify the filter conditions you want to retrieve for which content model. For example, if you have a product model with ID 1, you want to retrieve the filter conditions for all products under this model, you should pass inmoduleId=1.

In the returned data of the interface, you will see a list, where each list item represents a selectable dimension. Among them:

  • nameThis is the Chinese name of the filtering condition, which is convenient for users to understand, such as 'City' or 'Education level'.
  • field_nameThis is the internal field name of this filtering condition in the system (for examplecityorcertificateIt is used as a parameter name in subsequent filtering, very critical.
  • items: It is a list containing specific filtering options, each with onelabelChoose from cities like Beijing and Shanghai.

ByarchiveFiltersYour front-end application can dynamically retrieve all available filter categories and their specific options under the current content model, thereby flexibly rendering filter menus such as dropdowns, checkboxes, or tag clouds.

Apply filter condition: convert discovery to filter

Once your front-end page passesarchiveFiltersThe interface successfully retrieved and displayed all available filtering conditions and options, allowing users to make selections from these options. Next, the user's selection needs to be applied to the document list, which is wherearchiveListInterfaceTook the stage.

archiveListThe interface is a powerful tool used by AnQi CMS to obtain a document list.It supports various parameters to control document retrieval, including by category ID, keywords, sorting methods, etc.And for the custom filtering we are discussing here,archiveListProvided a flexible mechanism named "Custom Filter Parameter".

The core operation here is that you need toarchiveFiltersThe interface returnsfield_namefor examplecity) as the parameter key (key), and select theitemsfrom the selected one.labelThe value (e.g., 'Beijing') as the parameter value (value), added in the form ofkey=valueto thearchiveListrequest.

For example, if the user selects 'City' as 'Beijing' on the front-end page, then when constructingarchiveListyou need to add it to the URL query parameters.city=北京If the user also selects a "degree" of "Bachelor's", then the request parameters will becomecity=北京&certificate=本科.

At the same time, when callingarchiveListIt is recommended to use the interface for filtering,typethe parameter topageThis not only allows you to get the total number of documents needed for pagination, but also ensures that the custom filtering parameters can take effect correctly.

The actual application scenario and operation steps

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

  1. Initialization of page loading:When the user first visits the list page, the front-end calls first:archiveFiltersInterface, pass the corresponding current list pagemoduleId.
  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. The user selects a filter condition:The user clicks or selects one or more filter options on the page.
  4. BuildarchiveListRequest:The front-end captures the user's selection, based onfield_nameandlabelConstruct a new URL query parameter. 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 the request and update the list:The front-end uses these parameters to callarchiveListthe interface. After the back-end receives the request, it 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 meet the conditions and the total number.
  6. Display the filtered results:After the front-end receives new data, it updates the document list on the page, and may also update the document count next to the filter conditions (if necessary).

In this way, the Anqi CMS'sarchiveFiltersandarchiveListThe interface works collaboratively, providing a powerful and flexible dynamic filtering capability for website content, greatly improving the efficiency of users browsing and searching for information.

Frequently Asked Questions (FAQ)

Q1: Why do I callarchiveFiltersWhen interfacing, it returns thedataThe array is empty or there are very few filtering conditions?A1: This usually has several reasons. First, make sure you pass themoduleIdIt is correct, and the corresponding content model is indeed configured with custom fields in the Anqiy CMS backend.Secondly, most importantly, you need to explicitly check the fields you want to use as filter conditions in the custom field settings of the content model.If the field is not set to filterable,archiveFiltersThe interface will not return them.

Q2: Can I apply multiple filter conditions at the same time? For example, both the document where 'City' is 'Beijing' and the document where 'Education' is 'Bachelor'?A2: Absolutely. Anqi CMS'sarchiveListThe interface supports receiving multiple custom filter parameters. You just need to specify differentfield_name=labelAdd the key-value pair as a separate query parameter to the request URL. For example:/api/archive/list?moduleId=1&type=page&city=北京&certificate=本科.

Q3:archiveFiltersThe interface returnsitemsin the list oftotalWhat is the use of the field? Why is it always 0 in the example?A3:itemsin the list oftotalThe field is designed to indicate how many documents meet the criteria under the current filtering option. However, inarchiveFiltersIn the default implementation of the interface, it is mainly responsible for providing the *available* filter 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 statistics separately on the front end or consider custom development on the back end to provide this aggregated data.