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.

The JSON response for the URL:

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

Example JSON

{

"response": {

"docs": [ ... ],

"numFound": 55,

"start": 0,

"maxScore": 1,

"numFoundExact": true

"responseHeader": { ... },

"panl": {

"search": { ... },

"pagination": { ... },

"query_operand": { ... },

"sorting": { ... },

"available": {

"range_facets": [ ... ],

"facets": [ ... ],

"date_range_facets": [ ... ]

"timings": { ... },

"active": { ... },

"canonical_uri": "",

"fields": { ... }

"error": false,

"facet_counts": {

"facet_intervals": { ... },

"facet_queries": { ... },

"facet_fields": { ... },

"facet_heatmaps": { ... },

"facet_ranges": { ... }

"highlighting": { ... }

}

Lines 2-8:

This is part of the default Solr response which is not altered by the Panl server

Line 3:

These are the documents (i.e. the results) that are returned from the Solr server. This will be used to render the results to the page.

Line 9:

These are the headers which contain information about the query that was sent to the Solr server including the query time, field list, query operand, pagination information and other Solr parameters. Relevant information to Panl is replicated to the panl JSON key.

Lines 10-24:

This is the Panl JSON response object containing all data to implement the Panl URLs and user interface.

Lines 25:

Whether the Panl server encountered an error.

Lines 26-32:

This is part of the default Solr response which is not altered by the Panl server.

Lines 33:

Solr highlighted fields will be returned in this JSON Object

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 is around 800 lines of commented and formatted 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/4<panl_collection>/<field_set>

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 one of the JSON responses detailed below, either

An Error response (500 or 404), or
The Panl response JSON

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):

{

"error":true,

"status":404,

"message":"Not found"

}

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

{

"error":true,

"status":500,

"message":"Internal server error"

}

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^[34]:

{

"response": { ... },

"responseHeader": { ... },

"facet_counts": { ... },

"highlighting": { ... }

}

Note: The 'highlighting' key is only added to the response object if highlighting has been enabled.

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):

Note: The error key will __ALWAYS__ be false for a successful return of the Panl Response object.

{

"response": { ... },

"responseHeader": { ... },

"panl": { ... },

"error": false,

"facet_counts": { ... },

"highlighting": { ... }

}

Delving into the panl JSON object, the following keys are available:

{

"active": { ... },

"available": { ... },

"canonical_uri": "",

"fields": { ... },

"pagination": { ... },

"query_operand": { ... },

"search": { ... },

"sorting": { ... },

"timings": { ... }

}

The following sections will go into greater detail for each of the JSON keys contained within the Panl object.

Generating Panl Links

IMPORTANT: The Panl response object __NEVER__ contains the collection and field set (CaFUP) as there may be a difference between the URL of the search page and the URL of the Panl server (or you may want to redirect to a different page).

In the in-built Panl Web Apps uses the URL from the browser to determine the values.

The Panl response JSON object contains all information to:

The keyword search that is being used (if applicable),
Any specific fields that have been configured,
The query operand,
Pagination,
Number of results to display per page,
The currently selected and available facets and sort orders, and
The results containing the selected fields

This information is contained within two parts:

The information to display - be it the results, or the query, parameters, operands, and facets
The link information - to add, remove, replace, and invert parameters, operands, pagination and facets

In its most basic form, the HTML anchor tag (i.e. the <a /> tag) has the form of

<a href="https://synapticloop.github.io/panl/">Welcome to Synapticloop Panl</a>

With the href attribute being the link's destination (in the above example: https://synapticloop.github.io/panl/) and the text within the anchor tag (in the above example Welcome to Synapticloop Panl)being the text that is displayed for the link.

Generating the HTML

The image below shows the JSON response and the HTML and where each of the elements are used. The example was taken from the brand and name fieldSet for the mechanical pencils collection.

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

Whilst it may look confusing with links between various elements, it is relatively straightforward to implement - the Panl implementation renders more information to the web page than is required (for example, the LPSE code and the Facet type).

Image: Generating the HTML from the JSON response

Generating The href Attribute

To generate any of the href attributes, Panl provides the information in the JSON structure in various places, depending on the facet type, which is always available to interrogate in the response object. The following headings will provide the information about how to generate the specific hrefs.

For available facets the format for the href attribute is ALWAYS be:

uris.before + values[].encoded + uris.after.

Generating The Anchor Text

There are multiple values within the returned JSON structure that can be used to generate the Anchor text.

For available facets, you may choose to use either the values[].encoded (and URL decoding it first) or the values[].value. Both will work, however the encoded value will have prefixes/suffixes and value replacements and is the recommended JSON key to use.

Specific examples for each of the JSON structures are detailed in the following sections.

"response.docs" JSON Object Results Integration

The Solr documents (or results) are available on the JSON object with the key response. For the URL:

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

Example docs JSON Response

response: {

"docs": [

{ "name": "Goldfaber", "brand": "Faber-Castell" },

{ "name": "Criterium", "brand": "BIC" },

{ "name": "Fixpencil 22 (Textured)", "brand": "Caran d'Ache" },

{ "name": "Fixpencil 884", "brand": "Caran d'Ache" },

{ "name": "Nepresso Limited Edition", "brand": "Caran d'Ache" },

{ "name": "Sketch", "brand": "DEDEDEPRAISE" },

{ "name": "TK 4600", "brand": "Faber-Castell" },

{ "name": "TK 9400", "brand": "Faber-Castell" },

{ "name": "TK 9500", "brand": "Faber-Castell" },

{ "name": "Special", "brand": "Kaweco" }

"numFound": 55,

"start": 0,

"maxScore": 1,

"numFoundExact": true

}

Line 3-12:

The documents are returned with the fields as per the defined fieldSet of the CaFUP that was requested.

Line 14:

The number of results that were returned. Note: This information can also be found in the panl.pagination.num_results JSON object.

Line 15:

The start offset for the documents found.

Line 16:

The maximum result relevancy for the Solr query

Line 17:

Whether the returned number of results is exact - i.e. accurate. Note: This information can also be found in the panl.pagination.num_results_exact JSON object.

When integrating the display of the returned documents, you will need to know the Solr field name that you are going to render to the page. In the in-built Panl results viewer web app, the JSON keys are simply iterated and the value rendered to the page.

Example panl.fields JSON Response

"fields": {

"name": "Pencil Model",

"brand": "Brand"

}

The panl.fields JSON object can be used as a lookup between the returned document field name and the Panl name.

Example Rendering

The below image shows the relationship between the docs JSON object keys values and the panl.fields lookup JSON Object.

Implementation and Integration

Iterate through the docs JSON array, for each of the keys (e.g. "name" and brand") in the JSON object, use the panl.fields object as a lookup for the Panl name.

Image: Referencing the Panl name lookup for display of fields.

IMPORTANT: The JSON Response object is different for Solr version 8.*.* and below, see the section on Solr Version 8 & 7 Integration Notes for more information.

"panl.search" Keyword Search Integration

The keyword search parameters are the only URL parameters that the Panl server will recognise, this is configured in the <panl_collection_url>.panl.properties file with the panl.form.query.respondto=search property.

This property value MUST match the HTML form field name as shown below:

<label>

</label>

<button id="searchbutton" type="submit">Search</button>

</form>

Upon form submission, this will generate a URL of the form:

http://localhost:8181/mechanical-pencils/default/?search=search_term

The Panl Results Viewer ALWAYS performs a keyword search INCLUDING the currently selected facets.

Should you wish to search without any of the results, you may just submit the form to the base URL you are using for your implementation.

IMPORTANT: Whenever there is a panl.form.query.respondto URL parameter, the page number is __ALWAYS__ reset to 1.

Note the following URL:

http://localhost:8181/panl-results-viewer/mechanical-pencils-or/brandandname/Yellow/page-3/1-per-page/Koh-i-Noor/Wpnq/?search=Alvin

In the above URL, there is a LPSE code for q with the value of Koh-i-Noor AND there is a query parameter of search passed through with the value of Alvin. In this instance, the Koh-i-Noor Solr query (with the LPSE code of q) is overridden by the search URL parameter of Alvin and only results with the keyword search of Alvin are returned (in this instance, only one result)

Additionally, the page number LPSE code of p with the value of page-3 has been reset to page one. You can see this in the canonical URL that is generated:

http://localhost:8181/panl-results-viewer/mechanical-pencils-or/brandandname/Yellow/page-1/1-per-page/Alvin/Wpnq/

Example Rendering

Image: The Search Query with pre-populated form field value

Example JSON

"panl": {

"search": {

"query_respond_to": "search",

"keyword": "Alvin"

}

Implementation and Integration

To generate the name of the form field, use the panl.search.query_respond_to JSON key.

The JSON key panl.search.keyword can be used to retrieve the keyword that the user entered for the search. For the removal of this filter see the panl.active.query JSON key.

Action	JSON Key		Example
Generate the form field name	"query_respond_to": "search"		<label><input id="searchfield" type="text" name="search"></label>

"panl.search" Specific Solr Search Field Integration

In the Bookstore example, three Solr fields have been set up for specific field searches, the title, the author^[35], and the description. The user may select one or more of those fields in any combination, or select none of the fields (which will just perform a keyword search on the default field).

For the Panl server to know about the specific fields to search upon, the URL parameter is configured in the <panl_collection_url>.panl.properties file with the panl.form.query.respondto=search property, with specific fields, this value is appended by .<lpse_code>.

For example in the following HTML:

The name of the keyword search field is search and the value is the keyword Note: this is also passed through in the panl.search.query_respond_to JSON key.
to search in the Title field, a URL parameter of search.T must be passed through (the value of this parameter does not matter).
to search in the Author field, a URL parameter of search.t must be passed through (the value of this parameter does not matter).
to search in the Description field, a URL parameter of search.d must be passed through (the value of this parameter does not matter).

<button id="searchbutton" type="submit">Search</button>

<label for="search.t">Title</label>

<label for="search.T">Author</label>

<label for="search.d">Book Description</label>

</form>

Passing through any (or all) of these checkbox values will perform the search on the specific fields that are selected.

For example:

http://localhost:8181/panl-results-viewer/book-store/default/?search=mary&search.t=-&search.T=-&search.d=-

Will perform a keyword search of 'Mary' on the Title (search.t=-), Author - the analysed text field (search.T=-), and Description (search.d=-) fields and which is equivalent to the LPSE URL of

http://localhost:8181/panl-results-viewer/book-store/default/mary/q(tTd)/

Whilst you may only wish to search on the Author field

http://localhost:8181/panl-results-viewer/book-store/default/?search=mary&search.T=-

Which generates the LPSE URL of

http://localhost:8181/panl-results-viewer/book-store/default/mary/q(T)/

Example Rendering

Image: The Search Query with pre-populated form field value and the 'Search in Author' checkbox is selected

Example JSON

"panl": {

"search": {

"query_respond_to": "search",

"fields": [

{

"panl_code": "t",

"active": false,

"value": "Title"

{

"panl_code": "T",

"active": false,

"value": "Author"

{

"panl_code": "d",

"active": false,

"value": "Description"

}

"keyword": "mary"

}

Implementation and Integration

The JSON key panl.search.keyword can be used to retrieve the keyword that the user entered for the search to pre-populate the HTML form.

For each of the checkboxes, iterate through the panl.search.fields JSON array and if the active key is set to true, then the checkbox should be selected.

For the removal of this filter see the panl.active.query JSON key.

Action	JSON Key	Example
Generate the form field name	"query_respond_to": "search"	<label><input id="searchfield" type="text" name="search"></label>
Generate the checkbox name	"query_respond_to": "search" "value": "Author" "panl_code": "t"	<input type="checkbox" id="search.t" name="search.t" value="-">
Determine whether the checkbox is 'checked'	"active": true	<input type="checkbox" id="search.t" name="search.t" checked="" value="-">

"panl.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.

Notes: The keys contained within the JSON object will only appear if the related query, facet, or parameter has been applied to the query.

{

"facet": [ ... ],

"numrows": { ... },

"page": { ... },

"query_operand": { ... },

"query": { ... },

"sort": [ ... ],

"sort_fields": { ... }

}

Line 2:

The JSON array of active facets - REGULAR, BOOLEAN, 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 object

Line 7:

The array of 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.

Notes:

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

As a general rule, each of the active objects will contain at least the following keys and will not be explained for the other JSON object explanations:

{

...

"panl_code": "m",

"value": "Clutch",

"encoded": "Clutch",

"remove_uri": ↩

"/weighing%20from%2014%20grams%20to%2046%20grams/page-2/5-per-page/w-sb+pno+/"

...

}

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%20by%20OHTO%20Company

Line 6:

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

Integration and Implementation

At a base level, implementation is straightforward with any of the active facets. You may choose whether to render the active filters to the page. In the Panl Results Viewer, the only active facets that are rendered for removal are:

Any query phrase,
Any active facets, and
Any sort ordering

The following filters are not rendered to the page within the Active Filters section as these have other links on the UI to change these values:

Query operand,
Page number, and
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>
	remove_uri JSON key		URL decoded encoded JSON key

Notes: To render the text of the anchor tag, the encoded value will need to be URL decoded. In the panl-viewer.js file, additional processing is done thusly:

return(decodeURL(text)

.replaceAll("+", " ")

.replaceAll("%2B", "+")

.replaceAll("%3A", ":")

.replaceAll("%2F", "/"));

The above line will replace the + character with spaces (which is not done with the javascript function decodeURL()) then any encoded + characters (i.e. %2B) are replaced with the + character, along with colons and forward slashes.

"panl.active.facet" REGULAR facet object

The URL for this example shows mechanical pencils that 'have a cylindrical grip'.

http://localhost:8181/panl-results-viewer/mechanical-pencils/brandandname/Cylindrical%20Grip/G/

Example Rendering

Image: The In-Build Panl Results Viewer web app showing the REGULAR facet remove link.

Example JSON

{

"facet_name": "grip_shape",

"name": "Grip Shape",

"encoded": "Cylindrical%20Grip"

"panl_code": "G",

"value": "Cylindrical",

"remove_uri": "/",

}

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.

Action	href attribute JSON Key	anchor tag text JSON Key	Example
REMOVE	remove_uri	encoded OR value	<a href="/">Cylindrical Grip</a> OR <a href="/">Cylindrical</a>

Action

href attribute JSON Key

anchor tag text JSON Key

Example

REMOVE

remove_uri

encoded

OR

value

<a href="/">Cylindrical Grip</a>

OR

<a href="/">Cylindrical</a>

"panl.active.facet" BOOLEAN facet object

The URL for this example shows mechanical pencils that 'can be disassembled'

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

Example Rendering

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

Example JSON

{

"facet_name": "disassemble",

"is_booean_facet": true,

"inverse_encoded": "cannot%20be%20disassembled",

"inverse_uri": "/cannot%20be%20disassembled/D/",

"name": "Disassemble",

"encoded": "able%20to%20be%20disassembled",

"panl_code": "D",

"remove_uri": "/",

"value": "true"

}

Integration and Implementation

The JSON key is_booean_facet will be true for this facet type.

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/

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.

Action	href attribute JSON Key	anchor tag text JSON Key	Example
REMOVE	remove_uri	encoded	<a href="/">able to be disassembled</a>
INVERT	inverse_uri	inverse_encoded	<a href="/cannot%20be%20disassembled/D/">cannot be disassembled</a>

"panl.active.facet" BOOLEAN Checkbox facet object

The URL for this example shows the Bookstore example that has checkboxes for both 'On Backorder' and 'Speedy Delivery'

http://localhost:8181/panl-results-viewer/book-store/default/In%20Stock/Speedy%20Delivery/OV/

When rendering the BOOLEAN checkbox, information from BOTH the active and available facets is required.

Example Rendering

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

Example JSON - active facets

{

"inverse_uri": "/On%20BackorderSpeedy%20Delivery/OV/",

"remove_uri": "/Speedy%20Delivery/V/",

"inverse_encoded": "On%20Backorder",

"is_boolean_facet": true,

"checkbox_value": false,

"facet_name": "on_backorder",

"name": "On Backorder",

"panl_code": "O",

"value": "false",

"encoded": "In%20Stock"

{

"inverse_uri": "/In%20Stock/Regular%20Delivery/OV/",

"remove_uri": "/In%20Stock/O/",

"inverse_encoded": "Regular%20Delivery",

"is_boolean_facet": true,

"checkbox_value": true,

"facet_name": "speedy_delivery",

"name": "Speedy Delivery",

"panl_code": "V",

"value": "true",

"encoded": "Speedy%20Delivery"

}

Integration and Implementation

The JSON key is_booean_facet will be true for this facet type and there will be a JSON key of checkbox_value with the value either true or false.

The rendering of the checkbox depends on the value of the JSON key checkbox_value. If it is true then you want to emphasise the positive value of this BOOLEAN facet, when it is false, you want to emphasise the negative value of this checkbox.

The above example has both Speedy Delivery (which is a positive value) and On Backorder (which is a negative value) checked (the implementation uses images rather than HTML checkboxes.

The logic used in the Panl Results Viewer web app implementation is as follows:

If the checkbox_value is true, then

The anchor text is set to: Render 'Include' + encoded
If the value JSON key's value is "true"

then mark the checkbox as selected
Href link attribute is remove_uri

Else

Mark the checkbox as unselected
Note that this is rendered by the available.facets JSON key

Else if the checkbox_value is false, then

The anchor text is set to: Render 'Exclude' + encoded
If the value JSON key's value is "false"

then mark the checkbox as selected
Href link attribute is remove_uri

Else

Mark the checkbox as unselected
Note that this is rendered by the available.facets JSON key

Action	href attribute JSON Key	anchor tag text JSON Key	Example
REMOVE	remove_uri	encoded	<a href="/panl-results-viewer/book-store/default/"><img class="add" src="/webapp/static/checked.png" title="Remove facet" />Exclude 'On Backorder'</a>

"panl.active.facet" DATE Range facet object

URL for this example showing a DATE range of 'the next 10 months' of results

http://localhost:8181/panl-results-viewer/simple-date/default/next+10+months/S/

Example Rendering

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

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.

IMPORTANT: This example comes from the simple-date Solr collection and is see the Additional Data section for adding this sample data to Solr.

Example JSON

{

"facet_name": "solr_date",

"is_date_facet": true,

"name": "Solr Date",

"encoded": "next%2010%20months",

"panl_code": "S",

"remove_uri": "/",

"value": "10"

}

Integration and Implementation

Notes: This filter will also ALWAYS be returned in the available filters object, so you may choose not to display this in the active filters and use the available filters. Within the Panl Results Viewer web app, it displays both within the Active Filters and Range Filters.

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 .

Action	href attribute JSON Key	anchor tag text JSON Key	Example
REMOVE	remove_uri	encoded	<a href="/">next 10 months</a>

"panl.active.facet" OR facet object

URL for this example showing an OR facet for 'Pencils manufactured by Alvin'

http://localhost:8181/panl-results-viewer/mechanical-pencils-or/brandandname/Manufactured%20by%20Alvin/b/

Example Rendering

Image: The In-Build Panl Results Viewer web app showing active OR facet.

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.

Example JSON

{

"facet_name": "brand",

"is_or_facet": true,

"name": "Brand",

"encoded": "Manufactured%20by%20Alvin",

"panl_code": "b",

"remove_uri": "/",

"value": "Alvin"

}

Integration and Implementation

Action	href attribute JSON Key	anchor tag text JSON Key	Example
REMOVE	remove_uri	encoded OR value	<a href="/">Manufactured by Alvin</a> <a href="/">Alvin</a>

Action

href attribute JSON Key

anchor tag text JSON Key

Example

REMOVE

remove_uri

encoded

value

<a href="/">Manufactured by Alvin</a>

<a href="/">Alvin</a>

"panl.active.facet" RANGE facet object

URL for this example showing an OR facet for 'Pencils manufactured by Alvin'

http://localhost:8181/panl-results-viewer/mechanical-pencils/brandandname/weighing%20from%2014%20grams%20to%2045%20grams/w-/

Example Rendering

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

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.

Example JSON

{

"facet_name": "weight",

"has_infix": true,

"is_range_facet": true,

"name": "Weight",

"value_to": "45",

"encoded": "weighing%20from%2014%20grams%20to%2045%20grams",

"panl_code": "w",

"remove_uri": "/",

"value": "14"

}

Integration and Implementation

Action	href attribute JSON Key	anchor tag text JSON Key	Example
REMOVE	remove_uri	encoded	<a href="/">weighing from 14 grams to 45 grams</a>

Action

href attribute JSON Key

anchor tag text JSON Key

Example

REMOVE

remove_uri

encoded

<a href="/">weighing from 14 grams to 45 grams</a>

"panl.active.numrows"

The following URL:

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

Example Rendering

Image: The In-Build Panl Results Viewer web app showing the number of results per page 'Showing 5 results per page'

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]

Example JSON

{

"remove_uri": "/Clutch/m/",

"panl_code": "n",

"value": "5",

"encoded": "5-per-page"

}

Integration and Implementation

Note: In the in-built Panl Results Viewer web app, this is not shown within the active filter section, instead displaying it above the results in the pagination section.

Action	href attribute JSON Key	anchor tag text JSON Key	Example
REMOVE	remove_uri	encoded OR value	<a href="/Clutch/m/">5-per-page</a> OR <a href="/Clutch/m/">5</a>

Action

href attribute JSON Key

anchor tag text JSON Key

Example

REMOVE

remove_uri

encoded

value

"panl.active.page"

The following URL:

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

Example Rendering

Image: The In-Build Panl Results Viewer web app showing the page number 'Page 2 of 6'

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

Example JSON

{

"remove_uri": "/Clutch/5-per-page/mn/",

"panl_code": "p",

"value": "2",

"encoded": "page-2"

}

Integration and Implementation

Note: In the in-built Panl Results Viewer web app, this is not shown within the active filter section, instead displaying it above the results in the pagination section.

Action	href attribute JSON Key	anchor tag text JSON Key	Example
REMOVE	remove_uri	encoded OR value	<a href="/Clutch/5-per-page/mn/">page-2</a> OR <a href="/Clutch/5-per-page/mn/">2</a>

Action

href attribute JSON Key

anchor tag text JSON Key

Example

REMOVE

remove_uri

encoded

value

"panl.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

Example Rendering

Image: The Panl in-built Simple Results Viewer web app showing the keyword pre-populated in the Search Query form field and the active facet.

Example JSON

{

"remove_uri": "/o+/",

"panl_code": "q",

"value": "hexagonal",

"encoded": "hexagonal"

}

Integration and Implementation

Action	href attribute JSON Key	anchor tag text JSON Key	Example
REMOVE	remove_uri	encoded OR value	<a href="/o+/">hexagonal</a> OR <a href="/o+/">hexagonal</a>

Action

href attribute JSON Key

anchor tag text JSON Key

Example

REMOVE

remove_uri

encoded

value

<a href="/o+/">hexagonal</a>

"panl.active.query_operand" 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]

Example Rendering

Image: The Panl header for the Query Operand in the in-built Simple Results Viewer web app.

Example JSON

{

"remove_uri": "/hexagonal/q/",

"panl_code": "o",

"value": "+",

"encoded": "%2B"

}

Integration and Implementation

Note: In the in-built Panl Results Viewer web app, this is not shown within the active filter section, instead it is displayed above the returned results in the header section. You will also need to do a conversion between the + and AND, and - and OR.

Action

href attribute JSON Key

anchor tag text JSON Key

Example

REMOVE

remove_uri

encoded

value

"panl.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-sN-q/

Has the following active filters set:

Query (q) : hexagonal
Sorting (s):

Sorting by brand descending [ This is the active filter to remove / invert ]
Sorting by name descending

Example Rendering

Image: The active sorting methods which are editable from two places.

Example JSON

"sort": [

{

"inverse_uri": "/hexagonal/sb+sN-q/",

"remove_uri": "/hexagonal/sN-q/",

"is_descending": true,

"facet_name": "brand",

"name": "Brand",

"panl_code": "s",

"encoded": "Brand"

{

"inverse_uri": "/hexagonal/sb-sN+q/",

"remove_uri": "/hexagonal/sb-q/",

"is_descending": true,

"facet_name": "name",

"name": "Pencil Model",

"panl_code": "s",

"encoded": "Pencil%20Model"

}

]

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.

Action	href attribute JSON Key	anchor tag text JSON Key	Example
REMOVE	remove_uri	encoded OR name	<a href="/hexagonal/sN-q/">Pencil%20Model</a> OR <a href="/hexagonal/sN-q/">Pencil Model</a>
INVERT	inverse_uri	encoded OR name	<a href="/hexagonal/sb+sN-q/">Pencil%20Model</a> OR <a href="/hexagonal/sb+sN-q/">Pencil Model</a>
Note: For the anchor link text, you may also use a switch statement on the is_descending JSON key to output whether it is descending or descending.

Notes: The clear all sorting link above is generated from the panl.sorting.remove_uri JSON object path.

"panl.available" JSON Object

This JSON object contains three 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):

Example JSON

{

"date_range_facets": [ ... ],

"facets": [ ... ],

"range_facets": [ ... ]

}

Notes: The date_range_facets and range_facets key are __ALWAYS__ available, irrespective of any other facets that have been chosen.

Additionally, any LPSE code that is defined as a RANGE facet will also be included in the facets array as a REGULAR facet, if those facets are available.

"panl.available.date_range_facets" JSON Array

Example Rendering

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

Example JSON

{

"next": "next%20",

"uris": {

"before": "/",

"after": "/S/"

"designators": {

"hours": "%20hours",

"months": "%20months",

"days": "%20days",

"years": "%20years"

"previous": "previous%20",

"facet_name": "solr_date",

"name": "Solr Date",

"panl_code": "S"

}

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.

However the URL is generated,

To generate the URL,

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

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

Note: There can only ever be one DATE Range for the specified facet, and will __ALWAYS__ appear in the available.date_range_facets array. The URL will always be a replacement URL not an additive URL - i.e. if you already have a DATE Range facet selected, the generated URL will replace the current one.

"panl.available.facets" JSON Array

For each of the facet JSON objects in the available.facets JSON array adding a value to the LPSE URL is relatively straightforward. The 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.

Example JSON - OR Separator

From the URL:

http://localhost:8181/panl-results-viewer/mechanical-pencils-or-separator/brandandname/

{

"facet_name": "brand",

"facet_limit": 100,

"is_or_facet": true,

"name": "Brand",

"panl_code": "b",

"uris": {

"before": "/Manufactured%20by%20",

"after": "%20Co./b/"

"value_separator": ", or "

"values": [

{

"count": 11,

"encoded_multi": "Koh-i-Noor",

"value": "Koh-i-Noor",

"encoded": "Manufactured%20by%20Koh-i-Noor%20Co."

...

]

}

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.

From Panl version Panl 2.0.0, there is a new feature which allows an OR separator to be used, rather than prefixing and suffixing every value. The JSON key of or_separator should be tested, and if this key exists then the OR separator logic should be used.

OR Separator Logic

Start with the uris.before value (Line 11)
Append the values[i].encoded_or value (Line 19)
Append the uris.after value (Line 12)

Normal OR Facet Logic

Start with the uris.before value (Line 11)
Append the values[i].encoded value (Line 18)
Append the uris.after value (Line 12)

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

From version 2.0.0 there is an additional JSON key named facet_limit which is the maximum number of facet values that will be returned with the request. This value is set in the <panl_collection_url>.panl.properties file with the key solr.facet.limit.

If the size of the values array is greater than this number, then you may need to request additional facet values from the query by requesting more facets from the URL /panl-more-facets/<lpse_code>/<amount>

Where <lpse_code> is the Panl LPSE code for the facet you are requesting and <amount> is the new facet limit to request.

When more facets are requested the key facet_request will be populated with the number of facets that were requested.

If, at any time the facet_limit is greater than the number of values then there is no need to request more facets.

If the facet_request is -1 then all facets have been returned.

Note: The facet_limit key is only available on REGULAR and OR facets.

"panl.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.

{

"uris": {

"before": "/weighing%20from%20",

"before_min_value": "/from%20light",

"has_infix": true,

"after_max_value": "heavy%20pencils/w-/",

"during": "%20to%20",

"after": "%20grams/w-/"

"dynamic_max": 43,

"dynamic_min": 4

"min": "10",

"max": "50",

"prefix": "",

"range_min_value": "from%20light",

"facet_name": "weight",

"name": "Weight",

"panl_code": "w",

"suffix": "%20grams",

"range_max_value": "heavy%20pencils"

}

Integration and Implementation

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.

IMPORTANT: Range facets will __ALWAYS__ be returned in the JSON response object.

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

Use the hard-coded minimum and maximum values that are configured in the <panl_collection_url>.panl.properties file, or
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 (unless of course either, or both of the dynamic values match the minimum and maximum).

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: the actual minimum value is 4 (as shown by the dynamic minimum), however this value would be included 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: there are only values between 17 and 32 in the range, however the UI reflects the values that were selected by the user.

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+/
/10 grams~50 grams/w+/
/weight 10~weight 50/w+/
/weight 10 grams~weight 50 grams/w+/
/from light~heavy pencils/w+/
/from light~50/w+/
/from light~50 grams/w+/
/from light~weight 50 grams/w+/
/from light~weight 50/w+/
/10~heavy pencils/w+/
/10 grams~heavy pencils/w+/
/weight 10 grams~heavy pencils/w+/
/weight 10~heavy pencils/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-/
/weight 10 to weight 50/w-/
/weight 10 grams to weight 50 grams/w-/
/10 grams to 50 grams/w-/
/from light to 50/w-/
/from light to weight 50/w-/
/from light to weight 50 grams/w-/
/from light to 50 grams/w-/
/from light to heavy pencils/w-/
/10 to heavy pencils/w-/
/weight 10 to heavy pencils/w-/
/weight 10 grams to heavy pencils/w-/
/10 grams to heavy pencils/w-/
/weighing from 10 to 50 in grams/w-/
/weighing from 10 to 50/w-/
/weighing from 10 to weight 50/w-/
/weighing from 10 to weight 50 grams/w-/
/weighing from 10 to 50 grams/w-/
/10 to 50 in grams/w-/
/weight 10 to 50 in grams/w-/
/weight 10 grams to 50 in grams/w-/
/10 grams to 50 in grams/w-/
/10 to 50 in grams/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

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

"panl.pagination" JSON Object

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

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

The default query above returns all results (55 of them) with 5 results per page and is on page number 2:

Example JSON

{

"num_pages": 11,

"num_results_exact": true,

"page_uris": {

"next": "/page-3/5-per-page/pn/",

"previous": "/page-1/5-per-page/pn/",

"before": "/page-",

"after": "/5-per-page/pn/"

"page_num": 2,

"num_results": 55,

"num_per_page": 5,

"num_per_page_uris": {

"before": "/",

"after": "-per-page/n/"

}

Integration and Implementation

Unlike other returned JSON objects, the pagination object does not contain the uris key, instead it contains two new keys:

page_uris - used to generate the pagination
num_per_page_uris - used to generate the number of results to be shown per page

The 'page_uris' JSON Object

For convenience the page_uris JSON Object contains ready made links for the next and previous page. If this is the last page of the results, the next key will not be present, if this is the first page of the results, the previous key will not be present.

To render the full suite of pagination links to the pages of results, iterate from 1 to num_pages (inclusive) and

Start with the page_uris.before value (Line 7)
Append the integer page number value
Append the page_uris.after value (Line 8)

The 'num_per_page_uris' JSON Object

The num_per_page_uris will ALWAYS reset the page number back to the first page. The render the number per page link, use any positive integer value and

Start with the num_per_page_uris.before value (Line 7)
Append the integer page number value
Append the num_per_page_uris.after value (Line 8)

"panl.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

Example JSON

{

"remove_uri": "/11%20grams/hexagonal/wq/",

"fields": [

{

"name": "Brand",

"facet_name": "brand",

"set_uri_asc": "/11%20grams/hexagonal/wsb+q/",

"set_uri_desc": "/11%20grams/hexagonal/wsb-q/",

"add_uri_asc": "/11%20grams/hexagonal/wsN+sb+q/"

"add_uri_desc": "/11%20grams/hexagonal/wsN+sb-q/",

{

"name": "Name",

"facet_name": "name",

"set_uri_desc": "/11%20grams/hexagonal/wsN-q/",

"set_uri_asc": "/11%20grams/hexagonal/wsN+q/"

}

]

}

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)

Integration and Implementation

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

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

Note: The order of the initial sorting options will match the order that is defined by the panl.sort.fields property

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

Note: The additional sorting options will only be rendered in the Panl Results Viewer web app if an initial sort option has been selected.

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

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

Rendering the Initial Sorting Options

Iterate through the available.sorting.fields JSON array
Render the value keyed on name ⇒ output Name
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/

Note: To determine whether the link is currently active, the active.sort array will need to be interrogated where facet_name=<this_facet_name> and then conditionally display the URL path dependent on the value of the is_descending key.

Rendering the Additional Sorting Options

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

Render the value keyed on name ⇒ output Name
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

Notes: For this example, an additional Panl sort field was added, i.e. the property is now panl.sort.fields=brand,name,weight

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

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

No active filters rendered

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

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

Weight descending

Active filters show clear sorting order link

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

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

Weight descending, then
Brand ascending

Active filters show clear sorting order link

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

No additional sorting objects are available
Active filters show sorting by

Weight descending, then
Brand ascending, then
Name descending

Active filters show clear sorting order link

"response.highlighting"

~ ~ ~ * ~ ~ ~

Synapticloop :: Panl

Welcome to the Panl Book

A Note On Page Generation

Search Integration And The Panl Response Object

- Example JSON

- URL Bindings

- Error Responses

- Success Responses

- Generating the HTML

- Generating The href Attribute

- Generating The Anchor Text

- Example docs JSON Response

- Example panl.fields JSON Response

- Example Rendering

- Implementation and Integration

- Example Rendering

- Example JSON

- Implementation and Integration

- Example Rendering

- Example JSON

- Implementation and Integration

- Integration and Implementation

- Example Rendering

- Example JSON

- Integration and Implementation

- Example Rendering

- Example JSON

- Integration and Implementation

- Example Rendering

- Example JSON - active facets

- Integration and Implementation

- Example Rendering

- Example JSON

- Integration and Implementation

- Example Rendering

- Example JSON

- Integration and Implementation

- Example Rendering

- Example JSON

- Integration and Implementation

- Example Rendering

- Example JSON

- Integration and Implementation

- Example Rendering

- Example JSON

- Integration and Implementation

- Example Rendering

- Example JSON

- Integration and Implementation

- Example Rendering

- Example JSON

- Integration and Implementation

- Example Rendering

- Example JSON

- Integration and Implementation

- Example JSON

- Example Rendering

- Example JSON

- Integration and Implementation

- Example JSON - OR Separator

- Integration and Implementation

- Integration and Implementation

- Example JSON

- Integration and Implementation

- Example JSON

- Integration and Implementation

View this project on github

Search Integration And The Panl Response Object

Example JSON

URL Bindings

Error Responses

Success Responses

Generating Panl Links

Generating the HTML

Generating The href Attribute

Generating The Anchor Text

"response.docs" JSON Object Results Integration

Example docs JSON Response

Example panl.fields JSON Response

Example Rendering