Plugin: Faceted navigation - legacy query parameters
| Other versions of this plugin may exist. Please ensure you are viewing the documentation for the version that you are currently using. If you are not running the latest version of your plugin we recommend upgrading. See: list of all available versions of this plugin. |
Purpose
| This plugin should only be used when upgrading a search with existing integrations where the integration cannot be updated to use the current facet parameters. |
This plugin restores some deprecated faceted navigation data model parameters that were removed in Funnelback 16.
Integrations that rely on the deprecated queryStringParam* fields should be updated to use the toggleUrl field where possible. If you have an integration that cannot be updated, then this plugin provides a multi-step process for restoring that functionality from within Funnelback.
This plugin iterates through the search output when processing a query and appends the following values from the legacy data model to the response.customData element:
-
queryStringParamName -
queryStringParamValue -
queryStringParam
To restore it to the original location, you may need to further copy these values into a custom JSON template output.
| This plugin requires additional processing during query time which may impact the performance of your search. |
Usage
Enabling the plugin
Enable the restore-legacy-facet-queryparameters plugin on your results page from the Extensions screen in the administration dashboard or add the following results page configuration to enable the plugin.
plugin.restore-legacy-facet-queryparameters.enabled=true
plugin.restore-legacy-facet-queryparameters.version=1.0.0| The plugin will take effect as soon as it is enabled. |
Example
By default, the data model of the response object for the Funnelback search is similar to:
"response": {
// ...
"facets": [{
"name": "Example",
"customData": {},
"allValues": [{
"data": "squiz",
"label": "squiz",
"count": 394,
"selected": false,
"toggleUrl": "?log=false&profile=search&query=%21asdasd&collection=default%7Esp-squiz&f.Example%7Ct=squiz"
},
{
"data": "customer stories",
"label": "customer stories",
"count": 36,
"selected": false,
"toggleUrl": "?log=false&profile=search&query=%21asdasd&collection=default%7Esp-squiz&f.Example%7Ct=customer+stories"
}]
// ...
}]
}After enabling the plugin, the response.customData data model element will include the additional fields:
"customData": {
"legacyFacetQueryParameters": {
"squiz": {
"queryStringParam": "f.Example%7Ct=squiz",
"queryStringParamName": "f.Example|t",
"queryStringParamValue": "squiz"
},
"customer stories": {
"queryStringParam": "f.Example%7Ct=customer+stories",
"queryStringParamName": "f.Example|t",
"queryStringParamValue": "customer stories"
}
}
}
All values will be appended to response.customData.legacyFacetQueryParameters.<data> where <data> matches the data field of the json object under allValues.
|
Fully restoring the data model to look like a version older than v16.
The plugin above exposes the information that was removed, but not in the same location as it originally was. In versions before v16, the data model previously looked liked the following:
"response": {
// ...
"facets": [{
"name": "Example",
"customData": {},
"allValues": [{
"data": "squiz",
"label": "squiz",
"count": 394,
"selected": false,
"queryStringParam": "f.Example%7Ct=squiz",
"queryStringParamName": "f.Example|t",
"queryStringParamValue": "squiz",
"toggleUrl": "?log=false&profile=search&query=%21asdasd&collection=default%7Esp-squiz&f.Example%7Ct=squiz"
},
{
"data": "customer stories",
"label": "customer stories",
"count": 36,
"selected": false,
"queryStringParam": "f.Example%7Ct=customer+stories",
"queryStringParamName": "f.Example|t",
"queryStringParamValue": "customer stories",
"toggleUrl": "?log=false&profile=search&query=%21asdasd&collection=default%7Esp-squiz&f.Example%7Ct=customer+stories"
}]
// ...
}]
}In order to fully restore the values to their original location, this plugin must be paired with a custom JSON template that replicates the search.json format. An incomplete example of the facet section is shown below which may be used:
<#ftl encoding="utf-8" />
<#import "/web/templates/modernui/funnelback_classic.ftl" as s/>
<#import "/web/templates/modernui/funnelback.ftl" as fb/>
<#-- null event where no search query provided -->
<#escape x as x?json_string>
<#if !response.resultPacket??>null</#if>
<#-- Wrap entire JSON node in JSONP if JSONP callback is defined -->
<#-- <@JsonpWrapper> -->
<@s.AfterSearchOnly>
{
"response" : {
<#-- Facet Node *Uses extra search for tab functionality*-->
"facets" :
[
<#if response.facets?? && response.facets?size gt 0>
<#list response.facets as facet>
{
"name" : "${facet.name!?json_string}",
"unselectAllUrl" : "${facet.unselectAllUrl!?json_string}",
"customData" : { },
"allValues" :
[
<#list facet.allValues as facetValue>
{
"data" : <#if facetValue.data??>"${facetValue.data!?json_string}"<#else>null</#if>,
"label" : <#if facetValue.label??>"${facetValue.label!?json_string}"<#else>null</#if>,
"count" : <#if facetValue.count??>${facetValue.count!?c}<#else>null</#if>,
"selected" : <#if facetValue.selected??>${facetValue.selected!?c}<#else>false</#if>,
"queryStringParamValue" : <#if facetValue.data?? && ((facet.customData["legacyFacetQueryParameters"]!{})[facetValue.data]!{})["queryStringParamValue"]??>"${facet.customData["legacyFacetQueryParameters"][facetValue.data]["queryStringParamValue"]!?json_string}"<#else>null</#if>,
"queryStringParamName" : <#if facetValue.data?? && ((facet.customData["legacyFacetQueryParameters"]!{})[facetValue.data]!{})["queryStringParamName"]??>"${facet.customData["legacyFacetQueryParameters"][facetValue.data]["queryStringParamName"]!?json_string}"<#else>null</#if>,
"queryStringParam" : <#if facetValue.data?? && ((facet.customData["legacyFacetQueryParameters"]!{})[facetValue.data]!{})["queryStringParam"]??>"${facet.customData["legacyFacetQueryParameters"][facetValue.data]["queryStringParam"]!?json_string}"<#else>null</#if>,
"toggleUrl" : <#if facetValue.toggleUrl??>"${facetValue.toggleUrl!?json_string}"<#else>null</#if>
}
<#if facetValue_has_next>, </#if>
</#list>
]
}
<#if facet_has_next>, </#if>
</#list>
</#if>
],
}
}
</@s.AfterSearchOnly>
<#-- </@JsonpWrapper> -->
</#escape>