Expand all

mw.Uri

Create and manipulate MediaWiki URIs.

Intended to be minimal, but featureful; do not expect full RFC 3986 compliance. The use cases we have in mind are constructing 'next page' or 'previous page' URLs, detecting whether we need to use cross-domain proxies for an API, constructing simple URL-based API calls, etc. Parsing here is regex-based, so may not work on all URIs, but is good enough for most.

You can modify the properties directly, then use the toString method to extract the full URI string again. Example:

var uri = new mw.Uri( 'http://example.com/mysite/mypage.php?quux=2' );

if ( uri.host == 'example.com' ) {
    uri.host = 'foo.example.com';
    uri.extend( { bar: 1 } );

    $( 'a#id1' ).attr( 'href', uri );
    // anchor with id 'id1' now links to http://foo.example.com/mysite/mypage.php?bar=1&quux=2

    $( 'a#id2' ).attr( 'href', uri.clone().extend( { bar: 3, pif: 'paf' } ) );
    // anchor with id 'id2' now links to http://foo.example.com/mysite/mypage.php?bar=3&quux=2&pif=paf
}

Given a URI like http://usr:pwd@www.example.com:81/dir/dir.2/index.htm?q1=0&&test1&test2=&test3=value+%28escaped%29&r=1&r=2#top the returned object will have the following properties:

protocol  'http'
user      'usr'
password  'pwd'
host      'www.example.com'
port      '81'
path      '/dir/dir.2/index.htm'
query     {
              q1: '0',
              test1: null,
              test2: '',
              test3: 'value (escaped)'
              r: ['1', '2']
          }
fragment  'top'

Note: 'password' is technically not allowed for HTTP URIs, but it is possible with other kinds of URIs.

Parsing based on parseUri 1.2.2 (c) Steven Levithan http://stevenlevithan.com, MIT License. http://stevenlevithan.com/demo/parseuri/js/

Constructor

new mw.Uri([uri], [options]) #

Construct a new URI object. Throws error if arguments are illegal/impossible, or otherwise don't parse.

Parameters:

Name Type Attributes Description
uri Object | string optional

URI string, or an Object with appropriate properties (especially another URI object to clone). Object must have non-blank protocol, host, and path properties. If omitted (or set to undefined, null or empty string), then an object will be created for the default uri of this constructor (location.href for mw.Uri, other values for other instances -- see mw.UriRelative for details).
options mw.Uri.UriOptions | boolean optional

Object with options, or (backwards compatibility) a boolean for strictMode
Source:

Throws:

when the query string or fragment contains an unknown % sequence

Type
Error

Properties

fragment :string|undefined #

For example top.

Type:

Source:
For example top.

host :string #

For example www.example.com (always present).

Type:

Source:
For example www.example.com (always present).

password :string|undefined #

For example pwd.

Type:

Source:
For example pwd.

path :string #

For example /dir/dir.2/index.htm (always present).

Type:

Source:
For example /dir/dir.2/index.htm (always present).

port :string|undefined #

For example 81.

Type:

Source:
For example 81.

protocol :string #

For example http (always present).

Type:

Source:
For example http (always present).

query :Object #

For example { a: '0', b: '', c: 'value' } (always present).

Type:

Source:
For example { a: '0', b: '', c: 'value' } (always present).

user :string|undefined #

For example usr.

Type:

Source:
For example usr.

Methods

clone() → {Object} #

Clone this URI.

Source:

Returns:

New URI object with same properties

Type
Object
Clone this URI.

extend(parameters) → {Object} #

Extend the query section of the URI with new parameters.

Parameters:

Name Type Description
parameters Object

Query parameters to add to ours (or to override ours with) as an object
Source:

Returns:

This URI object

Type
Object
Extend the query section of the URI with new parameters.

getAuthority() → {string} #

Get the userInfo, host and port section of the URI.

In most real-world URLs this is simply the hostname, but the definition of 'authority' section is more general.

Source:

Returns:

Type
string
Get the userInfo, host and port section of the URI.

getHostPort() → {string} #

Get host and port section of a URI.

Source:

Returns:

Type
string
Get host and port section of a URI.

getQueryString() → {string} #

Get the query arguments of the URL, encoded into a string.

Does not preserve the original order of arguments passed in the URI. Does handle escaping.

Source:

Returns:

Type
string
Get the query arguments of the URL, encoded into a string.

getRelativePath() → {string} #

Get everything after the authority section of the URI.

Source:

Returns:

Type
string
Get everything after the authority section of the URI.

getUserInfo() → {string} #

Get user and password section of a URI.

Source:

Returns:

Type
string
Get user and password section of a URI.

toString() → {string} #

Get the entire URI string.

Note that the output may not be precisely the same as the constructor input, due to order of query arguments. Note also that the fragment is not always roundtripped as-is; some characters will become encoded, including the slash character, which can cause problems with e.g. mediawiki.router. It is recommended to use the native URL class (via web2017-polyfills, which loads a polyfill if needed) in contexts where the fragment is important.

Source:

Returns:

The URI string

Type
string
Get the entire URI string.

decode(s) → {string}static #

Decode a url encoded value.

Reversed encode. Standard decodeURIComponent, with addition of replacing + with a space.

Parameters:

Name Type Description
s string

String to decode
Source:

Returns:

Decoded string

Type
string

Throws:

when the string contains an unknown % sequence

Type
Error
Decode a url encoded value.

encode(s) → {string}static #

Encode a value for inclusion in a url.

Standard encodeURIComponent, with extra stuff to make all browsers work similarly and more compliant with RFC 3986. Similar to rawurlencode from PHP and our JS library mw.util.rawurlencode, except this also replaces spaces with +.

Parameters:

Name Type Description
s string

String to encode
Source:

Returns:

Encoded string for URI

Type
string
Encode a value for inclusion in a url.

Type Definitions

UriOptions #

Options for mw.Uri object.

Type:

Properties:

Name Type Attributes Default Description
strictMode boolean optional
 false

Trigger strict mode parsing of the url.
overrideKeys boolean optional
 false

Whether to let duplicate query parameters override each other (true) or automagically convert them to an array (false).
arrayParams boolean optional
 false

Whether to parse array query parameters (e.g. &foo[0]=a&foo[1]=b or &foo[]=a&foo[]=b) or leave them alone. Currently this does not handle associative or multi-dimensional arrays, but that may be improved in the future. Implies overrideKeys: true (query parameters without [...] are not parsed as arrays).
Source:
Options for mw.Uri object.