README.md 2.82 KB
Newer Older
fxa's avatar
fxa committed
1 2
URI Template JS
===============
fxa's avatar
fxa committed
3

fxa's avatar
fxa committed
4 5 6 7 8
This is a javascript implementation of [RFC6570](http://tools.ietf.org/html/rfc6570) - URI Template,
and can expand templates up to and including Level 4 in that specification.

It exposes a constructor function UriTemplate with the two methods:

fxa's avatar
fxa committed
9 10
* (static) parse(uriTemplateText) returning an instance of UriTemplate
* expand(variables) returning an string
fxa's avatar
fxa committed
11

12 13
Be aware, that a parsed UriTemplate is frozen, so it is stateless. You can reuse instances of UriTemplates.

fxa's avatar
fxa committed
14 15 16
Requirements
------------

fxa's avatar
fxa committed
17
You can use uritemplate.js in any even not so modern browser (Tested even with IE8 in IE7-Mode), see file demo.html.
fxa's avatar
fxa committed
18 19
But you can also use it with node:

fxa's avatar
fxa committed
20 21
**npm install uritemplate**

22
and then in a node application:
23

fxa's avatar
fxa committed
24
    var
25 26
        UriTemplate = require('uritemplate'),
        template;
fxa's avatar
fxa committed
27
    template = UriTemplate.parse('{?query*})';
28
    template.expand({query: {first: 1, second: 2}});
fxa's avatar
fxa committed
29
    --> "?first=1&second=2"
fxa's avatar
fxa committed
30

31 32 33 34 35 36 37 38 39
or within a html document (see also demo.html):

    <script type="text/javascript" src="bin/uritemplate.js"></script>
    <script type="text/javascript">
        var template = UriTemplate.parse('{?query*}');
        alert(template.expand({query: {first: 1, second: 2}}));
    </script>


40 41 42
If you want to clone the git project, be aware of the submodule uritemplate-test.
So you have to to:

fxa's avatar
fxa committed
43
    git clone --recursive https://github.com/fxa/uritemplate-js.git
44

fxa's avatar
fxa committed
45
    
fxa's avatar
fxa committed
46
Build
fxa's avatar
fxa committed
47
-----
fxa's avatar
fxa committed
48 49
    npm install
    npm test
fxa's avatar
fxa committed
50

fxa's avatar
fxa committed
51 52
Tests
-----
fxa's avatar
fxa committed
53

fxa's avatar
fxa committed
54 55
The integration tests are taken from https://github.com/uri-templates/uritemplate-test as a submodule.
The tests are integrated in the Jakefile.
fxa's avatar
fxa committed
56 57 58

License
-------
fxa's avatar
fxa committed
59
Copyright 2013 Franz Antesberger
fxa's avatar
fxa committed
60 61

MIT License, see http://mit-license.org/
fxa's avatar
fxa committed
62 63 64

Release Notes
-------------
fxa's avatar
fxa committed
65
* 0.3.4 minor package.json changes to support npm install and npm test 
66
* 0.3.3 fixed https://github.com/fxa/uritemplate-js/issues/12 Pct-Encoding-Error with chars < 0x100 (missing 0-padding). Thanks to https://github.com/pfraze!
67
* 0.3.2 fixed https://github.com/fxa/uritemplate-js/issues/11 Problems with older IE versions. Thanks to anozaki!
68
* 0.3.1 fixed https://github.com/fxa/uritemplate-js/issues/10 thank you, Paul-Martin!
69
* 0.3.0 introduced UriTemplateError as exception, so the interface changed from string to UriTemplateError (as the rfc suggested)
70
* 0.2.4 fixed double encoding according [RubenVerborgh] and some Prefix modifiers bugs
fxa's avatar
fxa committed
71
* 0.2.3 fixed bug with empty objects ('{?empty}' with '{empty:{}}' shall expand to '?empty=')
72 73 74
* 0.2.2 fixed pct encoding bug with multibyte utf8 chars
* 0.2.1 fixed a bug in package.json
* 0.2.0 heavy project refactoring, splitting source files, introducing jshint (preparation of next steps)
fxa's avatar
fxa committed
75 76 77

Next Steps
----------
78
* Implementing more unit tests (now only a view tests are implemented)
fxa's avatar
fxa committed
79 80
* A new method extract(uri), which tries to extract the variables from a given uri.
  This is harder, than you might think