Panl Cookbook

The type of the Solr field and Panl type will determine the configuration options and the display.

The Panl JSON response attempts to provide the implementer with information to determine the rendering to the interface, rather than hard-coding Solr field names and deciding on how they should be handled.

In this chapter, some 'recipes' for how to implement various faceted search queries that have been seen on other websites.

BOOLEAN Facets

Apart from the boolean true/false value replacement, the BOOLEAN facet can be designated as a checkbox.

Displaying a BOOLEAN facet as a checkbox

This is only useful when you want to select only one of the true/false values or no value.

Even though a BOOLEAN facet has only two values, there are actually three states that a BOOLEAN facet can have:

4. 'True' selected - only those results with a true value will be returned
5. 'False' selected - only those results with a false value will be returned
6. Not selected - all results are returned which have either a true or false value.

Using a checkbox is different from using the in-built Panl functionality in that you may select 'true', 'false' or remove the selection.  In the case of a checkbox, you will only be able to select one of the true or false values, or select neither.

This is a good use case if you want to highlight only one of the values.  

True Value BOOLEAN Facet Checkbox Example

As an example shopping sites may have a 'Speedy' delivery checkbox, which will filter those results which are available for speedy delivery, however the shopping site does not wish to highlight the results that do not qualify for speedy delivery.  Hence the facet may be selected as either 'True' or no facet value at all.

False Value BOOLEAN Facet Checkbox Example

As an example, shopping sites may have items which are on backorder, thus making them unavailable for immediate delivery, but still deliverable once the backorder has been fulfilled.  For the user experience, you may wish to present a 'Exclude items on backorder' checkbox.  In effect this will set the boolean value for 'backorder' to 'false', if unchecked then all items will be shown, both those on backorder, and those not on backorder'.

In either of the above cases, any BOOLEAN facet can be turned into a checkbox, provided that you understand how this impacts the facet selection.

For the implementation, either the LPSE code, or the Solr field name must be known ahead of time.  This does tie the implementation to the data - (there is an additional piece of functionality which is under consideration to be able to set a 'checkbox' property on a BOOLEAN Facet), in the meantime, the implementation is as follows:

Using the contrived example of:

• Solr field name - JSON key name facet_name = in_built_eraser
• LPSE code - JSON key name panl_code = I

If the facet with the above Solr field name or LPSE code:

• Is in the panl.active.facets JSON Array, then the checkbox should be selected.
  
  To deselect the checkbox, use the remove_uri JSON property.
  
• Is in the panl.available.facets JSON Array, then display a checkbox with the value deseelcted selected.  
  
  To select the checkbox, use the uris.before and uris.after in conjunction with the searching through the values array for the value key equalling either "true" of "false" and use the value of the encoded key.

RANGE Facets

Minimum and Maximum values

Being able to use dynamic values.

Some shopping sites will only allow you

'Reverse' star Ratings

Many sites allow ratings of items (and comments), however, rather than searching for a rating between two values, they only permit a variable start range and upwards.  For the URL.

https://www.ryman.co.uk/stationery/pens/ballpoint?bv_rating=[2+TO+*]

The facet that is rendered:

Example Properties

To generate this example, the following <panl_collection_url>.panl.properties file could be used.

To generate the links, iterate from the panl.range.min.r property value to the panl.range.max.r property value and generate the link of

panl.prefix.r + <value> + panl.infix.r + panl.range.max.value

With the appropriate before and after links from the JSON response.

From the JSON response object, the above link generation would become:

uris.before + <value> + uris.during + uris.after_max_value

Which would generate a URL which would look like:

/Rating from: 1-star-and-UP/r-/

REGULAR Facets

Condensed Multivalued Paths

This is especially useful where there is a prefix and/or a suffix that gets applied to every single facet value that is selected.  

Condensing the path is only available on REGULAR facets that are defined as multivalued in the Solr schema (i.e. on the XML field definition there is an attribute and value of multiValued="true") AND have the panl.multivalue.<lpse_code>=true property set in the <panl_collection_url>.panl.properties file.

