X-Git-Url: https://git.openstreetmap.org./rails.git/blobdiff_plain/2b4f8e92c969a5508b73ae7af45811a118fda6b1..e0706f06b19b04295cf8c87acceb536d96eaf427:/app/assets/javascripts/router.js diff --git a/app/assets/javascripts/router.js b/app/assets/javascripts/router.js index cbd418895..0f37e32f1 100644 --- a/app/assets/javascripts/router.js +++ b/app/assets/javascripts/router.js @@ -1,3 +1,51 @@ +/* + OSM.Router implements pushState-based navigation for the main page and + other pages that use a sidebar+map based layout (export, search results, + history, and browse pages). + + For browsers without pushState, it falls back to full page loads, which all + of the above pages support. + + The router is initialized with a set of routes: a mapping of URL path templates + to route controller objects. Path templates can contain placeholders + (`/note/:id`) and optional segments (`/:type/:id(/history)`). + + Route controller objects can define four methods that are called at defined + times during routing: + + * The `load` method is called by the router when a path which matches the + route's path template is loaded via a normal full page load. It is passed + as arguments the URL path plus any matching arguments for placeholders + in the path template. + + * The `pushstate` method is called when a page which matches the route's path + template is loaded via pushState. It is passed the same arguments as `load`. + + * The `popstate` method is called when returning to a previously + pushState-loaded page via popstate (i.e. browser back/forward buttons). + + * The `unload` method is called on the exiting route controller when navigating + via pushState or popstate to another route. + + Note that while `load` is not called by the router for pushState-based loads, + it's frequently useful for route controllers to call it manually inside their + definition of the `pushstate` and `popstate` methods. + + An instance of OSM.Router is assigned to `OSM.router`. To navigate to a new page + via pushState (with automatic full-page load fallback), call `OSM.router.route`: + + OSM.router.route('/way/1234'); + + If `route` is passed a path that matches one of the path templates, it performs + the appropriate actions and returns true. Otherwise it returns false. + + OSM.Router also handles updating the hash portion of the URL containing transient + map state such as the position and zoom level. Some route controllers may wish to + temporarily suppress updating the hash (for example, to omit the hash on pages + such as `/way/1234` unless the map is moved). This can be done by using + `OSM.router.withoutMoveListener` to run a block of code that may update + move the map without the hash changing. + */ OSM.Router = function(map, rts) { var escapeRegExp = /[\-{}\[\]+?.,\\\^$|#\s]/g; var optionalParam = /\((.*?)\)/g; @@ -28,6 +76,8 @@ OSM.Router = function(map, rts) { }); } + params = params.concat(Array.prototype.slice.call(arguments, 2)); + return (controller[action] || $.noop).apply(controller, params); }; @@ -36,7 +86,7 @@ OSM.Router = function(map, rts) { var routes = []; for (var r in rts) - routes.push(Route(r, rts[r])); + routes.push(new Route(r, rts[r])); routes.recognize = function(path) { for (var i = 0; i < this.length; i++) { @@ -44,40 +94,43 @@ OSM.Router = function(map, rts) { } }; - var currentPath = window.location.pathname + window.location.search, + var currentPath = window.location.pathname.replace(/(.)\/$/, '$1') + window.location.search, currentRoute = routes.recognize(currentPath), currentHash = location.hash || OSM.formatHash(map); - var router, stateChange; + var router = {}; if (window.history && window.history.pushState) { $(window).on('popstate', function(e) { if (!e.originalEvent.state) return; // Is it a real popstate event or just a hash change? - var path = window.location.pathname + window.location.search; + var path = window.location.pathname + window.location.search, + route = routes.recognize(path); if (path === currentPath) return; - currentRoute.run('unload'); + currentRoute.run('unload', null, route === currentRoute); currentPath = path; - currentRoute = routes.recognize(currentPath); + currentRoute = route; currentRoute.run('popstate', currentPath); - var state = e.originalEvent.state; - if (state.center) { - map.setView(state.center, state.zoom, {animate: false}); - map.updateLayers(state.layers); - } + map.setState(e.originalEvent.state, {animate: false}); }); - router = function (url) { + router.route = function (url) { var path = url.replace(/#.*/, ''), route = routes.recognize(path); if (!route) return false; - window.history.pushState(OSM.parseHash(url) || {}, document.title, url); - currentRoute.run('unload'); + currentRoute.run('unload', null, route === currentRoute); + var state = OSM.parseHash(url); + map.setState(state); + window.history.pushState(state, document.title, url); currentPath = path; currentRoute = route; currentRoute.run('pushstate', currentPath); return true; }; + router.replace = function (url) { + window.history.replaceState(OSM.parseHash(url), document.title, url); + }; + router.stateChange = function(state) { if (state.center) { window.history.replaceState(state, document.title, OSM.formatHash(state)); @@ -86,7 +139,7 @@ OSM.Router = function(map, rts) { } }; } else { - router = function (url) { + router.route = router.replace = function (url) { window.location.assign(url); }; @@ -107,18 +160,21 @@ OSM.Router = function(map, rts) { if (hash === currentHash) return; currentHash = hash; var state = OSM.parseHash(hash); - if (!state) return; - map.setView(state.center, state.zoom); - map.updateLayers(state.layers); + map.setState(state); router.stateChange(state, hash); }; - router.moveListenerOn = function() { - map.on('moveend', router.updateHash); - }; + router.withoutMoveListener = function (callback) { + function disableMoveListener() { + map.off('moveend', router.updateHash); + map.once('moveend', function () { + map.on('moveend', router.updateHash); + }); + } - router.moveListenerOff = function() { - map.off('moveend', router.updateHash); + map.once('movestart', disableMoveListener); + callback(); + map.off('movestart', disableMoveListener); }; router.load = function() { @@ -126,6 +182,11 @@ OSM.Router = function(map, rts) { router.stateChange(loadState || {}); }; + router.setCurrentPath = function (path) { + currentPath = path; + currentRoute = routes.recognize(currentPath); + }; + map.on('moveend baselayerchange overlaylayerchange', router.updateHash); $(window).on('hashchange', router.hashUpdated);