1 | [![Build Status](https://travis-ci.org/tildeio/route-recognizer.svg)](https://travis-ci.org/tildeio/route-recognizer)
|
2 |
|
3 | # About
|
4 | `route-recognizer` is a lightweight JavaScript library (under 2k!) that
|
5 | can be used as the recognizer for a more comprehensive router system
|
6 | (such as [`router.js`](https://github.com/tildeio/router.js)).
|
7 |
|
8 | In keeping with the Unix philosophy, it is a modular library that does one
|
9 | thing and does it well.
|
10 |
|
11 | # Usage
|
12 |
|
13 | Create a new router:
|
14 |
|
15 | ```javascript
|
16 | var router = new RouteRecognizer();
|
17 | ```
|
18 |
|
19 | Add a simple new route description:
|
20 |
|
21 | ```javascript
|
22 | router.add([{ path: "/posts", handler: handler }]);
|
23 | ```
|
24 |
|
25 | Every route can optionally have a name:
|
26 | ```javascript
|
27 | router.add([{ path: "/posts", handler: handler }], { as: "routeName"});
|
28 | ```
|
29 |
|
30 | The handler is an opaque object with no specific meaning to
|
31 | `route-recognizer`. A module using `route-recognizer` could
|
32 | use functions or other objects with domain-specific semantics
|
33 | for what to do with the handler.
|
34 |
|
35 | A route description can have handlers at various points along
|
36 | the path:
|
37 |
|
38 | ```javascript
|
39 | router.add([
|
40 | { path: "/admin", handler: admin },
|
41 | { path: "/posts", handler: posts }
|
42 | ]);
|
43 | ```
|
44 |
|
45 | Recognizing a route will return a list of the handlers and
|
46 | their associated parameters:
|
47 |
|
48 | ```javascript
|
49 | var result = router.recognize("/admin/posts");
|
50 | result === [
|
51 | { handler: admin, params: {} },
|
52 | { handler: posts, params: {} }
|
53 | ];
|
54 | ```
|
55 |
|
56 | Dynamic segments:
|
57 |
|
58 | ```javascript
|
59 | router.add([
|
60 | { path: "/posts/:id", handler: posts },
|
61 | { path: "/comments", handler: comments }
|
62 | ]);
|
63 |
|
64 | result = router.recognize("/posts/1/comments");
|
65 | result === [
|
66 | { handler: posts, params: { id: "1" } },
|
67 | { handler: comments, params: {} }
|
68 | ];
|
69 | ```
|
70 |
|
71 | A dynamic segment matches any character but `/`.
|
72 |
|
73 | Star segments:
|
74 |
|
75 | ```javascript
|
76 | router.add([{ path: "/pages/*path", handler: page }]);
|
77 |
|
78 | result = router.recognize("/pages/hello/world");
|
79 | result === [{ handler: page, params: { path: "hello/world" } }];
|
80 | ```
|
81 |
|
82 | # Sorting
|
83 |
|
84 | If multiple routes all match a path, `route-recognizer`
|
85 | will pick the one with the fewest dynamic segments:
|
86 |
|
87 | ```javascript
|
88 | router.add([{ path: "/posts/edit", handler: editPost }]);
|
89 | router.add([{ path: "/posts/:id", handler: showPost }]);
|
90 | router.add([{ path: "/posts/new", handler: newPost }]);
|
91 |
|
92 | var result1 = router.recognize("/posts/edit");
|
93 | result1 === [{ handler: editPost, params: {} }];
|
94 |
|
95 | var result2 = router.recognize("/posts/1");
|
96 | result2 === [{ handler: showPost, params: { id: "1" } }];
|
97 |
|
98 | var result3 = router.recognize("/posts/new");
|
99 | result3 === [{ handler: newPost, params: {} }];
|
100 | ```
|
101 |
|
102 | As you can see, this has the expected result. Explicit
|
103 | static paths match more closely than dynamic paths.
|
104 |
|
105 | This is also true when comparing star segments and other
|
106 | dynamic segments. The recognizer will prefer fewer star
|
107 | segments and prefer using them for less of the match (and,
|
108 | consequently, using dynamic and static segments for more
|
109 | of the match).
|
110 |
|
111 | # Building / Running Tests
|
112 |
|
113 | This project uses Ember CLI and Broccoli for building and testing.
|
114 |
|
115 | ## Getting Started
|
116 |
|
117 | Run the following commands to get going:
|
118 |
|
119 | ```bash
|
120 | npm install
|
121 | bower install
|
122 | ```
|
123 |
|
124 | The above assumes that you have `bower` installed globally (you can install
|
125 | via `npm install -g bower` if you do not).
|
126 |
|
127 | ## Running Tests
|
128 |
|
129 | Run the following:
|
130 |
|
131 | ```
|
132 | npm start
|
133 | ```
|
134 |
|
135 | At this point you can navigate to the url specified in the Testem UI (usually
|
136 | http://localhost:7357/). As you change the project the tests will rerun.
|
137 |
|
138 | ## Building
|
139 |
|
140 | ```
|
141 | npm run build
|
142 | ```
|