Search Integration And The Panl Response Object

The Panl response is always of the type JSON (with a MIME type of "application/json") with UTF-8 encoding.

To integrate your web app with the Panl response you may choose any language, and whilst the integration parts may seem daunting at first, the Panl Results Viewer Web App JavaScript file comes in at under 700 lines of code (not including the minified libraries).  Provided that your language of choice can parse JSON (which almost all have libraries for, if not built-in already), the burden should not be too onerous.

URL Bindings

The Panl JSON responses are bound to the Panl URL path in the form of
http://localhost:8181/<panl_collection>/<panl_FieldSet>

For example, the mechanical-pencils Panl collection with the default FieldSet is bound to the Panl URL

http://localhost:8181/mechanical-pencils/default/

Which will return the JSON response detailed below.

Error Responses

There will ALWAYS be an error key (with a boolean value of either true or false)  on all responses which makes it easy to determine the best course of action. If there is an error (either 404, or 500), then the error key will be set to true, an integer status code keyed on status, and keyed on message, a human readable response.

An example 404 response (in non-verbose mode):

An example 500 response (in non-verbose mode):

Success Responses

Rather than replacing the original Solr JSON response object, Panl appends a new JSON Object to the existing Solr JSON response object.

The Solr JSON response object has the following form:

The Panl server adds two additional keys, namely a boolean valued key of error, and a JSON object keyed on panl to the root object. The response becomes (bold emphasis added):

Within the above panl JSON object are the following keys:

The following sections will go into greater detail for each of the JSON keys.

The "active" JSON Object

This JSON object contains all active queries, sorting, pagination, operands, and BOOLEAN, DATE range, RANGE, OR, and Regular facets with links to remove the specific active filter.

Line 2:

The JSON array of active facets - Regular, OR, RANGE, or DATE Range facets.

Line 3:

The JSON object of the selected number of rows to display per page

Line 4:

The JSON object of active page number

Line 5:

The selected query operand

Line 6:

The query phrase

Line 7:

The array or selected sorting in order of their selection

Line 8:

The sort fields lookup containing a key/value pair of the Solr sort field name and the Panl sort field name.

If there are no active filters for the particular type of filter, then the associated key will not be present. Each of the JSON arrays can hold one or more JSON objects.  The sort_fields JSON object is added as a convenience lookup function of the active sort fields for use with the available.sorting integration and implementation

Each of the objects will contain at least the following keys and will not be repeated for the other JSON object explanations:

Line 3:

The Panl LPSE code

Line 4:

The value of the Solr field

Line 5:

The value with any prefix or suffix which is URL encoded.  For example the brand Solr field with Panl LPSE code w has a prefix of Manufactured by+ and a suffix of  +Company, the encoded key with a value of OHTO would look like the following:

Manufactured+by+OHTO+Company

Line 6:

The URL path to remove this facet from the search results.

Overall Integration and Implementation

At a base level, implementation is straightforward with any of the active facets, although not all of the active filters may be rendered to the page.  In the Panl Results Viewer, the only active facets that are rendered for removal are:

1. Any query phrase,
2. Any active facets, and
3. Any sort ordering

The following filters are not rendered to the page within the Active Filters section:

1. Query operand,
2. Page number, and
3. Number of results per page

This does not mean that your implementation cannot include them as well, it was just a choice that was made with the Panl Results Viewer.

The general rule for implementation of generating links is that the remove_uri value is used as the href attribute for the anchor tag and the encoded value used as the text - i.e.

<a href="/Clutch/page-2/msb+po+/">5-per-page</a>

The "active.facet" JSON Array (Regular facet object)

A Regular facet contains the information to display the value and the removal URL.

Note: Lines in italics above have already been described in the "active" JSON Object section and are not repeated.

Line 2:

The name of the Solr field

Line 3:

The Panl name of the Solr field, i.e. the configured display name

Integration and Implementation

The implementation details are as per the Overall Integration and Implementation details section for facets, i.e. render the remove_uri as the anchor tags's href attribute and the encoded value for the anchor text.

The "active.facet" JSON Array (BOOLEAN facet object)

A BOOLEAN facet contains the information to display the value and the removal URL and will have additional JSON keys inverse_encoded, inverse_uri, and is_boolean_facet - which is always set to true.

Note: Lines in italics above have already been described in the "active" JSON Object section and are not repeated.

Line 2:

The name of the Solr field

Line 3:

