Front-end facets response

HawkSearch v4.0 API allows websites to send an AJAX request when the user modifies the search parameters by changing filters, visiting landing pages or performing keyword search. The response is returned by Hawk in JSON format.
Throughout this article, we consider https://preview-prod.hawksearch.com/elasticdemo as the reference search engine.
When we send the following request to Hawk:

We get the JSON response as attached:

Open

The facet section is as follows:
From the Json Response, the facet array value indicated by the key "Facets" has the list of all the facets.
Every facet is an object with its properties represented as key-value pairs.
FacetId: This is the unique identifier of the facet which is displayed when editing the facet through the HawkSearch workbench:

Name: This is the name of the facet displayed to the user on the search results page. This property corresponds to the display name of the facet in the workbench:

This is displayed on the front end as highlighted below:

Note that the property List Name visible on the workbench is absent in the response. This is displayed on the workbench's facet listing page only.
Field: this is the unique name of the field which the facet is associated with. Every facet is associated with a field internally. In other words, facet is a representation of the field values stored in Hawk.
On the workbench, the Field property shows up as follows:

Note that the workbench shows the Field's label whereas the API response has the actual unique field's name. We can verify this by visiting the field in the workbench:

FieldType: This property indicates the type of field which the facet is associated with.

Possible values are as tabulated below:

FacetType: Indicates the mode in which the facet is displayed and configurable from the workbench as follows:

Possible values for this are:

• 
  
  Checkbox and Link List facets - these facets display the filter options in a vertical listing format.
  The checkbox facet type shows a checkbox next to every option allowing multiple facet options to be selected at the same time. This is one of the most widely used type of facets.
  
  The link list facet type shows the options as clickable hyperlinks limiting the user to filter by only one value.
  
  Nested Checkbox and Link List facets are displayed similar to Checkbox and Link List facets, in addition to that, we can also show the relationship in between the facet filter options by nesting one under the other. These are also called Hierarchical facets.
  Notice the presence of + and – signs. These indicate expanded or collapsed state, clicking them toggles the state. This can be set with the property IsCollapsible
  
  
  Nested facets can either be expanded or collapsed by default – this can be set through the property IsCollapsedDefault available on the workbench as so:
  
  Nested facets also have another property applicable for them – whether or not to preload the children on the initial load of the page itself. If set to yes, all the children options for every parent option are loaded during the initial page load, this helps display the values quickly however, for facets having significant filter options, this is not advisable.
  Instead, turning this property off helps load the page faster but sends request to Hawk. Since this happens only when the user clicks the parent option. Depending on the implementation of your site, this is either an ajax request or a full page load, the latter being too time consuming.
  The property for this is PreloadChildren in the API.
  
  Size facet – this facet type renders the filter options as a grid allowing multiple selections unlike listing them sequentially. This facet type is easily interchange-able with previous facet types.
  
  Swatch facet – this is similar to the Size facet type however this is used to display images instead of the actual values. The color facet is a great example for this type of facet where it is more intuitive to show the colors themselves rather than the names of the color values.
  This facet type is also configured differently compared to the Size facet. For this facet type, we need to provide the images during the facet creation. These image can be updated later also.
  
  Configuration – upload images or provide links to images:
  
  Preview the values in swatch section:
  
  Rating Facet Type – this facet type displays rating "stars".
  
  Slider – facets holding numeric values have this special facet type option to select continuous values across a given range. The selection is made by sliding the handles collectively indicating the available range of values applicable to the facet.
  This is especially useful where continuous numbers are to be selected and providing any other option specified earlier, the best example being price.
  
  Search facets: these are special calculated facets which do not correspond to the data feed directly. The options to these facets are calculated and powered by HawkSearch without the need of an associated field.
  Note that the Facet Field Type has to be Search for these facets only:
  
  There are three types of Search facets available on Hawk:
  Related Searches – based on the searches made by all the visitors to the site till date, this facet shows other search terms related to the current search term. Note that this is a dynamic facet meaning, the facet values are not always the same but instead, they get fine-tuned based on searches made y the users over time.

  Highlighted below are the related searches for the term "hammer"
  
  Recent Searches – this facet displays the terms recently searched by the individual user alone.
  
  Search Within – this facet type allows the user to search within the current search results.
  
  
  Ref: Facet Type Examples at https://hawksearch.atlassian.net/wiki/spaces/HSKB/pages/327746/Facets
  DisplayType: This is the property which provides options to fine-tune the way the list of facet values will be displayed.
  Workbench setting as follows:
  For facets with FacetType checkbox and link list facets, we can :
  
  In the JSON output, the three different choices that will determine what fields will need to be defined are the same as above but in lowercase:
  scrolling
  default
  truncating
  
  For more details on how this is rendered on the front end page, please refer to the section "Checkbox & Link List Options" at https://hawksearch.atlassian.net/wiki/spaces/HSKB/pages/327746/Facets
  MaxCount: The integer value which indicates the maximum number of facet values which can be displayed inside the facet.
  
  MinHitCount: The integer value which indicates the minimum number of facet values the minimum count of filters the facet must possess in order to be displayed as an option.
  
  This is set to 1 by default.
  ParamName: this is the parameter to be used if you need to apply filter using this facet. Example, if you need to filter by the brand "The North Face" then in send the parameter "brand=The North Face" in addition to the other filters. Here, the ParamName is brand.
  This is displayed in the workbench if the facet field type is range otherwise it is the name of the field the facet is associated with.
  
  SortBy: indicates the default sort order, this can also be customized by specifying the field name, value and sort order in the datafeed file custom_facet_order.txt.
  
  
  
  Available values for this property are tablulated below:
  