In this example, the original mechanical-pencils.panl.properties file has been edited so that the Colours facet has a prefix of 'Colour:':

Example Properties - Original

Base URL:

http://localhost:8181/panl-results-viewer/mechanical-pencils/brandandname 
(0 characters - not including the CaFUP)

One Facet, adding 'Black'

http://localhost:8181/panl-results-viewer/mechanical-pencils/brandandname/Colour:Black/W/ 
(15 characters - not including the CaFUP)

Two Facets, adding 'Blue'

http://localhost:8181/panl-results-viewer/mechanical-pencils/brandandname/Colour:Black/Colour:Blue/WW/ 
(28 characters - not including the CaFUP)

Three Facets, adding 'Red'

http://localhost:8181/panl-results-viewer/mechanical-pencils/brandandname/Colour:Black/Colour:Blue/Colour:Red/WWW/ 
(40 characters - not including the CaFUP)

Four Facets, adding 'Green'

http://localhost:8181/panl-results-viewer/mechanical-pencils/brandandname/Colour:Black/Colour:Blue/Colour:Red/Colour:Green/WWWW/ 
(54 characters - not including the CaFUP)

Five Facets, adding 'Yellow'

http://localhost:8181/panl-results-viewer/mechanical-pencils/brandandname/Colour:Black/Colour:Blue/Colour:Green/Colour:Red/Colour:Yellow/WWWWW/ 
(69 characters - not including the CaFUP)

Six Facets, adding 'Brown'

http://localhost:8181/panl-results-viewer/mechanical-pencils/brandandname/Colour:Black/Colour:Blue/Colour:Green/Colour:Red/Colour:Yellow/Colour:Brown/WWWWWW/ 
(83 characters - not including the CaFUP)

The  above URL will select pencil models that have colours in Black, Blue, Green, Red, Yellow, and Brown (There is only one result).  

Note the 6 'W' LPSE codes.

To condense the LPSE URL, configure Panl to have a multi value separator

Example Properties - Condensed

In the above configuration, note that the prefix is now 'Colours:' (plural) as opposed to the prefix of 'Colour:' in the previous configuration.  The impact of this is that the first facet will increase the LPSE URL length by 1, which has less of an impact as more facets are added.

Base URL:

http://localhost:8181/panl-results-viewer/mechanical-pencils-multi-separator/brandandname   
(0 characters - not including the CaFUP)

One Facet, adding 'Black'

http://localhost:8181/panl-results-viewer/mechanical-pencils-multi-separator/brandandname/Colours:Black/W/
(16 characters - not including the CaFUP)

Two Facets, adding 'Blue'

http://localhost:8181/panl-results-viewer/mechanical-pencils-multi-separator/brandandname/Colours:Black,Blue/W/
(21 characters - not including the CaFUP)

Three Facets, adding 'Red'

http://localhost:8181/panl-results-viewer/mechanical-pencils-multi-separator/brandandname/Colours:Black,Blue,Red/W/
(25 characters - not including the CaFUP)

Four Facets, adding 'Green'

http://localhost:8181/panl-results-viewer/mechanical-pencils-multi-separator/brandandname/Colours:Black,Blue,Red,Green/W/ 
(31 characters - not including the CaFUP)

Five Facets, adding 'Yellow'

http://localhost:8181/panl-results-viewer/mechanical-pencils-multi-separator/brandandname/Colours:Black,Blue,Green,Red,Yellow/W/ 
(38 characters - not including the CaFUP)

Six Facets, adding 'Brown'

http://localhost:8181/panl-results-viewer/mechanical-pencils-multi-separator/brandandname/Colours:Black,Blue,Green,Red,Yellow,Brown/W/
(44 characters - not including the CaFUP)

Which is slightly more readable, and saves space on the URL.

