JavaScript URL API (ai.urls)

Enable in conf/config.xml:

<config>
  <js-api>
    <url />
  </js-api>
</config>

URL API:

This API can be used to create URLs on the client via JavaScript. These URLs can be used to create custom links, or be used with the Ajax API or Partial Page Loading.

ai.urls.removeHash

ai.urls.removeHash(url)

Removes the hash from a URL and returns everything before the #.

  • @param {String} url the URL to remove the hash from
  • @return {String} the URL without the hash

ai.urls.getHash

ai.urls.getHash(url)

Get the hash from a URL and returns it including the leading #.

  • @param {String} url the URL to retrieve the hash from
  • @return {String} the hash including the #

ai.urls.currHostAbs

ai.urls.currHostAbs(url)

Makes a URL absolute to the current host if possible.

  • @param {String} url the URL to make absolute
  • @return {String} the absolute version of the URL if possible, otherwise the original URL

Note:

This function is not suitable to construct a URL to work with AI APIs (for example AJAX API or Partial Page Loading). Use the ai.urls.composeUrl function instead.

ai.urls.composeUrl

Creates an AI URL, including URL Marks and protocol.

ai.urls.composeUrl(url, marks, protocol)
  • @param {String} url the URL to use
  • @param {Object[]} marks an array containing the URL Marks to include in the URL (see below for details)
  • @param {String} protocol (optional) the protocol to use for the resulting URL. By default the current protocol is used. Possible values are http and https
  • @return {String} the composed URL

The URL Marks are expected in the following format:

  • An Array consisting of
    • Objects, with properties
      • name
        • String, name of the URL Mark
      • value
        • String, value of the URL Mark

The given url can be

Note:

This function does not use the URL map to create URLs. The composed URLs may look different than those created on the server, but they work the same.

Note:

Calling ai.urls.composeUrl() with a URL created by ai.urls.composeUrl() will not combine marks if url-rewriting/trailing-marks is activated in config.xml.

Some examples for ai.urls.composeUrl usage:

/* internal URL with two URL Marks added */
ai.urls.composeUrl("res/resource.html", [{name: "foo", value: "bar"}, {name: "fuu", value: "baz"}]);
/* external URL with URL Mark added */
ai.urls.composeUrl("http://example.com/path/file.html", [{name: "foo", value:"bar"}]);
/* external https URL with URL Mark added */
ai.urls.composeUrl("https://example.com/path/file.html", [{name: "bar", value:"foo"}]);
/* internal URL without URL Marks with https protocol */
ai.urls.composeUrl("res/resource.html", [], "https");

ai.urls.addQueryString

Add query parameters to the URL while retaining an already existing query string.

ai.urls.addQueryString(url, args)
  • @param {String} url the URL to add the query parameters to
  • @param {String[]} args an array of query parameters (in the form of key=value)
  • @return {String} the URL containing the new query parameters

ai.urls.replaceQueryString

Replace an existing query string from the URL with new parameters.

ai.urls.replaceQueryString(url, args)
  • @param {String} url the URL in which the query string should be replaced
  • @param {String[]} args an array of query parameters (in the form of key=value)
  • @return {String} the URL with the query string replaced with the new query parameters

ai.urls.isExternal

Determines whether the given URL is external according to the current configuration.

ai.urls.isExternal(url)
  • @param {String} url the URL to check
  • @param {Boolean} true if the URL is external, false otherwise

ai.urls.hasMark

Determines whether the given URL contains a URL Mark with the given name and possibly a given value.

ai.urls.hasMark(url, markName, markValue)
  • @param {String} url the URL to check for the URL Mark
  • @param {String} markName the name of the URL Mark to check for in the URL
  • @param {String} markValue (optional) the value of the URL Mark to check for in the URL
  • @return {Boolean} true if the URL contains a mark with the given name (and the optionally given value)

Image URL API

Enable Image URL generation in conf/config.xml:

<config>
  <js-api>
    <url images="true" />
  </js-api>
</config>

Note:

The image-scaling attribute is deprecated.

Note:

Image URLs can only be enabled via config.xml. They cannot be enabled via the set-config flow action.

If the optional attribute images="true" is set, URLs for images can be created with the same attributes that Image Scaling supports. By default images is set to false. To determine the correct parameters, the Delivery Context API is enabled and the following properties are sent to the client:

  • client/image/gif
  • client/image/gif/gif89a
  • client/image/jpg
  • client/image/png
  • client/image/svg
  • client/image/webp
  • client/image/webp/alpha
  • client/hw/display/width
  • viewport/width-landscape
  • viewport/width-portrait
  • viewport/device-pixel-ratio

ai.urls.composeImageUrl

Create a URL to an image. This compose function uses composeImageScalingUrl if Image Scaling is enabled in the config or composeImageCompressionUrl if Image Compression is enabled.

ai.urls.composeImageUrl(url, options)
  • @param {String} url the Url to the image
  • @param {Object} options (optional, only used if Image Scaling is used) scaling options for the image (see ai.urls.composeImageScalingUrl for details.
  • @return {String} the composed image URL

ai.urls.composeImageScalingUrl

Create a URL to an image using a Image Scaling URL.

ai.urls.composeImageScalingUrl(url, options)
  • @param {String} url the URL to the image
  • @param {Object} options (optional) scaling options for the image (see below for details)
  • @return {String} the composed image URL
  • @throws {RangeError} when the quality is larger than 100
  • @throws {Error} when either scaling-width or scaling-height contains a value without px or %

The following options are supported by the ai.urls.composeImageScalingUrl function:

{
    'scaling-width': {String}
  , 'scaling-height': {String}
  , 'quality': {Number}
  , 'scale': {Boolean}
  , 'scaling-cache': {Boolean}
  , 'viewport-fitting': {String}
}
  • scaling-width: equivalent to the ai-scaling-width attribute (e.g. ‘50%’, ‘200px’. Default: not set)
  • scaling-height: equivalent to ai-scaling-height (e.g. ‘50%’, ‘200px’. Default: not set)
  • quality: equivalent to ai-quality (e.g. 50. Default: 70)
  • scale: equivalent to ai-scale (Default: true)
  • scaling-cache: equivalent to ai-scaling-cache (Default: true)
  • viewport-fitting: equivalent to ai-viewport-fitting (‘max’ (default), ‘landscape’, ‘portrait’ or ‘current’)

See Image Scaling Parameters for more information on how these options work.

For PNG images transcoded to WebP via the Image URLs JS API FIT now always uses lossless compression and therefore sets the quality parameter to -1 in the created URL.

ai.urls.composeImageCompressionUrl

Create a URL to an image using a Image Compression URL.

ai.urls.composeImageCompressionUrl(url)
  • @param {String} url the URL to the image
  • @return {String} the composed image URL