UIZE JavaScript Framework

2013 NEWS 2013-03-25 - New Uize.Url.toRelative Method

The new Uize.Url.toRelative static method, implemented in the Uize.Url module, lets you create a relative URL from a base URL to a destination URL.

SYNTAX

relativeUrlSTR = Uize.Url.toRelative (baseUrlSTR,urlToRelativizeSTR);

EXAMPLE

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

RESULT

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

1. When a Relative URL Can Be Created

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

when both URLs have the same back-relative prefix
when both URLs are root-relative
when both URLs are forward-relative
when both URLs have the same domain

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

When both the base URL and the URL to relativize start with exactly the same back-relative prefix (i.e. "/", "../", "../../", etc.), then a relative URL can be created.

Even though both URLs may be relative URLs, a relative URL can still be created between the base URL and the URL to relativize. This is because the URLs having the identical back-relative prefix means that they essentially share a common base, even though we don't know what it is.

EXAMPLE

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

In the above example, both the base URL and the URL to relativize have a back-relative prefix that jumps back two folder levels.

RESULT

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

1.2. When Both URLs are Root-relative

When both the base URL and the URL to relativize are root-relative (i.e. start with a "/"), then a relative URL can be created.

EXAMPLE

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

RESULT

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

1.3. When Both URLs are Forward-relative

When both the base URL and the URL to relativize are forward-relative, then a relative URL can be created.

EXAMPLE

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

RESULT

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

1.4. When Both URLs Have the Same Domain

When both the base URL and the URL to relativize have the same domain, then a relative URL can be created.

EXAMPLE

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

RESULT

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

2. When a Relative URL Cannot Be Created

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

the base URL is absolute (i.e. has a domain) and the URL to relativize is either root-relative, forward-relative, back-relative, or has a domain that doesn't match that of the base URL
the base URL is root-relative and the URL to relativize is either forward-relative, back-relative, or is absolute (i.e. has a domain)
the base URL is forward-relative and the URL to relativize is either root-relative, back-relative, or is absolute (i.e. has a domain)
the base URL is back-relative and the URL to relativize is either root-relative, forward-relative, or is absolute (i.e. has a domain), or is also back-relative but has a differing amount of back folder jumps than the base URL

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.1. When the URL to Relativize is Absolute

When a relative URL cannot be created and the URL to relativize is absolute (i.e. has a domain), then the URL to relativize will be returned rather than the value null.

The rationale behind this behavior is that an absolute URL, when resolved against another URL, will always produce that absolute URL. So, returning an absolute URL that can work against the base URL is better than returning null.

3. When the Base URL Contains a File Part

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

4. Unit Tested and Documented

The new Uize.Url.toRelative method is comprehensively unit tested and documented.