Namespace: Urls:urlHref

Urls:urlHref

Source:

Methods

urlHref(urlopt, paramsopt, nullable, anchoropt, nullable, markListParamsopt, nullable, keepEncodedUrlSafeCharsopt, nullable) → {String}

Will return a fully qualified URL based on the given URL base string for use as a href/source-value or navigation target.

Provide a base URL or leave the URL out, to use the current URL. Add GET-parameters (adding to those already present in the URL), define an anchor (or automatically get the one defined in the URL).

Provided URLs are handled with some automagic:

  • a URL starting with "//" will receive the current page protocol
  • a URL starting with a single "/" will be seen as relative and will be expanded to an absolute URL, based on the current URL
  • a URL starting with "?" will be treated as a singular query string, resulting in the query being added to the current URL, replacing any present query
  • a URL starting with "#" will be treated as a singular hash string, resulting in the hash being added to the current URL, replacing any present hash
  • if, after all automagic applied, the URL still does not start with a http-protocol, the current page's protocol will be added

Provided params have to be a flat plain object, with ordinal values or arrays of ordinal values on the first level. Everything else will be stringified and url-encoded as is. Usually, parameters defined here add to present parameters in the URL. To force-override present values, declare the param name with a "!" prefix ({'!presentparam' : 'new'}).

This method implements some quality-of-life improvements, that differ from the native result of new URL().href:

  • +-encoding for whitespace is replaced with %20, while + will stay what it is, a verbatim URL-safe character with repeating keys (tags=1&tags=2&tags=3)
  • empty parameters are rendered without "=". So, "?test=&foo" will be "?test&foo"
  • path/? will become just path?
  • path/# will become just path#
  • trailing slashes will be removed
  • parameters will be sorted alphabetically by keys (value order will be kept if possible, might change, when using markListParams)
  • identical key/value pairs will be reduced to one occurrence, so ?q=a&q=a will become ?q=a
Parameters:
Name Type Attributes Default Description
url String | URL <optional>
 null

the base URL to use, if nullish current location is used
params Object <optional>
<nullable>
 null

plain object of GET-parameters to add to the url
anchor String <optional>
<nullable>
 null

anchor/hash to set, has precedence over URL hash
markListParams Boolean <optional>
<nullable>
 false

if true, params with more than one value will be marked with "[]" preceding the param name
keepEncodedUrlSafeChars Boolean <optional>
<nullable>
 false

if true, encoded chars, which are URL-safe, are kept encoded, instead of being returned raw
Source:
Throws:

error if url is not usable

Returns:
the created URL including parameters and anchor
Type
String
Example
buildUrl('https://test.com', {search : 'kittens', order : 'asc'}, 'fluffykittens');
=> 'https://test.com?search=kittens&order=asc#fluffykittens'
buildUrl(null, {order : 'desc'});
=> 'https://current.url?order=desc'