Plugin: alter-live-url

Purpose

This plugin can be used to alter the live URL of search results.

The live URL of a search result is the one a user will go to when a result is clicked. This plugin allows editing that URL at search time. The plugin allows, for example, editing the live URL with regex, appending URL query parameters, setting the live URL to something else from the search transaction and more. This plugin updates the live URL within the data model, thus it applies to all search end points including search.json and also ensures that other elements based on the live URL (such as the click tracking URL) are correct.

Usage

Enabling the plugin

Enable the alter-live-url 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.alter-live-url.enabled=true
plugin.alter-live-url.version=1.0.0
The plugin will take effect as soon as it is enabled.

Plugin configuration options

The following options can be set in the results page configuration to configure the plugin:

  • plugin.alter-live-url.config.regex-trigger: Defines the regex pattern used to match with the result’s live URL to which the reformat will be applied. By default nothing is matched so the plugin doesn’t run.

  • plugin.alter-live-url.config.reformat-ftl: Defines a Freemarker template which transforms the live URL. By default this is not defined and no transformation will be applied to the liveURL.

Defining the Freemarker template

The reformat-ftl uses a small Freemarker template 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://eg.com , https://eg.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://eg.com/p?f=1&

  • question: The SearchQuestion from the SearchTransaction.

  • response: The SearchResponse from the SearchTransaction.

  • result: The current result the template is being called on.

Examples

Replace http:// with https:// using regex

# Match http:// URLs
plugin.alter-live-url.config.regex-trigger=http://.*
# Switch to secure URLs
plugin.alter-live-url.config.reformat-ftl=${result.getLiveUrl()!?replace("http://(.*)", "https://$1", "r")}

The regex-trigger matches on any http schema URLs.

Breaking down the reformat-ftl:

${
result.getLiveUrl()  // Gets the live URL from the current result.
!                    // Prevents errors when getLiveUrl() returns null.
?replace(            // Calls the freemarker replace method.
    "http://(.*)", // Specifies our matching regex with a group that is everything after http://
    "https://$1",  // Specifies what to replace with making reference to the group above.
    "r")           // Special character 'r' tells Freemarker to use regex.
}

Append a URL parameter from result metadata

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

# Match all live URLs
plugin.alter-live-url.config.regex-trigger=.*
# Add the fid metadata to the id URL paramater
plugin.alter-live-url.config.reformat-ftl=${liveUrlParts.scheme_host_port_path_query_ends_with_query_separator}fid=${result.getListMetadata().get("id")[0]!?url}${liveUrlParts.fragment}

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://foo.com/?a=b&
id=                                                                   // Our new URL paramater we are adding.
${result.getListMetadata()                                            // Gets the metadata for the current result.
    .get("fid")                                                       // Gets the fid metadata class values.
    [0]                                                               // Gets the first value of fid values
    !                                                                 // Handles the null case, handling the case we have no metadata for fid using instead the empty string.
    ?url}                                                             // URL escapes the value of the fid metadata.
    ${liveUrlParts.fragment}                                          // Appends the url fragment if any.

© 2015- Squiz Pty Ltd