MODULES Uize.Url
SEARCHEXAMPLESSOURCETEST

1. Introduction

The Uize.Url module eases working with URLs, supporting query string parsing and serialization, resolving relative URLs to absolute URLs, and more.

DEVELOPERS: Chris van Rensburg

1.1. Examples

There are no dedicated showcase example pages for the Uize.Url module.

SEARCH FOR EXAMPLES

Use the link below to search for example pages on the UIZE Web site that reference the Uize.Url module...

SEARCH

1.2. Implementation Info

The Uize.Url module defines the Uize.Url package under the Uize namespace.

1.2.1. Features Introduced in This Module

The features listed in this section have been introduced in this module.

STATIC METHODS

Uize.Url.from | Uize.Url.fromParams | Uize.Url.fromPiece | Uize.Url.getCacheDefeatStr | Uize.Url.resolve | Uize.Url.toAbsolute | Uize.Url.toParams | Uize.Url.toPiece

STATIC PROPERTIES

Uize.Url.moduleName

1.2.2. Features Overridden in This Module

No features have been overridden in this module.

1.2.3. Features Inherited From Other Modules

This module has no inherited features.

1.2.4. Modules Directly Under This Namespace

There are no modules directly under this namespace.

1.2.5. Unit Tests

The Uize.Url module is unit tested by the Uize.Test.Uize.Url test module.

2. Static Methods

2.1. Uize.Url.from

Returns an object, containing properties for the various logical segments of the specified URL string.

SYNTAX

urlSegmentsOBJ = Uize.Url.from (urlSTR);

This method provides a convenient way to get at very precise portions of a URL string, such as the file name without the extension, the file type without the "." (period) character, the query params string without the "?" (question mark) character, the anchor without the "#" (pound / hash) character, etc.

2.1.1. URL Segment Properties

The urlSegmentsOBJ object returned by this method has the following structure...

URL SEGMENTS OBJECT

{
  href       : hrefSTR,       //  http://uize.com:80/reference/Uize.html?param=value#anchor
  fullDomain : fullDomainSTR, //  http://uize.com:80
  protocol   : protocolSTR,   //  http:
  host       : hostSTR,       //  uize.com:80
  hostname   : hostnameSTR,   //  uize.com
  port       : portSTR,       //  80
  pathname   : pathnameSTR,   //  /reference/Uize.html
  folderPath : folderPathSTR, //  /reference/
  file       : fileSTR,       //  Uize.html
  fileName   : fileNameSTR,   //  Uize
  extension  : extensionSTR,  //  .html
  fileType   : fileTypeSTR,   //  html
  search     : searchSTR,     //  ?param=value
  query      : querySTR,      //  param=value
  hash       : hashSTR,       //  #anchor
  anchor     : anchorSTR      //  hash
}

The URL segment properties are described in more detail below...

2.1.1.1. href

A string, representing the entire URL string parsed by the Uize.Url.from method.

ILLUSTRATION

URL      :  http://uize.com:80/reference/Uize.html?param=value#anchor
PORTION  :  |<----------------------------------------------------->|
VALUE    :  http://uize.com:80/reference/Uize.html?param=value#anchor

NOTES

this property is equivalent to the same named property of the window.location object (see Properties Consistent with window.location)

2.1.1.2. fullDomain

A string, representing the portion of the URL comprised of the protocol, "//" (two forward slashes), and the host.

ILLUSTRATION

URL      :  http://uize.com:80/reference/Uize.html?param=value#anchor
PORTION  :  |<-------------->|
VALUE    :  http://uize.com:80

NOTES

for relative URLs that only specify a pathname and/or search and/or hash, the value of this property will be '' (an empty string)

2.1.1.3. protocol

A string, representing the Internet protocol in use by the URL (eg. http, ftp, irc, ssh, etc.)

ILLUSTRATION

URL      :  http://uize.com:80/reference/Uize.html?param=value#anchor
PORTION  :  |<->|
VALUE    :  http:

NOTES

