diff options
Diffstat (limited to 'thirdparty/URI.js/docs.html')
| -rw-r--r-- | thirdparty/URI.js/docs.html | 1399 |
1 files changed, 0 insertions, 1399 deletions
diff --git a/thirdparty/URI.js/docs.html b/thirdparty/URI.js/docs.html deleted file mode 100644 index 31d58ed5d..000000000 --- a/thirdparty/URI.js/docs.html +++ /dev/null @@ -1,1399 +0,0 @@ -<!DOCTYPE html> -<html lang="en"> -<head> - <meta charset="utf-8" /> - <meta http-equiv="content-type" content="text/html; charset=utf-8" /> - <title>URI.js - API Documentation</title> - <meta name="description" content="URI.js is a Javascript library for working with URLs." /> - - <script src="jquery-1.9.1.min.js" type="text/javascript"></script> - <script src="prettify/prettify.js" type="text/javascript"></script> - <script src="screen.js" type="text/javascript"></script> - <link href="screen.css" rel="stylesheet" type="text/css" /> - <link href="prettify/prettify.sunburst.css" rel="stylesheet" type="text/css" /> - <script src="src/URI.min.js" type="text/javascript"></script> - <script type="text/javascript"> - - var _gaq = _gaq || []; - _gaq.push(['_setAccount', 'UA-8922143-3']); - _gaq.push(['_trackPageview']); - - (function() { - var ga = document.createElement('script'); ga.type = 'text/javascript'; ga.async = true; - ga.src = ('https:' == document.location.protocol ? 'https://ssl' : 'http://www') + '.google-analytics.com/ga.js'; - var s = document.getElementsByTagName('script')[0]; s.parentNode.insertBefore(ga, s); - })(); - - </script> -</head> -<body> - <a id="github-forkme" href="https://github.com/medialize/URI.js"><img src="http://s3.amazonaws.com/github/ribbons/forkme_right_darkblue_121621.png" alt="Fork me on GitHub" /></a> - <div id="container"> - <h1><a href="https://github.com/medialize/URI.js">URI.js</a></h1> - - <ul class="menu"> - <li><a href="/URI.js/">Intro</a></li> - <li><a href="/URI.js/about-uris.html">Understanding URIs</a></li> - <li class="active"><a href="docs.html">API-Documentation</a></li> - <li><a href="jquery-uri-plugin.html">jQuery Plugin</a></li> - <li><a href="uri-template.html">URI Template</a></li> - <li><a href="build.html">Build</a></li> - <li><a href="http://rodneyrehm.de/en/">Author</a></li> - </ul> - - <ul class="toc"> - <li> - <a href="#constructor">Constructing an URI</a> - <ul> - <li><a href="#clone">cloning an URI instance</a></li> - <li><a href="#href">href()</a></li> - <li><a href="#toString">toString(), valueOf()</a></li> - </ul> - </li> - <li> - Working with URI parts - <ul> - <li><a href="#accessors-protocol">protocol(), scheme()</a></li> - <li><a href="#accessors-username">username()</a></li> - <li><a href="#accessors-password">password()</a></li> - <li><a href="#accessors-hostname">hostname()</a></li> - <li><a href="#accessors-port">port()</a></li> - <li><a href="#accessors-host">host()</a></li> - <li><a href="#accessors-userinfo">userinfo()</a></li> - <li><a href="#accessors-authority">authority()</a></li> - <li><a href="#accessors-origin">origin()</a></li> - <li><a href="#accessors-subdomain">subdomain()</a></li> - <li><a href="#accessors-domain">domain()</a></li> - <li><a href="#accessors-tld">tld()</a></li> - - <li><a href="#accessors-pathname">pathname(), path()</a></li> - <li><a href="#accessors-directory">directory()</a></li> - <li><a href="#accessors-filename">filename()</a></li> - <li><a href="#accessors-suffix">suffix()</a></li> - <li><a href="#accessors-segment">segment()</a></li> - <li><a href="#accessors-segmentCoded">segmentCoded()</a></li> - - <li><a href="#accessors-search">search(), query()</a></li> - <li><a href="#accessors-hash">hash(), fragment()</a></li> - <li><a href="#accessors-resource">resource()</a></li> - <li><a href="#is">determine URL types</a></li> - </ul> - </li> - <li> - Working with the query string - <ul> - <li><a href="#accessors-search">search(), query()</a></li> - <li><a href="#search-set">setSearch(), setQuery()</a></li> - <li><a href="#search-add">addSearch(), addQuery()</a></li> - <li><a href="#search-remove">removeSearch(), removeQuery()</a></li> - <li><a href="#search-has">hasSearch(), hasQuery()</a></li> - </ul> - </li> - <li> - <a href="#fragment-abuse">Working with the Fragment (Hash)</a> - <ul> - <li><a href="#fragment-abuse-query">Data in Fragments (Hash)</a></li> - <li><a href="#fragment-abuse-uri">URLs in Fragments (Hash)</a></li> - </ul> - </li> - <li> - Normalizing URLs - <ul> - <li><a href="#normalize">normalize()</a></li> - <li><a href="#normalize-protocol">normalizeProtocol()</a></li> - <li><a href="#normalize-host">normalizeHostname()</a></li> - <li><a href="#normalize-port">normalizePort()</a></li> - <li><a href="#normalize-path">normalizePathname(), normalizePath()</a></li> - <li><a href="#normalize-search">normalizeSearch(), normalizeQuery()</a></li> - <li><a href="#normalize-hash">normalizeHash(), normalizeFragment()</a></li> - </ul> - </li> - <li> - Charsets / Encodings - <ul> - <li><a href="#iso8859">iso8859()</a></li> - <li><a href="#unicode">unicode()</a></li> - </ul> - </li> - <li><a href="#readable">readable()</a></li> - <li> - Relative and Absolute URLs - <ul> - <li><a href="#relativeto">relativeTo()</a></li> - <li><a href="#absoluteto">absoluteTo()</a></li> - <li><a href="#static-joinPaths">URI.URI.joinPaths()</a></li> - </ul> - </li> - <li> - Comparing URLs - <ul> - <li><a href="#equals">equals()</a></li> - </ul> - </li> - <li> - Parsing URLs - <ul> - <li><a href="#static-parse">URI.parse()</a></li> - <li><a href="#static-parseAuthority">URI.parseAuthority()</a></li> - <li><a href="#static-parseUserinfo">URI.parseUserinfo()</a></li> - <li><a href="#static-parseHost">URI.parseHost()</a></li> - <li><a href="#static-parseQuery">URI.parseQuery()</a></li> - </ul> - </li> - <li> - Serializing URLs - <ul> - <li><a href="#static-build">URI.build()</a></li> - <li><a href="#static-buildAuthority">URI.buildAuthority()</a></li> - <li><a href="#static-buildUserinfo">URI.buildUserinfo()</a></li> - <li><a href="#static-buildHost">URI.buildHost()</a></li> - <li><a href="#static-buildQuery">URI.buildQuery()</a></li> - </ul> - </li> - <li> - Encoding and Decoding URLs - <ul> - <li><a href="#static-encode">URI.encode()</a></li> - <li><a href="#static-decode">URI.decode()</a></li> - - <li><a href="#static-encodeReserved">URI.encodeReserved()</a></li> - - <li><a href="#static-encodeQuery">URI.encodeQuery()</a></li> - <li><a href="#static-decodeQuery">URI.decodeQuery()</a></li> - </ul> - </li> - <li> - Static Helper Functions - <ul> - <li><a href="#static-noConflict">URI.noConflict()</a></li> - - <li><a href="#static-addQuery">URI.addQuery()</a></li> - <li><a href="#static-removeQuery">URI.removeQuery()</a></li> - <li><a href="#static-commonPath">URI.commonPath()</a></li> - - <li><a href="#static-joinPaths">URI.joinPath()</a></li> - - <li><a href="#static-withinString">URI.withinString()</a></li> - - <li><a href="#static-iso8859">URI.iso8859()</a></li> - <li><a href="#static-unicode">URI.unicode()</a></li> - - <li><a href="#static-expand">URI.expand()</a></li> - </ul> - </li> - </ul> - - <h2 id="api-methods">URI.js API</h2> - - <h3 id="constructor">URI Constructor</h3> - <pre class="prettyprint lang-js">var uri = new URI(); // same as new URI(location.href) -// string -var uri = new URI("http://example.org"); - -// URI object for cloning -var uri = new URI(new URI("http://example.org")); - -// URI parts object -var uri = new URI({ - protocol: "http", - hostname: "example.org" -}); - -// without new keyword -var uri = URI("http://example.org"); - -// resolving right in the constructor -var uri = URI("../foobar.html", "http://example.org/hello/world.html"); -// which is exactly the same as -URI("../foobar.html").absoluteTo("http://example.org/hello/world.html"); -// but specified in <a href="http://dvcs.w3.org/hg/url/raw-file/tip/Overview.html#constructor">URL constructor</a></pre> - - <p>The following parts can be specified in an object:</p> - <pre class="prettyprint lang-js">var uri = new URI({ - protocol: "http", // no trailing : - username: "user", - password: "pass", - hostname: "example.org", - port: "80", // string, please - // "path", not "pathname", sorry - path: "/foo/bar.html", - // "query", not "search", sorry - query: "foo=bar&bar=baz", // no leading ? - // "fragment", not "hash", sorry - fragment: "frag" // no leading # -});</pre> - - <p>using only components of URIs:</p> - <pre class="prettyprint lang-js">// Look ma! I'm only working the pathname -var uri = new URI("some/directory/file.html"); - -// Look ma! I'm only working the query string -var uri = new URI("?foo=bar"); - -// Look ma! I'm only working the fragment / hash -var uri = new URI("#call-me-hash"); - -// and any combination of the above…</pre> - - <p>using DOM elements:</p> - <pre class="prettyprint lang-js">var element = document.createElement('a'); -element.href = 'http://example.org'; -var uri = new URI(element); -// uri.domain() === 'example.org';</pre> -<pre class="prettyprint lang-html">The following DOM elements can be parsed: - -<a href="..."> -<blockquote cite="..."> -<link href="..."> -<base href="..."> -<script src="..."> -<form action="..."> -<input type="image" src="..."> -<img src="..."> -<area href="..."> -<iframe src="..."> -<embed src="..."> -<source src="..."> -<track src="..."> - - -any other element yields URI("") -</pre> - - <h3 id="clone">cloning URIs</h3> - <p>Get a copy of the current URI instance</p> - <pre class="prettyprint lang-js">var uri = new URI("http://example.org"); -var uri2 = uri.clone(); - -uri2.tld("com"); -uri == "http://example.org/"; -uri2 == "http://example.com/";</pre> - - <h3 id="href">href()</h3> - <p>get and set the entire URI</p> - <pre class="prettyprint lang-js">var uri = URI("http://example.com"); -uri.href() === "http://example.com/"; - -uri.href("ftp://google.org"); -uri.toString() === "ftp://google.org/"</pre> - - <h3 id="toString">toString(), valueOf()</h3> - <p>serialize the URI to string. <code>valueOf()</code> is an alias to <code>toString()</code>, as string is the base primitive.</p> - <pre class="prettyprint lang-js">var uri = URI("http://example.com"); -var s = uri.toString(); -typeof s === "string"; -s === "http://example.com/";</pre> - - - <h3 id="accessors-protocol">protocol(), scheme()</h3> - <p>.scheme() is an alias of .protocol()</p> - <pre class="prettyprint lang-js">var uri = new URI("http://example.org/foo/hello.html"); -// get protocol -uri.protocol(); // returns string "http" -// set protocol -uri.protocol("ftp"); // returns the URI instance for chaining - -// relative scheme -uri.protocol(""); -uri.toString() === "//example.org/foo/hello.html";</pre> - <p class="note">Throws a <code>TypeError</code> on illegal input, that is anything but <code>[a-z0-9.+-]</code> and <code>[empty string]</code> and <code>null</code></p> - - <h3 id="accessors-username">username()</h3> - <pre class="prettyprint lang-js">var uri = new URI("http://user:pass@example.org/foo/hello.html"); -// get username -uri.username(); // returns string "user" -// set username -uri.username("user"); // returns the URI instance for chaining</pre> - - <h3 id="accessors-password">password()</h3> - <pre class="prettyprint lang-js">var uri = new URI("http://user:pass@example.org/foo/hello.html"); -// get password -uri.password(); // returns string "pass" -// set password -uri.password("user"); // returns the URI instance for chaining</pre> - - <h3 id="accessors-hostname">hostname()</h3> - <pre class="prettyprint lang-js">var uri = new URI("http://example.org/foo/hello.html"); -// get hostname -uri.hostname(); // returns string -// set hostname -uri.hostname("example.org"); // returns the URI instance for chaining</pre> - <p class="note"><a href="#accessors-hostname">.hostname()</a> returns the actual hostname, whereas <a href="#accessors-host">.host()</a> returns the hostname including the port</p> - - <h3 id="accessors-port">port()</h3> - <pre class="prettyprint lang-js">var uri = new URI("http://example.org:8080/foo/hello.html"); -// get port -uri.port(); // returns string "8080" -// set port -uri.port("80"); // returns the URI instance for chaining</pre> - <p class="note">although the port may be considered an integer, within URI it is a string.</p> - <p class="note">Throws a <code>TypeError</code> on illegal input</p> - - <h3 id="accessors-host">host()</h3> - <pre class="prettyprint lang-js">var uri = new URI("http://example.org:80/foo/hello.html"); -// get host -uri.host(); // returns string "example.org:80" -// set host -uri.host("example.org:80"); // returns the URI instance for chaining</pre> - <p class="note"><a href="#accessors-hostname">.hostname()</a> returns the actual hostname, whereas <a href="#accessors-host">.host()</a> returns the hostname including the port</p> - <p class="note">Throws a <code>TypeError</code> if <code>path</code> is part of the input</p> - - <h3 id="accessors-userinfo">userinfo()</h3> - <p>Userinfo is comprised of username and password</p> - <pre class="prettyprint lang-js">var uri = new URI("http://user:pass@example.org:88/foo/hello.html"); -// get userinfo -uri.userinfo(); // returns string "user:pass" -// set userinfo -uri.userinfo("user:pass"); // returns the URI instance for chaining</pre> - - <h3 id="accessors-authority">authority()</h3> - <p>Authority is comprised of username, password, hostname and port</p> - <pre class="prettyprint lang-js">var uri = new URI("http://user:pass@example.org:88/foo/hello.html"); -// get authority -uri.authority(); // returns string "user:pass@example.org:88" -// set authority -uri.authority("user:pass@example.org:80"); // returns the URI instance for chaining</pre> - <p class="note">.authority() will reset any of username, password and port if they're not specified.</p> - <p class="note">Throws a <code>TypeError</code> if <code>path</code> is part of the input</p> - - <h3 id="accessors-origin">origin()</h3> - <p>Origin is comprised of the scheme and authority.</p> - <pre class="prettyprint lang-js">var uri = new URI("http://example.com/foo.html?q=hello"); -// get origin -uri.origin(); // returns string "http://example.com" -// set origin -uri.origin('https://other.org'); // returns URI instance for chaining - -// the URI will now have the string representation of: -// "https://other.org/foo.html?q=hello"</pre> - <p class="note">.origin() will reset the entire authority, including username, password and port if not specified in the new origin.</p> - <p class="note">.origin() will be empty if there is no authority.</p> - <p class="note">.origin() will be the same as .authority() (e.g. "example.org") if there is no scheme available.</p> - - <h3 id="accessors-domain">domain()</h3> - <p>.domain() is a convenience method that returns <code>example.org</code> from the hostname <code>www.example.org</code>.</p> - <pre class="prettyprint lang-js">var uri = new URI("http://example.org/foo/hello.html"); -// get domain -uri.domain(); // returns string "example.org" -// set domain -uri.domain("otherdomain.com"); // returns the URI instance for chaining - -// Second Level Domain (SLD) Support (as of URI.js 1.5.0) -uri = new URI("http://example.co.uk/foo/hello.html"); -uri.domain(); // return string "example.co.uk" -uri.domain(true); // return string "co.uk"</pre> - <p class="note"><code>.domain()</code> will throw an error if you pass it an empty string.</p> - <p class="note">Throws a <code>TypeError</code> on illegal input</p> - - <h3 id="accessors-subdomain">subdomain()</h3> - <p>.subdomain() is a convenience method that returns <code>www</code> from the hostname <code>www.example.org</code>.</p> - <pre class="prettyprint lang-js">var uri = new URI("http://www.example.org/foo/hello.html"); -// get subdomain -uri.subdomain(); // returns string "www" -// set subdomain -uri.subdomain("other.subdomain"); // returns the URI instance for chaining</pre> - <p class="note">Throws a <code>TypeError</code> on illegal input</p> - - <h3 id="accessors-tld">tld()</h3> - <p>.tld() is a convenience method that returns <code>org</code> from the hostname <code>www.example.org</code>.</p> - <pre class="prettyprint lang-js">var uri = new URI("http://example.org/foo/hello.html"); -// get tld -uri.tld(); // returns string "org" -// set tld -uri.tld("com"); // returns the URI instance for chaining - -// Second Level Domain (SLD) Support (as of URI.js 1.5.0) -uri = new URI("http://example.co.uk/foo/hello.html"); -uri.tld(); // return string "co.uk" -uri.tld(true); // return string "uk"</pre> - <p class="note">Throws an <code>Error</code> if you pass it an empty string or use it on an IP-host.</p> - - <h3 id="accessors-pathname">pathname(), path()</h3> - <p>.path() is an alias of .pathname()</p> - <pre class="prettyprint lang-js">var uri = new URI("http://example.org/foo/hello.html"); -// get pathname -uri.pathname(); // returns string "/foo/hello.html" -// set pathname -uri.pathname("/foo/hello.html"); // returns the URI instance for chaining - -// will encode for you -uri.pathname("/hello world/"); -uri.pathname() === "/hello%20world/"; -// will decode for you -uri.pathname(true) === "/hello world/"; - -// will return empty string for empty paths, but: -URI("").path() === ""; -URI("/").path() === "/"; -URI("http://example.org").path() === "/"; -</pre> - - <h3 id="accessors-directory">directory()</h3> - <p>.directory() is an convenience method for mutating the directory part of a path</p> - <pre class="prettyprint lang-js">var uri = new URI("http://example.org/foo/hello.html"); -// get directory -uri.directory(); // returns string "/foo" (no trailing slash) -// set directory -uri.directory("/bar"); // returns the URI instance for chaining -// uri == "http://example.org/bar/hello.html" - -// will encode for you -uri.directory("/hello world/"); -uri.directory() === "/hello%20world"; -// will decode for you -uri.directory(true) === "/hello world"; - -uri.href("http://example.com/foo").directory() -// -&t; "/" -uri.href("/foo").directory() -// -&t; "/" -uri.href("foo").directory() -// -&t; ""</pre> - - <h3 id="accessors-filename">filename()</h3> - <p>.filename() is an convenience method for mutating the filename part of a path</p> - <pre class="prettyprint lang-js">var uri = new URI("http://example.org/foo/hello.html"); -// get filename -uri.filename(); // returns string "hello.html" (no leading slash) -// set filename -uri.filename("world.xml"); // returns the URI instance for chaining -// uri == "http://example.org/foo/world.xml" - -// will encode for you -uri.filename("hello world.html"); -uri.filename() === "hello%20world.html"; -// will decode for you -uri.filename(true) === "hello world.html";</pre> - <p class="note">If you pass <code>../file.html</code>, the directory will be changed accordingly</p> - - <h3 id="accessors-suffix">suffix()</h3> - <p>.suffix() is an convenience method for mutating the filename part of a path</p> - <pre class="prettyprint lang-js">var uri = new URI("http://example.org/foo/hello.html"); -// get suffix -uri.suffix(); // returns string "html" (no leading dot) -// set suffix -uri.suffix("xml"); // returns the URI instance for chaining -// uri == "http://example.org/bar/world.xml" - -// will encode for you -uri.suffix("würgh"); -uri.suffix() === "w%C3%BCrgh"; -// will decode for you -uri.suffix(true) === "würgh";</pre> - - <h3 id="accessors-segment">segment()</h3> - <p>.segment() allows convenient access to directory levels / URN segments within the path. See <a href="#accessors-segmentCoded">.segmentCoded()</a> for an interface that transparently encodes and decodes path segments.</p> - <pre class="prettyprint lang-js">var uri = new URI("http://example.org/foo/hello.html"); -// get segments -uri.segment(); // returns array ["foo", "hello.html"] -// set segments -uri.segment(["foo", "bar", "foobar.html"]); // -> http://example.org/foo/bar/foobar.html - -// get specific level -uri.segment(0); // returns "foo" -uri.segment(1); // returns "bar" -uri.segment(-1); // returns "foobar.html" -// set specific level -uri.segment(0, "bar"); // -> http://example.org/bar/bar/foobar.html -// remove specific level -uri.segment(0, ""); // -> http://example.org/bar/foobar.html - -// append level -uri.segment("appendthis"); // -> http://example.org/bar/foobar.html/appendthis</pre> - - <h3 id="accessors-segmentCoded">segmentCoded()</h3> - <p>.segmentCoded() works the same way <a href="#accessors-segment">.segment()</a> does, with the difference of transparently encoding and decoding values.</p> - <pre class="prettyprint lang-js">var uri = new URI("http://example.org/foo/hello%20world.html"); -// get segments -uri.segmentCoded(); // returns array ["foo", "hello world.html"] -// set segments -uri.segmentCoded(["foo", "bar", "foo bar.html"]); // -> http://example.org/foo/bar/foo%20bar.html - -// get specific level -uri.segmentCoded(0); // returns "foo" -uri.segmentCoded(1); // returns "bar" -uri.segmentCoded(-1); // returns "foo bar.html" -// set specific level -uri.segmentCoded(0, "bar bam"); // -> http://example.org/bar%20bam/bar/foobar.html -// remove specific level -uri.segmentCoded(0, ""); // -> http://example.org/bar/foobar.html - -// append level -uri.segmentCoded("append this"); // -> http://example.org/bar/foobar.html/append%20this</pre> - - - <h3 id="accessors-search">search(), query()</h3> - <pre class="prettyprint lang-js">var uri = new URI("http://example.org/foo/hello.html?foo=bar&bar=baz"); -// get search -uri.search(); // returns string "?foo=bar&bar=baz" (leading ?) -// get query -uri.query(); // returns string "foo=bar&bar=baz" (no leading ?) - -// .query() and .search() behave the same for the following: - -// set search -uri.search("?foo=bar&bar=baz"); // returns the URI instance for chaining -uri.search("foo=bar&bar=baz"); // returns the URI instance for chaining -// uri == "http://example.org/bar/world.html?foo=bar&bar=baz" - -// remove query -uri.search(""); // returns the URI instance for chaining -// uri == "http://example.org/bar/world.html" - -// get data map: -uri.search(true); // returns { foo: "bar", hello : ["world", "mars"] } - -// set data map: -uri.search({ foo: "bar", hello : ["world", "mars"] }); -// uri == "http://example.org/bar/world.html?foo=bar&hello=world&hello=mars" - -// overwrite data through callback -uri.search(function(data) { - return { hello : "world" }; -}); -// uri == "http://example.org/bar/world.html?hello=world" - -// augment data through callback -uri.search(function(data) { - data.foo = "bar"; -}); -// uri == "http://example.org/bar/world.html?hello=world&foo=bar" - -// CAUTION: beware of arrays, the following are not quite the same -// If you're dealing with PHP, you probably want the latter… -uri.search("?foo=bar&bar=baz"); -uri.search("?foo=bar[]&bar[]=baz");</pre> - <p>Note that names and values passed in an object are encoded automatically. - The object, resulting from parsing the query string, contains decoded values</p> - <p>Hint: If you're using jQuery, have a look at their <a href="http://api.jquery.com/serialize/">.serialize()</a> function.</p> - - <h3 id="accessors-hash">hash(), fragment()</h3> - <pre class="prettyprint lang-js">var uri = new URI("http://example.org/foo/hello.html#world"); -// get hash -uri.hash(); // returns string "#world" (leading #) -// get fragment -uri.fragment(); // returns string "world" (no leading #) - -// remove fragment -uri.fragment(""); // returns the URI instance for chaining -// uri == "http://example.org/bar/world.html" - -// .hash() and .fragment() behave the same for the following: - -// set hash -uri.hash("#mars"); // returns the URI instance for chaining -uri.hash("mars"); // returns the URI instance for chaining -// uri == "http://example.org/bar/world.xml#mars"</pre> - - <h3 id="accessors-resource">resource()</h3> - <p>Resource is comprised of path, query and fragment</p> - <pre class="prettyprint lang-js">var uri = new URI("http://example.org/foo/hello.html?query=string#hash"); -// get resource -uri.resource(); // returns string "/foo/hello.html?query=string#hash" -// set resource -uri.resource("/mars.txt?query=foo#other"); // returns the URI instance for chaining</pre> - <p class="note"><code>.resource()</code> will reset any of path, query and fragment if they're not specified.</p> - - <h3 id="is">is()</h3> - <p>.is() tells what a URL is. It responds with a boolean and can be asked the following questions:</p> - <dl> - <dt><code>relative</code></dt><dd><code>true</code> if URL doesn't have a hostname</dd> - <dt><code>absolute</code></dt><dd><code>true</code> if URL has a hostname</dd> - <dt><code>urn</code></dt><dd><code>true</code> if URI looks like a URN</dd> - <dt><code>url</code></dt><dd><code>true</code> if URI is a URL</dd> - <dt><code>domain</code>, <code>name</code></dt><dd><code>true</code> if hostname is not an IP</dd> - <dt><code>sld</code></dt><dd><code>true</code> if hostname is a second level domain (i.e. "example.co.uk")</dd> - <dt><code>idn</code></dt><dd><code>true</code> if hostname contains non-alphanumeric characters and is not an IP</dd> - <dt><code>punycode</code></dt><dd><code>true</code> if hostname contains <code>xn--</code></dd> - <dt><code>ip</code></dt><dd><code>true</code> if hostname is IPv4 or IPv6</dd> - <dt><code>ip4</code>, <code>ipv4</code>, <code>inet4</code></dt><dd><code>true</code> if hostname is IPv4</dd> - <dt><code>ip6</code>, <code>ipv6</code>, <code>inet6</code></dt><dd><code>true</code> if hostname is IPv6</dd> - </dl> - <pre class="prettyprint lang-js">var uri = new URI("http://example.org/"); -uri.is("relative") === false; -uri.is("absolute") === true; -uri.is("urn") === false; -uri.is("url") === true; -uri.is("name") === true; -uri.is("sld") === false; -uri.is("punycode") === false; -uri.is("IDN") === false; // case doesn't matter -uri.is("idn") === false; // case doesn't matter -uri.is("ip") === false; - -var uri = new URI("http://123.123.123.123/"); -uri.is("relative") === false; -uri.is("absolute") === true; -uri.is("urn") === false; -uri.is("url") === true; -uri.is("name") === false; -uri.is("sld") === false; -uri.is("IP") === true; -uri.is("IPv4") === true; -uri.is("IPv6") === false; - -var uri = new URI("http://fe80:0000:0000:0000:0204:61ff:fe9d:f156/"); -uri.is("IP") === true; -uri.is("IPv4") === false; -uri.is("IPv6") === true; - -var uri = new URI("/hello/world.html"); -uri.is("relative") === true; -uri.is("absolute") === false; -uri.is("urn") === false; -uri.is("url") === true; -uri.is("name") === false; -uri.is("IP") === false; - -var uri = new URI("http://example.co.uk/"); -uri.is("name") === true; -uri.is("sld") === true; - -var uri = new URI("mailto:mail@example.org"); -uri.is("relative") === false; -uri.is("absolute") === false; -uri.is("urn") === true; -uri.is("url") === false; -uri.is("name") === false; -uri.is("sld") === false; -uri.is("punycode") === false; -uri.is("idn") === false; -uri.is("ip") === false;</pre> - - - <h2 id="querystrings">Working with the query string</h2> - - <h3 id="search-set">setSearch(), setQuery()</h3> - <p>.setQuery() is an alias of .setSearch()</p> - <pre class="prettyprint lang-js">var uri = new URI("?hello=world"); -uri.setSearch("hello", "mars"); // returns the URI instance for chaining -// uri == "?hello=mars" - -uri.setSearch({ foo: "bar", goodbye : ["world", "mars"] }); -// uri == "?hello=mars&foo=bar&goodbye=world&goodbye=mars" - -uri.setSearch("goodbye", "sun"); -// uri == "?hello=mars&foo=bar&goodbye=sun" - -// CAUTION: beware of arrays, the following are not quite the same -// If you're dealing with PHP, you probably want the latter… -uri.setSearch("foo", ["bar", "baz"]); -uri.setSearch("foo[]", ["bar", "baz"]);</pre> - <p>Note that names and values passed in are encoded automatically.</p> - - <h3 id="search-add">addSearch(), addQuery()</h3> - <p>.addQuery() is an alias of .addSearch()</p> - <pre class="prettyprint lang-js">var uri = new URI("?hello=world"); -uri.addSearch("hello", "mars"); // returns the URI instance for chaining -// uri == "?hello=world&hello=mars" - -uri.addSearch({ foo: "bar", goodbye : ["world", "mars"] }); -// uri == "?hello=world&hello=mars&foo=bar&goodbye=world&goodbye=mars" - -uri.addSearch("no-value"); -// uri == "?hello=world&hello=mars&foo=bar&goodbye=world&goodbye=mars&no-value" - -// CAUTION: beware of arrays, the following are not quite the same -// If you're dealing with PHP, you probably want the latter… -uri.addSearch("foo", ["bar", "baz"]); -uri.addSearch("foo[]", ["bar", "baz"]);</pre> - <p>Note that names and values passed in are encoded automatically.</p> - - <h3 id="search-remove">removeSearch(), removeQuery()</h3> - <p>.removeQuery() is an alias of .removeSearch()</p> - <pre class="prettyprint lang-js">var uri = new URI("?hello=world&hello=mars&foo=bar"); -// remove an attribute -uri.removeSearch("hello"); // returns the URI instance for chaining -// uri == "?foo=bar" - -// remove an attribute with value filter -uri.search("?hello=world&hello=mars&foo=bar"); -uri.removeSearch("hello", "world"); // returns the URI instance for chaining -// uri == "?hello=mars&foo=bar" - -// remove multiple values -uri.search("?hello=world&hello=mars&foo=bar&mine=true"); -uri.removeSearch(["hello", "foo"]); -// uri == "?mine=true" - -// remove multiple values with value filter -uri.search("?hello=world&hello=mars&foo=bar&mine=true&a=1&a=2&a=3"); -uri.removeSearch({hello: "world", foo: undefined, a: ["1", "3"]}); -// uri == "?hello=mars&mine=true&a=2" - -// remove multiple values with RegExp -uri.search("?hello=world&hello=mars&foo=bar&mine=true&a=1&a=2&a=3"); -uri.removeSearch(/^hello/); -// uri == "?foo=bar&mine=true&a=1&a=2&a=3" - -// filter values with RegExp -uri.search("?foo=bar&foo=baz&foo=bam&obj=bam&bar=bar&bar=baz&bar=bam"); -uri.removeSearch('foo', /[rz]$/); -// uri == "?foo=bam&obj=bam&bar=bar&bar=baz&bar=bam"</pre> - - <h3 id="search-has">hasSearch(), hasQuery()</h3> - <p>.hasQuery() is an alias of .hasSearch(). The method checks the existence and value of a given parameter within the query string.</p> - <pre class="prettyprint lang-js">var uri = URI("?string=bar&list=one&list=two&number=123&null&empty="); - -// check if parameter exists (regardless of value) -uri.hasQuery("string") === true; -uri.hasQuery("nono") === false; - -// check if parameter has a truthy / falsy value -uri.hasQuery("string", true) === true; -uri.hasQuery("string", false) === false; -uri.hasQuery("empty", true) === false; -uri.hasQuery("empty", false) === true; - -// check if parameter has a given value -uri.hasQuery("string", "bar") === true; -uri.hasQuery("number", 123) === true; - -// check if value is contained in parameter list -uri.hasQuery("list", "two", true) === true; -uri.hasQuery("list", ["two"], true) === true; -uri.hasQuery("list", "three", true) === false; -uri.hasQuery("list", ["two", "three"], true) === false; -uri.hasQuery("list", /ne$/, true) === true; - -// check if parameter matches an expression -uri.hasQuery("string", /ar$/) === true; - -// check if parameter name matches an expression -uri.hasQuery(/^str/) === true; -// check if parameter name matches an expression and value exists -uri.hasQuery(/^li/, "two") === true; - -// check by comparison function -uri.hasQuery("string", function(value, name, data) { - // value === "bar"; - // name === "string"; - // data === uri.query(true); - return true; -}) === true;</pre> - - <h2 id="fragment-abuse">Working with the Fragment (Hash)</h2> - - <p> - There are virtually no limits to what you might do with fragments (hash). - Every system has their own bag of tricks. - As a result URI.js cannot offer any of the following tools right out of the box. - The most common <em>abuse of fragments</em> are storing URLs or query string like data. - </p> - - <p> - Usually a prefix is used to identify data with special meaning. This prefix can be pretty much what you want. - For URIs it's usually <code>!</code> and for query-like data it often is <code>?</code>. - But they don't have to, which is why you can define a global default: <code>URI.fragmentPrefix = "$";</code> - </p> - - <h3 id="fragment-abuse-query">Query String Fragments</h3> - <p>The file <a href="https://github.com/medialize/URI.js/blob/gh-pages/src/URI.fragmentQuery.js">src/URI.fragmentQuery.js</a> is a "plugin" that allows you to store data in hashes in the same manner the .query() functions provide.</p> - - <pre class="prettyprint lang-js">var uri = new URI("#?hello=world"); -uri.addFragment("hello", "mars"); // returns the URI instance for chaining -// uri == "#?hello=world&hello=mars" - -// to change the fragment prefix on an instance level: -uri.fragmentPrefix("!"); - -// to change the fragment prefix on a global level: -URI.fragmentPrefix = "!";</pre> - - - <h3 id="fragment-abuse-uri">URL Fragments</h3> - <p>The file <a href="https://github.com/medialize/URI.js/blob/gh-pages/src/URI.fragmentURI.js">src/URI.fragmentURI.js</a> is a "plugin" that allows you to store URLs in hashes.</p> - - <pre class="prettyprint lang-js">var uri = URI("http://example.org/#!/foo/bar/baz.html"); -var furi = uri.fragment(true); - -// manipulating the fragment URI -furi.pathname() === "/foo/bar/baz.html"; -furi.pathname("/hello.html"); - -// has direct effect on the actual URI -uri.toString() === "http://example.org/#!/hello.html" - -// to change the fragment prefix on an instance level: -uri.fragmentPrefix("?"); - -// to change the fragment prefix on a global level: -URI.fragmentPrefix = "?";</pre> - - <h2 id="normalizing">Normalizing URLs</h2> - - <h3 id="normalize">normalize()</h3> - <p>executes normalizeProtocol(), normalizeHostname(), normalizePort(), normalizePath(), normalizeSearch(), normalizeHash()</p> - - <h3 id="normalize-protocol">normalizeProtocol()</h3> - <pre class="prettyprint lang-js">var uri = new URI("hTTp://www.example.org/"); -// normalize protocol -uri.normalizeProtocol(); // returns the URI instance for chaining -// uri == "http://www.example.org/"</pre> - - <h3 id="normalize-host">normalizeHostname()</h3> - <p>For IDN conversion <a href="https://github.com/bestiejs/punycode.js">punycode.js</a> must be available (bundled in URI.js). - For IPv6-best-notation conversion IPv6.js must be available (bundled in URI.js). Also lower-cases hostnames.</p> - <pre class="prettyprint lang-js">var uri = new URI("http://www.exämple.org/"); -// normalize IDN host -uri.normalizeHostname(); // returns the URI instance for chaining -// uri == "http://www.xn--exmple-cua.org/" - -// normalize IPv6 host -uri.hostname("fe80:0000:0000:0000:0204:61ff:fe9d:f156"); -uri.normalizeHostname(); // returns the URI instance for chaining -// uri == "http://fe80::204:61ff:fe9d:f156/" - -// normalize hostname to lower case -uri.hostname("wWw.eXample.Org"); -uri.normalizeHostname(); // returns the URI instance for chaining -// uri == "http://www.example.org/"</pre> - <p>There is no .normalizeHost(), as <a href="#accessors-host">.host()</a> is a property comprised of <a href="#accessors-hostname">.hostname()</a> and <a href="#accessors-port">.port()</a></p> - - <h3 id="normalize-port">normalizePort()</h3> - <p>Removes the port, if it's the default for the given protocol (http: 80, https: 443, ftp: 21).</p> - <p>The list of default ports can be modified at <code>URI.defaultPorts</code></p> - <pre class="prettyprint lang-js">var uri = new URI("http://example.org:80/foo.html"); -// normalize port -uri.normalizePort(); // returns the URI instance for chaining -// uri == "http://example.org/foo.html"</pre> - - <h3 id="normalize-path">normalizePathname(), normalizePath()</h3> - <p>.normalizePath() is an alias of .normalizePathname(), they resolve relative hierarchies</p> - <pre class="prettyprint lang-js">var uri = new URI("/hello/foo/woo/.././../world.html"); -// normalize path -uri.normalizePathname(); // returns the URI instance for chaining -// uri == "/hello/world.html"</pre> - - <h3 id="normalize-search">normalizeSearch(), normalizeQuery()</h3> - <p>Turns <code>?&foo=bar&&foo=bar&foo=baz&</code> into <code>?foo=bar&foo=baz</code> and removes ? if there is no query string.</p> - <pre class="prettyprint lang-js">var uri = new URI("?&foo=bar&&foo=bar&foo=baz&"); -// normalize search -uri.normalizeSearch(); // returns the URI instance for chaining -// uri == "?foo=bar&foo=baz"</pre> - - <h3 id="normalize-hash">normalizeHash(), normalizeFragment()</h3> - <p>removes # if there is no hash</p> - <pre class="prettyprint lang-js">var uri = new URI("http://example.org/foo/hello.html#"); -// normalize hash -uri.normalizeHash(); // returns the URI instance for chaining -// uri == "http://example.org/bar/world.xml"</pre> - - - <h2 id="charsets">Charsets / Encodings</h2> - - <h3 id="iso8859">iso8859()</h3> - <p>.iso8859() converts unicode-encoded escape sequences to ISO8859-encoded escape sequences. It does this by calling <a href="#normalize">.normalize()</a> internally.</p> - <pre class="prettyprint lang-js">var uri = new URI("/%C3%A4.html"); -uri.iso8859(); // returns the URI instance for chaining -// uri == "/%E4.html"</pre> - <p class="note">You can make URI work with ISO8859 encoding by default by calling <a href="#static-iso8859">URI.iso8859()</a>. - - <h3 id="unicode">unicode()</h3> - <p>.unicode() converts ISO8859-encoded escape sequences to unicode-encoded escape sequences. It does this by calling <a href="#normalize">.normalize()</a> internally.</p> - <pre class="prettyprint lang-js">var uri = new URI("/%E4.html"); -uri.unicode(); // returns the URI instance for chaining -// uri == "/%C3%A4.html"</pre> - - - <h2 id="formatting">Formatting URLs</h2> - - <h3 id="readable">readable()</h3> - <p>Formats URLs to be human readable (much like your browser does nowadays).</p> - <pre class="prettyprint lang-js">var uri = new URI("http://foo:bar@www.xn--exmple-cua.org/" - + "hello%20world/ä.html?foo%5B%5D=b+är#fragment"); - -uri.readable() === "http://www.exämple.org/" - + "hello world/ä.html?foo[]=b är#fragment";</pre> - - - <h2 id="relative-and-absolute">Relative and Absolute URLs</h2> - - <h3 id="relativeto">relativeTo()</h3> - <p>.relativeTo() compares two <em>paths</em> and makes one relative to the other</p> - <pre class="prettyprint lang-js">var uri = new URI("/relative/path"); -// make path relative -var relUri = uri.relativeTo("/relative/sub/foo/sub/file"); // returns a new URI instance -// relUri == "../../../path" - -// absolute URLs are passed through unchanged -URI("http://example.org/world.html") - .relativeTo("http://google.com/baz"); -// -> "http://example.org/world.html" - -// absolute URLs relative to absolute URLs -// may resolve the protocol -URI("http://example.org/world.html") - .clone() - .authority("") - .relativeTo("http://google.com/baz"); -// -> "//google.com/world.html" - -// equal URLs are relative by empty string -URI("http://www.example.com:8080/dir/file") - .relativeTo('http://www.example.com:8080/dir/file'); -// -> "" - -// relative on fragment and query string as well -URI("http://www.example.com:8080/dir/file?foo=bar#abcd") - .relativeTo('http://www.example.com:8080/dir/file'); -// -> "?foo=bar#abcd"</pre> - <p>.relativeTo() and .absoluteTo() reverse each other.</p> - - <h3 id="absoluteto">absoluteTo()</h3> - <p>.absoluteTo() makes a <em>relative path</em> absolute based on another path</p> - <pre class="prettyprint lang-js">var uri = new URI("../../../path"); -// make path absolute -var relUri = uri.absoluteTo("/relative/sub/foo/sub/file"); // returns a new URI instance -// relUri == "/relative/path" - -// resolves protocols -var u = new URI('//example.com/path'); -u.absoluteTo('https://example.com'); -// -> "https://example.com/path" -var u = new URI('//example.com/path'); -u.absoluteTo('https://'); -// -> "https://example.com/path"</pre> - <p>.relativeTo() and .absoluteTo() reverse each other.</p> - - - <h2 id="comparison">Comparing URLs</h2> - - <h3 id="equals">equals()</h3> - <p>.equals() determines if the given URLs are the same - disregarding default ports, capitalization, dot-pathnames, query-parameter order, etc.</p> - <pre class="prettyprint lang-js">var a = "http://example.org/foo/bar.html" - + "?foo=bar&hello=world&hello=mars#fragment"; -var b; - -// normalizing URI before comparison: -b = "http://exAMPle.org:80/foo/../foo/bar.html" - + "?foo=bar&hello=world&hello=mars#fragment"; - -a !== b; -URI(a).equals(b) === true; - - -// comparing query string parameters: -b = "http://example.org/foo/bar.html" - + "?hello=mars&foo=bar&hello=world&#fragment"; - -a !== b; -URI(a).equals(b) === true; - -// shorthand for comparing to window.location.href: -URI(a).equals();</pre> - - - <h2 id="parsing-urls">Parsing URLs</h2> - - <h3 id="static-parse">URI.parse(<em>string</em> url)</h3> - <p>parses a string into its URI components. returns an object containing the found components</p> - <pre class="prettyprint lang-js">var result = URI.parse("http://example.org/foo.html"); -result === { - protocol: "http", - username: null, - password: null, - hostname: "example.org", - port: null, - path: "/foo.html", - query: null, - fragment: null -};</pre> - - <h3 id="static-parseAuthority">URI.parseAuthority(<em>string</em> url, <em>object</em> parts)</h3> - <p>parses a string's beginning into its URI components username, password, hostname, port. - Found components are appended to the <code>parts</code> parameter. - Remaining string is returned</p> - <pre class="prettyprint lang-js">var parts = {}; -var result = URI.parseAuthority("user:pass@example.org:8080/foo.html", parts); -result === "/foo.html"; -parts === { - username: "user", - password: "pass", - hostname: "example.org", - port: "8080" -};</pre> - - <h3 id="static-parseUserinfo">URI.parseUserinfo(<em>string</em> url, <em>object</em> parts)</h3> - <p>parses a string's beginning into its URI components username, password. - Found components are appended to the <code>parts</code> parameter. - Remaining string is returned</p> - <pre class="prettyprint lang-js">var parts = {}; -var result = URI.parseUserinfo("user:pass@example.org:8080/foo.html", parts); -result === "example.org:8080/foo.html"; -parts === { - username: "user", - password: "pass" -};</pre> - - <h3 id="static-parseHost">URI.parseHost(<em>string</em> url, <em>object</em> parts)</h3> - <p>parses a string's beginning into its URI components hostname, port. - Found components are appended to the <code>parts</code> parameter. - Remaining string is returned</p> - <pre class="prettyprint lang-js">var parts = {}; -var result = URI.parseHost("example.org:8080/foo.html", parts); -result === "/foo.html"; -parts === { - hostname: "example.org", - port: "8080" -};</pre> - - <h3 id="static-parseQuery">URI.parseQuery(<em>string</em> querystring)</h3> - <p>Parses the passed query string into an object. Returns object <code>{propertyName: propertyValue}</code></p> - <pre class="prettyprint lang-js">var result = URI.parseQuery("?foo=bar&hello=world&hello=mars&bam=&yup"); -result === { - foo: "bar", - hello: ["world", "mars"], - bam: "", - yup: null -};</pre> - - <h2 id="serializing-urls">Serializing URLs</h2> - - <h3 id="static-build">URI.build(<em>object</em> parts)</h3> - <p>serializes the URI components passed in <code>parts</code> into a URI string</p> - <pre class="prettyprint lang-js">var parts = { - protocol: "http", - username: null, - password: null, - hostname: "example.org", - port: null, - path: "/foo.html", - query: null, - fragment: null -}; -URI.build(parts) === "http://example.org/foo.html";</pre> - - <h3 id="static-buildAuthority">URI.buildAuthority(<em>object</em> parts)</h3> - <p>serializes the URI components username, password, hostname, port passed in <code>parts</code> into a URI string</p> - <pre class="prettyprint lang-js">var parts = { - username: "user", - password: "pass", - hostname: "example.org", - port: "8080" -}; -URI.buildAuthority(parts) === "user:pass@example.org:8080";</pre> - - <h3 id="static-buildUserinfo">URI.buildUserinfo(<em>object</em> parts)</h3> - <p>serializes the URI components username, password passed in <code>parts</code> into a URI string</p> - <pre class="prettyprint lang-js">var parts = { - username: "user", - password: "pass" -}; -URI.buildUserinfo(parts) === "user:pass@";</pre> - - <h3 id="static-buildHost">URI.buildHost(<em>object</em> parts)</h3> - <p>serializes the URI components hostname, port passed in <code>parts</code> into a URI string</p> - <pre class="prettyprint lang-js">var parts = { - hostname: "example.org", - port: "8080" -}; -URI.buildHost(parts) === "example.org:8080";</pre> - - <h3 id="static-buildQuery">URI.buildQuery(<em>object</em> data, [<em>boolean</em> duplicateQueryParameters], [<em>boolean</em> escapeQuerySpace])</h3> - <p>serializes the query string parameters</p> - <pre class="prettyprint lang-js">var data = { - foo: "bar", - hello: ["world", "mars", "mars"], - bam: "", - yup: null, - removed: undefined -}; - -// Note: duplicate hello=mars is dropped (default behavior!) -URI.buildQuery(data) === "foo=bar&hello=world&hello=mars&bam=&yup"; - -// Note: duplicate hello=mars is preserved -URI.buildQuery(data, true) === "foo=bar&hello=world&hello=mars&hello=mars&bam=&yup";</pre> - <p>To preserve duplicate values, use URI.buildQuery() directly:</p> - <pre class="prettyprint lang-js">var uri = new URI("http://example.org/foo.html?bar=baz"); -var data = uri.query(true); - -data.some = "new data"; -uri.query(URI.buildQuery(data, true)); - -// you can also use the static <a href="#static-addQuery">URI.addQuery()</a> and <a href="#static-removeQuery">URI.removeQuery()</a> -URI.addQuery(data, "hello", "world"); -uri.query(URI.buildQuery(data, true));</pre> - - <p id="setting-duplicateQueryParameters">As of v1.8.0 you can configure query parameter de/duplication:</p> - <pre class="prettyprint lang-js">// make all new URI instances allow duplicates: -URI.duplicateQueryParameters = true; // default is false - -// make a specific URI instance allow duplicates: -var withDuplicates = URI("?bar=1&bar=1") - .duplicateQueryParameters(true) - .normalizeQuery() - .toString(); - -// make a specific URI instance avoid duplicates (default): -var noDuplicates = URI("?bar=1&bar=1") - .duplicateQueryParameters(false) - .normalizeQuery() - .toString(); - -withDuplicates === "?bar=1&bar=1"; -noDuplicates === "?bar=1";</pre> - - <p id="setting-escapeQuerySpace">As of v1.11.0 you can configure query space en/decoding:</p> - <pre class="prettyprint lang-js">// prevent all new URI instances from escaping spaces in query strings: -URI.escapeQuerySpace = false; // default is true - -// make a specific URI instance escape spaces in query: -var withPlus = URI("?bar=hello+world") - .escapeQuerySpace(true) - .query(true).bar; - -// make a specific URI instance not escape spaces in query -var withPercent = URI("?bar=hello%20world") - .escapeQuerySpace(false) - .query(true).bar; - -withPlus === "hello world"; -withPercent === "hello world";</pre> - - <h2 id="encoding-decoding">Encoding and Decoding URLs</h2> - - <h3 id="static-encode">URI.encode()</h3> - <p>Encode an URI component with strict compliance to RFC3986</p> - <pre class="prettyprint lang-js">URI.encode("hä lo#w*rl:d!") === "h%C3%A4%20lo%23w%2Arl%3Ad%21"; -// vs. -encodeURIComponent("hä lo#w*rl:d!") === "h%C3%A4%20lo%23w*rl%3Ad!"; -// not how * and ! were not encoded</pre> - - <h3 id="static-decode">URI.decode()</h3> - <p>Decode an URI component</p> - <pre class="prettyprint lang-js">URI.decode("h%C3%A4%20lo%23w%2Arl%3Ad%21") === "hä lo#w*rl:d!"; -// note: -URI.decode === decodeURIComponent;</pre> - - <h3 id="static-encodeReserved">URI.encodeReserved()</h3> - <p>Encode an URI component whilst preserving <a href="http://tools.ietf.org/html/rfc3986#section-2.2">reserved characters</a></p> - <pre class="prettyprint lang-js">URI.encodeReserved("ä:/?#[]@!$&'()*+,;=") === "%C3%A4:/?#[]@!$&'()*+,;="; -// vs. -URI.encode("ä:/?#[]@!$&'()*+,;=") === - "%C3%A4%3A%2F%3F%23%5B%5D%40%21%24%26%27%28%29%2A%2B%2C%3B%3D";</pre> - - <h3 id="static-encodeQuery">URI.encodeQuery()</h3> - <p>Encode a query string component. Works like <a href="#static-encode">encode()</a>, except it handles <code>%20</code> as <code>+</code> (space) if <a href="#setting-escapeQuerySpace"><code>URI.escapeQuerySpace = true;</code></a>.</p> - <pre class="prettyprint lang-js">URI.escapeQuerySpace = true; // default -URI.encodeQuery(" ") === "+"; - -URI.escapeQuerySpace = false; -URI.encodeQuery(" ") === "%20"; - -// vs. -URI.encode(" ") === "%20";</pre> - - <h3 id="static-decodeQuery">URI.decodeQuery()</h3> - <p>Decode a query string component. Works like <a href="#static-decode">decode()</a>, except it handles <code>+</code> as <code>%20</code> (space) if <a href="#setting-escapeQuerySpace"><code>URI.escapeQuerySpace = true;</code></a>.</p> - <pre class="prettyprint lang-js">URI.escapeQuerySpace = true; // default -URI.decodeQuery("+") === " "; - -URI.escapeQuerySpace = false; -URI.decodeQuery("+") === "+"; - -// vs. -URI.decode("+") === "+";</pre> - - - <h2 id="static-functions">Static Helper Functions</h2> - - <h3 id="static-noConflict">URI.noConflict()</h3> - <p>removes URI variables from global scope</p> - <pre class="prettyprint lang-js">// restores window.URI to its previous state and returns URI -URI.noConflict(); -// restores the global variable to its previous state and returns the object itself -URITemplate.noConflict(); -IPv6.noConflict(); -SecondLevelDomains.noConflict(); - -// restore all objects and return them as a map {URI: ..., IPv6: ..., ....} -URI.noConflict(true);</pre> - - <h3 id="static-addQuery">URI.addQuery()</h3> - <p>adds data to a map</p> - <pre class="prettyprint lang-js">var data = {}; - -URI.addQuery(data, "hello", "mars"); -data === {hello: "mars"}; - -URI.addQuery(data, "hello", "world"); -data === {hello: ["mars", "world"]}; - -URI.addQuery(data, {foo: "bar", goodbye : ["world", "mars"]}); -data === {hello: ["mars", "world"], foo: "bar", goodbye : ["world", "mars"]};</pre> - - <h3 id="static-removeQuery">URI.removeQuery()</h3> - <p>removes data from a map</p> - <pre class="prettyprint lang-js">var data === {hello: ["mars", "world"], foo: "bar", goodbye : ["world", "mars"]}; - -URI.removeQuery(data, "hello"); -data === {foo: "bar", goodbye : ["world", "mars"]}; - -// remove an attribute with value filter -data = {hello: ["world", "mars"], foo: "bar"}; -URI.removeQuery(data, "hello", "world"); -data === {hello: ["mars"], foo: "bar"} // yes, still an array - -// remove multiple values -data = {hello: ["world", "mars"], foo: "bar", mine: "true"} -URI.removeQuery(["hello", "foo"]); -data === {mine: "true"}; - -// remove multiple values with value filter -data = {hello: ["world", "mars"], foo: "bar", mine: "true", a: ["1", "2", "3"]} -URI.removeQuery({hello: "world", foo: undefined, a: ["1", "3"]}); -data === {hello: ["mars"], mine: "true", a: ["2"]}</pre> - - <h3 id="static-commonPath">URI.commonPath()</h3> - <p>URI.commonPath() determines the common base directory of two paths.</p> - <pre class="prettyprint lang-js">URI.commonPath("/foo/bar/baz.html", "/foo/bar/world.html"); -// returns "/foo/bar/" - -URI.commonPath("/foo/bar/baz.html", "/foo/bazz/world.html"); -// returns "/foo/" - -URI.commonPath("/foo/bar/baz.html", "/other/world.html"); -// returns "/" - -URI.commonPath("/foo", "bar"); -// returns ""</pre> - - <h3 id="static-joinPaths">URI.joinPath()</h3> - <p>URI.joinPath() composes a path from directory tokens.</p> - <pre class="prettyprint lang-js">URI.joinPaths('/a/b', '/c', 'd', '/e'); -// returns URI("/a/b/c/d/e") - -URI.joinPaths('a/b', 'http://example.com/c', new URI('d/'), '/e'); -// returns URI("a/b/c/d/e") - -URI.joinPaths('/a/'); -// returns URI("/a/") - -URI.joinPaths(''); -// returns URI("") - -URI.joinPaths('', 'a', ''); -// returns URI("/a/")</pre> - - <h3 id="static-withinString">URI.withinString()</h3> - <p>URI.withinString() identifies URIs within text, e.g. to translate them to <a>-Tags. (Obviously you'd want to put the urls inside the href-Attribute and escape them properly…)</p> - <p class="note">.withinString() only works on plain text, it will not work with HTML!</p> - <pre class="prettyprint lang-js">var source = "Hello www.example.com,\n" - + "http://google.com is a search engine, like http://www.bing.com\n" - + "http://exämple.org/foo.html?baz=la#bumm is an IDN URL,\n" - + "http://123.123.123.123/foo.html is IPv4 and " - + "http://fe80:0000:0000:0000:0204:61ff:fe9d:f156/foobar.html is IPv6.\n" - + "links can also be in parens (http://example.org) " - + "or quotes »http://example.org«."; - -var result = URI.withinString(source, function(url) { - // callback needs to return a string - // feel free to URI(url).normalize().toString() or something - return "<a>" + url + "</a>"; -}); - -/* result is: -Hello <strong><a>www.example.com</a></strong>, -<strong><a>http://google.com</a></strong> is a search engine, like <strong><a>http://www.bing.com</a></strong> -<strong><a>http://exämple.org/foo.html?baz=la#bumm</a></strong> is an IDN URL, -<strong><a>http://123.123.123.123/foo.html</a></strong> is IPv4 and <strong><a>http://fe80:0000:0000:0000:0204:61ff:fe9d:f156/foobar.html</a></strong> is IPv6. -links can also be in parens (<strong><a>http://example.org</a></strong>) or quotes »<strong><a>http://example.org</a></strong>«. -*/ - -// a proper replacement could look like the following: -var escapeHtml = function(string) { - return string - .replace(/&/g, "&amp;") - .replace(/</g, "&lt;") - .replace(/>/g, "&gt;") - .replace(/"/g, "&quot;"); -}; -var result = URI.withinString(source, function(url) { - var uri = new URI(url); - uri.normalize(); - return "<a href="" + escapeHtml(uri) + "">" - + escapeHtml(uri.<a href="#readable">readable</a>()) + "</a>"; -}); -</pre> - <p>As of URI.js 1.12.0 withinString accepts the following parameters:</p> - <pre class="prettyprint lang-js">var source = "Hello www.example.com."; -var decorate = function(url) { - return "<code>" + url + "</code>"; -}; -var result = null; - -// access to the original input text from the callback -URI.withinString(source, function(url, start, end, source) { - source.slice(start, end) === url; - return url; -}); - -// ignore certain URLs -source = "Hello www.example.com,\n" - + "ohgodno://example.org/ is a a protocol we want ignored"; -result = URI.withinString(source, decorate, { - ignore: /^ohgodno:/i -}); - -/* result is: -Hello <strong><code>www.example.com</code></strong>, -ohgodno://example.org/ is a a protocol we want ignored -*/ - -// ignore URLs in HTML -source = "Hello www.example.com,\n" - + '<img src="http://example.org/image.png" alt=""> is HTML,\n' - + "<a href='http://example.org/target.html'> is HTML</a>,\n" - + "<a href=http://example.org/target.html> is HTML, too</a>."; -result = URI.withinString(source, decorate, { - ignoreHtml: true -}); - -/* result is: -Hello <strong><code>www.example.com</code></strong>, -<img src="http://example.org/image.png" alt=""> is HTML, -<a href='http://example.org/target.html'> is HTML</a>, -<a href=http://example.org/target.html> is HTML, too</a> -*/ - -// custom URI beginning pattern -source = "That example.com/ is just a domain"; -result = URI.withinString(source, decorate, { - // "scheme://" or "www." or "domain.tld/" - start: /\b(?:([a-z][a-z0-9.+-]*:\/\/)|www\.|[a-z]+\.[a-z]{2,4}\/)/gi -}); - -/* result is: -That <strong><code>example.com/</code></strong> is just a domain -*/</pre> - - <h3 id="static-iso8859">URI.iso8859()</h3> - <p>URI.iso8859() tells URI.js to use the older escape/unescape methods, for backwards compatibility with non-unicode platforms.</p> - <pre class="prettyprint lang-js">URI.iso8859(); - -var uri = new URI("http://example.org/foo/æ.html"); -// http://example.org/foo/%E6.html</pre> - - <h3 id="static-unicode">URI.unicode()</h3> - <p>URI.unicode() restores the default unicode-encoded URLs.</p> - <pre class="prettyprint lang-js">URI.unicode(); - -var uri = new URI("http://example.org/foo/æ.html"); -// http://example.org/foo/%C3%A6.html</pre> - - <h3 id="static-expand">URI.expand()</h3> - <p>URI.expand() is a convenience wrapper for <a href="uri-template.html"><code>URITemplate</code></a>. - While <code>URITemplate#expand</code> returns a string, <code>URI.expand()</code> returns an <code>URI</code> instance.</p> - <pre class="prettyprint lang-js">URI.expand("/foo/{var}/{iable}", { - "var": "bar", - "iable": "hello world.html" -}); - -// returns URI("/foo/bar/hello%20world.html")</pre> - - - </div> -</body> -</html> |