Help Center

Menu

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

An option is also provided which updates the displayUrl data model element in addition to the liveUrl.

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.
Version 2.0.0 of the Modify the search result URL plugin is NOT backwards compatible with previous versions due to a configuration key format change. Please refer to the upgrade notes for the upgrade instructions.

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. 'Parameter 1' is a unique identifier used to enable multiple URL match pattern to be defined.

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. 'Parameter 1' is a unique identifier which needs to match the corresponding URL match pattern option

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

Update display URL

Configuration key

plugin.alter-live-url.config.*.update-display-url

Data type

boolean

Default value

false

Required

This setting is optional

Should the display URL also be updated? 'Parameter 1' is a unique identifier which needs to match the corresponding URL match pattern option

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

Upgrade notes

Upgrading from version [1.x.x] to version [2.x.x]

Version 2.0.0 of the Modify the search result URL plugin is NOT backwards compatible with version 1.x.

Please follow the instructions below to upgrade from 1.x.x to version 2.x.x

Step 1: edit your results page configuration and unpublish the old plugin configuration keys:

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

  • plugin.alter-live-url.config.reformat-ftl, and

  • plugin.alter-live-url.config.update-display-url

Step 2: Open the raw configuration key editor by selecting Tools  Edit raw data.

Edit the configuration keys to add an additional parameter 1 identifier into all the keys that you just unpublished. This updates the key format from plugin.alter-live-url.config.<config item> to plugin.alter-live-url.config.*.<config item>. Replace the * with an identifier.

For example, from

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

  • plugin.alter-live-url.config.reformat-ftl, and

  • plugin.alter-live-url.config.update-display-url

to

  • plugin.alter-live-url.config.1.regex-trigger,

  • plugin.alter-live-url.config.1.reformat-ftl, and

  • plugin.alter-live-url.config.1.update-display-url.

Step 3: Update the plugin version to the current plugin version number.

e.g. update

  • plugin.alter-live-url.version=1.2.0

to

  • plugin.alter-live-url.version=2.0.0

Step 4: Press the save button, then publish the updated key values.

Examples

Update all http URLs to https

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

Configuration key name

Parameter 1

Value

Description

URL match pattern

http

http://.*

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

URL reformatting template

http

${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

Parameter 1

Value

Description

URL match pattern

all

.*

Apply this to all URLs

URL reformatting template

all

${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

[2.1.0]

Fixed

  • Fixed a bug where the plugin fails to process URLs containing special characters such as "|".

[2.0.0]

Added

  • Multiple URL match patterns and reformatting templates can now be defined. This allows for more complex URL transformations to be defined.

Changed

[1.2.0]

Added

  • Added an option to also apply the updated URL to the displayUrl data model field. The default behavior does not update this field so upgrading to this version will not change existing behavior.

[1.1.0]

Changed

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

See also