for relative URLs that only specify a pathname and/or search and/or hash, the value of this property will be '' (an empty string)
this property is equivalent to the same named property of the window.location object (see Properties Consistent with window.location)

2.1.1.4. host

A string, representing the portion of the URL comprised of the hostname, followed by a ":" (colon) character and the port if a port is present in the URL.

ILLUSTRATION

URL      :  http://uize.com:80/reference/Uize.html?param=value#anchor
PORTION  :         |<------->|
VALUE    :         uize.com:80

NOTES

for relative URLs that only specify a pathname and/or search and/or hash, the value of this property will be '' (an empty string)
this property is equivalent to the same named property of the window.location object (see Properties Consistent with window.location)

2.1.1.5. hostname

A string, representing the portion of the URL comprised of just the name of the host (ie. domain name or IP address) and without the protocol and port portions.

ILLUSTRATION

URL      :  http://uize.com:80/reference/Uize.html?param=value#anchor
PORTION  :         |<---->|
VALUE    :         uize.com

NOTES

for relative URLs that only specify a pathname and/or search and/or hash, the value of this property will be '' (an empty string)
this property is equivalent to the same named property of the window.location object (see Properties Consistent with window.location)

2.1.1.6. port

A string, representing the portion of the URL that specifies the port on which to communicate with a server.

ILLUSTRATION

URL      :  http://uize.com:80/reference/Uize.html?param=value#anchor
PORTION  :                  ^^
VALUE    :                  80

Most URLs will not contain an explicit port, and the port will typically be defaulted by the server to 80 for communication via HTTP, and 443 for secure communication via HTTPS. For URLs that do not specify a port, the value of the port property will be '' (an empty string).

NOTES

for relative URLs that only specify a pathname and/or search and/or hash, the value of this property will be '' (an empty string)
this property is equivalent to the same named property of the window.location object (see Properties Consistent with window.location)

2.1.1.7. pathname

A string, representing the portion of the URL comprised of the folderPath and file, and excluding the fullDomain, search, and hash.

ILLUSTRATION

URL      :  http://uize.com:80/reference/Uize.html?param=value#anchor
PORTION  :                    |<---------------->|
VALUE    :                    /reference/Uize.html

NOTES

this property is equivalent to the same named property of the window.location object (see Properties Consistent with window.location)

2.1.1.8. folderPath

A string, representing the complete path to a folder (which may include multiple nested folder levels), and excluding the fullDomain, file, search, and hash.

ILLUSTRATION

URL      :  http://uize.com:80/reference/Uize.html?param=value#anchor
PORTION  :                    |<------->|
VALUE    :                    /reference/

2.1.1.9. file

A string, representing the portion of the URL comprised of just the fileName and extension, and excluding the fullDomain, folderPath, search, and hash.

ILLUSTRATION

URL      :  http://uize.com:80/reference/Uize.html?param=value#anchor
PORTION  :                               |<----->|
VALUE    :                               Uize.html

2.1.1.10. fileName

A string, representing the portion of the URL that specifies just the file name for a file, and excluding its extension.

ILLUSTRATION

URL      :  http://uize.com:80/reference/Uize.html?param=value#anchor
PORTION  :                               |<>|
VALUE    :                               Uize

2.1.1.11. extension

A string, representing the portion of the URL that specifies just the file extension for a file, and excluding its fileName.

ILLUSTRATION

URL      :  http://uize.com:80/reference/Uize.html?param=value#anchor
PORTION  :                                   |<->|
VALUE    :                                   .html

Unlike the fileType property, the extension property contains the conventional "." (period character) delimiter that separates the fileName and fileType.

2.1.1.12. fileType

A string, representing the portion of the URL that specifies just the file type for a file, and excluding the conventional "." (period character) delimiter that separates the fileName and fileType.

ILLUSTRATION

URL      :  http://uize.com:80/reference/Uize.html?param=value#anchor
PORTION  :                                    |<>|
VALUE    :                                    html

2.1.1.13. search

A string, representing the portion of the URL comprised of the "?" (question mark) character and query, if present in the URL.

ILLUSTRATION

