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 | Uize.Url.toRelative

STATIC PROPERTIES

Uize.Url.moduleName | Uize.Url.pathToResources

No features have been overridden in this module.

This module has no inherited features.

There are no modules directly under this namespace.

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

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

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

2.1.1.2. fullDomain

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

2.1.1.3. protocol

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

2.1.1.4. host

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

2.1.1.5. hostname

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

2.1.1.6. port

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

2.1.1.7. pathname

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

2.1.1.8. folderPath

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

2.1.1.9. file

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

2.1.1.10. fileName

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

2.1.1.11. extension

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

2.1.1.12. fileType

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

2.1.1.13. search

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

2.1.1.14. query

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

2.1.1.15. hash

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

2.1.1.16. anchor

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

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.

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

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 #.

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'.

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'.

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'.

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'.

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 (e.g. 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 us 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.

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.

The Uize.Url.toRelative method can create a relative URL in any case where the URL it would create, when applied against the specified base URL, would produce the original URL to relativize.

Situations in which a relative URL can be created include...

2.9.1.1. When Both URLs Have the Same Back-relative Prefix

var relativeUrl = Uize.Url.toRelative (
  '../../foo/bar/',
  '../../foo/baz/qux/file.html'
);

'../baz/qux/file.html'

2.9.1.2. When Both URLs are Root-relative

var relativeUrl = Uize.Url.toRelative (
  '/foo/bar/',
  '/foo/baz/qux/file.html'
);

'../baz/qux/file.html'

2.9.1.3. When Both URLs are Forward-relative

var relativeUrl = Uize.Url.toRelative (
  'foo/bar/',
  'foo/baz/qux/file.html'
);

'../baz/qux/file.html'

2.9.1.4. When Both URLs Have the Same Domain

var relativeUrl = Uize.Url.toRelative (
  'http://www.somedomain.com/foo/bar/',
  'http://www.somedomain.com/foo/baz/qux/file.html'
);

'../baz/qux/file.html'

In cases where it is impossible to create a relative URL (see When a Relative URL Can Be Created), the value null will be returned, unless the URL to relativize is an absolute URL, in which case the URL to relativize will be returned.

Whenever the base URL and the URL to relativize do not have the same shared base, then a relative URL cannot be created. This can occur when...

EXAMPLES

// base URL is absolute (i.e. has a domain)

Uize.Url.toRelative ('http://www.foo.com/','/foo/bar/');            // null
Uize.Url.toRelative ('http://www.foo.com/','foo/bar/');             // null
Uize.Url.toRelative ('http://www.foo.com/','../foo/bar/');          // null
Uize.Url.toRelative ('http://www.foo.com/','http://www.bar.com/');  // 'http://www.bar.com/'


// base URL is root-relative

Uize.Url.toRelative ('/foo/bar/','foo/bar/');                       // null
Uize.Url.toRelative ('/foo/bar/','../foo/bar/');                    // null
Uize.Url.toRelative ('/foo/bar/','http://www.bar.com/');            // 'http://www.bar.com/'


// base URL is forward-relative

Uize.Url.toRelative ('foo/bar/','/foo/bar/');                       // null
Uize.Url.toRelative ('foo/bar/','../foo/bar/');                     // null
Uize.Url.toRelative ('foo/bar/','http://www.bar.com/');             // 'http://www.bar.com/'


// base URL is back-relative

Uize.Url.toRelative ('../foo/bar/','/foo/bar/');                    // null
Uize.Url.toRelative ('../foo/bar/','foo/bar/');                     // null
Uize.Url.toRelative ('../foo/bar/','../../foo/bar/');               // null
Uize.Url.toRelative ('../foo/bar/','http://www.bar.com/');          // 'http://www.bar.com/'

2.9.2.1. When the URL to Relativize is Absolute

When the base URL contains a file part, that file part will be ignored and discarded when creating the relative URL.

This is a convenient behavior if you are using this method in a Web page to create relative URLs from absolute URLs, and where the created URLs should be relative to the current document's URL. In such cases, the value of the window.location.href property can simply be passed to the Uize.Url.toRelative method as the value of the baseUrlSTR parameter.

EXAMPLE

var relativeUrl = Uize.Url.toRelative (
  'http://www.somedomain.com/foo/bar/file.html',
  'http://www.somedomain.com/foo/hello/world.html'
);

RESULT

'../hello/world.html'

Because of this behavior, for any base URL that ends in a folder, the URL must also end with a "/" (slash) character, otherwise the last folder will be assumed to be a file part and will be discarded when creating the relative URL. The Uize.Url.toRelative method cannot tell the difference between a folder name and a filename that has no file extension (filename's are not required to have an extension indicating file type, after all, even though they often may).