Indicates that this is a BOOLEAN facet, with only two available values, true, or false.

Line 4:

This is the display for the inverse of the current value.  In the above example, the value is set to "true", so this inverse_value displays the "false" value, with boolean value replacement.

Line 5:

This is the URL path to use to invert the currently selected value, if true, this is the false URL path, if false, this is the true URL path.

Line 6:

The Panl name of the Solr field, i.e. the configured display name

Integration and Implementation

The BOOLEAN facet also includes two additional keys which can be used to render an 'inverse' link. So, in additional to the remove link, the inverse can be constructed using the inverse_uri value as the href attribute for the anchor tag and the inverse_encoded value used as the text - e.g. the URL:

http://localhost:8181/panl-results-viewer/mechanical-pencils/brandandname/able+to+be+disassembled/D/ 

The the inverse link is:

http://localhost:8181/panl-results-viewer/mechanical-pencils/brandandname/cannot+be+disassembled/D/ 

And an example anchor tag implementation for the inverse would be:

The rest of the implementation details are as per the Overall Integration and Implementation details section for facets, i.e. render the remove_uri as the anchor tags's href attribute and the encoded value for the anchor text.

Image: The In-Build Panl Results Viewer web app showing the BOOLEAN filter with the invert link.

The "active.facet" JSON Array (DATE Range facet object)

A DATE facet contains the information to display the value and the removal URL  and will have an additional key of and is_date_facet - which is always set to true.

Note: Lines in italics above have already been described in the "active" JSON Object section and are not repeated.

Line 2:

The name of the Solr field

Line 3:

Indicates that this is a DATE facet allowing a range of dates to be selected

Line 4:

The Panl name of the Solr field, i.e. the configured display name

Integration and Implementation

The base implementation details are as per the Overall Integration and Implementation details section for facets, i.e. render the remove_uri as the anchor tags's href attribute and the encoded value for the anchor text, however you may not want to to render this facet in the Active Filters, and just use the Range Filters section .

Image: The In-Build Panl Results Viewer web app showing the DATE filter in both the Active Filters and Range Filters sections.

The "active.facet" JSON Array (OR facet object)

An OR facet contains the information to display the value and the removal URL and will have an additional key of and is_or_facet - which is always set to true.

Note: Lines in italics above have already been described in the "active" JSON Object section and are not repeated.

Line 2:

The name of the Solr field

Line 3:

Indicates that this is an OR facet allowing multiple selections of this facet

Line 4:

The Panl name of the Solr field, i.e. the configured display name

Integration and Implementation

The implementation details are as per the Overall Integration and Implementation details section for facets, i.e. render the remove_uri as the anchor tags's href attribute and the encoded value for the anchor text.

The "active.facet" JSON Array (RANGE facet object)

A RANGE facet contains the information to display the value and the removal URL. A RANGE facet will have an additional key of value_to, and have two additional boolean keys, has_infix, and is_range_facet - which is always set to true.

Note: Lines in italics above have already been described in the "active" JSON Object section and are not repeated.

Line 2:

The name of the Solr field

Line 3:

Whether this field has an infix for the RANGE facet

Line 4:

Whether this is a RANGE facet

Line 5:

The Panl name of the Solr field, i.e. the configured display name

Line 6:

The ending range value for this range, used in conjunction with the value key of this JSON object.

Integration and Implementation

The base implementation details are as per the Overall Integration and Implementation details section for facets, i.e. render the remove_uri as the anchor tags's href attribute and the encoded value for the anchor text, however you may not want to to render this facet in the Active Filters, and just use the Range Filters section with the value and value_to already populated.

Image: The In-Build Panl Results Viewer web app showing the RANGE filter in both the Active Filters and Range Filters sections.

The "active.numrows" JSON Object

The following URL:

http://localhost:8181/panl-results-viewer/mechanical-pencils/brandandname/Clutch/page-2/5-per-page/mpn/

Has the following active filters set:

• Mechanism type (m) : Clutch
• Page number (p): page 2
• Number of rows per page (n): 5 per page [This is the active filter to remove]
  

Note: Lines in italics above have already been described in the "active" JSON Object section.

Integration and Implementation

The implementation details are as per the Overall Integration and Implementation details section for facets, i.e. render the remove_uri as the anchor tags's href attribute and the encoded value for the anchor text.

The "active.page" JSON Object

The following URL:

http://localhost:8181/panl-results-viewer/mechanical-pencils/brandandname/Clutch/page-2/5-per-page/mpn/