URL      :  http://uize.com:80/reference/Uize.html?param=value#anchor
PORTION  :                                        |<-------->|
VALUE    :                                        ?param=value

Unlike the query property, the search property contains the conventional "?" (question mark character) that delimits the query from preceding portions of the URL.

NOTES

this property is equivalent to the same named property of the window.location object (see Properties Consistent with window.location)

2.1.1.14. query

A string, representing the portion of the URL that specifies just the query parameters, and excluding the conventional "?" (question mark character) that delimits the query from preceding portions of the URL.

ILLUSTRATION

URL      :  http://uize.com:80/reference/Uize.html?param=value#anchor
PORTION  :                                         |<------->|
VALUE    :                                         param=value

2.1.1.15. hash

A string, representing the portion of the URL comprised of the "#" (hash / pound) character and anchor, if present in the URL.

ILLUSTRATION

URL      :  http://uize.com:80/reference/Uize.html?param=value#anchor
PORTION  :                                                    |<--->|
VALUE    :                                                    #anchor

Unlike the anchor property, the hash property contains the conventional "#" (hash / pound character) that delimits the anchor from preceding portions of the URL.

NOTES

this property is equivalent to the same named property of the window.location object (see Properties Consistent with window.location)

2.1.1.16. anchor

A string, representing the portion of the URL that specifies just the anchor name, and excluding the conventional "#" (hash / pound character) that delimits the anchor from preceding portions of the URL.

ILLUSTRATION

URL      :  http://uize.com:80/reference/Uize.html?param=value#anchor
PORTION  :                                                     |<-->|
VALUE    :                                                     anchor

2.1.2. Properties Consistent with window.location

Of the properties in the urlSegmentsOBJ object returned by the Uize.Url.from method, the properties href, protocol, host, hostname, port, pathname, search, and hash are consistent with the properties of the built-in window.location object.

2.1.3. URL Segments, as a Tree

The following diagram shows the properties of the urlSegmentsOBJ object as a tree structure, illustrating the relationship between the properties...

URL SEGMENTS, AS A TREE

href
|__ fullDomain
|       |__ protocol
|       |__ //
|       |__ host
|            |__ hostname
|            |__ :
|            |__ port
|
|__ pathname
|      |__ folderPath
|      |__ file
|            |__ fileName
|            |__ extension
|                    |__ .
|                    |__ fileType
|
|__ search
|      |__ ?
|      |__ query
|
|__ hash
      |__ #
      |__ anchor

2.1.4. Reconstructing a URL String

A URL string can be reconstructed from a urlSegmentsOBJ type value in one of the following ways...

urlStr =
  urlSegments.fullDomain +
  urlSegments.pathname +
  urlSegments.search +
  urlSegments.hash
;

urlStr =
  urlSegments.fullDomain +
  urlSegments.folderPath +
  urlSegments.file +
  urlSegments.search +
  urlSegments.hash
;

urlStr =
  urlSegments.fullDomain +
  urlSegments.folderPath +
  urlSegments.fileName +
  urlSegments.extension +
  urlSegments.search +
  urlSegments.hash
;

If you wish to reconstruct a URL string using any of the more granular URL segment properties, such as protocol, hostname, port, fileType, query, etc., then you will have to use logic to conditionally include the delimiters //, :, ., ?, and #.

NOTES

see also the Uize.Url.fromParams and Uize.Url.fromPiece static methods

IMPLEMENTATION INFO

this feature was introduced in this module

2.2. Uize.Url.fromParams

A utility method that parses a query string and returns the query parameters as an object.

SYNTAX

paramsOBJ = Uize.Url.fromParams (queryParamsSTR);

This method assumes that the query string was serialized using "&" to separate parameters, and "=" to separate parameter name from parameter value in each name/value pair.

EXAMPLE

Uize.Url.fromParams ('category=holiday&type=all&results=20');

With the above query string, the Uize.Url.fromParams method would produce the object...

{
  category:'holiday',
  type:'all',
  results:'20'
}

