One common requirement for product listings is to include a filtering function, which enables users to narrow down the list based on pre-defined criteria.
Norce satisfies this requirement through the use of Filters, and achieves th is by using the ListProductFilters2 method. This method mirrors the ListProducts2 method by utilizing the same input parameters, but returns filters based on the same result set that ListProducts2 would return.
It's common to use ListProducts2 and ListProductsFilter2 simultaneously. While ListProducts2 returns a batch of products, ListProductFilters2 returns filtering information based on the full result.
You can use this information to build a filtering mechanism in your app.
Norce Commerce provides several methods that are similar to ListProductFilters2 but with some specific variations.
| Name | Description |
|---|---|
| ListProductFiltersByCustomer | Corresponds to ListProductsByCustomer. |
| ListProductFiltersByIds | Corresponds to ListProductsByIds |
| ListProductFiltersByPricelist | Corresponds to ListProductsByPriceList |
It might be easier to explain filtering and further filtering by walking through an example:
| Action | Implementation | Result |
|---|---|---|
| Clicks on a navigation listing (all IPhones) | Calls ListProducts2 (with category smartphones and manufacturer apple) | The first 10 apple phones are returned |
Calls ListProductFilters2 | A list of filters is returned including  and  Only filters that has a count more than 0 is returned. | |
| User chooses to further filter on “iPhone 11” | Calls ListProducts2 with same input parameters, except the variable “filter” that gets parf|L6360_13239 (where parameterid for model is 6360 and listid for iPhone11 is 13239) | A new list of ProductItems is returned. Only Iphone 11 this time. (First 10 of 20) |
Calls ListProductFilters2 with same input as ListProduct2 above. | Same list of filters is returned as before but with new count values.
We change all count values in our UI, except for the filter we last changed (Iphone model), to make it easier to change  | |
| User chooses to further filter on “iPhone 11 Pro” | Calls ListProducts2 with same input parameters, and the variable “filter” has now parf|L6360_13239*L6360_13240 (where listid for iPhone11 pro is 13240) | A new list of ProductItems is returned. Only Iphone 11 and 11 pro. (First 10 of 34) |
Calls ListProductFilters2 with same input as ListProduct2 above. | Same list of filters is returned as before but with new count values. As before, we change all count values in our UI, except for the filter we last changed.  and  | |
| User chooses to further filter on “Internal Memory capacity” | Calls ListProducts2 with filter parf|L6360_13239*L6360_13240*L6361_13241 (where parameterid for memory is 6361 and listid for 128GB is 13241) | A new list of ProductItems is returned, containing only items with model "Iphone 11" or "11 pro" and internal memory at "128GB". (all product, 7 of 7 returned) |
Calls ListProductFilters2 with same input as ListProduct2 above. | Same list of filters is returned as before but with new count values. As before, we change all count values in our UI, except for the filter we last changed (which this time is the internal memory capacity).
 and  | |
| User chooses a product page. | GetProductById is called. | See separate article about [product presentation](working-with-products-and-variants.md#product-presentation). |
When using ListProductFilter, you will receive a collection of filters that include a Name, Type, and a list of FilterItems. The FilterItem may contain different fields depending on the filter type and the parameter type.
See more about the filter schemas.
The Name value is necessary if you need to add additional filtering to your subsequent calls to the Norce Commerce Product Service (for both ListProduct and ListProductFilter). The Type value provides a more descriptive name.
If all products in the result set belong to a specific filter, that filter will not be included in the response since it can no longer be used to narrow down the results.
For instance, if you list products belonging to a specific category, all products will have that category and no category filter will be included in the response.
All calls return the following:
A
Filterentity containing aNameattribute that is used for further filtering. The name ends with an "f" to indicate it is a filter.On the
FilterItemlevel, each item has anIdthat is used for further filtering, aCountthat indicates how many products have this filter, and aSortOrder(if not null) that specifies how to sort the filters. If it exists,Uomis the unit of measurement set on the parameter and can be used in conjunction with theName.
To filter the product result based on user actions, you can create a filter string and pass it as an input parameter to both ListProduct and ListProductFilter. While ListProduct will return a new result set, ListProductFilter will return the same filters as before, but with updated count values.
The table below provides information on what the ListProductFilter returns and how to use it for further filtering.
Further filtering with many different types of filters implies a logical "and" operation between them. However, when dealing with multiple values of the same type, a logical "or" operation is applied except in the case of parametric filters. Please refer to the restrictions outlined in the table below.
| Type (name) | Description | Restrictions | Further filtering |
|---|---|---|---|
Category (catf) | Returns FilterItem. Id has the categoryId. Products can have one or more categories. | Products can have 0, 1 or many. Filtering on more than one implies a logical “or” between them. | catf|categoryId1,categoryId2; example: `catf |
Flag (flgf) | Returns FilterItem.Id has the flagId. | Products can have 0, 1 or many. Filtering on more than one implies a logical “or” between them. | flgf|flagId1,flagId2; `flgf |
Manufacturer (mfrf) | Returns FilterItem.Id has the manufacturerId. | Products must have 1. Filtering on more than one implies a logical “or” between them. | mfrf|manufacturerId1,manufacturerId2; `mfrf |
OnHand (ohf) | Returns FilterItem.Count has the number of products that has on-hand over 0. | Products can have true or false. Multiple values are not allowed. | ohf|[true or false]; `ohf |
Price (prcf) | Returns FilterPriceItem. The fields From, To, FromIncVat, ToIncVat is returned. | Products can have any decimal value. Multiple ranges are not allowed. | prcf|[inc/excl vat]_[from]-[to]; `prcf |
Parametric (parf) | Returns a list of FilterItem's. | Products can have 0, 1 or many. ! or * separates the different parametric filters. Filtering on many different parametrics implies a logical “and” between them. Many filters between same parametric implies a logical “or”. | parf|[list and multiplelist filters]*[range and bool filters]; parf|ListFilter*MultiFilter*RangeFilter*BoolFilter; |
| Parametrics of type List | If returned, it is a FilterListItem Contains a list of FilterItem's representing the different parametric list values. | - | L[ParameterId]_[ListValueId]*L6360_13239* |
| Parametrics of type MultipleList | If returned, it is a FilterMultiItem | - | M[ParameterId]_[MultiListId]*M6355_3390* |
| Parametrics of type Integer, Decimal or Date. | If returned, it is a FilterRangeItem | - | V[ParameterId]_[From]-[To]V60_256-1024V123_1.4-2.5 |
| Parametrics of type Boolean | If returned, it is a FilterBoolItemCount (number of Products that have the value true), FalseCount (number of Products that have the value false). | - | V[ParameterId]_[0 or 1]-[0 or 1]V123_1-1 (123 is set to true)V123_0-0 (123 is set to false)V123_0-1 (123 is set to true or false) |
Please note that all filter parameters are returned, however, the Text and Html parameters, despite being set as filters, will not be included.