X-Git-Url: https://git.openstreetmap.org/rails.git/blobdiff_plain/1082d3a6535c5c2a777ae64a3067e9f8657bd32c..544ed362472f4e5504b1fc4c51ad7bd3fa16afae:/app/assets/javascripts/router.js diff --git a/app/assets/javascripts/router.js b/app/assets/javascripts/router.js index fbad1e28c..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,7 +76,9 @@ OSM.Router = function(map, rts) { }); } - (controller[action] || $.noop).apply(controller, params); + params = params.concat(Array.prototype.slice.call(arguments, 2)); + + return (controller[action] || $.noop).apply(controller, params); }; return route; @@ -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,72 +94,101 @@ 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); - currentRoute.run('load', currentPath); - - var stateChange; - - map.on('moveend baselayerchange overlaylayerchange', function() { - var hash = OSM.formatHash(map); - if (hash === currentHash) return; - currentHash = hash; - stateChange(OSM.parseHash(hash), hash); - }); - - $(window).on('hashchange', function() { - var hash = location.hash; - if (hash === currentHash) return; - currentHash = hash; - var state = OSM.parseHash(hash); - if (!state) return; - map.setView(state.center, state.zoom); - map.updateLayers(state.layers); - stateChange(state, hash); - }); + var router = {}; if (window.history && window.history.pushState) { - stateChange = function(state, hash) { - window.history.replaceState(state, document.title, hash); - }; - - // Set a non-null initial state, so that the e.originalEvent.state - // check below works correctly when going back to the initial page. - stateChange(OSM.parseHash(currentHash), currentPath + currentHash); - $(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; - map.setView(state.center, state.zoom, {animate: false}); - map.updateLayers(state.layers); + map.setState(e.originalEvent.state, {animate: false}); }); - return 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; - } - } else { - stateChange = function(state, hash) { - window.location.replace(hash); }; - return function (url) { + 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)); + } else { + window.history.replaceState(state, document.title, window.location); + } + }; + } else { + router.route = router.replace = function (url) { window.location.assign(url); - } + }; + + router.stateChange = function(state) { + if (state.center) window.location.replace(OSM.formatHash(state)); + }; } + + router.updateHash = function() { + var hash = OSM.formatHash(map); + if (hash === currentHash) return; + currentHash = hash; + router.stateChange(OSM.parseHash(hash)); + }; + + router.hashUpdated = function() { + var hash = location.hash; + if (hash === currentHash) return; + currentHash = hash; + var state = OSM.parseHash(hash); + map.setState(state); + router.stateChange(state, hash); + }; + + router.withoutMoveListener = function (callback) { + function disableMoveListener() { + map.off('moveend', router.updateHash); + map.once('moveend', function () { + map.on('moveend', router.updateHash); + }); + } + + map.once('movestart', disableMoveListener); + callback(); + map.off('movestart', disableMoveListener); + }; + + router.load = function() { + var loadState = currentRoute.run('load', currentPath); + 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); + + return router; };