The value of the queryParamsSTR parameter may contain a prepended query '?' character, and even a URL path. These will simply be ignored when parsing the query parameters, so this method can be applied to a complete URL without worrying about first having to remove the path. So, extending on the above example, the same result would be produced if the value of the queryParamsSTR parameter was 'http://www.somedomain.com/search?category=holiday&type=all&results=20'.

NOTES

when parsing the query string, all parameter values are treated as strings
see also the corresponding Uize.Url.toParams static method

IMPLEMENTATION INFO

this feature was introduced in this module

2.3. Uize.Url.fromPiece

Returns a string, representing the decoded form of the specified URL segment string.

SYNTAX

unencodedSTR = Uize.Url.fromPiece (encodedUrlPieceSTR);

EXAMPLE

unencoded = Uize.Url.fromPiece ('solar%2C%20wind%2C%20efficiency%20%26%20biofuels');

After executing the above statement, the variable unencoded would have the value 'solar, wind, efficiency & biofuels'.

NOTES

see also the corresponding Uize.Url.toPiece static method

IMPLEMENTATION INFO

this feature was introduced in this module

2.4. Uize.Url.getCacheDefeatStr

A utility method that returns a string value, generated using time and a random number, that can then be used as a uniquifying query parameter on request URLs in order to defeat client caching.

SYNTAX

cacheDefeatSTR = Uize.Url.getCacheDefeatStr ();

NOTES

this method takes no parameters

IMPLEMENTATION INFO

this feature was introduced in this module

2.5. Uize.Url.resolve

Returns a string, representing a URL that has been resolved from the specified URL path string and query params object.

SYNTAX

urlSTR = Uize.Url.resolve (urlPathSTR,urlParamsOBJ);

EXAMPLE

searchUrl = Uize.Url.resolve (
  'http://www.somedomain.com/search',
  {
    category:'holiday',
    type:'all',
    results:'20'
  }
);

In the above example, the Uize.Url.resolve method would produce the result 'http://www.somedomain.com/search?category=holiday&type=all&results=20'.

2.5.1. An Existing Query Character

The value of the urlPathSTR parameter may already contain a query '?' character at the end.

If this is the case, the Uize.Url.resolve method will not add an additional query character. So, the following example would produce the same result as the first example...

EXAMPLE

searchUrl = Uize.Url.resolve (
  'http://www.somedomain.com/search?',
  {
    category:'holiday',
    type:'all',
    results:'20'
  }
);

In the above example, the Uize.Url.resolve method would produce the result 'http://www.somedomain.com/search?category=holiday&type=all&results=20'.

2.5.2. Augmenting Existing Query Params

The value of the urlPathSTR parameter may already contain query parameters.

If this is the case, the Uize.Url.resolve method will concatenate the additional query parameters using the '&' query param delimiter.

EXAMPLE

searchUrl = Uize.Url.resolve (
  'http://www.somedomain.com/search?sort=recent',
  {
    category:'holiday',
    type:'all',
    results:'20'
  }
);

In the above example, the Uize.Url.resolve method would produce the result 'http://www.somedomain.com/search?sort=recent&category=holiday&type=all&results=20'.

2.5.3. Modifying Existing Query Params

The value of the urlPathSTR parameter may contain query parameters whose values you wish to modify.

Overwriting existing values for query params is handled automatically by the Uize.Url.resolve method - all you have to do is specify the new values in the urlParamsOBJ parameter.

EXAMPLE

searchUrl = Uize.Url.resolve (
  'http://www.somedomain.com/search?sort=recent&results=20',
  {
    sort:'popular',      // overwrites existing sort param in URL
    category:'holiday',
    type:'all',
    results:'100'        // overwrites existing results param in URL
  }
);

In the above example, the Uize.Url.resolve method would produce the result 'http://www.somedomain.com/search?sort=popular&results=100&category=holiday&type=all'.

2.5.4. Removing Existing Query Params

The value of the urlPathSTR parameter may contain query parameters that you wish to remove.

Removing existing query params from a URL can be accomplished by specifying the value null for the params you wish to remove in the urlParamsOBJ parameter. You can specify to remove params that don't exist in the URL, without any ill effects - those params will simply be ignored.

