<!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&amp;b=jupiter&amp;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 "&amp;"; and,</td></tr>
        <tr><td><code>&amp;</code></td><td>Continuation of query-style &amp;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>&amp;</code></td><td><code>&amp;var=hello%5Bworld%5D</code></td><td><code>&amp;var=hello%5Bworld%5D</code></td><td><code>&amp;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&amp;var=two&amp;var=three</code></td><td><code>?var=on,tw,th</code></td></tr>
        <tr><td><code>&amp;</code></td><td><code>&amp;var=one,two,three</code></td><td><code>&amp;var=one&amp;var=two&amp;var=three</code></td><td><code>&amp;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&amp;two=bravo</code></td><td><code>?var=on,al,tw,br</code></td></tr>
        <tr><td><code>&amp;</code></td><td><code>&amp;var=one,alpha,two,bravo</code></td><td><code>&amp;one=alpha&amp;two=bravo</code></td><td><code>&amp;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&amp;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>