Has the following active filters set:

• Mechanism type (m) : Clutch
• Page number (p): page 2 [This is the active filter to remove]
• Number of rows per page (n): 5 per page
  

Note: Lines in italics above have already been described in the "active" JSON Object section.

Integration and Implementation

The implementation details are as per the Overall Integration and Implementation details section for facets, i.e. render the remove_uri as the anchor tags's href attribute and the encoded value for the anchor text.

The "active.query" JSON Object

The following URL:

http://localhost:8181/panl-results-viewer/mechanical-pencils/brandandname/hexagonal/qo+/ 

Has the following active filters set:

• Query (q) : hexagonal
• Query operand (o): q.op = AND [This is the active filter to remove]
  

Note: Lines in italics above have already been described in the "active" JSON Object section.

Integration and Implementation

The implementation details are as per the Overall Integration and Implementation details section for facets, i.e. render the remove_uri as the anchor tags's href attribute and the encoded value for the anchor text.

The "active.query" JSON Object

The following URL:

http://localhost:8181/panl-results-viewer/mechanical-pencils/brandandname/hexagonal/qo+/ 

Has the following active filters set:

• Query (q) : hexagonal [This is the active filter to remove]
• Query operand (o): q.op = AND
  

Note: Lines in italics above have already been described in the "active" JSON Object section.

Integration and Implementation

The implementation details are as per the Overall Integration and Implementation details section for facets, i.e. render the remove_uri as the anchor tags's href attribute and the encoded value for the anchor text.

The "active.sort" JSON Array

The sorting active filter contains the information to display the value and the removal URL. The object will have additional keys of inverse_uri and is_descending.

The following URL:

http://localhost:8181/panl-results-viewer/mechanical-pencils/brandandname/hexagonal/sb-q/ 

Has the following active filters set:

• Query (q) : hexagonal
• Sorting (s): Sorting by brand descending [ This is the active filter to remove / invert ]
  

Note: Lines in italics above have already been described in the "active" JSON Object section.

Integration and Implementation

Like the BOOLEAN facet, this has an inverse_uri which will allow you to generate a link that will invert the sort order, without interfering with any further sort orderings.

The is_descending key is a boolean value which can be used to generate the inverse link text.

The implementation details are as per the Overall Integration and Implementation details section for facets, i.e. render the remove_uri as the anchor tags's href attribute and the encoded value for the anchor text.

Image: The In-Build Panl Results Viewer web app showing a sort order of Brand descending, with the remove link, the change to ascending link, and the clear all sorting link.

The "available" JSON Object

This JSON object contains at maximum two JSON arrays (Note that the range_facets and date_range_facets JSON arrays will be empty if no facet was defined as a RANGE or DATE Range facet):

Line 2:

An array of facet objects that are available for DATE Range facets, this will be an empty array if no DATE Range facets have been configured.

Line 2:

An array of facet objects that are available for filtering the results

Line 3:

An array of facets that are configured as RANGE facets in the, this will be

The "available.date_range_facets" JSON Array

For each of the DATE Range facet objects, the following information is available:

Integration and Implementation

In the Panl Results Viewer, this is implemented as two drop downs (one for each of the range indicator and range type) and a text field for the value.

Image: The In-Build Panl Results Viewer web app showing the implementation of the DATE Range facet.

Of course, you may implement your interface in any way that you desire.

To generate the URL,

1. Start with the uris.before value (Line 4)
2. Append the URL encoded next or previous value (Line 2 or 13)
3. Append the integer value that is entered
4. Append one of the designators (e.g. designators.months) (Line 8 to 11)
5. Append the uris.after value (Line 5)

Render the above value as the href attribute for the link.

The "available.facets" JSON Array

For each of the facet JSON objects in the available.facets JSON array

An example of the brand available facet

This JSON array contains a list of all available facets (including names, encoded names, and counts) for the search, with links to add this facet to the Solr search query.

Integration and Implementation

To render the link on the search page, iterate through the values array (which is already sorted as per the Panl configuration) and generate the link with the following information.

1. Start with the uris.before value (Line 8)
2. Append the values[i].encoded value (Line 15)
3. Append the uris.after value (Line 9)

To render the value of the anchor tag use the encoded value and URL decode it.

The "available.range_facets" JSON Object

Range facts allow a variety of URL paths to be generated from the same dataset, the example included below is from the Mechanical Pencils collection.

