<!DOCTYPE html>
<html lang="en">
<head>
<meta charset="utf-8" />
<meta http-equiv="content-type" content="text/html; charset=utf-8" />
<title>URI.js - URI-Template</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>
<style type="text/css">
.tpl-operator {
font-weight: bold;
color: #669933;
}
.tpl-variable {
font-weight: bold;
color: #336699;
}
.tpl-modifier {
font-weight: bold;
color: #663399;
}
pre {
padding: 10px;
background: #EEE;
}
table {
width: 100%;
border: 1px solid #AAA;
border-collapse: collapse;
}
td, th {
border: 1px solid #AAA;
text-align: left;
padding: 3px;
}
th {
background: #EEE;
}
</style>
</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="about-uris.html">Understanding URIs</a></li>
<li><a href="docs.html">API-Documentation</a></li>
<li><a href="jquery-uri-plugin.html">jQuery Plugin</a></li>
<li class="active"><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>
<h2>URI Template</h2>
<p>As of version 1.7.0 URI.js includes an implementation of URI Templates, as specified in <a href="http://tools.ietf.org/html/rfc6570">RFC 6570</a> (Level 4, March 2012).</p>
<h2>Using URI Templates</h2>
<pre class="prettyprint lang-js">
// creating a new URI Template
var template = new URITemplate("http://example.org/{file}");
var result = template.expand({file: "hello world.html"});
result === "http://example.org/hello%20world.html";
// of course you can call the constructor like a function and chain things:
result = URITemplate("http://example.org/{file}")
.expand({file: "hello world.html"});
result === "http://example.org/hello%20world.html";
// access via URI
result = URI.expand("http://example.org/{file}", {file: "hello world.html"});
// result == new URI("http://example.org/hello%20world.html");
// expand() accepts data-callbacks:
template.expand(function(key) {
var data = {file: "hello world.html"};
return data[key];
});
// expand() accepts key-callbacks:
template.expand({file : function(key) {
return "hello world.html";
}});
</pre>
<h2>URI Template Syntax</h2>
<p><em>Expressions</em> are placeholders which are to be substituted by the values their variables reference.</p>
<ul>
<li><code>http://example.org/~<strong>{<em class="tpl-variable">username</em>}</strong>/</code></li>
<li><code>http://example.org/dictionary/<strong>{<em class="tpl-variable">term</em><span class="tpl-modifier">:1</span>}</strong>/<strong>{<em class="tpl-variable">term</em>}</strong></code></li>
<li><code>http://example.org/search<strong>{<span class="tpl-operator">?</span><em class="tpl-variable">q</em><span class="tpl-modifier">*</span>,<em class="tpl-variable">lang</em>}</strong></code></li>
</ul>
<p>
An expression consists of an <span class="tpl-operator">operator</span> and a (comma-separated) list of <em>variable-specifications</em>.
A variable-specification consists of a <em class="tpl-variable">variable</em> and an optional <em class="tpl-modifier">modifier</em>.
</p>
<hr>
<p>Given the template</p>
<pre><code>http://example.org/~<strong>{<em class="tpl-variable">username</em>}</strong>/<strong>{<em class="tpl-variable">term</em><span class="tpl-modifier">:1</span>}</strong>/<strong>{<em class="tpl-variable">term</em>}</strong><strong>{<span class="tpl-operator">?</span><em class="tpl-variable">q</em><span class="tpl-modifier">*</span>,<em class="tpl-variable">lang</em>}</strong></code></pre>
<p>and the following data: </p>
<pre><code>{username: "rodneyrehm", term: "hello world", q: {a: "mars", b: "jupiter"}, lang: "en"}</code></pre>
<p>the expansion looks as follows:
<pre><code>"http://example.org/~rodneyrehm/h/hello%20world?a=mars&b=jupiter&lang=en"</code></pre>
<hr>
<p>List of supported <span class="tpl-operator">operators</span>:</p>
<table>
<tr><th>Operator</th><th>Description</th></tr>
<tr><td><code><em>None</em></code></td><td>Simple String Expansion;</td></tr>
<tr><td><code>+</code></td><td>Reserved character strings;</td></tr>
<tr><td><code>#</code></td><td>Fragment identifiers prefixed by "#";</td></tr>
<tr><td><code>.</code></td><td>Name labels or extensions prefixed by ".";</td></tr>
<tr><td><code>/</code></td><td>Path segments prefixed by "/";</td></tr>
<tr><td><code>;</code></td><td>Path parameter name or name=value pairs prefixed by ";";</td></tr>
<tr><td><code>?</code></td><td>Query component beginning with "?" and consisting of name=value pairs separated by "&"; and,</td></tr>
<tr><td><code>&</code></td><td>Continuation of query-style &name=value pairs within a literal query component.</td></tr>
</table>
<p>List of supported <span class="tpl-modifier">modifiers</span>:</p>
<table>
<tr><th>Modifier</th><th>Description</th></tr>
<tr><td><code><em>None</em></code></td><td>No modification, arrays and objects are joined with ","</td></tr>
<tr><td><code>*</code></td><td>Explode arrays and objects (see tables below)</td></tr>
<tr><td><code>:3</code></td><td>Substring of the first 3 characters of the variable's value</td></tr>
</table>
<h3>Strings and Numbers</h3>
<p>
Given <code>{"var": "hello[world]"}</code>, the expression <code>{var}</code> expands to <code>hello%5Bworld%5D</code>.
The following table shows an output matrix for every possible operator/modifier combination produced for <code>string</code> input.
</p>
<table>
<tr><th></th><th colspan="3">Modifier</th></tr>
<tr><th>Operator</th><th><em>None</em></th><th>*</th><th>:2</th></tr>
<tr><td><code><em>None</em></code></td><td><code>hello%5Bworld%5D</code></td><td><code>hello%5Bworld%5D</code></td><td><code>he</code></td></tr>
<tr><td><code><em>+</em></code></td><td><code>hello[world]</code></td><td><code>hello[world]</code></td><td><code>he</code></td></tr>
<tr><td><code>#</code></td><td><code>#hello[world]</code></td><td><code>#hello[world]</code></td><td><code>#he</code></td></tr>
<tr><td><code>.</code></td><td><code>.hello%5Bworld%5D</code></td><td><code>.hello%5Bworld%5D</code></td><td><code>.he</code></td></tr>
<tr><td><code>/</code></td><td><code>/hello%5Bworld%5D</code></td><td><code>/hello%5Bworld%5D</code></td><td><code>/he</code></td></tr>
<tr><td><code>;</code></td><td><code>;var=hello%5Bworld%5D</code></td><td><code>;var=hello%5Bworld%5D</code></td><td><code>;var=he</code></td></tr>
<tr><td><code>?</code></td><td><code>?var=hello%5Bworld%5D</code></td><td><code>?var=hello%5Bworld%5D</code></td><td><code>?var=he</code></td></tr>
<tr><td><code>&</code></td><td><code>&var=hello%5Bworld%5D</code></td><td><code>&var=hello%5Bworld%5D</code></td><td><code>&var=he</code></td></tr>
</table>
<h3>Arrays</h3>
<p>
Given <code>{"var": ["one", "two", "three"]}</code>, the expression <code>{var}</code> expands to <code>one,two,three</code>.
The following table shows an output matrix for every possible operator/modifier combination produced for <code>array</code> input.
</p>
<table>
<tr><th></th><th colspan="3">Modifier</th></tr>
<tr><th>Operator</th><th><em>None</em></th><th>*</th><th>:2</th></tr>
<tr><td><code><em>None</em></code></td><td><code>one,two,three</code></td><td><code>one,two,three</code></td><td><code>on,tw,th</code></td></tr>
<tr><td><code><em>+</em></code></td><td><code>one,two,three</code></td><td><code>one,two,three</code></td><td><code>on,tw,th</code></td></tr>
<tr><td><code>#</code></td><td><code>#one,two,three</code></td><td><code>#one,two,three</code></td><td><code>#on,tw,th</code></td></tr>
<tr><td><code>.</code></td><td><code>.one,two,three</code></td><td><code>.one.two.three</code></td><td><code>.on,tw,th</code></td></tr>
<tr><td><code>/</code></td><td><code>/one,two,three</code></td><td><code>/one/two/three</code></td><td><code>/on,tw,th</code></td></tr>
<tr><td><code>;</code></td><td><code>;var=one,two,three</code></td><td><code>;var=one;var=two;var=three</code></td><td><code>;var=on,tw,th</code></td></tr>
<tr><td><code>?</code></td><td><code>?var=one,two,three</code></td><td><code>?var=one&var=two&var=three</code></td><td><code>?var=on,tw,th</code></td></tr>
<tr><td><code>&</code></td><td><code>&var=one,two,three</code></td><td><code>&var=one&var=two&var=three</code></td><td><code>&var=on,tw,th</code></td></tr>
</table>
<h3>Objects ("plain objects" / "hash maps")</h3>
<p>
Given <code>{"var": {"one": "alpha", "two": "bravo"}}</code>, the expression <code>{var}</code> expands to <code>one,two,three</code>.
The following table shows an output matrix for every possible operator/modifier combination produced for <code>object</code> input.
</p>
<table>
<tr><th></th><th colspan="3">Modifier</th></tr>
<tr><th>Operator</th><th><em>None</em></th><th>*</th><th>:2</th></tr>
<tr><td><code><em>None</em></code></td><td><code>one,alpha,two,bravo</code></td><td><code>one=alpha,two=bravo</code></td><td><code>on,al,tw,br</code></td></tr>
<tr><td><code><em>+</em></code></td><td><code>one,alpha,two,bravo</code></td><td><code>one=alpha,two=bravo</code></td><td><code>on,al,tw,br</code></td></tr>
<tr><td><code>#</code></td><td><code>#one,alpha,two,bravo</code></td><td><code>#one=alpha,two=bravo</code></td><td><code>#on,al,tw,br</code></td></tr>
<tr><td><code>.</code></td><td><code>.one,alpha,two,bravo</code></td><td><code>.one=alpha.two=bravo</code></td><td><code>.on,al,tw,br</code></td></tr>
<tr><td><code>/</code></td><td><code>/one,alpha,two,bravo</code></td><td><code>/one=alpha/two=bravo</code></td><td><code>/on,al,tw,br</code></td></tr>
<tr><td><code>;</code></td><td><code>;var=one,alpha,two,bravo</code></td><td><code>;one=alpha;two=bravo</code></td><td><code>;var=on,al,tw,br</code></td></tr>
<tr><td><code>?</code></td><td><code>?var=one,alpha,two,bravo</code></td><td><code>?one=alpha&two=bravo</code></td><td><code>?var=on,al,tw,br</code></td></tr>
<tr><td><code>&</code></td><td><code>&var=one,alpha,two,bravo</code></td><td><code>&one=alpha&two=bravo</code></td><td><code>&var=on,al,tw,br</code></td></tr>
</table>
<h2>Limitations</h2>
<p>URI Template is a <em>Proposed Standard</em> and because of that I did not want to deviate from it. That said I'm not at all happy with how the specification turned out. Here are some of my thoughts:</p>
<ul>
<li>The <em>explode modifier</em> works the wrong way. <code>{?some_object}</code> should lead to <code>?foo=bar&hello=world</code>, as this is the common expansion</li>
<li>The <em>prefix modifier</em> (which I would've named <em>truncate modifier</em>) only has an end-offset.
The specification says it's »used to partition an identifier space hierarchically«. <code>abc</code> may become <code>a/bc</code> or <code>a/ab/abc</code>.
But there is no way of modifying output to <code>a/b/c</code> or <code>a/b/abc</code>. Whenever I had to partition identifier spaces, I used one of the latter patterns.</li>
<li>Operators like <code>.</code> automatically prefix the expansion. So <code>{"var": ["filename", "extension"]}</code> and <code>{.var*}</code> results in <code>.filename.extension</code> - obviously not what I wanted.</li>
<li>Variable names (<em>varname</em>) may only contain <code>ALPHA / DIGIT / "_" / pct-encoded</code> and may not be decoded for resolving the reference. This simply feels weird, especially the "may not be decoded" part.</li>
<li>Other possible modifiers could include some simple character-munging like <em>UPPERCASE</em>, <em>LOWERCASE</em>, <em>CAPITALCASE</em></li>
<li><code>{/var,empty,empty}</code> results in <code>/foobar//</code> - clearly not what one intended</li>
<li><code>{var}</code> and <code>{"var" : {"a": "1", "b": "2"}}</code> results in <code>a,1,b,2</code> - excusemewhat? I would've expected <code>a=1,b=2</code> or <code>a:1,b:2</code> (in a perverse parallel universe).</li>
<li>Spaces in the <em>query string</em> should be encoded to <code>+</code>, not <code>%20</code> according to <a href="http://www.w3.org/TR/html401/interact/forms.html#form-content-type">application/x-www-form-urlencoded</a></li>
</ul>
</div>
</body>
</html>