Plugin: Modify the search result URL

Purpose

Use this plugin if you need to update the URL that is associated with a search result.

This plugin alters ths URL at the time the search results are returned. The URL is updated within the JSON response, ensuring that the change will work with both Freemarker templates and also any integrations with the JSON response.

The updated URL also works with click tracking (so clicks against the updated URL are correctly tracked against the indexed document).

Changing the URL at the time the search results are returned does have some limitations. Any functionality that operates on the search index must continue to use the indexed URL. This includes things like sorting by URL and result-time scoping, which are based on the indexed URL when the lookup occurs; and tuning and gscopes which apply changes to the search index based on the URL.

Usage

Enable the plugin

  1. Select Plugins from the side navigation pane and click on the Modify the search result URL tile.

  2. From the Location section, select the results page to which you would like to enable this plugin from the Select a results page select list.

The plugin will take effect as soon as you finish running through the plugin setup steps.

Configuration settings

The configuration settings section is where you do most of the configuration for your plugin. The settings enable you to control how the plugin behaves.

The configuration key names below are only used if you are configuring this plugin manually. The configuration keys are set in the results page configuration to configure the plugin. When setting the keys manually you need to type in (or copy and paste) the key name and value.

URL match pattern

Configuration key

plugin.alter-live-url.config.regex-trigger

Data type

string

Required

This setting is optional

Regular expression used to match against the original live URL, to which the reformat will be applied.

If the original URL matches the Java regular expression then the URL will be replaced based on the Freemarker template defined in the URL reformatting template option.

URLs will not be modified by default.

URL reformatting template

Configuration key

plugin.alter-live-url.config.reformat-ftl

Data type

string

Required

This setting is optional

Freemarker template fragment that defines the new, modified live URL.

The live URL will be replaced with the generated output of this Freemarker template.

Defining the Freemarker template

The URL reformatting template option uses a small Freemarker template fragment to define the transformed live URL. The following parameters can be used within the template:

  • liveUrlParts.fragment: The fragment of the live URL e.g. #foo.

  • liveUrlParts.path: The path of the live URL e.g. /path.

  • liveUrlParts.path_ends_with_slash: The path of the live URL ending in a slash e.g. /path/, /.

  • liveUrlParts.query: The URL query parameters of the live URL e.g. ?f=1.

  • liveUrlParts.query_ends_with_query_separator: The URL query parameters ending with a query separator so that you can append easily add parameters e.g. ?f=1&, ?.

  • liveUrlParts.scheme_host_port: The schema, host and port of the live URL e.g. +https://example.com+ , https://example.com:8443.

  • liveUrlParts.scheme_host_port_path_query_ends_with_query_separator: The schema, host, port, path and URL query parameters ending with a query separator so that you can append easily add parameters e.g. https://example.com/p?f=1&

  • question: The SearchQuestion from the SearchTransaction. You can target sub-elements directly. e.g. question.query

  • response: The SearchResponse from the SearchTransaction. You can target sub-elements directly. e.g. response.resultPacket.resultsSummary.fullyMatching

  • result: The current result the template is being called on. You can target sub-elements directly. e.g. result.title

Examples

Update all http URLs to https

This example updates all http URLs to be accessed via https.

Configuration key name

Value

Description

URL match pattern

http://.*

Apply this to all URLs that contain http:// followed by other characters.

URL reformatting template

${result.getLiveUrl()!?replace("http://(.*)", "https://$1", "r")}

Updates the URL protocol to https.

The URL match pattern matches on any http schema URLs (.* will match anything that follows the http://).

Breaking down the URL reformatting template:

  • result.getLiveUrl(): Gets the live URL of the current result.

  • !: Prevents errors when getLiveUrl() returns null.

  • ?replace(: Calls the freemarker replace method.

  • http://(.*): Defines a regular expression which is matched against the document’s live URL. This example extracts everything after http:// as the first capture group.

    This regular expression doesn’t have to be the same as the one you defined for your URL match pattern. The URL match pattern determines if the transformation will run, the Freemarker regular expression extracts things from the live URL to build the transformed URL. https://$1: Defines the URL to generate - in this case, https:// followed by the first capture group ($1). "r": Tells Freemarker to use a regular expression when applying the Freemarker replacement. You can use the simpler replacement options within Freemarker when defining the template, if these serve your replacement needs.

Append a URL parameter from result metadata

This example appends the id parameter to the live URL with the value sourced from the fid metadata class of the result.

Configuration key name

Value

Description

URL match pattern

.*

Apply this to all URLs

URL reformatting template

${liveUrlParts.scheme_host_port_path_query_ends_with_query_separator}fid=${result.getListMetadata().get("id")[0]!?url}${liveUrlParts.fragment}

Add the fid metadata to the id URL parameter.

The regex-trigger matches on any http schema URLs.

Breaking down the reformat-ftl:

  • ${liveUrlParts.scheme_host_port_path_query_ends_with_query_separator}: Most of the URL ending with a query separator e.g. https://example.com/?a=b&

  • id=: adds an id parameter to the generated URL.

  • ${result.getListMetadata().get("fid")[0]: Inserts the first value of fid metadata from the result.listMetadata["fid"] element of the data model.

  • !: Prevents errors if getListMetadata() returns a null value.

  • ?url: Applies URL encoding to any special characters within the metadata field to ensure a valid URL is generated.

  • ${liveUrlParts.fragment}: Appends the url fragment, if there is one.

Change log

[1.1.0]

Changed

  • Updated to the latest version plugin framework (Funnelback shared v16.20) to enable integration with the new plugin management dashboard.