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

Firstly, let's briefly understand the core functions of these two interfaces.

archiveParamsThe interface (Get document parameters) is mainly used to get all the definitions of custom fields of a document model, or the values of custom fields filled in by a specific document instance.When we request this interface, it returns a list that includes field names, field call names (field_name), type, default values, and even all possible values for a particular field (for example, if it is a multi-select field, it returns 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.archiveParamsIt is very suitable.

whilearchiveFiltersThe interface (get document parameter filtering conditions) is an interface that is more focused on the 'filtering' function.Its original design was to facilitate the construction of dynamic filters on the front-end page.archiveFiltersWhen passing a model ID, it will return all custom fields marked as 'filterable' under the model, and each field will be accompanied by aitemsarray.itemsThe array includes all possible options (label) for the filtered field, and more importantly, it may also include the number of documents under each option (total). Imagine a product list page where users usually see 'brand', 'price range', 'color' and other filtering conditions. Behind each condition, there is a display of the number of products corresponding to each option under the current filtering result, which is exactly whatarchiveFiltersThe provided information.

Under what circumstances should we prioritize?archiveFiltersInstead ofarchiveParamsThe answer lies in whether your core need is tobuild an interactive document filtering interface.

When your goal is to provide a user-friendly, operable filter panel,archiveFiltersThis is your better choice.It directly provides the "dimensions" and "options" list required by the filter.For example, you are developing a recruitment website, and users hope to filter the job list according to conditions such as "city

  1. dynamically generate filter options:archiveFiltersit will return the "city" field,itemsThe array includes specific city options such as “Beijing”, “Shanghai”, “Guangzhou”, etc. This isarchiveParamsavalue: "北京\n上海\n广州"This original string is much more convenient, you don't have to manually parse the string and can traverse it directlyitemsUse an array to generate the frontend filter buttons or dropdown menus.
  2. Get the number of documents under the filter optionsIfarchiveFiltersreturneditemsintotalIf a field has actual values, 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 quickly see which filter conditions have content and avoid selecting empty results.
  3. A clearer definition of purpose:archiveFiltersExplicitly tell us which custom fields are designed to be used as filter criteria. This helps us focus on building filtering functionality rather than guessing whicharchiveParamsThe returned field can be used for filtering.

In contrast, 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, not the preprocessed 'option list' for dynamic filtering.

In summary, when you need to provide users withinteractive, selectable dynamic filtering featuresand you want to display the matching count for each filtering option, undoubtedly,archiveFiltersis your preference. It can help you efficiently build a feature-rich and user-friendly filter interface.archiveParamsIt is more focused on obtaining the original structure and specific content of the document or model's custom fields.

Common Questions (FAQ)

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

  2. Can I sayarchiveParamsThe custom fields obtained after manual processing are used for filtering?Theoretically, it is possible.archiveParamsCan provide custom fields?valuefor examplevalue: "北京\n上海\n重庆"。You can manually parse this string and split it into individual options. However, this will increase the complexity of the front-end logic, andarchiveParamsIt is not possible to directly provide the number of documents corresponding to each option, which would greatly reduce the user experience of the filtering interface. Therefore, unlessarchiveFiltersIt is not recommended to proceed through unless it meets your special requirementsarchiveParamsBuild the filter.

  3. If my custom field is not inarchiveFiltersthe interface returned, what should I do? archiveFiltersOnly fields explicitly marked as 'filterable' in the AnQi CMS backend model management will be returned. If a field you wish to use for filtering does not appear inarchiveFiltersThe 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 this field and its options.