Tutorials

1. How to add a facet?

2. How to change a facet?

3. How to contextualize a facet?

Configured Facets List View

The facet view displays the list of configured facets. A facet can appear several times if it is configured differently for different widgets or in different contexts for the same widget.

The default listing view options are all available as in any other list view (see documentation here).

Edit a Facet

This document will focus on the edit dialog of a facet. Check the two tutorials above for more advanced use-cases!

When editing a facet, a dialog opens with 5 Tabs:

Context
Values
Dependencies
Parameters
Advanced

We will describe here the content and role of each of the 5 tabs.

After you are finished with your changes you can click on the SAVE (or CANCEL) button on the bottom right of the dialog.

Edit a Facet: Main Tab (Context):

Column	Description
Context	List of contexts that this facet applies to. This means that your configuration will only apply in the scope of the configured context. You can configure several entries in the Facet table for the same facet and for the same Widget(s) but for different Context (for example, if you want a facet to appear in a specific category, but not in another one). To learn more about Context, read the documentation here.
Widgets	List of widgets that this facet applies to (typically ‘search’ for the search page and ‘navigation’ for product listing pages)
Field names	List of fields that this facet applies to (this is the most important aspect, this is the product attribute which should be used as a facet, if you do not have a
Segments	Same as with Context, you can reduce the application of your configuration within a specific segmentation (see the segmentation menu)

Edit a Facet: Values Tab

Element	Use
Label	This is an optional input that allows you to override the label of the facet.
Evaluate	Allows you to select if the facet should be evaluated. If set to false, the facet will not be displayed, and its value will not be calculated.
Force include	Allows you to specify if the facet should be returned even if it was not requested.
Order	The order in which this facet should appear in. It’s a numerical value, and the smallest number appear first. The facet provided in the request will have the order 0..n according to their order of the request. If you want to put a facet before the first requested facet, you might need to set negative numbers. If you defined the facets in the admin only, we recommend you to consider a buffer of at least 10 between the orders (e.g.: 10, 20, 30, …) to it will be easy after-wise to inject a facet between two other facets without changing the order numbers of all the facets.
Position	Allows you to select the position in which the value should appear in the layout (this only is useful if you have facets appearing at different places of your layout, like for example on top of the results and on the left of the results). (for M2 projects: review how the "position" configuration is linked to which facets are displayed on different sections on your layout )
Display type*	Allows you to set if the facet should appear expanded, collapsed or hidden. (The facet will still be evaluated while hidden)
Visualisation*	Allows you to set how the facet should appear visually.
Value order enumeration	Allows you to set how the values of the facet are ordered: Counter (descending) show the facet values with the biggest amount of hits first Alphabetical (ascending/descending) order according to the alphabetical value Size automated ordering of sizes (e.g.: S,M,L,XL as well as 90x100,120x120,…) Custom / Natural / Store Option Definition custom cases, are not processed, only returned with the following values ('natural', ‘custom’, ‘store’)
Show counter	Allows you to set if the counter value should appear in parenthesis next to the facet values.
Position of user-selected value*	Allows you to set where the facet values selected by the user should appear.
Min value size**	Minimum amount of values that should be displayed.
Max value size**	Maximum amount of values that should be displayed.
Min display coverage	The facet should only appear if the facet options cover as many products as whatever the user enters here. E.g. If there are 100 products and the facet options for the facet colour only covers 35% of them. The user can enter 0.4 here and the facet won't appear.

* These parameters do not change any part of the behavior of Boxalino. They will be simply returned in our API Response so you can use them in your front-end templates, but do not expect any direct effect if you change their value and didn’t use them in your front-end templates.

** The Min/Max value size options will be evaluated in real-time and will affect the Boxalino Narrative API response. As in the example here, the values which are supposed to be appearing (shown to the user) will have the parameter “show:true” according to this rule (with “count” the index of the facet value in the list):
count < enumDisplaySize || facet.getValues().size() <= enumDisplayMaxSize
This means that if you have 10 values returned with enumDisplayMaxSize=7 and enumDisplaySize=5 then only the first 5 values will have parameter “show:true”.

Edit a Facet: Parameters Tab

The following additional parameters can be configured:

Element	Use
andSelectedValues	When several values are selected by the user, should the condition be and logical AND (only products with multiple values matching all of the selected ones should match) or a logical OR (any of the values should match)
dateRangeGap	(ignored, do not consider)
hierarchical	should be set to true only and always for the case of the configured field is a hierarchical field like ‘categories’
maxCount	Define a maximum number of facet values which can be returned (default value : -1 which means unlimited)
minPopulation	Indicate what is the minimum value for a facet value to be returned (default value : 1)
numerical	is the value numerical (otherwise considered as a string) WARNING: THE PRODUCT FIELD MUST BE NUMERICAL TOO IF TRUE (default value: false)
range	is the facet a range facet (like for price with a min and max) WARNING: IF TRUE, YOU MUST SET NUMERICAL TO TRUE TOO
boundsOnly	SHOULD ALWAYS BE SET TO TRUE IF range=true
selectedValues	(ignored, do not consider)
sortAscending	(deprecated, do not use)
sortOrder	(deprecated, do not use)
functions	will add a calculation function on the values but without using it in the ordering the values (typically, consider using more functions-asc or functions-desc which are also using the result to order the facet values
functions-asc	define a sort function in order to order the list of the facet values. typically, as you want to order with the highest value first, consider using functions-desc rather than function-asc
functions-desc	for example, ordering the facet values according to the sum of the product attribute bq_order_count_all_time (the field must be a single-value (not multi-value) numeric product attribute). orders=sum(bq_order_count_all_time) this will show the facet value with the highest sales first in this case, “orders=” is just a temporary name to put the value of the sum, but it could be something else, what is important is the function itself, so here sum(bq_order_count_all_time)
data-owner	define a data owner in case you have configured one in the menu “Data > Data Owners”, this will add all the meta-data of the returned data owners
facet-value-correlation	In case you provide additional facet value extra info in your doc_attribute_value export, you should set this parameter to “rtux-data-integration_facetValueExtraInfo” (but you can also do it in the facet parameters you send in your request). See the following tutorial for more details: https://boxalino.atlassian.net/wiki/spaces/BPKB/pages/856948860
allowMultiselect	(ignored, but passed through, so you can use it if you want to retrieve it in your front-end)
rangeFromField	(used in SW6/M2) for range facets, set the name of the field used as parameter in URL when range-from is selected(ex: price-from)
rangeToField	(used in SW6/M2) for range facets, set the name of the field used as parameter in URL when range-to is selected (ex: price-to)
requestField	(ignored, do not consider)

Edit a Facet: Dependencies Tab

The dependencies are only returned by the API response of Boxalino and are not processed, as they are supposed to be a client-side behavior (where the fact the user changes a value in a drop-down can have effect on the values of another drop-down without any page refresh).

As an example, we can see that the value “couple” should have, as an effect, the removal (effect : hide) of the age groups “kid”, “toddler” and “baby”. The jsonDependencies array is returned as a parameter of each of the returned the ‘bx-facets’

"jsonDependencies": [
                        {
                            "values": [
                                "couple"
                            ],
                            "conditions": [
                                {
                                    "fieldName": "age_group",
                                    "fieldValues": [
                                        "kid",
                                        "toddler",
                                        "baby"
                                    ]
                                }
                            ],
                            "effect": {
                                "hide": "true",
                                "order": "0",
                                "extraInfo": []
                            }
                        }
                    ]

Element	Use
	This is a dependency. Some basic information such as its values and conditions are displayed in the title. To edit and view the values in more detail click on the text to display the entire dependency.
	Click to add a new dependency.

Element	Use
Values	Allows you to set one or more values for this dependency.
Conditions	This panel is a list of conditions for your dependency. You can add additional conditions by clicking the “Add” button.
Conditions: Field	Allows you to set a field for a condition.
Conditions: Values	Allows you to set one or more values for a condition.
Conditions: Any	Allows you to set whether or not any value should apply.
Conditions: Negative	Allows you to set whether or not this condition should be inverted.
Effect	Here you can define the behaviour of the dependency.
Effect: Hide	Defines if the Values should be hidden or shown. (true = hide, false = show)
Effect: Order	Defines the order of the Values that are defined.
Effect: Add	Allows you to add one or more extra info’s to the effect.
Effect: Extra Info	Allows you to define a custom parameter with a name and value. Can be deleted using the trashcan button.

Edit a Facet: Advanced Tab

The advanced parameters you define are typically returned as part of the Narrative API response (in the bx-facets sections) without any modification / processing. This is therefore a way to “add” parameters which you want to be “returned” in our API response.

Element	Use
	Allows you to add a new extra info.
Extra info	Allows you to set custom parameters. (Parameter name goes on the left, value on the right) The trashcan button lets you remove an extra info.

Above It is explained how to configure facets in general, but the productfinder is slightly more specific. Here I will quickly explain what is special for the Productfinder facets.