]> git.openstreetmap.org Git - rails.git/blob - app/assets/javascripts/router.js
Merge pull request #14 from tomhughes/routing
[rails.git] / app / assets / javascripts / router.js
1 /*
2   OSM.Router implements pushState-based navigation for the main page and
3   other pages that use a sidebar+map based layout (export, search results,
4   history, and browse pages).
5
6   For browsers without pushState, it falls back to full page loads, which all
7   of the above pages support.
8
9   The router is initialized with a set of routes: a mapping of URL path templates
10   to route controller objects. Path templates can contain placeholders
11   (`/note/:id`) and optional segments (`/:type/:id(/history)`).
12
13   Route controller objects can define four methods that are called at defined
14   times during routing:
15
16      * The `load` method is called by the router when a path which matches the
17        route's path template is loaded via a normal full page load. It is passed
18        as arguments the URL path plus any matching arguments for placeholders
19        in the path template.
20
21      * The `pushstate` method is called when a page which matches the route's path
22        template is loaded via pushState. It is passed the same arguments as `load`.
23
24      * The `popstate` method is called when returning to a previously
25        pushState-loaded page via popstate (i.e. browser back/forward buttons).
26
27      * The `unload` method is called on the exiting route controller when navigating
28        via pushState or popstate to another route.
29
30    Note that while `load` is not called by the router for pushState-based loads,
31    it's frequently useful for route controllers to call it manually inside their
32    definition of the `pushstate` and `popstate` methods.
33
34    An instance of OSM.Router is assigned to `OSM.router`. To navigate to a new page
35    via pushState (with automatic full-page load fallback), call `OSM.router.route`:
36
37        OSM.router.route('/way/1234');
38
39    If `route` is passed a path that matches one of the path templates, it performs
40    the appropriate actions and returns true. Otherwise it returns false.
41
42    OSM.Router also handles updating the hash portion of the URL containing transient
43    map state such as the position and zoom level. Some route controllers may wish to
44    temporarily suppress updating the hash (for example, to omit the hash on pages
45    such as `/way/1234` unless the map is moved). This can be done by calling
46    `OSM.router.moveListenerOff` and `OSM.router.moveListenerOn`.
47  */
48 OSM.Router = function(map, rts) {
49   var escapeRegExp  = /[\-{}\[\]+?.,\\\^$|#\s]/g;
50   var optionalParam = /\((.*?)\)/g;
51   var namedParam    = /(\(\?)?:\w+/g;
52   var splatParam    = /\*\w+/g;
53
54   function Route(path, controller) {
55     var regexp = new RegExp('^' +
56       path.replace(escapeRegExp, '\\$&')
57         .replace(optionalParam, '(?:$1)?')
58         .replace(namedParam, function(match, optional){
59           return optional ? match : '([^\/]+)';
60         })
61         .replace(splatParam, '(.*?)') + '(?:\\?.*)?$');
62
63     var route = {};
64
65     route.match = function(path) {
66       return regexp.test(path);
67     };
68
69     route.run = function(action, path) {
70       var params = [];
71
72       if (path) {
73         params = regexp.exec(path).map(function(param, i) {
74           return (i > 0 && param) ? decodeURIComponent(param) : param;
75         });
76       }
77
78       return (controller[action] || $.noop).apply(controller, params);
79     };
80
81     return route;
82   }
83
84   var routes = [];
85   for (var r in rts)
86     routes.push(Route(r, rts[r]));
87
88   routes.recognize = function(path) {
89     for (var i = 0; i < this.length; i++) {
90       if (this[i].match(path)) return this[i];
91     }
92   };
93
94   var currentPath = window.location.pathname.replace(/(.)\/$/, '$1') + window.location.search,
95     currentRoute = routes.recognize(currentPath),
96     currentHash = location.hash || OSM.formatHash(map);
97
98   var router = {};
99
100   if (window.history && window.history.pushState) {
101     $(window).on('popstate', function(e) {
102       if (!e.originalEvent.state) return; // Is it a real popstate event or just a hash change?
103       var path = window.location.pathname + window.location.search;
104       if (path === currentPath) return;
105       currentRoute.run('unload');
106       currentPath = path;
107       currentRoute = routes.recognize(currentPath);
108       currentRoute.run('popstate', currentPath);
109       map.setState(e.originalEvent.state, {animate: false});
110     });
111
112     router.route = function (url) {
113       var path = url.replace(/#.*/, ''),
114         route = routes.recognize(path);
115       if (!route) return false;
116       currentRoute.run('unload');
117       window.history.pushState(OSM.parseHash(url), document.title, url);
118       currentPath = path;
119       currentRoute = route;
120       currentRoute.run('pushstate', currentPath);
121       return true;
122     };
123
124     router.stateChange = function(state) {
125       if (state.center) {
126         window.history.replaceState(state, document.title, OSM.formatHash(state));
127       } else {
128         window.history.replaceState(state, document.title, window.location);
129       }
130     };
131   } else {
132     router.route = function (url) {
133       window.location.assign(url);
134     };
135
136     router.stateChange = function(state) {
137       if (state.center) window.location.replace(OSM.formatHash(state));
138     };
139   }
140
141   router.updateHash = function() {
142     var hash = OSM.formatHash(map);
143     if (hash === currentHash) return;
144     currentHash = hash;
145     router.stateChange(OSM.parseHash(hash));
146   };
147
148   router.hashUpdated = function() {
149     var hash = location.hash;
150     if (hash === currentHash) return;
151     currentHash = hash;
152     var state = OSM.parseHash(hash);
153     map.setState(state);
154     router.stateChange(state, hash);
155   };
156
157   router.moveListenerOn = function() {
158     map.on('moveend', router.updateHash);
159   };
160
161   router.moveListenerOff = function() {
162     map.off('moveend', router.updateHash);
163   };
164
165   router.load = function() {
166     var loadState = currentRoute.run('load', currentPath);
167     router.stateChange(loadState || {});
168   };
169
170   router.setCurrentPath = function (path) {
171     currentPath = path;
172     currentRoute = routes.recognize(currentPath);
173   };
174
175   map.on('moveend baselayerchange overlaylayerchange', router.updateHash);
176   $(window).on('hashchange', router.hashUpdated);
177
178   return router;
179 };