• 
  ExpandSelection: Boolean value for collapsible facets, to set the default view as expanded (on page load/refresh).
  
  IsNumeric: Indicator for range type of facets to show the slider. This property is hidden for all other facet types.
  
  This is Boolean value (true/false) in the API response.
  
  
  
  
  
  
  IsCurrency: Indicates if the facet needs to display the currency symbol. If the facet's FieldType is set as either numeric or range, and the display type is slider, then this option is displayed.
  
  IsSearch: This makes the facet searchable for its filters. This is useful for facets containing more than 15 values in general.
  
  Front end site shows this way:
  
  The API response has Boolean value.
  ScrollHeight and ScrollThreshold: Shown in the workbench's facet page when the facet's DisplayType is set to scrolling. Enables adjustment of the facet height based on the values passed. ScrollHeight sets the height of the facet in pixels. ScrollThreshold sets the minimum limit for the number of filters to be present in the facet for it to be displayed in a scrolling manner.
  Typical values for ScrollHeight and ScrollThreshold are 150 and 10 respectively. If facet displaytype is not scrolling, then default values need to be 0 for both.
  
  Below example is a facet set to scrolling display type. Since this facet has more than 10 filters (ScrollThreshold), the height of 150px (ScrollHeight) is set to the facet.
  
  
  
  
  
  
  TruncateThreshold: This is similar to the scrolling facet. The difference is that the truncated facet shows only the first N values where N is the number set in the workbench, to load more values, user needs to click the "show more" link:
  
  More info available here - https://hawksearch.atlassian.net/wiki/spaces/HSKB/pages/327746/Facets#Facets-TruncatingDisplayType
  SearchThreshold: Similar to the truncating threshold, search threshold specifies the minimum number of filters to be present in the facet to make it search-able. The facet needs to have "Is Search Enabled?" set to on, in other words IsSearch property needs to be true.
  
  
  AlwaysVisible: Boolean indicator for visibility of the facets. Any facet which needs to be displayed on the front end has to have this set to true. If false, one or more rules needs to be defined which when satisfied, will display the facet.
  
  
  
  This has secondary priority against the "IsVisible" property which, if turned off, doesn't display the facet regardless of the AlwaysVisible property's value.
  Values: this is the property holding a list of facet filter (facet value) objects.
  Every facet filter has the following properties:
  a. Label – display name of the filter
  b. Value – internal value associated with the filter.
  c. Count – number of items in the search results which match the facet filter.
  d. NoFollow – text field either blank "" or rel="nofollow" to indicate if the facet does not need to be followed by web crawlers – this pertains to SEO optimization.
  
  Front end output has these values displayed, clicking on which the internal Value field is sent to Hawk as a filter request.
  
  
  
  
  
  Tooltip: quick help for the user available when hovered over the question mark next to the facet name
  
  
  
  
  IsCollapsible: Boolean value indicating whether the facet can be completely collapsed into a header
  
  
  
  
  IsCollapsedDefault: Boolean value indicating collapsible display
  
  
  The facet is collapsed/expanded by default based on this property.
  
  
  SortOrder:
  
  The sort order is relative to the other facets. It can be updated by entering the number or using the arrows highlighted below to drag and drop the facet relative to other facets.
  
  
  
  
  
  IsVisible: Boolean switch to toggle the visibility of the facet
  
  
  NofVisible:
  
  
  Height:
  
  
  
  FacetRangeDisplayType: Numeric value to indicate the sub type of the facet when it is a range.
  
  Available values:
  0 - None/Not a range facet
  1 - Text
  
  
  2 - Image
  
  
  3 - Both
  
  
  
  
  PreloadChildren: Nested facets can load children filters either upon click event of the parent filter or automatically. This choice can be opted based on the value of this property.
  Available values:
  
  
  ShowSliderInputs: For slider facet, the user-entered inputs can be made visible using this property.
  
  
  SwatchData: A special type of facet is a swatch which displays images instead of the facet filters. The JSON output consists of the list of images. This is most useful for colors.
  
  
  
  
  
  
  
  
  
  Ranges: This property corresponds to the facet which displays the ranges. A range facet, if changed to display like a checkbox list or link list, will provide an option for adding ranges. This helps with fields which need to provide searching continuous values within discrete ranges.
  
  
  Updating Field and Facet properties
  The article - API Documentation - v4 and the api info page http://lusearchapi-na.hawksearch.com/api/v9 - have detailed information on the API.
  To update the field, below are the recommended steps to follow:
  i. Query Hawk for the list of all fields with a GET request for this endpoint: https://lusearchapi-na.hawksearch.com/api/v9/Field

• this will return all the fields with their properties.

ii. Then copy the properties of the field to be updated.iii. Then send a PUT request with the updated property/properties to this endpoint: https://lusearchapi-na.hawksearch.com/api/v9/Field/{id}

• this will update one or more field property/properties using a single request

Similarly, to update the facet, below are the recommended steps to follow:
i. Query Hawk for the list of all fields with a GET request for this endpoint: https://lusearchapi-na.hawksearch.com/api/v9/Facet

• this will return all the facets with their properties.

ii. Then copy the properties of the facet to be updated.iii. Then send a PUT request with the updated property/properties to this endpoint: https://lusearchapi-na.hawksearch.com/api/v9/Facet/{id}

• this will update one or more facet property/properties using a single request