If the LPSE code is multivalued enabled (i.e the panl.multivalue.separator.<lpse_code> exists and is not an empty string), then the generated LPSE URLs will automatically include the correct information.

When rendering the value that the end user will see, you may choose either the encoded (which will include the prefix), or the encoded_multi (which will preclude the prefix) JSON key's value.

For the above example the compression rate - i.e. the ratio of condensed to normal as a percentage is as follows:

In the above table, remember that the condensed figure has a longer suffix that is applied to the values, hence the slight expansion for the addition of 1 colour.

OR Facets

Condensed OR Facets

Like the condensed multivalued facets, an OR Facet can have their LPSE path condensed by using only one prefix and one suffix irrespective of how many values are used within the URI.

In this example, the mechanical-pencils-or.panl.properties file for the 'brand' facet configuration is below:

Example Properties - Original

The above configures the brand facet to have a prefix of 'Manufactured by ' without any suffix.  When adding facets to the query, the URL quickly grows with the prefix being added to each facet value:

The landing page:

http://localhost:8181/panl-results-viewer/mechanical-pencils-or/brandandname
(0 characters - not including the CaFUP)

Adding the brand facet value 'Staedtler':

http://localhost:8181/panl-results-viewer/mechanical-pencils-or/brandandname/Manufactured by Staedtler/b/ 
(28 characters  - not including the CaFUP)

Adding another brand facet value of 'Mitsubishi'

http://localhost:8181/panl-results-viewer/mechanical-pencils-or/brandandname/Manufactured by Staedtler/Manufactured by Mitsubishi/bb/
(28 characters  - not including the CaFUP)

Adding a third brand facet value of 'Hightide Penco'

http://localhost:8181/panl-results-viewer/mechanical-pencils-or/brandandname/Manufactured by Mitsubishi/Manufactured by Staedtler/Manufactured by Hightide Penco/bbb/
(88 characters  - not including the CaFUP)

With a condensed LPSE path configuration (from the mechanical-pencils-or-separator.panl.properties file):

Example Properties - Condensed

The above configures the brand facet to have a prefix of 'Manufactured by ' (note the trailing space) and a suffix of ' Co.' (note the leading space) and an OR separator of ', or '.  When adding facets to the query, the URL will now have:

• Only one prefix
• Only one suffix
• Only one LPSE code

The landing page:

http://localhost:8181/panl-results-viewer/mechanical-pencils-or-separator/brandandname
(0 characters  - not including the CaFUP)

Adding the brand facet value 'Staedtler':

http://localhost:8181/panl-results-viewer/mechanical-pencils-or-separator/brandandname/Manufactured by Staedtler Co./b/
(32 characters  - not including the CaFUP)

Adding another brand facet value of 'Mitsubishi'

http://localhost:8181/panl-results-viewer/mechanical-pencils-or-separator/brandandname/Manufactured by Staedtler, or Mitsubishi Co./b/
(47 characters  - not including the CaFUP)

Adding a third brand facet value of 'Hightide Penco'

http://localhost:8181/panl-results-viewer/mechanical-pencils-or-separator/brandandname/Manufactured by Mitsubishi, or Staedtler, or Hightide Penco Co./b/
(66 characters  - not including the CaFUP)

For the above example the compression rate - i.e. the ratio of condensed to normal as a percentage is as follows:

In the above table, remember that the condensed figure has an additional prefix that is applied to the values, hence the slight expansion for the addition of 1 brand.

Analysed Facets (think Word Clouds)

Whilst Word Clouds have probably gone out of fashion, there is still value in being able to facet on individual words within a document.  The example that I will use here is government legislation and being able to allow people a quick way to search on specific phrases (which are facets as their query).

Whilst

The steps for implementation are

You will need to add information to the stopwords.txt file to stop them from being indexed.

Stemming is also a good idea to enable the stem of the word to be selected, so you don't have words such as stem, stemming, stemmed as individual words and

~ ~ ~ * ~ ~ ~