Docs for DefaultLocationProxy

lib/sammy.js

@@ -205,15 +205,27 @@
   // The DefaultLocationProxy is the default location proxy for all Sammy applications.
   // A location proxy is a prototype that conforms to a simple interface. The purpose
   // of a location proxy is to notify the Sammy.Application its bound to when the location
-  // or 'external state' changes. The DefaultLocationProxy considers the state to be
-  // changed when the 'hash' (window.location.hash / '#') changes. It does this in two
-  // different ways depending on what browser you are using. The newest browsers
-  // (IE, Safari > 4, FF >= 3.6) support a 'onhashchange' DOM event, thats fired whenever
-  // the location.hash changes. In this situation the DefaultLocationProxy just binds
-  // to this event and delegates it to the application. In the case of older browsers
-  // a poller is set up to track changes to the hash. Unlike Sammy 0.3 or earlier,
-  // the DefaultLocationProxy allows the poller to be a global object, eliminating the
-  // need for multiple pollers even when thier are multiple apps on the page.
+  // or 'external state' changes.
+  //
+  // The `DefaultLocationProxy` watches for changes to the path of the current window and
+  // is also able to set the path based on changes in the application. It does this by
+  // using different methods depending on what is available in the current browser. In
+  // the latest and greatest browsers it used the HTML5 History API and the `pushState`
+  // `popState` events/methods. This allows you to use Sammy to serve a site behind normal
+  // URI paths as opposed to the older default of hash (#) based routing. Because the server
+  // can interpret the changed path on a refresh or re-entry, though, it requires additional
+  // support on the server side. If you'd like to force disable HTML5 history support, please
+  // use the `disable_push_state` setting on `Sammy.Application`. If pushState support
+  // is enabled, `DefaultLocationProxy` also binds to all links on the page. If a link is clicked
+  // that matches the current set of routes, the URL is changed using pushState instead of
+  // fully setting the location and the app is notified of the change.
+  //
+  // If the browser does not have support for HTML5 History, `DefaultLocationProxy` automatically
+  // falls back to the older hash based routing. The newest browsers (IE, Safari > 4, FF >= 3.6)
+  // support a 'onhashchange' DOM event, thats fired whenever the location.hash changes.
+  // In this situation the DefaultLocationProxy just binds to this event and delegates it to
+  // the application. In the case of older browsers a poller is set up to track changes to the
+  // hash.
   Sammy.DefaultLocationProxy = function(app, run_interval_every) {
     this.app = app;
     // set is native to false and start the poller immediately
@@ -231,15 +243,13 @@
     return [location_obj.pathname, location_obj.search, hash].join('');
   };
   Sammy.DefaultLocationProxy.prototype = {
-
     // bind the proxy events to the current app.
     bind: function() {
       var proxy = this, app = this.app, lp = Sammy.DefaultLocationProxy;
       $(window).bind('hashchange.' + this.app.eventNamespace(), function(e, non_native) {
         // if we receive a native hash change event, set the proxy accordingly
         // and stop polling
         if (proxy.is_native === false && !non_native) {
-          Sammy.log('native hash change exists, using');
           proxy.is_native = true;
           window.clearInterval(lp._interval);
         }