diff options
Diffstat (limited to 'uri-template.html')
| -rw-r--r-- | uri-template.html | 234 |
1 files changed, 234 insertions, 0 deletions
diff --git a/uri-template.html b/uri-template.html new file mode 100644 index 000000000..d49065c9c --- /dev/null +++ b/uri-template.html @@ -0,0 +1,234 @@ +<!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>
\ No newline at end of file |