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 using
  46    `OSM.router.withoutMoveListener` to run a block of code that may update
  47    move the map without the hash changing.
  48  */
  49 OSM.Router = function (map, rts) {
  50   var escapeRegExp = /[-{}[\]+?.,\\^$|#\s]/g;
  51   var optionalParam = /\((.*?)\)/g;
  52   var namedParam = /(\(\?)?:\w+/g;
  53   var splatParam = /\*\w+/g;
  54
  55   function Route(path, controller) {
  56     var regexp = new RegExp("^" +
  57       path.replace(escapeRegExp, "\\$&")
  58         .replace(optionalParam, "(?:$1)?")
  59         .replace(namedParam, function (match, optional) {
  60           return optional ? match : "([^/]+)";
  61         })
  62         .replace(splatParam, "(.*?)") + "(?:\\?.*)?$");
  63
  64     var route = {};
  65
  66     route.match = function (path) {
  67       return regexp.test(path);
  68     };
  69
  70     route.run = function (action, path) {
  71       var params = [];
  72
  73       if (path) {
  74         params = regexp.exec(path).map(function (param, i) {
  75           return (i > 0 && param) ? decodeURIComponent(param) : param;
  76         });
  77       }
  78
  79       params = params.concat(Array.prototype.slice.call(arguments, 2));
  80
  81       return (controller[action] || $.noop).apply(controller, params);
  82     };
  83
  84     return route;
  85   }
  86
  87   var routes = [];
  88   for (var r in rts) {
  89     routes.push(new Route(r, rts[r]));
  90   }
  91
  92   routes.recognize = function (path) {
  93     for (var i = 0; i < this.length; i++) {
  94       if (this[i].match(path)) return this[i];
  95     }
  96   };
  97
  98   var currentPath = window.location.pathname.replace(/(.)\/$/, "$1") + window.location.search,
  99       currentRoute = routes.recognize(currentPath),
 100       currentHash = location.hash || OSM.formatHash(map);
 101
 102   var router = {};
 103
 104   $(window).on("popstate", function (e) {
 105     if (!e.originalEvent.state) return; // Is it a real popstate event or just a hash change?
 106     var path = window.location.pathname + window.location.search,
 107         route = routes.recognize(path);
 108     if (path === currentPath) return;
 109     currentRoute.run("unload", null, route === currentRoute);
 110     currentPath = path;
 111     currentRoute = route;
 112     currentRoute.run("popstate", currentPath);
 113     map.setState(e.originalEvent.state, { animate: false });
 114   });
 115
 116   router.route = function (url) {
 117     var path = url.replace(/#.*/, ""),
 118         route = routes.recognize(path);
 119     if (!route) return false;
 120     currentRoute.run("unload", null, route === currentRoute);
 121     var state = OSM.parseHash(url);
 122     map.setState(state);
 123     window.history.pushState(state, document.title, url);
 124     currentPath = path;
 125     currentRoute = route;
 126     currentRoute.run("pushstate", currentPath);
 127     return true;
 128   };
 129
 130   router.replace = function (url) {
 131     window.history.replaceState(OSM.parseHash(url), document.title, url);
 132   };
 133
 134   router.stateChange = function (state) {
 135     if (state.center) {
 136       window.history.replaceState(state, document.title, OSM.formatHash(state));
 137     } else {
 138       window.history.replaceState(state, document.title, window.location);
 139     }
 140   };
 141
 142   router.updateHash = function () {
 143     var hash = OSM.formatHash(map);
 144     if (hash === currentHash) return;
 145     currentHash = hash;
 146     router.stateChange(OSM.parseHash(hash));
 147   };
 148
 149   router.hashUpdated = function () {
 150     var hash = location.hash;
 151     if (hash === currentHash) return;
 152     currentHash = hash;
 153     var state = OSM.parseHash(hash);
 154     map.setState(state);
 155     router.stateChange(state, hash);
 156   };
 157
 158   router.withoutMoveListener = function (callback) {
 159     function disableMoveListener() {
 160       map.off("moveend", router.updateHash);
 161       map.once("moveend", function () {
 162         map.on("moveend", router.updateHash);
 163       });
 164     }
 165
 166     map.once("movestart", disableMoveListener);
 167     callback();
 168     map.off("movestart", disableMoveListener);
 169   };
 170
 171   router.load = function () {
 172     var loadState = currentRoute.run("load", currentPath);
 173     router.stateChange(loadState || {});
 174   };
 175
 176   router.setCurrentPath = function (path) {
 177     currentPath = path;
 178     currentRoute = routes.recognize(currentPath);
 179   };
 180
 181   map.on("moveend baselayerchange overlaylayerchange", router.updateHash);
 182   $(window).on("hashchange", router.hashUpdated);
 183
 184   return router;
 185 };