EXAMPLE

searchUrl = Uize.Url.resolve (
  'http://www.somedomain.com/search?sort=recent&results=20',
  {
    sort:null,      // removes existing sort param in URL
    category:null,  // would remove category param in URL, if it existed
    type:'all',
    results:null    // removes existing results param in URL
  }
);

In the above example, the Uize.Url.resolve method would produce the result 'http://www.somedomain.com/search?type=all'.

2.5.5. Variations

The Uize.Url.resolve method is quite versatile in its signature, with several variations that can come in handy under different circumstances.

VARIATION 1

urlSTR = Uize.Url.resolve (urlPathSTR,urlParamsObjectsARRAY);

When a urlParamsObjectsARRAY parameter is specified, multiple params objects can be specified in an array. This provides for an easy way to merge query param sets from multiple sources, or to blend fixed params with parameterized params (eg. passed in a method call), or to override the values in param sets. The values from params objects later in the array override those from earlier params objects. None of the objects in the array will be modified by the operation.

EXAMPLE

var defaultSearchSettings = {
  sort:'recent',
  type:'all',
  results:'20'
};
searchUrl = Uize.Url.resolve (
  'http://www.somedomain.com/search',
  [
    defaultSearchSettings,
    {
      category:'holiday',
      sort:'popular'
    }
  ]
);

In the above example, the values of the category and sort properties of the second params object in the urlParamsObjectsARRAY value would be stitched in to the values provided by the defaultSearchSettings query params object that appears first in the array, with the value of the sort property of the second params object overriding the value contained in the defaultSearchSettings object, and with the defaultSearchSettings object not being modified in the process.

VARIATION 2

urlSTR = Uize.Url.resolve (urlPathAndParamsObjectsARRAY);

Another versatile variation allows a single urlPathAndParamsObjectsARRAY parameter to be specified, where the array specified by this parameter contains the URL path string as its first element, and an arbitrary number of params objects in subsequent elements. Using this variation, the example shown for VARIATION 1 could be re-written as...

EXAMPLE

var defaultSearchSettings = {
  sort:'recent',
  type:'all',
  results:'20'
};
searchUrl = Uize.Url.resolve ([
  'http://www.somedomain.com/search',
  defaultSearchSettings,
  {
    category:'holiday',
    sort:'popular'
  }
]);

This variation is powerful in that it allows you to write functions that can accept a single URL parameter, where that parameter's value may be a string, or an array containing a string path and params objects - and a single call to the Uize.Url.resolve method will resolve it to a string for the benefit of your functions' implementation code.

VARIATION 3

urlSTR = Uize.Url.resolve (urlPathAndParamsObjectsARRAY,urlParamsOBJ);

When using the urlPathAndParamsObjectsARRAY parameter, you can still specify the urlParamsOBJ second parameter to stitch in further query params.

EXAMPLE

var defaultSearchSettings = {
  sort:'recent',
  type:'all',
  results:'20'
};
searchUrl = Uize.Url.resolve (
  ['http://www.somedomain.com/search',defaultSearchSettings],
  {
    category:'holiday',
    sort:'popular'
  }
);

The above example would produce the same results as the previous example.

VARIATION 4

urlSTR = Uize.Url.resolve (urlPathAndParamsObjectsARRAY,urlParamsObjectsARRAY);

Finally, it is also possible to specify the urlParamsObjectsARRAY second parameter, allowing ridiculous numbers of query params objects to be specified where desired and/or convenient.

EXAMPLE

var defaultSearchSettings = {
  sort:'recent',
  type:'all',
  results:'20'
};
searchUrl = Uize.Url.resolve (
  ['http://www.somedomain.com/search',{category:'holiday'}],
  [
    defaultSearchSettings,
    {sort:'popular'}
  ]
);

The above example would produce the same results as the previous example.

2.5.6. Conditional Params

If the value for a query params object is null or undefined, it will simply be treated as an empty params object, regardless of whether it's specified for the urlParamsOBJ parameter or one of the elements in the urlPathAndParamsObjectsARRAY or urlParamsObjectsARRAY parameters. This is convenient when using conditional expressions to choose params that should or should not be present.

