In what scenario should `archiveFilters` be used instead of `archiveParams`?

During the development and content management of Anqi CMS, we often need to obtain relevant information about documents (Archive). Among them,archiveFiltersandarchiveParamsThese are two API interfaces closely related to custom fields, but they have different design purposes and application scenarios.Understanding the difference can help us build website features more efficiently and improve user experience.

Let's take a simple look at the core functions of these two interfaces.

archiveParamsThe interface (get document parameters) is mainly used to retrieve the definitions of all custom fields of a document model, or the custom field values filled in by a specific document instance.When we request this interface, it will return a list containing field names, field names (field_name), types, default values, and even the optional values of a field (for example, if it is a multi-select field, it will return a string separated by newline characters).Its main purpose is to let developers understand the structure of the document model or to display the complete attribute information of a single document on the front end.For example, on a product detail page, you may need to display all custom attributes of the product such as "size", "color", "material", and their corresponding values, at this timearchiveParamsIt's very suitable.

AndarchiveFiltersThe interface (to get the document parameter filtering conditions) is an interface focused on the 'filtering' function.Its original design was to facilitate the construction of dynamic filters on the front-end page.When we callarchiveFiltersWhen a model ID is passed, it returns all custom fields marked as 'filterable' under the model, each with an attacheditemsThis array.itemsThe array includes all possible options (label) for the filtering field, and more importantly, it may also include the document count (total) for each option. Imagine, on a product list page, users will usually see "Brand", "Price Range", "Color", and other filtering conditions, with each condition showing the number of products corresponding to each option under the current filtering result, which isarchiveFiltersWhat is provided.

In what scenarios should we prioritize?archiveFiltersInsteadarchiveParamsWhat? The answer lies in whether your core need is tobuild an interactive document filtering interface.

When your goal is to provide users with an intuitive, operable filter panel,archiveFiltersIt is your better choice. It directly provides the 'dimensions' and 'options' list required by the filter.For example, you are developing a job recruitment website where users can filter job listings based on conditions such as 'city', 'education', 'work experience', and so on.

1. dynamically generate filter options:archiveFiltersit will return the 'city' field, itsitemsThe array contains specific city options such as “Beijing”, “Shanghai”, “Guangzhou”, etc. This isarchiveParamsa return ofvalue: "北京\n上海\n广州"This original string is more convenient, you do not need to manually parse the string, you can iterate through it directlyitemsArray to generate the front-end filter buttons or drop-down menus.
2. Get the number of documents under the filtered optionsIf:archiveFiltersreturneditemsintotalIf the field has an actual value, it can also tell you how many matching documents there will be under the current conditions, such as "City: Beijing".This is crucial for user experience, allowing users to clearly see which filter conditions have content and avoid selecting empty results.
3. A clearer definition of purpose:archiveFiltersClearly tell us which custom fields are designed to be used as filtering criteria. This helps us focus on building filtering functions rather than guessing whicharchiveParamsThe field can be used to filter.

On the contrary, if you just want to display all the details of a document (including its custom field values), or if you want to view the complete field configuration of a document model in the background tools,archiveParamsIt remains irreplaceable. It provides the "properties" of each field itself, rather than preprocessed "option lists" for dynamic filtering.

In summary, when you need to provide users withinteractive, selectable dynamic filtering functionalityand you want to display the matching count for each filtering option, without a doubt,archiveFiltersIt is your first choice. It can help you efficiently build a rich and user-friendly filtering interface.archiveParamsIt focuses more on obtaining the original structure and specific content of the document or model's custom fields.

Frequently Asked Questions (FAQ)

1. archiveFiltersThe interface returnstotalWhy is the field sometimes 0? totalThe field indicates the number of documents included in the current filter condition. If all filter optionstotalIt shows 0, which usually means there are no documents under this model, or all documents do not meet the default filtering conditions that the system may exist (such as not published, not reviewed, etc.). In addition, if your project is new or has a small amount of data,totalThe value may be displayed as 0 due to lack of data.

2. Can I usearchiveParamsThe custom field obtained after manual processing for filtering?Theoretically, it is possible.archiveParamsCan provide custom fieldsvalueFor examplevalue: "北京\n上海\n重庆"You can manually parse this string and split it into independent options. However, doing so will increase the complexity of the frontend logic, andarchiveParamsUnable to provide the number of documents corresponding to each option directly, which will greatly reduce the user experience of the filtering interface. Therefore, unlessarchiveFiltersUnable to meet your special requirements, it is not recommended to proceedarchiveParamsBuild a filter.

3. If my custom field is not inarchiveFiltersreturned in the interface, what should I do? archiveFiltersOnly fields marked as 'filterable' in the AnQi CMS backend model management will be returned. If a field you want to use for filtering does not appeararchiveFiltersIn the result, you need to log in to the Anqi CMS backend, go to the corresponding "Document Model Management", find the custom field and edit its properties, make sure it is checked as "filterable". Save after that,archiveFiltersThe interface will return the field and its options.