var uri = new URI(); // same as new URI(location.href) // string @@ -204,10 +204,10 @@- +URI Constructor
// resolving right in the constructor var uri = URI("../foobar.html", "http://example.org/hello/world.html"); -// which is exactly the same as +// which is exactly the same as URI("../foobar.html").absoluteTo("http://example.org/hello/world.html"); // but specified in URL constructor
The following parts can be specified in an object:
var uri = new URI({
protocol: "http", // no trailing :
@@ -268,7 +268,7 @@ cloning URIs
uri2.tld("com");
uri == "http://example.org/";
uri2 == "http://example.com/";
-
+
get and set the entire URI
var uri = URI("http://example.com");
@@ -276,15 +276,15 @@ href()
uri.href("ftp://google.org");
uri.toString() === "ftp://google.org/"
-
+
serialize the URI to string. valueOf() is an alias to toString(), as string is the base primitive.
var uri = URI("http://example.com");
var s = uri.toString();
typeof s === "string";
s === "http://example.com/";
-
-
+
+
.scheme() is an alias of .protocol()
var uri = new URI("http://example.org/foo/hello.html");
@@ -304,14 +304,14 @@ username()
uri.username(); // returns string "user"
// set username
uri.username("user"); // returns the URI instance for chaining
-
+
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
-
+
var uri = new URI("http://example.org/foo/hello.html");
// get hostname
@@ -319,7 +319,7 @@ hostname()
// set hostname
uri.hostname("example.org"); // returns the URI instance for chaining
.hostname() returns the actual hostname, whereas .host() returns the hostname including the port
- +var uri = new URI("http://example.org:8080/foo/hello.html");
// get port
@@ -328,7 +328,7 @@ port()
uri.port("80"); // returns the URI instance for chaining
although the port may be considered an integer, within URI it is a string.
Throws a TypeError on illegal input
var uri = new URI("http://example.org:80/foo/hello.html");
// get host
@@ -345,7 +345,7 @@ userinfo()
uri.userinfo(); // returns string "user:pass"
// set userinfo
uri.userinfo("user:pass"); // returns the URI instance for chaining
-
+
Authority is comprised of username, password, hostname and port
var uri = new URI("http://user:pass@example.org:88/foo/hello.html");
@@ -384,7 +384,7 @@ domain()
uri.domain(true); // return string "co.uk"
.domain() will throw an error if you pass it an empty string.
Throws a TypeError on illegal input
.subdomain() is a convenience method that returns www from the hostname www.example.org.
var uri = new URI("http://www.example.org/foo/hello.html");
@@ -393,7 +393,7 @@ subdomain()
// set subdomain
uri.subdomain("other.subdomain"); // returns the URI instance for chaining
Throws a TypeError on illegal input
.tld() is a convenience method that returns org from the hostname www.example.org.
var uri = new URI("http://example.org/foo/hello.html");
@@ -427,7 +427,7 @@ pathname(), path()
URI("/").path() === "/";
URI("http://example.org").path() === "/";
-
+
.directory() is an convenience method for mutating the directory part of a path
var uri = new URI("http://example.org/foo/hello.html");
@@ -449,7 +449,7 @@ directory()
// -&t; "/"
uri.href("foo").directory()
// -&t; ""
-
+
.filename() is an convenience method for mutating the filename part of a path
var uri = new URI("http://example.org/foo/hello.html");
@@ -465,7 +465,7 @@ filename()
// will decode for you
uri.filename(true) === "hello world.html";
If you pass ../file.html, the directory will be changed accordingly
.suffix() is an convenience method for mutating the filename part of a path
var uri = new URI("http://example.org/foo/hello.html");
@@ -480,7 +480,7 @@ suffix()
uri.suffix() === "w%C3%BCrgh";
// will decode for you
uri.suffix(true) === "würgh";
-
+
.segment() allows convenient access to directory levels / URN segments within the path. See .segmentCoded() for an interface that transparently encodes and decodes path segments.
var uri = new URI("http://example.org/foo/hello.html");
@@ -520,8 +520,8 @@ segmentCoded()
// append level
uri.segmentCoded("append this"); // -> http://example.org/bar/foobar.html/append%20this
-
-
+
+
var uri = new URI("http://example.org/foo/hello.html?foo=bar&bar=baz");
// get search
@@ -563,7 +563,7 @@ search(), query()
// If you're dealing with PHP, you probably want the latter…
uri.search("?foo=bar&bar=baz");
uri.search("?foo=bar[]&bar[]=baz");
- Note that names and values passed in an object are encoded automatically. +
Note that names and values passed in an object are encoded automatically. The object, resulting from parsing the query string, contains decoded values
Hint: If you're using jQuery, have a look at their .serialize() function.
@@ -584,7 +584,7 @@Resource is comprised of path, query and fragment
var uri = new URI("http://example.org/foo/hello.html?query=string#hash");
@@ -659,10 +659,10 @@ is()
uri.is("punycode") === false;
uri.is("idn") === false;
uri.is("ip") === false;
-
-
+
+
.setQuery() is an alias of .setSearch()
var uri = new URI("?hello=world");
@@ -680,7 +680,7 @@ setSearch(), setQuery()
uri.setSearch("foo", ["bar", "baz"]);
uri.setSearch("foo[]", ["bar", "baz"]);
Note that names and values passed in are encoded automatically.
- +.addQuery() is an alias of .addSearch()
var uri = new URI("?hello=world");
@@ -698,7 +698,7 @@ addSearch(), addQuery()
uri.addSearch("foo", ["bar", "baz"]);
uri.addSearch("foo[]", ["bar", "baz"]);
Note that names and values passed in are encoded automatically.
- +.removeQuery() is an alias of .removeSearch()
var uri = new URI("?hello=world&hello=mars&foo=bar");
@@ -714,7 +714,7 @@ removeSearch(), removeQuery()
// remove multiple values
uri.search("?hello=world&hello=mars&foo=bar&mine=true");
uri.removeSearch(["hello", "foo"]);
-// uri == "?mine=true"
+// 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");
@@ -775,27 +775,27 @@ hasSearch(), hasQuery()
Working with the Fragment (Hash)
- There are virtually no limits to what you might do with fragments (hash).
- Every system has their own bag of tricks.
+ 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 abuse of fragments are storing URLs or query string like data.
-
+
- 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 ! and for query-like data it often is ?.
+ 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 ! and for query-like data it often is ?.
But they don't have to, which is why you can define a global default: URI.fragmentPrefix = "$";
Query String Fragments
The file src/URI.fragmentQuery.js is a "plugin" that allows you to store data in hashes in the same manner the .query() functions provide.
-
+
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("!");
+uri.fragmentPrefix("!");
// to change the fragment prefix on a global level:
URI.fragmentPrefix = "!";
@@ -803,7 +803,7 @@ Query String Fragments
URL Fragments
The file src/URI.fragmentURI.js is a "plugin" that allows you to store URLs in hashes.
-
+
var uri = URI("http://example.org/#!/foo/bar/baz.html");
var furi = uri.fragment(true);
@@ -815,22 +815,22 @@ URL Fragments
uri.toString() === "http://example.org/#!/hello.html"
// to change the fragment prefix on an instance level:
-uri.fragmentPrefix("?");
+uri.fragmentPrefix("?");
// to change the fragment prefix on a global level:
URI.fragmentPrefix = "?";
-
+
Normalizing URLs
-
+
normalize()
executes normalizeProtocol(), normalizeHostname(), normalizePort(), normalizePath(), normalizeSearch(), normalizeHash()
-
+
normalizeProtocol()
var uri = new URI("hTTp://www.example.org/");
// normalize protocol
uri.normalizeProtocol(); // returns the URI instance for chaining
// uri == "http://www.example.org/"
-
+
normalizeHostname()
For IDN conversion punycode.js 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.
@@ -878,7 +878,7 @@ normalizeHash(), normalizeFragment()
// normalize hash
uri.normalizeHash(); // returns the URI instance for chaining
// uri == "http://example.org/bar/world.xml"
-
+
var uri = new URI("/%E4.html");
uri.unicode(); // returns the URI instance for chaining
// uri == "/%C3%A4.html"
-
-
+
+
Formats URLs to be human readable (much like your browser does nowadays).
var uri = new URI("http://foo:bar@www.xn--exmple-cua.org/"
@@ -955,10 +955,10 @@ absoluteTo()
u.absoluteTo('https://');
// -> "https://example.com/path"
.relativeTo() and .absoluteTo() reverse each other.
- +.equals() determines if the given URLs are the same - disregarding default ports, capitalization, dot-pathnames, query-parameter order, etc.
var a = "http://example.org/foo/bar.html" @@ -982,52 +982,52 @@- +equals()
// shorthand for comparing to window.location.href: URI(a).equals();
parses a string into its URI components. returns an object containing the found components
var result = URI.parse("http://example.org/foo.html");
result === {
- protocol: "http",
- username: null,
- password: null,
+ protocol: "http",
+ username: null,
+ password: null,
hostname: "example.org",
port: null,
path: "/foo.html",
query: null,
fragment: null
};
-
+
parses a string's beginning into its URI components username, password, hostname, port. +
parses a string's beginning into its URI components username, password, hostname, port.
Found components are appended to the parts parameter.
Remaining string is returned
var parts = {};
var result = URI.parseAuthority("user:pass@example.org:8080/foo.html", parts);
result === "/foo.html";
parts === {
- username: "user",
- password: "pass",
+ username: "user",
+ password: "pass",
hostname: "example.org",
port: "8080"
};
-
+
parses a string's beginning into its URI components username, password. +
parses a string's beginning into its URI components username, password.
Found components are appended to the parts parameter.
Remaining string is returned
var parts = {};
var result = URI.parseUserinfo("user:pass@example.org:8080/foo.html", parts);
result === "example.org:8080/foo.html";
parts === {
- username: "user",
+ username: "user",
password: "pass"
};
-
+
parses a string's beginning into its URI components hostname, port. +
parses a string's beginning into its URI components hostname, port.
Found components are appended to the parts parameter.
Remaining string is returned
var parts = {};
@@ -1037,7 +1037,18 @@ URI.parseHost(string url, object par
hostname: "example.org",
port: "8080"
};
-
+ As of v1.19.0 you can activate host name validation (disabled by default):
+URI.preventInvalidHostname = true;
+var parts = {};
+var result = URI.parseHost("/foo.html", parts);
+// throws TypeError
+
+URI.preventInvalidHostname = false;
+var uri = new URI('http://example.org/')
+ .preventInvalidHostname(true)
+ .hostname('')
+// throws TypeError
+
Parses the passed query string into an object. Returns object {propertyName: propertyValue}
var result = URI.parseQuery("?foo=bar&hello=world&hello=mars&bam=&yup");
@@ -1047,15 +1058,15 @@ URI.parseQuery(string querystring)
bam: "",
yup: null
};
-
+
serializes the URI components passed in parts into a URI string
var parts = {
- protocol: "http",
- username: null,
- password: null,
+ protocol: "http",
+ username: null,
+ password: null,
hostname: "example.org",
port: null,
path: "/foo.html",
@@ -1063,12 +1074,12 @@ URI.build(object parts)
fragment: null
};
URI.build(parts) === "http://example.org/foo.html";
-
+
serializes the URI components username, password, hostname, port passed in parts into a URI string
var parts = {
- username: "user",
- password: "pass",
+ username: "user",
+ password: "pass",
hostname: "example.org",
port: "8080"
};
@@ -1077,11 +1088,11 @@ URI.buildAuthority(object parts)
URI.buildUserinfo(object parts)
serializes the URI components username, password passed in parts into a URI string
var parts = {
- username: "user",
+ username: "user",
password: "pass"
};
URI.buildUserinfo(parts) === "user:pass@";
-
+
URI.buildHost(object parts)
serializes the URI components hostname, port passed in parts into a URI string
var parts = {
@@ -1089,7 +1100,7 @@ URI.buildHost(object parts)
port: "8080"
};
URI.buildHost(parts) === "example.org:8080";
-
+
URI.buildQuery(object data, [boolean duplicateQueryParameters], [boolean escapeQuerySpace])
serializes the query string parameters
var data = {
@@ -1115,7 +1126,7 @@ URI.buildQuery(object data, [booleanURI.addQuery() and URI.removeQuery()
URI.addQuery(data, "hello", "world");
uri.query(URI.buildQuery(data, true));
-
+
As of v1.8.0 you can configure query parameter de/duplication:
// make all new URI instances allow duplicates:
URI.duplicateQueryParameters = true; // default is false
@@ -1151,29 +1162,29 @@ URI.buildQuery(object data, [boolean
-
+
Encoding and Decoding URLs
-
+
URI.encode()
Encode an URI component with strict compliance to RFC3986
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
-
+
URI.decode()
Decode an URI component
URI.decode("h%C3%A4%20lo%23w%2Arl%3Ad%21") === "hä lo#w*rl:d!";
// note:
URI.decode === decodeURIComponent;
-
+
URI.encodeReserved()
Encode an URI component whilst preserving reserved characters
URI.encodeReserved("ä:/?#[]@!$&'()*+,;=") === "%C3%A4:/?#[]@!$&'()*+,;=";
// vs.
-URI.encode("ä:/?#[]@!$&'()*+,;=") ===
+URI.encode("ä:/?#[]@!$&'()*+,;=") ===
"%C3%A4%3A%2F%3F%23%5B%5D%40%21%24%26%27%28%29%2A%2B%2C%3B%3D";
-
+
URI.encodeQuery()
Encode a query string component. Works like encode(), except it handles %20 as + (space) if URI.escapeQuerySpace = true;.
URI.escapeQuerySpace = true; // default
@@ -1184,7 +1195,7 @@ URI.encodeQuery()
// vs.
URI.encode(" ") === "%20";
-
+
URI.decodeQuery()
Decode a query string component. Works like decode(), except it handles + as %20 (space) if URI.escapeQuerySpace = true;.
URI.escapeQuerySpace = true; // default
@@ -1195,8 +1206,8 @@ URI.decodeQuery()
// vs.
URI.decode("+") === "+";
-
-
+
+
Static Helper Functions
URI.noConflict()
@@ -1210,7 +1221,7 @@ URI.noConflict()
// restore all objects and return them as a map {URI: ..., IPv6: ..., ....}
URI.noConflict(true);
-
+
URI.addQuery()
adds data to a map
var data = {};
@@ -1223,7 +1234,7 @@ URI.addQuery()
URI.addQuery(data, {foo: "bar", goodbye : ["world", "mars"]});
data === {hello: ["mars", "world"], foo: "bar", goodbye : ["world", "mars"]};
-
+
URI.removeQuery()
removes data from a map
var data === {hello: ["mars", "world"], foo: "bar", goodbye : ["world", "mars"]};
@@ -1260,8 +1271,8 @@ URI.commonPath()
URI.commonPath("/foo", "bar");
// returns ""
- URI.joinPath()
- URI.joinPath() composes a path from directory tokens.
+ URI.joinPaths()
+ URI.joinPaths() composes a path from directory tokens.
URI.joinPaths('/a/b', '/c', 'd', '/e');
// returns URI("/a/b/c/d/e")
@@ -1303,7 +1314,7 @@ URI.withinString()
*/
// a proper replacement could look like the following:
-var escapeHtml = function(string) {
+var escapeHtml = function(string) {
return string
.replace(/&/g, "&")
.replace(/</g, "<")
@@ -1313,7 +1324,7 @@ URI.withinString()
var result = URI.withinString(source, function(url) {
var uri = new URI(url);
uri.normalize();
- return "<a href="" + escapeHtml(uri) + "">"
+ return "<a href="" + escapeHtml(uri) + "">"
+ escapeHtml(uri.readable()) + "</a>";
});
@@ -1368,23 +1379,23 @@ URI.withinString()
/* result is:
That <code>example.com/</code> is just a domain
*/
-
+
URI.iso8859() tells URI.js to use the older escape/unescape methods, for backwards compatibility with non-unicode platforms.
URI.iso8859();
var uri = new URI("http://example.org/foo/æ.html");
// http://example.org/foo/%E6.html
-
+
URI.unicode() restores the default unicode-encoded URLs.
URI.unicode();
var uri = new URI("http://example.org/foo/æ.html");
// http://example.org/foo/%C3%A6.html
-
+
URI.expand() is a convenience wrapper for URITemplate.
+
URI.expand() is a convenience wrapper for URITemplate.
While URITemplate#expand returns a string, URI.expand() returns an URI instance.
URI.expand("/foo/{var}/{iable}", {
"var": "bar",
@@ -1393,7 +1404,7 @@ URI.expand()
// returns URI("/foo/bar/hello%20world.html")
-
+