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