Web applications often choose to change their URL fragment (#fragment) in order to provide shareable, bookmarkable URLs for an Ajax-heavy application. - Backbone.Controller provides methods for routing client-side URL + Backbone.Router provides methods for routing client-side URL fragments, and connecting them to actions and events.
-- Backbone controllers do not yet make use of HTML5 pushState and - replaceState. Currently, pushState and replaceState - need special handling on the server-side, cause you to mint duplicate URLs, - and have an incomplete API. We may start supporting them in the future - when these issues have been resolved. -
-- During page load, after your application has finished creating all of its controllers, - be sure to call Backbone.history.start() to route the initial URL. + During page load, after your application has finished creating all of its routers, + be sure to call Backbone.history.start(), or + Backbone.history.start({pushState: true}) to route the initial URL.
-
- extendBackbone.Controller.extend(properties, [classProperties])
+
+ extendBackbone.Router.extend(properties, [classProperties])
- Get started by creating a custom controller class. You'll
+ Get started by creating a custom router class. You'll
want to define actions that are triggered when certain URL fragments are
- matched, and provide a routes hash
+ matched, and provide a routes hash
that pairs routes to actions.
-var Workspace = Backbone.Controller.extend({
+var Workspace = Backbone.Router.extend({
routes: {
"help": "help", // #help
@@ -1449,10 +1443,10 @@ var Workspace = Backbone.Controller.extend({
});
-
- routescontroller.routes
+
+ routesrouter.routes
- The routes hash maps URLs with parameters to functions on your controller,
+ The routes hash maps URLs with parameters to functions on your router,
similar to the View's events hash.
Routes can contain parameter parts, :param, which match a single URL
component between slashes; and splat parts *splat, which can match
@@ -1470,9 +1464,9 @@ var Workspace = Backbone.Controller.extend({
When the visitor presses the back button, or enters a URL, and a particular route is matched, the name of the action will be fired as an - event, so that other objects can listen to the controller, + event, so that other objects can listen to the router, and be notified. In the following example, visiting #help/uploading - will fire a route:help event from the controller. + will fire a route:help event from the router.
@@ -1485,25 +1479,25 @@ routes: {
-controller.bind("route:help", function(page) {
+router.bind("route:help", function(page) {
...
});
-
- constructor / initializenew Controller([options])
+
+ constructor / initializenew Router([options])
- When creating a new controller, you may pass its
- routes hash directly as an option, if you
+ When creating a new router, you may pass its
+ routes hash directly as an option, if you
choose. All options will also be passed to your initialize
function, if defined.
- routecontroller.route(route, name, callback)
+
+ routerouter.route(route, name, callback)
- Manually create a route for the controller, The route argument may
- be a routing string or regular expression.
+ Manually create a route for the router, The route argument may
+ be a routing string or regular expression.
Each matching capture from the route or regular expression will be passed as
an argument to the callback. The name argument will be triggered as
a "route:name" event whenever the route is matched.
@@ -1521,8 +1515,8 @@ initialize: function(options) {
}
-
- saveLocationcontroller.saveLocation(fragment)
+
+ saveLocationrouter.saveLocation(fragment)
Whenever you reach a point in your application that you'd like to save
as a URL, call saveLocation in order to update the URL fragment
@@ -1535,6 +1529,18 @@ openPage: function(pageNumber) {
this.document.pages.at(pageNumber).open();
this.saveLocation("page/" + pageNumber);
}
+
+
+
+ setLocationrouter.setLocation(fragment)
+
+ Just like saveLocation, 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.
+
+app.setLocation("help/troubleshooting");
startBackbone.history.start()
- When all of your Controllers have been created,
+ When all of your Routers have been created,
and all of the routes are set up properly, call Backbone.history.start()
to begin monitoring hashchange events, and dispatching routes.
$(function(){
- new WorkspaceController();
- new HelpPaneController();
+ new WorkspaceRouter();
+ new HelpPaneRouter();
Backbone.history.start();
});
@@ -2103,7 +2109,7 @@ var model = localBackbone.Model.extend(...);
Tzigla, a collaborative drawing
application where artists make tiles that connect to each other to
create surreal drawings.
- Backbone models help organize the code, controllers provide
+ Backbone models help organize the code, routers provide
bookmarkable deep links,
and the views are rendered with
haml.js and
@@ -2123,7 +2129,7 @@ var model = localBackbone.Model.extend(...);
Michael Aufreiter is building an open source document authoring and publishing engine: Substance. - Substance makes use of Backbone.View and Backbone.Controller, while + Substance makes use of Backbone.View and Backbone.Router, while Backbone plays well together with Data.js, which is used for data persistence. @@ -2153,7 +2159,7 @@ var model = localBackbone.Model.extend(...);