Document/clarify OSM.Router use

diff --git a/app/assets/javascripts/index.js b/app/assets/javascripts/index.js
index ba1f08407d1587343bf5b6532faab2ff52a36e6b..6f4603923a4d4783168c434c8fc6e80f3deaa447 100644 (file)
--- a/app/assets/javascripts/index.js
+++ b/app/assets/javascripts/index.js
@@ -244,7 +244,7 @@ $(document).ready(function () {
 
   var history = OSM.History(map);
 
 
   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),
     "/":                           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)
   });
 
     "/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;
 
   $(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) {
   });
 
   $(".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) {
     $("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 {
     } 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());
     }
   });
 
   $(".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)));
   });
       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 c70228501a2e8f32f91fd4a8375e94407abe8117..2133857908f60e910bbd797008d27bd41f7ac476 100644 (file)
--- 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});
 
     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;
 
     // Stash the currently drawn feature
     selectedLayer = layer;

diff --git a/app/assets/javascripts/index/history.js b/app/assets/javascripts/index/history.js
index cd012ee160275e896e73b6cdcc9dff263957f10d..639705f91c33ca364347795b0b03b27912e8d139 100644 (file)
--- 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) {
   }
 
   function clickChangeset(id) {

-    OSM.route($("#changeset_" + id).find(".changeset_id").attr("href"));
+    OSM.router.route($("#changeset_" + id).find(".changeset_id").attr("href"));

   }
 
   function loadData() {
   }
 
   function loadData() {

diff --git a/app/assets/javascripts/index/new_note.js.erb b/app/assets/javascripts/index/new_note.js.erb
index 29977cd5775e5e542aa8a6351db84e15ed8bfeab..0541ba6e92a72f177c50a9bb58844c0488842c2b 100644 (file)
--- 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;
 
 
     if ($(this).hasClass('disabled')) return;
 

-    OSM.route('/new_note');
+    OSM.router.route('/new_note');

   });
 
   function createNote(marker, form, url) {
   });
 
   function createNote(marker, form, url) {

diff --git a/app/assets/javascripts/index/note.js.erb b/app/assets/javascripts/index/note.js.erb
index 1f9dbe37538313ccbf0ef30b229cd6ecdad4cc9a..aa746265cb409ed595228b97cc040bb88c3f5577 100644 (file)
--- 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) {
       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);
     }
 
       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 11363fca8ed64c40a0522e9910fe10c104280e59..928d91fe2fee5fc18d0eb637776bc4ae800a4f3b 100644 (file)
--- 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) {
   });
 
   noteLayer.on('click', function(e) {

-    OSM.route('/browse/note/' + e.layer.id);
+    OSM.router.route('/browse/note/' + e.layer.id);

   });
 
   function updateMarker(marker, feature) {
   });
 
   function updateMarker(marker, feature) {

diff --git a/app/assets/javascripts/leaflet.map.js.erb b/app/assets/javascripts/leaflet.map.js.erb
index bfb3685a1750e9fd772707c2922b5646c497426d..f65325e37b94cffbd580afa25e1f647409918975 100644 (file)
--- 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()) {
         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);
           }
         }
             map.fitBounds(bounds);
           }
         }

diff --git a/app/assets/javascripts/router.js b/app/assets/javascripts/router.js
index cbd41889590b32114b9f8134511687278339ee90..88bae59ecb214eda71e96dfcf5e3322a0c416a76 100644 (file)
--- 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;
 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);
 
     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 (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;
       var path = url.replace(/#.*/, ''),
         route = routes.recognize(path);
       if (!route) return false;


@@ -86,7 +133,7 @@ OSM.Router = function(map, rts) {
       }
     };
   } else {
       }
     };
   } else {

-    router = function (url) {
+    router.route = function (url) {

       window.location.assign(url);
     };
 
       window.location.assign(url);
     };