Implementation and Integration

RANGE facets have a variety of configuration options, and depending on the requirements of the URL path generation will depend on what properties need to be set.

However the UI component is generated, there are two options for generating the minimum and maximum value.

1. Use the hard-coded minimum and maximum values that are configured in the <panl_collection_url>.panl.properties file, or
2. Use the dynamic maximum and minimum that are passed through in the facet.

Using the hard coded values will enable you to also use the minimum and maximum value replacement, whilst using the dynamic values will not.

If you are using the hard-coded values, it is recommended that the minimum and maximum wildcard properties are set to true.

Example of hard-coded values

The Panl Results Viewer uses this method, setting the range slider to the values of a minimum of 5 and a maximum of 50. Note that the actual minimum value is 4, however this is included in the minimum value as the minimum wildcard range search is enabled.

Image: The RANGE facet with hard-coded values with no selected range.

In the above image, no range was selected, in the below image a range of 17 to 40 grams was selected.  Note that there are only values between 17 and 32 in the range, however the UI reflects the values chosen.

Image: The RANGE facet with hard-coded values and a selected range of 17 to 40 grams

Image: The RANGE facet with dynamic range values and a selected range of 17 to 32 grams

In the above image, the same selection is made, and the range values have been updated to the maximum and minimum available (this UI example is not included in the Panl Results Viewer).

A dynamic range will allow a user to further refine the range to get a smaller subset of the range.  The above example does not allow a user to expand the range, however you are free to implement the range facet in whichever way that you choose.

Defining a Range Without an infix

Depending on the properties that are set,  all of the following URL paths are equivalent and will return exactly the same results. without an infix (this defaults to the ~ character) are equivalent and will return exactly the same results:

• /10~50/w+w/
• /10+grams~50+grams/w+w/
• /weight+10~weight+50/w+w/
• /weight+10+grams~weight+50+grams/w+w/
• /from+light~heavy+pencils/w+w/
• /from+light~50/w+w/
• /from+light~50+grams/w+w/
• /from+light~weight+50+grams/w+w/
• /from+light~weight+50/w+w/
• /10~heavy+pencils/w+w/
• /10+grams~heavy+pencils/w+w/
• /weight+10+grams~heavy+pencils/w+w/
• /weight+10~heavy+pencils/w+w/

Defining a Range With an Infix

Depending on the properties that are set, all of the following URL paths with an infix (set to +to+) are equivalent and will return the exactly the same results:

• /10+to+50/w-w/
• /weight+10+to+weight+50/w-w/
• /weight+10+grams+to+weight+50+grams/w-w/
• /10+grams+to+50+grams/w-w/
• /from+light+to+50/w-w/
• /from+light+to+weight+50/w-w/
• /from+light+to+weight+50+grams/w-w/
• /from+light+to+50+grams/w-w/
• /from+light+to+heavy+pencils/w-w/
• /10+to+heavy+pencils/w-w/
• /weight+10+to+heavy+pencils/w-w/
• /weight+10+grams+to+heavy+pencils/w-w/
• /10+grams+to+heavy+pencils/w-w/
• /weighing+from+10+to+50+in+grams/w-w/
• /weighing+from+10+to+50/w-w/
• /weighing+from+10+to+weight+50/w-w/
• /weighing+from+10+to+weight+50+grams/w-w/
• /weighing+from+10+to+50+grams/w-w/
• /10+to+50+in+grams/w-w/
• /weight+10+to+50+in+grams/w-w/
• /weight+10+grams+to+50+in+grams/w-w/
• /10+grams+to+50+in+grams/w-w/
• /10+to+50+in+grams/w-w/

The order of precedence with an infix set

The order of precedence for the text before the infix is:

• If it exists, the minimum range value replacement

~ else ~

• If there is a range prefix, the prefix + the 'from' value

~ else ~

• If it a value prefix or value suffix exists, the value prefix + value + value suffix

~ otherwise ~

• Just the value

The order of precedence for the text after the infix is:

• If it exists, the maximum range value replacement

~ else ~

• If there is a range suffix, the value  +  the range suffix

~ else ~

• If it a value prefix or value suffix exists, the value prefix + value + value suffix

~ otherwise ~

• Just the value

The flow chart below shows the logic for how the complete URL path for how a range facet is determined and generated

Flowchart: Logic for generation of the URL path values for range prefixes

Flowchart: Logic for generation of the URL path values for range prefixes

