From 0dbd18e2bb685c432d775f186f114cf4f3de3ca4 Mon Sep 17 00:00:00 2001 From: John Firebaugh Date: Mon, 25 Nov 2013 13:08:24 -0800 Subject: [PATCH] Document/clarify OSM.Router use --- app/assets/javascripts/index.js | 12 ++--- app/assets/javascripts/index/browse.js | 2 +- app/assets/javascripts/index/history.js | 2 +- app/assets/javascripts/index/new_note.js.erb | 2 +- app/assets/javascripts/index/note.js.erb | 4 +- app/assets/javascripts/index/notes.js.erb | 2 +- app/assets/javascripts/leaflet.map.js.erb | 4 +- app/assets/javascripts/router.js | 53 ++++++++++++++++++-- 8 files changed, 64 insertions(+), 17 deletions(-) diff --git a/app/assets/javascripts/index.js b/app/assets/javascripts/index.js index ba1f08407..6f4603923 100644 --- a/app/assets/javascripts/index.js +++ b/app/assets/javascripts/index.js @@ -244,7 +244,7 @@ $(document).ready(function () { var history = OSM.History(map); - OSM.route = OSM.Router(map, { + OSM.router = OSM.Router(map, { "/": OSM.Index(map), "/search": OSM.Search(map), "/export": OSM.Export(map), @@ -257,11 +257,11 @@ $(document).ready(function () { "/browse/:type/:id(/history)": OSM.Browse(map) }); - OSM.route.load(); + OSM.router.load(); $(document).on("click", "a", function(e) { if (e.isDefaultPrevented() || e.isPropagationStopped()) return; - if (this.host === window.location.host && OSM.route(this.pathname + this.search + this.hash)) e.preventDefault(); + if (this.host === window.location.host && OSM.router.route(this.pathname + this.search + this.hash)) e.preventDefault(); }); $(".search_form").on("submit", function(e) { @@ -269,16 +269,16 @@ $(document).ready(function () { $("header").addClass("closed"); var query = $(this).find("input[name=query]").val(); if (query) { - OSM.route("/search?query=" + encodeURIComponent(query) + OSM.formatHash(map)); + OSM.router.route("/search?query=" + encodeURIComponent(query) + OSM.formatHash(map)); } else { - OSM.route("/" + OSM.formatHash(map)); + OSM.router.route("/" + OSM.formatHash(map)); } }); $(".describe_location").on("click", function(e) { e.preventDefault(); var precision = zoomPrecision(map.getZoom()); - OSM.route("/search?query=" + encodeURIComponent( + OSM.router.route("/search?query=" + encodeURIComponent( map.getCenter().lat.toFixed(precision) + "," + map.getCenter().lng.toFixed(precision))); }); diff --git a/app/assets/javascripts/index/browse.js b/app/assets/javascripts/index/browse.js index c70228501..213385790 100644 --- a/app/assets/javascripts/index/browse.js +++ b/app/assets/javascripts/index/browse.js @@ -124,7 +124,7 @@ function initializeBrowse(map) { layer.originalStyle = layer.options; layer.setStyle({color: '#0000ff', weight: 8}); - OSM.route('/browse/' + layer.feature.type + '/' + layer.feature.id); + OSM.router.route('/browse/' + layer.feature.type + '/' + layer.feature.id); // Stash the currently drawn feature selectedLayer = layer; diff --git a/app/assets/javascripts/index/history.js b/app/assets/javascripts/index/history.js index cd012ee16..639705f91 100644 --- a/app/assets/javascripts/index/history.js +++ b/app/assets/javascripts/index/history.js @@ -39,7 +39,7 @@ OSM.History = function(map) { } function clickChangeset(id) { - OSM.route($("#changeset_" + id).find(".changeset_id").attr("href")); + OSM.router.route($("#changeset_" + id).find(".changeset_id").attr("href")); } function loadData() { diff --git a/app/assets/javascripts/index/new_note.js.erb b/app/assets/javascripts/index/new_note.js.erb index 29977cd57..0541ba6e9 100644 --- a/app/assets/javascripts/index/new_note.js.erb +++ b/app/assets/javascripts/index/new_note.js.erb @@ -30,7 +30,7 @@ OSM.NewNote = function(map) { if ($(this).hasClass('disabled')) return; - OSM.route('/new_note'); + OSM.router.route('/new_note'); }); function createNote(marker, form, url) { diff --git a/app/assets/javascripts/index/note.js.erb b/app/assets/javascripts/index/note.js.erb index 1f9dbe375..aa746265c 100644 --- a/app/assets/javascripts/index/note.js.erb +++ b/app/assets/javascripts/index/note.js.erb @@ -65,8 +65,8 @@ OSM.Note = function (map) { latLng = data.coordinates.split(','); if (!window.location.hash) { - OSM.route.moveListenerOff(); - map.once('moveend', OSM.route.moveListenerOn); + OSM.router.moveListenerOff(); + map.once('moveend', OSM.router.moveListenerOn); map.getZoom() > 15 ? map.panTo(latLng) : map.setView(latLng, 16); } diff --git a/app/assets/javascripts/index/notes.js.erb b/app/assets/javascripts/index/notes.js.erb index 11363fca8..928d91fe2 100644 --- a/app/assets/javascripts/index/notes.js.erb +++ b/app/assets/javascripts/index/notes.js.erb @@ -34,7 +34,7 @@ function initializeNotes(map) { }); noteLayer.on('click', function(e) { - OSM.route('/browse/note/' + e.layer.id); + OSM.router.route('/browse/note/' + e.layer.id); }); function updateMarker(marker, feature) { diff --git a/app/assets/javascripts/leaflet.map.js.erb b/app/assets/javascripts/leaflet.map.js.erb index bfb3685a1..f65325e37 100644 --- a/app/assets/javascripts/leaflet.map.js.erb +++ b/app/assets/javascripts/leaflet.map.js.erb @@ -222,8 +222,8 @@ L.OSM.Map = L.Map.extend({ if (!window.location.hash) { var bounds = map._objectLayer.getBounds(); if (bounds.isValid()) { - OSM.route.moveListenerOff(); - map.once('moveend', OSM.route.moveListenerOn); + OSM.router.moveListenerOff(); + map.once('moveend', OSM.router.moveListenerOn); map.fitBounds(bounds); } } diff --git a/app/assets/javascripts/router.js b/app/assets/javascripts/router.js index cbd418895..88bae59ec 100644 --- a/app/assets/javascripts/router.js +++ b/app/assets/javascripts/router.js @@ -1,3 +1,50 @@ +/* + 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 + (`/browse/note/:id`) and optional segments (`/browse/:type/:id(/history)`). + + Route controller objects can define three 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('/browse/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 `/browse/way/1234` unless the map is moved). This can be done by calling + `OSM.router.moveListenerOff` and `OSM.router.moveListenerOn`. + */ OSM.Router = function(map, rts) { var escapeRegExp = /[\-{}\[\]+?.,\\\^$|#\s]/g; var optionalParam = /\((.*?)\)/g; @@ -48,7 +95,7 @@ OSM.Router = function(map, rts) { 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) { @@ -66,7 +113,7 @@ OSM.Router = function(map, rts) { } }); - router = function (url) { + router.route = function (url) { var path = url.replace(/#.*/, ''), route = routes.recognize(path); if (!route) return false; @@ -86,7 +133,7 @@ OSM.Router = function(map, rts) { } }; } else { - router = function (url) { + router.route = function (url) { window.location.assign(url); }; -- 2.39.5