replacing setLocation and saveLocation with navigate, after Spine's API.

backbone.js

@@ -691,17 +691,9 @@
       }, this));
     },
 
-    // Simple proxy to `Backbone.history` to save a fragment into the history,
-    // without triggering routes.
-    saveLocation : function(fragment) {
-      Backbone.history.saveLocation(fragment);
-    },
-
-    // Simple proxy to `Backbone.history` to both save a fragment into the
-    // history and to then load the route at that fragment.
-    setLocation : function(fragment) {
-      Backbone.history.saveLocation(fragment);
-      Backbone.history.loadUrl(fragment);
+    // Simple proxy to `Backbone.history` to save a fragment into the history.
+    navigate : function(fragment, triggerRoute) {
+      Backbone.history.navigate(fragment, triggerRoute);
     },
 
     // Bind all defined routes to `Backbone.history`. We have to reverse the
@@ -792,7 +784,7 @@
       var oldIE             = (isExplorer.exec(navigator.userAgent.toLowerCase()) && (!docMode || docMode <= 7));
       if (oldIE) {
         this.iframe = $('<iframe src="javascript:0" tabindex="-1" />').hide().appendTo('body')[0].contentWindow;
-        this.saveLocation(fragment);
+        this.navigate(fragment);
       }
 
       // Depending on whether we're using pushState or hashes, and whether
@@ -830,7 +822,7 @@
       var current = this.getFragment();
       if (current == this.fragment && this.iframe) current = this.getFragment(this.iframe.location.hash);
       if (current == this.fragment || current == decodeURIComponent(this.fragment)) return false;
-      if (this.iframe) this.saveLocation(current);
+      if (this.iframe) this.navigate(current);
       this.loadUrl() || this.loadUrl(window.location.hash);
     },
 
@@ -851,7 +843,7 @@
     // Save a fragment into the hash history. You are responsible for properly
     // URL-encoding the fragment in advance. This does not trigger
     // a `hashchange` event.
-    saveLocation : function(fragment) {
+    navigate : function(fragment, triggerRoute) {
       fragment = (fragment || '').replace(hashStrip, '');
       if (this.fragment == fragment || this.fragment == decodeURIComponent(fragment)) return;
       if (this._hasPushState) {
@@ -866,6 +858,7 @@
           this.iframe.location.hash = fragment;
         }
       }
+      if (triggerRoute) this.loadUrl(fragment);
     }
 
   });

index.html

@@ -232,8 +232,7 @@
       <li>– <a href="#Router-routes">routes</a></li>
       <li>– <a href="#Router-constructor">constructor / initialize</a></li>
       <li>– <a href="#Router-route">route</a></li>
-      <li>– <a href="#Router-saveLocation">saveLocation</a></li>
-      <li>– <a href="#Router-setLocation">setLocation</a></li>
+      <li>– <a href="#Router-navigate">navigate</a></li>
     </ul>
 
     <a class="toc_title" href="#History">
@@ -379,9 +378,12 @@ <h2 id="Upgrading">Upgrading to 0.5.0</h2>
 
     <p>
       We've taken the opportunity to clarify some naming with the <b>0.5.0</b>
-      release. <tt>Controller</tt> is now <tt>Router</tt>, and <tt>refresh</tt>
-      is now <tt>reset</tt>. Be sure to <a href="#History-start">opt-in</a> to 
-      <tt>pushState</tt> support, if you want to use it.
+      release. <tt>Controller</tt> is now <a href="#Router">Router</a>, and 
+      <tt>refresh</tt> is now <a href="#Collection-reset">reset</a>. 
+      The previous <tt>saveLocation</tt> and <tt>setLocation</tt>
+      functions have peen replaced by <a href="#Router-navigate">navigate</a>. 
+      Be sure to <a href="#History-start">opt-in</a> to <tt>pushState</tt> support, 
+      if you want to use it.
     </p>
 
     <h2 id="Introduction">Introduction</h2>
@@ -1538,39 +1540,30 @@ <h2 id="Router">Backbone.Router</h2>
 }
 </pre>
 
-    <p id="Router-saveLocation">
-      <b class="header">saveLocation</b><code>router.saveLocation(fragment)</code>
+    <p id="Router-navigate">
+      <b class="header">navigate</b><code>router.navigate(fragment, [triggerRoute])</code>
       <br />
       Whenever you reach a point in your application that you'd like to save
-      as a URL, call <b>saveLocation</b> in order to update the URL fragment
-      without triggering an event that would cause a route to be called. 
-      If you wish to also trigger the event, use <a href="#Router-setLocation">setLocation</a>.
+      as a URL, call <b>navigate</b> in order to update the URL.
+      If you wish to also call the route function, pass <b>triggerRoute</b>.
     </p>
 
 <pre>
 openPage: function(pageNumber) {
   this.document.pages.at(pageNumber).open();
-  this.saveLocation("page/" + pageNumber);
+  this.navigate("page/" + pageNumber);
 }
-</pre>
 
-    <p id="Router-setLocation">
-      <b class="header">setLocation</b><code>router.setLocation(fragment)</code>
-      <br />
-      Just like <a href="#Router-saveLocation">saveLocation</a>, but also triggers
-      your route action at the same time. Useful if you want to transition to a page
-      where no state serialization is necessary, like a simple string.
-    </p>
-
-<pre>
-app.setLocation("help/troubleshooting");
+# Or ...
+
+app.navigate("help/troubleshooting", true);
 </pre>
 
     <h2 id="History">Backbone.history</h2>
 
     <p>
       <b>History</b> serves as a global router (per frame) to handle <tt>hashchange</tt>
-      events, match the appropriate route, and trigger callbacks. You shouldn't
+      events or <tt>pushState</tt>, match the appropriate route, and trigger callbacks. You shouldn't
       ever have to create one of these yourself &mdash; you should use the reference
       to <tt>Backbone.history</tt> that will be created for you automatically if you make use
       of <a href="#Router">Routers</a> with <a href="#Router-routes">routes</a>.
@@ -2464,6 +2457,7 @@ <h2 id="changelog">Change Log</h2>
       <tt>Collection#refresh</tt> was renamed to <tt>Collection#reset</tt> to emphasize
       its ability to both reset the collection with new models, as well as empty
       out the collection when used with no parameters.
+      <tt>saveLocation</tt> was replaced with <tt>navigate</tt>.
       RESTful persistence methods (save, fetch, etc.) now return the jQuery deferred
       object for further success/error chaining and general convenience.
       Improved XSS escaping for <tt>Model#escape</tt>.