From 46fbd4cd7f42e51bfc1c17c8fe4d502969ddac94 Mon Sep 17 00:00:00 2001 From: Jeremy Ashkenas Date: Thu, 26 May 2011 13:38:30 -0400 Subject: [PATCH] Controller -> Router in the docs, and adding docco for setLocation(). --- index.html | 102 ++++++++++++++++++++++++++++------------------------- 1 file changed, 54 insertions(+), 48 deletions(-) diff --git a/index.html b/index.html index 8581d473..acecf777 100644 --- a/index.html +++ b/index.html @@ -224,15 +224,16 @@
  • – create
    • - - Controller + + Router @@ -1398,39 +1399,32 @@ var othello = NYPL.create({ }); -

    Backbone.Controller

    +

    Backbone.Router

    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");

    Backbone.history

    @@ -1544,13 +1550,13 @@ openPage: function(pageNumber) { events, match the appropriate route, and trigger callbacks. You shouldn't ever have to create one of these yourself — you should use the reference to Backbone.history that will be created for you automatically if you make use - of Controllers with routes. + of Routers with routes.

    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.

    @@ -1563,8 +1569,8 @@ openPage: function(pageNumber) { 
     $(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(...);

  • "change:[attribute]" (model, collection) — when a specific attribute has been updated.
  • "destrooy" (model, collection) — when a model is destroyed.
  • "error" (model, collection) — when a model's validation fails, or a save call fails on the server.
    • -
  • "route:[name]" (controller) — when one of a controller's routes has matched.
    • +
  • "route:[name]" (router) — when one of a router's routes has matched.
  • "all" — this special event fires for any triggered event, passing the event name as the first argument.
    • @@ -2236,7 +2242,7 @@ Inbox.messages.fetch(); with sorting/filtering/aggregation logic.
  • - Backbone.Controller – Rails routes.rb + Rails controller + Backbone.Router – Rails routes.rb + Rails controller actions. Maps URLs to functions.