The order of precedence without an infix set

The order of precedence for the text without an infix set is:

• If it exists, the minimum range value replacement, or

• If it exists, the value prefix
• The value
• If it exists, the value suffix

The order of precedence for the text after the infix is:

• If it exists, the maximum range value replacement, or

• If it exists, the value prefix
• The 'to' value
• If it exists, the value suffix

The flow chart below shows the logic for how the complete URL path for how a range facet is determined and generated

Flowchart: Logic for generation of the URL path values for range suffixes

The "sorting" JSON Object

The following URL will return the sorting JSON object listed below.

http://localhost:8181/panl-results-viewer/mechanical-pencils/brandandname/11+grams/hexagonal/wsN+q/

The above query decodes to:

• A weight (w) of 11 (with a suffix of  grams) - note the white space   before grams),
• Sorting by name (N) ascending (+), and
• A search query of hexagonal

Looking at the response:

If you wanted to remove all sorting:

• remove_uri is the URL path to reset to no sorting - which is the default Solr sort of relevance descending (Line 2)

If you wanted to replace the sorting - i.e. remove the name sorting, and replace it with brand sorting:

• set_uri_asc is the URL path for ascending (Line 7)
• set_uri_desc is the URL path for descending (Line 8)

If you wanted to add sorting by brand in addition to the current sort of name - i.e. sort first by name ascending then by brand:

• add_uri_asc is the URL path for sorting by the current sort order, then by brand ascending (Line 9)
• add_uri_desc is the URL path for sorting by the current sort order, then by brand descending (Line 10)

Implementation and Integration

Image: The In-Built Panl Results Viewer web app showing the rendering of sorting options, additional sorting options and active facets.

1. Initial sorting options - a list of all available initial sort fields with links to both ascending and descending.
   

2. Additional sorting options - a list of additional sorting options available with links to both ascending and descending.
   

3. Active sorting options - for sorting options that have been applied, they will be listed in order of application, including links to

1. Remove this sorting option (keeping any other sorting options that have been applied.
2. Invert the sorting option (i.e. if the sort order is ascending, change it to descending, and vice versa)
3. Clear all of the sorting options

Rendering the Initial Sorting Options

1. Iterate through the available.sorting.fields JSON array
2. Render the value keyed on name ⇒ output Name
3. For the ascending link render the
   <CaFUPs><set_uri_asc> ⇒ output /mechanical-pencils/brandandname/11+grams/hexagonal/wsb+q/
   For the descending link render the
   <CaFUPs><set_uri_desc> ⇒ output
   /mechanical-pencils/brandandname/11+grams/hexagonal/wsb-q/

Rendering the Additional Sorting Options

1. Iterate through the available.sorting.fields JSON array
2. If the set_uri_asc or set_uri_desc key exists then

1. Render the value keyed on name ⇒ output Name
2. For the ascending link render the
   <CaFUPs><add_uri_asc> ⇒ output /mechanical-pencils/brandandname/11+grams/hexagonal/wsN+sb+q/
   For the descending link render the
   <CaFUPs><add_uri_desc> ⇒ output
   /mechanical-pencils/brandandname/11+grams/hexagonal/wsN+sb+q/

Example of Multi Sorting Display

Image: The In-Built Panl Results Viewer web app showing the rendering of sorting options as they are selected

1. No Initial sorting options selected - URL:
   http://localhost:8181/panl-results-viewer/mechanical-pencils/brandandname

1. No active filters rendered

2. Weight descending initial sorting option selected - URL:
   http://localhost:8181/panl-results-viewer/mechanical-pencils/brandandname/sw-/

1. brand and name additional sorting options are available
2. Active filters show sorting by

1. Weight descending

3. Active filters show clear sorting order link

3. Brand ascending additional sorting option selected - URL:
   http://localhost:8181/panl-results-viewer/mechanical-pencils/brandandname/sw-sb+/

1. Only the name additional sorting option is now available
2. Active filters show sorting by

1. Weight descending, then
2. Brand ascending

3. Active filters show clear sorting order link

4. Name descending additional sorting option selected - URL:
   http://localhost:8181/panl-results-viewer/mechanical-pencils/brandandname/sw-sb+sN-/

1. No additional sorting objects are available
2. Active filters show sorting by

1. Weight descending, then
2. Brand ascending, then
3. Name descending

3. Active filters show clear sorting order link

~ ~ ~ * ~ ~ ~