## SipaUrl SipaUrl Tool class to access and manipulate the current or given URLs All non getter methods return the class itself for chaining. * [SipaUrl](#SipaUrl) * [.getUrl()](#SipaUrl.getUrl) → string * [.getUrlWithoutParamsAndAnchor(url)](#SipaUrl.getUrlWithoutParamsAndAnchor) → string * [.setUrl(url, [options])](#SipaUrl.setUrl) → [SipaUrl](#SipaUrl) * [.loadCurrentUrl()](#SipaUrl.loadCurrentUrl) → [SipaUrl](#SipaUrl) * [.load()](#SipaUrl.load) → [SipaUrl](#SipaUrl) * [.loadUrl(url)](#SipaUrl.loadUrl) → [SipaUrl](#SipaUrl) * [.getProtocol()](#SipaUrl.getProtocol) → string * [.setProtocol(protocol)](#SipaUrl.setProtocol) → [SipaUrl](#SipaUrl) * [.setProtocolOfUrl(url, protocol)](#SipaUrl.setProtocolOfUrl) → string * [.getHostName()](#SipaUrl.getHostName) → string * [.getHostNameOfUrl(url)](#SipaUrl.getHostNameOfUrl) → string * [.setHostName(hostname)](#SipaUrl.setHostName) → [SipaUrl](#SipaUrl) * [.setHostNameOfUrl(url, hostname)](#SipaUrl.setHostNameOfUrl) → string * [.getParams()](#SipaUrl.getParams) → Object.<string, string> * [.setParams(params)](#SipaUrl.setParams) → [SipaUrl](#SipaUrl) * [.setParam(param_key, value)](#SipaUrl.setParam) → [SipaUrl](#SipaUrl) * [.removeParams(param_keys)](#SipaUrl.removeParams) → [SipaUrl](#SipaUrl) * [.removeParam(param_key)](#SipaUrl.removeParam) → [SipaUrl](#SipaUrl) * [.resetParams()](#SipaUrl.resetParams) → [SipaUrl](#SipaUrl) * [.hasParam(param_key)](#SipaUrl.hasParam) → boolean * [.createUrlParams(params, options)](#SipaUrl.createUrlParams) → string * [.getParamsOfUrl(url, options)](#SipaUrl.getParamsOfUrl) → Object.<string, string> * [.removeParamsOfUrl(url, param_keys)](#SipaUrl.removeParamsOfUrl) → string * [.removeParamOfUrl(url, param_key)](#SipaUrl.removeParamOfUrl) → string * [.setParamsOfUrl(url, params)](#SipaUrl.setParamsOfUrl) → string * [.setAnchor(anchor, jump)](#SipaUrl.setAnchor) → [SipaUrl](#SipaUrl) * [.removeAnchor()](#SipaUrl.removeAnchor) → [SipaUrl](#SipaUrl) * [.getAnchor()](#SipaUrl.getAnchor) → string \| undefined * [.setAnchorOfUrl(url, anchor)](#SipaUrl.setAnchorOfUrl) → string * [.getAnchorOfUrl(url, options)](#SipaUrl.getAnchorOfUrl) → string \| undefined * [.removeAnchorOfUrl(url)](#SipaUrl.removeAnchorOfUrl) → string ### SipaUrl.getUrl() → string Get the current URL of the address bar **Example** ```js SipaUrl.getUrl(); // => https://my-website.com/web/?page=abc¶m=ok ``` ### SipaUrl.getUrlWithoutParamsAndAnchor(url) → string Get the given url without query parameters and without anchors. **Returns**: string - url without parameters | Param | Type | | --- | --- | | url | string | **Example** ```js const url = "https://my-business.com/post?some=stuff&foo=bar#my-anchor"; SipaUrl.getUrlWithoutParamsAndAnchor(url); // => https://my-business.com/post ``` ### SipaUrl.setUrl(url, [options]) → [SipaUrl](#SipaUrl) Overwrite the current url with the given url in the address bar, by default without reloading the page, if the hostname did not change. **Returns**: [SipaUrl](#SipaUrl) - for chaining | Param | Type | Default | Description | | --- | --- | --- | --- | | url | string | | | | [options] | Object | | | | [options.force_load] | boolean | false | if true, the given url will be (re)loaded, default: false | **Example** ```js // Current URL: https://my-business.com/?some=stuff&foo=bar#my-anchor SipaUrl.setUrl("https://my-business.com/?other=param#new-anchor"); // New URL: https://my-business.com/?other=param#new-anchor ``` ### SipaUrl.loadCurrentUrl() → [SipaUrl](#SipaUrl) Reload the current URL in the address bar. Typically used, when the URL was changed by other URL manipulation methods, that do not reload the page by default. **Returns**: [SipaUrl](#SipaUrl) - for chaining **Example** ```js // Current URL: https://my-business.com/?some=stuff&foo=bar#my-anchor SipaUrl.setParam("new","param"); SipaUrl.setHostName("new-host.com"); SipaUrl.setAnchor("new-anchor"); SipaUrl.loadCurrentUrl(); ``` ### SipaUrl.load() → [SipaUrl](#SipaUrl) Alias for SipaUrl.loadCurrentUrl() **Returns**: [SipaUrl](#SipaUrl) - for chaining ### SipaUrl.loadUrl(url) → [SipaUrl](#SipaUrl) Load the given URL in the address bar. **Returns**: [SipaUrl](#SipaUrl) - for chaining | Param | Type | | --- | --- | | url | string | **Example** ```js SipaUrl.loadUrl("https://my-business.com/?some=stuff&foo=bar#my-anchor"); ``` ### SipaUrl.getProtocol() → string Get the protocol of the current url (without colon) **Example** ```js // URL: https://my-business.com/some-param SipaUrl.getProtocol(); // => 'https' // URL: http://my-insecure-business.com/other-param SipaUrl.getProtocol(); // => 'http' ``` ### SipaUrl.setProtocol(protocol) → [SipaUrl](#SipaUrl) Set the protocol of the current url without reloading the page. **Returns**: [SipaUrl](#SipaUrl) - for chaining **Throws**: - Error if given protocol is not supported | Param | Type | | --- | --- | | protocol | string | **Example** ```js // URL: http://my-insecure-business.com/other-param SipaUrl.setProtocol("https"); // URL: https://my-insecure-business.com/other-param SipaUrl.load(); ``` ### SipaUrl.setProtocolOfUrl(url, protocol) → string Set the protocol of the given url. **Returns**: string - with given protocol **Throws**: - Error if given protocol is not supported | Param | Type | | --- | --- | | url | string | | protocol | string | **Example** ```js const url = "http://my-insecure-business.com/other-param"; SipaUrl.setProtocolOfUrl(url, "https"); // => "https://my-insecure-business.com/other-param" ``` ### SipaUrl.getHostName() → string Get the host name of the current url. **Example** ```js // URL: https://my-business.com/some-param SipaUrl.getHostName(); // => 'my-business.com' // URL https://www.my-business.com/some-param SipaUrl.getHostName(); // => 'www.my-business.com' // URL: https://subdomain.my-business.com/some-param SipaUrl.getHostName(); // => 'subdomain.my-business.com' // URL: http://localhost:7000/other-param SipaUrl.getHostName(); // => 'localhost' // URL: http://127.0.0.1/foo SipaUrl.getHostName(); // => '127.0.0.1' // URL: http://localhost/foo SipaUrl.getHostName(); // => 'localhost' ``` ### SipaUrl.getHostNameOfUrl(url) → string Get the host name of the given url. Returns an empty string if the given url is not valid or no hostname could be extracted. | Param | Type | | --- | --- | | url | string | **Example** ```js const url = "https://my-business.com/some-param"; SipaUrl.getHostNameOfUrl(url); // => 'my-business.com' const url2 = "https://www.my-business.com/some-param"; SipaUrl.getHostNameOfUrl(url2); // => 'www.my-business.com' const url3 = "https://subdomain.my-business.com/some-param"; SipaUrl.getHostNameOfUrl(url3); // => 'subdomain.my-business.com' ``` ### SipaUrl.setHostName(hostname) → [SipaUrl](#SipaUrl) Set the host name of the current url without reloading the page. | Param | Type | | --- | --- | | hostname | string | **Example** ```js // URL: https://my-business.com/some-param SipaUrl.setHostName("new-host.com"); // URL: https://new-host.com/some-param ``` ### SipaUrl.setHostNameOfUrl(url, hostname) → string Set/overwrite the host name of the given url. | Param | Type | | --- | --- | | url | string | | hostname | string | **Example** ```js const url = "https://my-business.com/some-param"; SipaUrl.setHostNameOfUrl(url, "new-host.com"); // => https://new-host.com/some-param const url2 = "https://www.my-business.com/some-param"; SipaUrl.setHostNameOfUrl(url2, "other-host.org"); // => https://other-host.org/some-param const url3 = "https://subdomain.my-business.com/some-param"; SipaUrl.setHostNameOfUrl(url3, "127.0.0.1"); // => https://127.0.0.1/some-param ``` ### SipaUrl.getParams() → Object.<string, string> Get all params of the current URL. **Example** ```js // URL: https://my-business.com/?one=1&stat=true SipaUrl.getParams(); // => { "one": "1", "stat": "true" } ``` ### SipaUrl.setParams(params) → [SipaUrl](#SipaUrl) Set or overwrite given parameters of the current url. **Returns**: [SipaUrl](#SipaUrl) - for chaining | Param | Type | Description | | --- | --- | --- | | params | Object.<string, string> | in format { param1: value1, param2: value2, ... } | **Example** ```js // URL: https://my-business.com/?one=1&stat=true&that=cool SipaUrl.setParams({ "more": "better", "stat": "false"}); // URL: https://my-business.com/?one=1&stat=false&that=cool&more=better ``` ### SipaUrl.setParam(param_key, value) → [SipaUrl](#SipaUrl) Set or overwrite one specific parameter of the current url. **Returns**: [SipaUrl](#SipaUrl) - for chaining | Param | Type | | --- | --- | | param_key | string | | value | string | **Example** ```js // URL: https://my-business.com/?super=banana&coca=cola SipaUrl.setParam("pepsi","coke"); // URL: https://my-business.com/?super=banana&coca=cola&pepsi=coke ``` ### SipaUrl.removeParams(param_keys) → [SipaUrl](#SipaUrl) Remove given params of the current url. **Returns**: [SipaUrl](#SipaUrl) - for chaining | Param | Type | | --- | --- | | param_keys | Array.<String> | **Example** ```js // URL: https://my-business.com/?some=stuff&foo=bar&more=power SipaUrl.removeParams(["some","more"]); // URL: https://my-business.com/?foo=bar ``` ### SipaUrl.removeParam(param_key) → [SipaUrl](#SipaUrl) Remove given param of the current url. **Returns**: [SipaUrl](#SipaUrl) - for chaining | Param | Type | | --- | --- | | param_key | string | **Example** ```js // URL: https://my-business.com/?some=stuff&foo=bar SipaUrl.removeParam("foo"); // URL: https://my-business.com/?some=stuff ``` ### SipaUrl.resetParams() → [SipaUrl](#SipaUrl) Remove all params of the current url. If there is no parameter, nothing happens. If there is an anchor, it will be preserved. **Returns**: [SipaUrl](#SipaUrl) - for chaining **Example** ```js // URL: https://my-business.com/?some=stuff&foo=bar#my-anchor SipaUrl.resetParams(); // URL: https://my-business.com/#my-anchor ``` ### SipaUrl.hasParam(param_key) → boolean Check if the current url has the given parameter. If the parameter exists, it does not matter if it has a value or not. If the parameter exists multiple times, it also returns true. If the parameter does not exist, it returns false. | Param | Type | | --- | --- | | param_key | string | ### SipaUrl.createUrlParams(params, options) → string Creates a URL query string based on the given key<->value object. | Param | Type | Description | | --- | --- | --- | | params | Object.<string, string> | in format { param1: value1, param2: value2, ... } | | options | Object | | | options.url_encode | boolean | url encode parameter keys and values, default: true | | options.multi_param_attributes | boolean | if attribute is of array, make it 'id=1&id=2&id=3' on true, or 'id=1,2,3' on false | **Example** ```js SipaUrl.createUrlParams({ a: 1, b: [1,2,3], c: "test space" }) // => 'a=1&b=1&b=2&b=3&c=test%20space' ``` ### SipaUrl.getParamsOfUrl(url, options) → Object.<string, string> Create a JSON, containing the parameters of the given url. **Returns**: Object.<string, string> - return a JSON with { param1: value1, param2: value2, ... } | Param | Type | Description | | --- | --- | --- | | url | string | the url to extract parameters from | | options | Object | | | options.decode_uri | boolean | decode uri parameter values | **Example** ```js SipaUrl.getParamsOfUrl("https://my-business.com/?some=stuff&foo=bar"); // => { "some": "stuff", "foo": "bar" } ``` ### SipaUrl.removeParamsOfUrl(url, param_keys) → string Remove the given parameters from the given url. | Param | Type | Description | | --- | --- | --- | | url | string | to remove the params from | | param_keys | Array.<String> | array of keys to remove from the given url, e.g. ['key1','key2'} | **Example** ```js const url = "https://my-business.com/?some=stuff&foo=bar&more=power"; SipaUrl.removeParamsOfUrl(url, ["some","more"]); // => https://my-business.com/?foo=bar ``` ### SipaUrl.removeParamOfUrl(url, param_key) → string Remove the given one parameter from the given url. **Returns**: string - with given parameter removed | Param | Type | Description | | --- | --- | --- | | url | string | | | param_key | string | name of the param | **Example** ```js const url = "https://my-business.com/?some=stuff&foo=bar"; SipaUrl.removeParamOfUrl(url, "foo"); // => https://my-business.com/?some=stuff ``` ### SipaUrl.setParamsOfUrl(url, params) → string Set/overwrite the parameters of the given url. **Returns**: string - with given parameters | Param | Type | Description | | --- | --- | --- | | url | string | | | params | Object.<string, string> | in format { param1: value1, param2: value2, ... } | **Example** ```js const url = "https://my-business.com/?one=1&stat=true&that=cool" SipaUrl.setParamsOfUrl(url, { "more": "better", "stat": "false"}); // => https://my-business.com/?one=1&stat=false&that=cool&more=better ``` ### SipaUrl.setAnchor(anchor, jump) → [SipaUrl](#SipaUrl) Set or overwrite given anchor of the current url. **Returns**: [SipaUrl](#SipaUrl) - for chaining | Param | Type | Default | Description | | --- | --- | --- | --- | | anchor | string | | without leading # character | | jump | boolean | false | jump to anchor | **Example** ```js // URL: https://my-business.com/?some=stuff#my-anchor SipaUrl.setAnchor("new-anchor"); // URL: https://my-business.com/?some=stuff#new-anchor // URL: https://my-business.com/?without=anchor SipaUrl.setAnchor("added-anchor"); // URL: https://my-business.com/?without=anchor#added-anchor ``` ### SipaUrl.removeAnchor() → [SipaUrl](#SipaUrl) Remove the anchor of the current URL. **Returns**: [SipaUrl](#SipaUrl) - for chaining **Example** ```js // URL: https://my-business.com/?some=stuff&foo=bar#my-anchor SipaUrl.removeAnchor(); // URL: https://my-business.com/?some=stuff&foo=bar ``` ### SipaUrl.getAnchor() → string \| undefined Get the anchor of the current URL without leading #. Returns undefined if there is no anchor. **Example** ```js // URL: https://my-business.com/?some=stuff&foo=bar#my-anchor SipaUrl.getAnchor(); // => 'my-anchor' // URL: https://my-business.com/?some=stuff&foo=bar SipaUrl.getAnchor(); // => undefined ``` ### SipaUrl.setAnchorOfUrl(url, anchor) → string Set/overwrite the anchor of the given url. **Returns**: string - with given anchor | Param | Type | Description | | --- | --- | --- | | url | string | | | anchor | string | as string, without leading # | **Example** ```js const url = "https://my-business.com/?some=stuff#my-anchor"; SipaUrl.setAnchorOfUrl(url, "new-anchor"); // => https://my-business.com/?some=stuff#new-anchor const url2 = "https://my-business.com/?without=anchor"; SipaUrl.setAnchorOfUrl(url2, "added-anchor"); // => https://my-business.com/?without=anchor#added-anchor ``` ### SipaUrl.getAnchorOfUrl(url, options) → string \| undefined Get the anchor of the given url. **Returns**: string \| undefined - the anchor of the given url | Param | Type | Description | | --- | --- | --- | | url | string | | | options | object | | | options.return_prefixed_hash | boolean | return the prefixed hash | **Example** ```js const url = "https://my-business.com/?some=stuff&foo=bar#my-anchor"; SipaUrl.getAnchorOfUrl(url); // => 'my-anchor' const url2 = "https://my-business.com/?some=stuff&foo=bar"; SipaUrl.getAnchorOfUrl(url2); // => undefined ``` ### SipaUrl.removeAnchorOfUrl(url) → string Remove the anchor of the given url. **Returns**: string - without anchor | Param | Type | | --- | --- | | url | string | **Example** ```js const url = "https://my-business.com/?some=stuff&foo=bar#my-anchor"; SipaUrl.removeAnchorOfUrl(url); // => https://my-business.com/?some=stuff&foo=bar ```