EXAMPLE

var defaultSearchSettings = {
  category:'any',
  sort:'recent',
  type:'all',
  results:'20'
};
searchUrl = Uize.Url.resolve ([
  'http://www.somedomain.com/search',
  defaultSearchSettings,
  searchCategory ? {category:searchCategory} : null,
  useUserSearchSettings ? userSearchSettings : null,
  useCustomSort ? {sort:customSortValue} : null
]);

In the above example, conditional expressions that result in a null value will be treated as params objects containing no param values, so they will have no effect.

NOTES

see also the Uize.Url.toParams static method

IMPLEMENTATION INFO

this feature was introduced in this module

2.6. Uize.Url.toAbsolute

Returns a string, representing the specified relative URL resolved against the specified base URL.

SYNTAX

absoluteUrlSTR = Uize.Url.toAbsolute (baseUrlSTR,relativeUrlSTR);

EXAMPLE 1

Uize.Url.toAbsolute (
  'http://www.uize.com/reference/source-code/Uize.html',
  '../../download.html'
);

The above statement would produce the value 'http://www.uize.com/download.html'.

EXAMPLE 2

Uize.Url.toAbsolute ('http://www.uize.com/index.html','download.html');

The above statement would produce the value 'http://www.uize.com/download.html'.

EXAMPLE 3

Uize.Url.toAbsolute ('http://www.uize.com/index.html','');

The above statement would produce the value 'http://www.uize.com'.

IMPLEMENTATION INFO

this feature was introduced in this module

2.7. Uize.Url.toParams

A utility method that serializes the properties of the specified object to produce a URL query params string.

SYNTAX

queryParamsSTR = Uize.Url.toParams (paramsOBJ);

This method assumes that the params in paramsOBJ should be serialized using "&" to separate parameters, and "=" to separate parameter name from parameter value in each name/value pair.

EXAMPLE

Uize.Url.toParams ({
  category:'holiday',
  type:'all',
  results:'20'
});

With the above paramsOBJ value, the Uize.Url.toParams method would produce the string...

'category=holiday&type=all&results=20'

VARIATION

queryParamsSTR = Uize.Url.toParams (urlParamsObjectsARRAY);

When a urlParamsObjectsARRAY parameter is specified, multiple params objects can be specified in an array. This provides for an easy way to merge query param sets from multiple sources, or to blend fixed params with parameterized params (eg. passed in a method call), or to override the values in param sets. The values from params objects later in the array override those from earlier params objects. None of the objects in the array will be modified by the operation.

EXAMPLE

var defaultSearchSettings = {
  sort:'recent',
  type:'all',
  results:'20'
};
searchQueryParamsStr = Uize.Url.toParams (
  [defaultSearchSettings,{category:'holiday',sort:'popular'}]
);

In the above example, the values of the category and sort properties of the second params object in the urlParamsObjectsARRAY value would be stitched in to the values provided by the defaultSearchSettings query params object that appears first in the array, with the value of the sort property of the second params object overriding the value contained in the defaultSearchSettings object, and with the defaultSearchSettings object not being modified in the process.

NOTES

this method does not prepend the query '?' character to the params string
see also the corresponding Uize.Url.fromParams static method

IMPLEMENTATION INFO

this feature was introduced in this module

2.8. Uize.Url.toPiece

Returns a string, representing the URL encoded form of the specified string.

SYNTAX

encodedUrlPieceSTR = Uize.Url.toPiece (unencodedSTR);

EXAMPLE

encodedUrlPiece = Uize.Url.toPiece ('solar, wind, efficiency & biofuels');

After executing the above statement, the variable encodedUrlPiece would have the value 'solar%2C%20wind%2C%20efficiency%20%26%20biofuels'.

NOTES

see also the corresponding Uize.Url.fromPiece static method

IMPLEMENTATION INFO

this feature was introduced in this module

3. Static Properties

3.1. Uize.Url.moduleName

IMPLEMENTATION INFO

this feature was introduced in this module