PageRenderTime 85ms CodeModel.GetById 3ms app.highlight 72ms RepoModel.GetById 1ms app.codeStats 0ms

/chapters/06-extensions.md

https://github.com/bicccio/backbone-fundamentals
Markdown | 1125 lines | 807 code | 318 blank | 0 comment | 0 complexity | be6844dada1ad7cc7d6cd0b89043dca0 MD5 | raw file
   1# Backbone Extensions
   2
   3Backbone is flexible, simple, and powerful. However, you may find that the complexity of the application you are working on requires more than what it provides out of the box. There are certain concerns which it just doesn't address directly as one of it's goals is to be minimalist. 
   4
   5Take for example Views, which provide a default `render` method which does nothing and produces no real results when called, despite most implementations using it to generate the HTML that the view manages. Also, Models and Collections have no built-in way of handling nested hierarchies - if you require this functionality, you need to write it yourself or use a plugin.
   6
   7In these cases, there are many existing Backbone plugins which can provide advanced solutions for large-scale Backbone apps. A fairly complete list of plugins and frameworks available can be found on the Backbone [wiki](https://github.com/documentcloud/backbone/wiki/Extensions%2C-Plugins%2C-Resources). Using these add-ons, there is enough for applications of most sizes to be completed successfully.
   8
   9In this section of the book we will look at two popular Backbone add-ons: MarionetteJS and Thorax.
  10
  11## MarionetteJS (Backbone.Marionette)
  12
  13*By Derick Bailey & Addy Osmani*
  14
  15As we've seen, Backbone provides a great set of building blocks for our JavaScript applications. It gives us the core constructs that are needed to build small to mid-sized apps, organize jQuery DOM events, or create single page apps that support mobile devices and large scale enterprise needs. But Backbone is not a complete framework. It's a set of building blocks that leaves much of the application design, architecture, and scalability to the developer, including memory management, view management, and more.
  16
  17[MarionetteJS](http://marionettejs.com) (a.k.a Backbone.Marionette) provides many of the features that the non-trivial application developer needs, above what Backbone itself provides. It is a composite application library that aims to simplify the construction of large scale applications. It does this by providing a collection of common design and implementation patterns found in the applications that the creator, [Derick Bailey](http://lostechies.com/derickbailey/), and many other [contributors](https://github.com/marionettejs/backbone.marionette/graphs/contributors) have been using to build Backbone apps.
  18 
  19
  20Marionette's key benefits include:
  21
  22* Scaling applications out with modular, event driven architecture
  23* Sensible defaults, such as using Underscore templates for view rendering
  24* Easy to modify to make it work with your application's specific needs
  25* Reducing boilerplate for views, with specialized view types
  26* Build on a modular architecture with an Application and modules that attach to it
  27* Compose your application's visuals at runtime, with Region and Layout
  28* Nested views and layouts within visual regions
  29* Built-in memory management and zombie killing in views, regions, and layouts
  30* Built-in event clean up with the EventBinder
  31* Event-driven architecture with the EventAggregator
  32* Flexible, "as-needed" architecture allowing you to pick and choose what you need
  33* And much, much more
  34
  35Marionette follows a similar philosophy to Backbone in that it provides a suite of components that can be used independently of each other, or used together to create significant advantages for us as developers. But it steps above the structural components of Backbone and provides an application layer, with more than a dozen components and building blocks.
  36
  37Marionette's components range greatly in the features they provide, but they all work together to create a composite application layer that can both reduce boilerplate code and provide a much needed application structure. Its core components include various and specialized view types that take the boilerplate out of rendering common Backbone.Model and Backbone.Collection scenarios; an Application object and Module architecture to scale applications across sub-applications, features and files; integration of a command pattern, event aggregator, and request/response mechanism; and many more object types that can be extended in a myriad of ways to create an architecture that facilitates an application's specific needs. 
  38
  39In spite of the large number of constructs that Marionette provides, though, you're not required to use all of it just because you want to use some of it. Much like Backbone itself, you can pick and choose which features you want to use and when. This allows you to work with other Backbone frameworks and plugins very easily. It also means that you are not required to engage in an all-or-nothing migration to begin using Marionette.
  40
  41### Boilerplate Rendering Code
  42
  43Consider the code that it typically requires to render a view with Backbone and Underscore template. We need a template to render, which can be placed in the DOM directly, and we need the JavaScript that defines a view that uses the template and populates it with data from a model.
  44
  45```
  46<script type="text/html" id="my-view-template">
  47  <div class="row">
  48    <label>First Name:</label>
  49    <span><%= firstName %></span>
  50  </div>
  51  <div class="row">
  52    <label>Last Name:</label>
  53    <span><%= lastName %></span>
  54  </div>
  55  <div class="row">
  56    <label>Email:</label>
  57    <span><%= email %></span>
  58  </div>
  59</script>
  60```
  61
  62```javascript
  63var MyView = Backbone.View.extend({
  64  template: $('#my-view-template').html(),
  65
  66  render: function(){
  67
  68    // compile the Underscore.js template
  69    var compiledTemplate = _.template(this.template);
  70
  71    // render the template with the model data
  72    var data = this.model.toJSON();
  73    var html = compiledTemplate(data);
  74
  75    // populate the view with the rendered html
  76    this.$el.html(html);
  77  }
  78});
  79```
  80
  81Once this is in place, you need to create an instance of your view and pass your model into it. Then you can take the view's `el` and append it to the DOM in order to display the view.
  82
  83```javascript
  84var Derick = new Person({
  85  firstName: 'Derick',
  86  lastName: 'Bailey',
  87  email: 'derickbailey@example.com'
  88});
  89
  90var myView = new MyView({
  91  model: Derick
  92})
  93
  94myView.render();
  95
  96$('#content').html(myView.el)
  97```
  98
  99This is a standard set up for defining, building, rendering, and displaying a view with Backbone. This is also what we call "boilerplate code" - code that is repeated over and over and over again, across every project and every implementation with the same functionality. It gets to be tedious and repetitious very quickly.
 100
 101Enter Marionette's `ItemView` - a simple way to reduce the boilerplate of defining a view.
 102
 103### Reducing Boilerplate With Marionette.ItemView
 104
 105All of Marionette's view types - with the exception of `Marionette.View` - include a built-in `render` method that handles the core rendering logic for you. We can take advantage of this by changing the `MyView` instance to inherit from one of these rather than `Backbone.View`. Instead of having to provide our own `render` method for the view, we can let Marionette render it for us. We'll still use the same Underscore.js template and rendering mechanism, but the implementation of this is hidden behind the scenes. Thus, we can reduce the amount of code needed for this view.
 106
 107
 108```javascript
 109var MyView = Marionette.ItemView.extend({
 110  template: '#my-view-template'
 111});
 112```
 113
 114And that's it - that's all you need to get the exact same behaviour as the previous view implementation. Just replace `Backbone.View.extend` with `Marionette.ItemView.extend`, then get rid of the `render` method. You can still create the view instance with a `model`, call the `render` method on the view instance, and display the view in the DOM the same way that we did before. But the view definition has been reduced to a single line of configuration for the template.
 115
 116### Memory Management
 117
 118In addition to the reduction of code needed to define a view, Marionette includes some advanced memory management in all of its views, making the job of cleaning up a view instance and it's event handlers easy.
 119
 120Consider the following view implementation:
 121
 122```javascript
 123var ZombieView = Backbone.View.extend({
 124  template: '#my-view-template',
 125
 126  initialize: function(){
 127
 128    // bind the model change to re-render this view
 129    this.model.on('change', this.render, this);
 130
 131  },
 132
 133  render: function(){
 134
 135    // This alert is going to demonstrate a problem
 136    alert('We`re rendering the view');
 137
 138  }
 139});
 140```
 141
 142If we create two instances of this view using the same variable name for both instances, and then change a value in the model, how many times will we see the alert box?
 143
 144
 145```javascript
 146
 147var Person = Backbone.Model.extend({
 148  defaults: {
 149    "firstName": "Jeremy",
 150    "lastName": "Ashkenas",
 151    "email":    "jeremy@example.com"
 152  }
 153});
 154
 155var Derick = new Person({
 156  firstName: 'Derick',
 157  lastName: 'Bailey',
 158  email: 'derick@example.com'
 159});
 160
 161
 162// create the first view instance
 163var zombieView = new ZombieView({
 164  model: Derick
 165});
 166
 167// create a second view instance, re-using
 168// the same variable name to store it
 169zombieView = new ZombieView({
 170  model: Derick
 171});
 172
 173Derick.set('email', 'derickbailey@example.com');
 174```
 175
 176Since we're re-using the same `zombieView` variable for both instances, the first instance of the view will fall out of scope immediately after the second is created. This allows the JavaScript garbage collector to come along and clean it up, which should mean the first view instance is no longer active and no longer going to respond to the model's "change" event.
 177
 178But when we run this code, we end up with the alert box showing up twice!
 179
 180The problem is caused by the model event binding in the view's `initialize` method. Whenever we pass `this.render` as the callback method to the model's `on` event binding, the model itself is being given a direct reference to the view instance. Since the model is now holding a reference to the view instance, replacing the `zombieView` variable with a new view instance is not going to let the original view fall out of scope. The model still has a reference, therefore the view is still in scope.
 181
 182Since the original view is still in scope, and the second view instance is also in scope, changing data on the model will cause both view instances to respond.
 183
 184Fixing this is easy, though. You just need to call `stopListening` when the view is done with its work and ready to be closed. To do this, add a `close` method to the view.
 185
 186```javascript
 187var ZombieView = Backbone.View.extend({
 188  template: '#my-view-template',
 189
 190  initialize: function(){
 191    // bind the model change to re-render this view
 192    this.listenTo(this.model, 'change', this.render);
 193  },
 194
 195  close: function(){
 196    // unbind the events that this view is listening to
 197    this.stopListening();
 198  },
 199
 200  render: function(){
 201
 202    // This alert is going to demonstrate a problem
 203    alert('We`re rendering the view');
 204
 205  }
 206});
 207```
 208
 209Then call `close` on the first instance when it is no longer needed, and only one view instance will remain alive. For more information about the `listenTo` and `stopListening` functions, see the earlier Backbone Basics chapter and Derick's post on [Managing Events As Relationships, Not Just Resources](http://lostechies.com/derickbailey/2013/02/06/managing-events-as-relationships-not-just-references/).
 210
 211```javascript
 212var Jeremy = new Person({
 213  firstName: 'Jeremy',
 214  lastName: 'Ashkenas',
 215  email: 'jeremy@example.com'
 216});
 217
 218// create the first view instance
 219var zombieView = new ZombieView({
 220  model: Person
 221})
 222zombieView.close(); // double-tap the zombie
 223
 224// create a second view instance, re-using
 225// the same variable name to store it
 226zombieView = new ZombieView({
 227  model: Person
 228})
 229
 230Person.set('email', 'jeremyashkenas@example.com');
 231```
 232
 233Now we only see one alert box when this code runs. 
 234
 235Rather than having to manually remove these event handlers, though, we can let Marionette do it for us.
 236
 237```javascript
 238var ZombieView = Marionette.ItemView.extend({
 239  template: '#my-view-template',
 240
 241  initialize: function(){
 242
 243    // bind the model change to re-render this view
 244    this.listenTo(this.model, 'change', this.render);
 245
 246  },
 247
 248  render: function(){
 249
 250    // This alert is going to demonstrate a problem
 251    alert('We`re rendering the view');
 252
 253  }
 254});
 255```
 256
 257Notice in this case we are using a method called `listenTo`. This method comes from Backbone.Events, and is available in all objects that mix in Backbone.Events - including most Marionette objects. The `listenTo` method signature is similar to that of the `on` method, with the exception of passing the object that triggers the event as the first parameter. 
 258
 259Marionette's views also provide a `close` event, in which the event bindings that are set up with the `listenTo` are automatically removed. This means we no longer need to define a `close` method directly, and when we use the `listenTo` method, we know that our events will be removed and our views will not turn into zombies.
 260
 261But how do we automate the call to `close` on a view, in the real application? When and where do we call that? Enter the `Marionette.Region` - an object that manages the lifecycle of an individual view.
 262
 263### Region Management
 264
 265After a view is created, it typically needs to be placed in the DOM so that it becomes visible. This is usually done with a jQuery selector and setting the `html()` of the resulting object:
 266
 267```javascript
 268var Joe = new Person({
 269  firstName: 'Joe',
 270  lastName: 'Bob',
 271  email: 'joebob@example.com'
 272});
 273
 274var myView = new MyView({
 275  model: Joe
 276})
 277
 278myView.render();
 279
 280// show the view in the DOM
 281$('#content').html(myView.el)
 282```
 283
 284This, again, is boilerplate code. We shouldn't have to manually call `render` and manually select the DOM elements to show the view. Furthermore, this code doesn't lend itself to closing any previous view instance that might be attached to the DOM element we want to populate. And we've seen the danger of zombie views already.
 285
 286To solve these problems, Marionette provides a `Region` object - an object that manages the lifecycle of individual views, displayed in a particular DOM element.
 287
 288```javascript
 289// create a region instance, telling it which DOM element to manage
 290var myRegion = new Marionette.Region({
 291  el: '#content'
 292});
 293
 294// show a view in the region
 295var view1 = new MyView({ /* ... */ });
 296myRegion.show(view1);
 297
 298// somewhere else in the code,
 299// show a different view
 300var view2 = new MyView({ /* ... */ });
 301myRegion.show(view2);
 302```
 303
 304There are several things to note, here. First, we're telling the region what DOM element to manage by specifying an `el` in the region instance. Second, we're no longer calling the `render` method on our views. And lastly, we're not calling `close` on our view, either, though this is getting called for us.
 305
 306When we use a region to manage the lifecycle of our views, and display the views in the DOM, the region itself handles these concerns. By passing a view instance into the `show` method of the region, it will call the render method on the view for us. It will then take the resulting `el` of the view and populate the DOM element.
 307
 308The next time we call the `show` method of the region, the region remembers that it is currently displaying a view. The region calls the `close` method on the view, removes it from the DOM, and then proceeds to run the render & display code for the new view that was passed in.
 309
 310Since the region handles calling `close` for us, and we're using the `listenTo` event binder in our view instance, we no longer have to worry about zombie views in our application.
 311
 312Regions are not limited to just Marionette views, though. Any valid Backbone.View can be managed by a Marionette.Region. If your view happens to have a `close` method, it will be called when the view is closed. If not, the Backbone.View built-in method, `remove`, will be called instead. 
 313
 314### Marionette Todo app
 315
 316Having learned about Marionette's high-level concepts, let's explore refactoring the Todo application we created in our first exercise to use it. The complete code for this application can be found in Derick's TodoMVC [fork](https://github.com/derickbailey/todomvc/tree/marionette/labs/architecture-examples/backbone_marionette/js).
 317
 318Our final implementation will be visually and functionally equivalent to the original app, as seen below.
 319
 320![](img/marionette_todo0.png)
 321
 322First, we define an application object representing our base TodoMVC app. This will contain initialization code and define the default layout regions for our app. 
 323
 324**TodoMVC.js:**
 325
 326```javascript
 327var TodoMVC = new Backbone.Marionette.Application();
 328
 329TodoMVC.addRegions({
 330  header : '#header',
 331  main   : '#main',
 332  footer : '#footer'
 333});
 334
 335TodoMVC.on('initialize:after', function(){
 336  Backbone.history.start();
 337});
 338```
 339
 340Regions are used to manage the content that's displayed within specific elements, and the `addRegions` method on the `TodoMVC` object is just a shortcut for creating `Region` objects. We supply a jQuery selector for each region to manage (e.g., `#header`, `#main`, and `#footer`) and then tell the region to show various Backbone views within that region.
 341
 342Once the application object has been initialized, we call `Backbone.history.start()` to route the initial URL.
 343
 344Next, we define our Layouts. A layout is a specialized type of view that directly extends `Marionette.ItemView`. This means it's intended to render a single template and may or may not have a model (or `item`) associated with the template.
 345
 346One of the main differences between a Layout and an `ItemView` is that the layout contains regions. When defining a Layout, we supply it with both a `template` and the regions that the template contains. After rendering the layout, we can display other views within the layout using the regions that were defined.
 347
 348In our TodoMVC Layout module below, we define Layouts for:
 349
 350* Header: where we can create new Todos
 351* Footer: where we summarize how many Todos are remaining/have been completed
 352
 353
 354This captures some of the view logic that was previously in our `AppView` and `TodoView`.
 355
 356Note that Marionette modules (such as the below) offer a simple module system which is used to create privacy and encapsulation in Marionette apps. These certainly don't have to be used however, and later on in this section we'll provide links to alternative implementations using RequireJS + AMD instead.
 357
 358
 359**TodoMVC.Layout.js:**
 360
 361```javascript
 362TodoMVC.module('Layout', function(Layout, App, Backbone, Marionette, $, _){
 363
 364  // Layout Header View
 365  // ------------------
 366
 367  Layout.Header = Marionette.ItemView.extend({
 368    template : '#template-header',
 369
 370    // UI bindings create cached attributes that
 371    // point to jQuery selected objects
 372    ui : {
 373      input : '#new-todo'
 374    },
 375
 376    events : {
 377      'keypress #new-todo':   'onInputKeypress'
 378    },
 379
 380    onInputKeypress : function(evt) {
 381      var ENTER_KEY = 13;
 382      var todoText = this.ui.input.val().trim();
 383
 384      if ( evt.which === ENTER_KEY && todoText ) {
 385        this.collection.create({
 386          title : todoText
 387        });
 388        this.ui.input.val('');
 389      }
 390    }
 391  });
 392
 393  // Layout Footer View
 394  // ------------------
 395  
 396
 397  Layout.Footer = Marionette.Layout.extend({
 398    template : '#template-footer',
 399
 400    // UI bindings create cached attributes that
 401    // point to jQuery selected objects
 402    ui : {
 403      count   : '#todo-count strong',
 404      filters : '#filters a'
 405    },
 406
 407    events : {
 408      'click #clear-completed' : 'onClearClick'
 409    },
 410
 411    initialize : function() {
 412      this.listenTo(App.vent, 'todoList:filter', this.updateFilterSelection);
 413      this.listenTo(this.collection, 'all', this.updateCount);
 414    },
 415
 416    onRender : function() {
 417      this.updateCount();
 418    },
 419
 420    updateCount : function() {
 421      var count = this.collection.getActive().length;
 422      this.ui.count.html(count);
 423
 424      if (count === 0) {
 425        this.$el.parent().hide();
 426      } else {
 427        this.$el.parent().show();
 428      }
 429    },
 430
 431    updateFilterSelection : function(filter) {
 432      this.ui.filters
 433        .removeClass('selected')
 434        .filter('[href="#' + filter + '"]')
 435        .addClass('selected');
 436    },
 437
 438    onClearClick : function() {
 439      var completed = this.collection.getCompleted();
 440      completed.forEach(function destroy(todo) {
 441        todo.destroy();
 442      });
 443    }
 444  });
 445
 446});
 447
 448```
 449
 450Next, we tackle application routing and workflow, such as controlling Layouts in the page which can be shown or hidden.
 451
 452Recall how Backbone routes trigger methods within the Router as shown below in our original Workspace router from our first exercise:
 453
 454```javascript
 455  var Workspace = Backbone.Router.extend({
 456    routes:{
 457      '*filter': 'setFilter'
 458    },
 459
 460    setFilter: function( param ) {
 461      // Set the current filter to be used
 462      window.app.TodoFilter = param.trim() || '';
 463
 464      // Trigger a collection filter event, causing hiding/unhiding
 465      // of Todo view items
 466      window.app.Todos.trigger('filter');
 467    }
 468  });
 469
 470```
 471
 472Marionette uses the concept of an AppRouter to simplify routing. This reduces the boilerplate for handling route events and allows routers to be configured to call methods on an object directly. We configure our AppRouter using `appRoutes` which replaces the `'*filter': 'setFilter'` route defined in our original router and invokes a method on our Controller.
 473
 474The TodoList Controller, also found in this next code block, handles some of the remaining visibility logic originally found in `AppView` and `TodoView`, albeit using very readable Layouts.
 475
 476**TodoMVC.TodoList.js:**
 477
 478```javascript
 479TodoMVC.module('TodoList', function(TodoList, App, Backbone, Marionette, $, _){
 480
 481  // TodoList Router
 482  // ---------------
 483  //
 484  // Handle routes to show the active vs complete todo items
 485
 486  TodoList.Router = Marionette.AppRouter.extend({
 487    appRoutes : {
 488      '*filter': 'filterItems'
 489    }
 490  });
 491
 492  // TodoList Controller (Mediator)
 493  // ------------------------------
 494  //
 495  // Control the workflow and logic that exists at the application
 496  // level, above the implementation detail of views and models
 497  
 498  TodoList.Controller = function(){
 499    this.todoList = new App.Todos.TodoList();
 500  };
 501
 502  _.extend(TodoList.Controller.prototype, {
 503
 504    // Start the app by showing the appropriate views
 505    // and fetching the list of todo items, if there are any
 506    start: function(){
 507      this.showHeader(this.todoList);
 508      this.showFooter(this.todoList);
 509      this.showTodoList(this.todoList);
 510
 511      this.todoList.fetch();
 512    },
 513
 514    showHeader: function(todoList){
 515      var header = new App.Layout.Header({
 516        collection: todoList
 517      });
 518      App.header.show(header);
 519    },
 520
 521    showFooter: function(todoList){
 522      var footer = new App.Layout.Footer({
 523        collection: todoList
 524      });
 525      App.footer.show(footer);
 526    },
 527
 528    showTodoList: function(todoList){
 529      App.main.show(new TodoList.Views.ListView({
 530        collection : todoList
 531      }));
 532    },
 533
 534    // Set the filter to show complete or all items
 535    filterItems: function(filter){
 536      App.vent.trigger('todoList:filter', filter.trim() || '');
 537    }
 538  });
 539
 540  // TodoList Initializer
 541  // --------------------
 542  //
 543  // Get the TodoList up and running by initializing the mediator
 544  // when the the application is started, pulling in all of the
 545  // existing Todo items and displaying them.
 546  
 547  TodoList.addInitializer(function(){
 548
 549    var controller = new TodoList.Controller();
 550    new TodoList.Router({
 551      controller: controller
 552    });
 553
 554    controller.start();
 555
 556  });
 557
 558});
 559
 560```
 561
 562####Controllers
 563
 564In this particular app, note that Controllers don't add a great deal to the overall workflow. In general, Marionette's philosophy on routers is that they should be an afterthought in the implementation of applications. Quite often, we've seen developers abuse Backbone's routing system by making it the sole controller of the entire application workflow and logic.
 565
 566This inevitably leads to mashing every possible combination of code into the router methods - view creation, model loading, coordinating different parts of the app, etc. Developers such as Derick view this as a violation of the [single-responsibility principle](http://en.wikipedia.org/wiki/Single_responsibility_principle) (SRP) and separation of concerns.
 567
 568
 569Backbone's router and history exist to deal with a specific aspect of browsers - managing the forward and back buttons. Marionette's philosophy is that it should be limited to that, with the code that gets executed by the navigation being somewhere else. This allows the application to be used with or without a router. We can call a controller's "show" method from a button click, from an application event handler, or from a router, and we will end up with the same application state no matter how we called that method.
 570
 571Derick has written extensively about his thoughts on this topic, which you can read more about on his blog:
 572
 573* [http://lostechies.com/derickbailey/2011/12/27/the-responsibilities-of-the-various-pieces-of-backbone-js/](http://lostechies.com/derickbailey/2011/12/27/the-responsibilities-of-the-various-pieces-of-backbone-js/)
 574* [http://lostechies.com/derickbailey/2012/01/02/reducing-backbone-routers-to-nothing-more-than-configuration/](http://lostechies.com/derickbailey/2012/01/02/reducing-backbone-routers-to-nothing-more-than-configuration/)
 575* [http://lostechies.com/derickbailey/2012/02/06/3-stages-of-a-backbone-applications-startup/](http://lostechies.com/derickbailey/2012/02/06/3-stages-of-a-backbone-applications-startup/)
 576
 577#### CompositeView
 578
 579Our next task is defining the actual views for individual Todo items and lists of items in our TodoMVC application. For this, we make use of Marionette's `CompositeView`s. The idea behind a CompositeView is that it represents a visualization of a composite or hierarchical structure of leaves (or nodes) and branches.
 580
 581Think of these views as being a hierarchy of parent-child models, and recursive by default. The same CompositeView type will be used to render each item in a collection that is handled by the composite view. For non-recursive hierarchies, we are able to override the item view by defining an `itemView` attribute.
 582
 583For our Todo List Item View, we define it as an ItemView, then our Todo List View is a CompositeView where we override the `itemView` setting and tell it to use the Todo List item View for each item in the collection.
 584
 585
 586TodoMVC.TodoList.Views.js
 587
 588```javascript
 589TodoMVC.module('TodoList.Views', function(Views, App, Backbone, Marionette, $, _){
 590
 591  // Todo List Item View
 592  // -------------------
 593  //
 594  // Display an individual todo item, and respond to changes
 595  // that are made to the item, including marking completed.
 596
 597  Views.ItemView = Marionette.ItemView.extend({
 598      tagName : 'li',
 599      template : '#template-todoItemView',
 600
 601      ui : {
 602        edit : '.edit'
 603      },
 604
 605      events : {
 606        'click .destroy' : 'destroy',
 607        'dblclick label' : 'onEditClick',
 608        'keypress .edit' : 'onEditKeypress',
 609        'click .toggle'  : 'toggle'
 610      },
 611
 612      initialize : function() {
 613        this.listenTo(this.model, 'change', this.render);
 614      },
 615
 616      onRender : function() {
 617        this.$el.removeClass('active completed');
 618        if (this.model.get('completed')) this.$el.addClass('completed');
 619        else this.$el.addClass('active');
 620      },
 621
 622      destroy : function() {
 623        this.model.destroy();
 624      },
 625
 626      toggle  : function() {
 627        this.model.toggle().save();
 628      },
 629
 630      onEditClick : function() {
 631        this.$el.addClass('editing');
 632        this.ui.edit.focus();
 633      },
 634
 635      onEditKeypress : function(evt) {
 636        var ENTER_KEY = 13;
 637        var todoText = this.ui.edit.val().trim();
 638
 639        if ( evt.which === ENTER_KEY && todoText ) {
 640          this.model.set('title', todoText).save();
 641          this.$el.removeClass('editing');
 642        }
 643      }
 644  });
 645
 646  // Item List View
 647  // --------------
 648  //
 649  // Controls the rendering of the list of items, including the
 650  // filtering of active vs completed items for display.
 651
 652  Views.ListView = Marionette.CompositeView.extend({
 653      template : '#template-todoListCompositeView',
 654      itemView : Views.ItemView,
 655      itemViewContainer : '#todo-list',
 656
 657      ui : {
 658        toggle : '#toggle-all'
 659      },
 660
 661      events : {
 662        'click #toggle-all' : 'onToggleAllClick'
 663      },
 664
 665      initialize : function() {
 666        this.listenTo(this.collection, 'all', this.update);
 667      },
 668
 669      onRender : function() {
 670        this.update();
 671      },
 672
 673      update : function() {
 674        function reduceCompleted(left, right) { return left && right.get('completed'); }
 675        var allCompleted = this.collection.reduce(reduceCompleted,true);
 676        this.ui.toggle.prop('checked', allCompleted);
 677
 678        if (this.collection.length === 0) {
 679          this.$el.parent().hide();
 680        } else {
 681          this.$el.parent().show();
 682        }
 683      },
 684
 685      onToggleAllClick : function(evt) {
 686        var isChecked = evt.currentTarget.checked;
 687        this.collection.each(function(todo){
 688          todo.save({'completed': isChecked});
 689        });
 690      }
 691  });
 692
 693  // Application Event Handlers
 694  // --------------------------
 695  //
 696  // Handler for filtering the list of items by showing and
 697  // hiding through the use of various CSS classes
 698  
 699  App.vent.on('todoList:filter',function(filter) {
 700    filter = filter || 'all';
 701    $('#todoapp').attr('class', 'filter-' + filter);
 702  });
 703
 704});
 705
 706```
 707
 708At the end of the last code block, you will also notice an event handler using `vent`. This is an event aggregator that allows us to handle `filterItem` triggers from our TodoList controller.
 709
 710Finally, we define the model and collection for representing our Todo items. These are semantically not very different from the original versions we used in our first exercise and have been re-written to better fit in with Derick's preferred style of coding.
 711
 712**Todos.js:**
 713
 714```javascript
 715TodoMVC.module('Todos', function(Todos, App, Backbone, Marionette, $, _){
 716
 717  // Todo Model
 718  // ----------
 719  
 720  Todos.Todo = Backbone.Model.extend({
 721    localStorage: new Backbone.LocalStorage('todos-backbone'),
 722
 723    defaults: {
 724      title     : '',
 725      completed : false,
 726      created   : 0
 727    },
 728
 729    initialize : function() {
 730      if (this.isNew()) this.set('created', Date.now());
 731    },
 732
 733    toggle  : function() {
 734      return this.set('completed', !this.isCompleted());
 735    },
 736
 737    isCompleted: function() { 
 738      return this.get('completed'); 
 739    }
 740  });
 741
 742  // Todo Collection
 743  // ---------------
 744
 745  Todos.TodoList = Backbone.Collection.extend({
 746    model: Todos.Todo,
 747
 748    localStorage: new Backbone.LocalStorage('todos-backbone'),
 749
 750    getCompleted: function() {
 751      return this.filter(this._isCompleted);
 752    },
 753
 754    getActive: function() {
 755      return this.reject(this._isCompleted);
 756    },
 757
 758    comparator: function( todo ) {
 759      return todo.get('created');
 760    },
 761
 762    _isCompleted: function(todo){
 763      return todo.isCompleted();
 764    }
 765  });
 766
 767});
 768
 769```
 770
 771We finally kick-start everything off in our application index file, by calling `start` on our main application object:
 772
 773Initialization:
 774
 775```javascript
 776      $(function(){
 777        // Start the TodoMVC app (defined in js/TodoMVC.js)
 778        TodoMVC.start();
 779      });
 780```
 781
 782And that's it!
 783
 784### Is the Marionette implementation of the Todo app more maintainable?
 785
 786Derick feels that maintainability largely comes down to modularity, separating responsibilities (Single Responsibility Principle and Separation of Concerns) by using patterns to keep concerns from being mixed together. It can, however, be difficult to simply extract things into separate modules for the sake of extraction, abstraction, or dividing the concept down into its simplest parts.
 787
 788The Single Responsibility Principle (SRP) tells us quite the opposite - that we need to understand the context in which things change. What parts always change together, in _this_ system? What parts can change independently? Without knowing this, we won't know what pieces should be broken out into separate components and modules versus put together into the same module or object.
 789
 790The way Derick organizes his apps into modules is by creating a breakdown of concepts at each level. A higher level module is a higher level of concern - an aggregation of responsibilities. Each responsibility is broken down into an expressive API set that is implemented by lower level modules (Dependency Inversion Principle). These are coordinated through a mediator - which he typically refers to as the Controller in a module.
 791
 792
 793The way Derick organizes his files also plays directly into maintainability and he has also written posts about the importance of keeping a sane application folder structure that I recommend reading:
 794
 795* [http://lostechies.com/derickbailey/2012/02/02/javascript-file-folder-structures-just-pick-one/](http://lostechies.com/derickbailey/2012/02/02/javascript-file-folder-structures-just-pick-one/)
 796* [http://hilojs.codeplex.com/discussions/362875#post869640](http://hilojs.codeplex.com/discussions/362875#post869640)
 797
 798### Marionette And Flexibility
 799
 800Marionette is a flexible framework, much like Backbone itself. It offers a wide variety of tools to help create and organize an application architecture on top of Backbone, but like Backbone itself, it doesn't dictate that you have to use all of its pieces in order to use any of them.
 801
 802The flexibility and versatility in Marionette is easiest to understand by examining three variations of TodoMVC implemented with it that have been created for comparison purposes:
 803
 804* [Simple](https://github.com/jsoverson/todomvc/tree/master/labs/architecture-examples/backbone_marionette) - by Jarrod Overson
 805* [RequireJS](https://github.com/jsoverson/todomvc/tree/master/labs/dependency-examples/backbone_marionette_require) - also by Jarrod
 806* [Marionette modules](https://github.com/derickbailey/todomvc/tree/marionette/labs/architecture-examples/backbone_marionette/js) - by Derick Bailey
 807
 808**The simple version**: This version of TodoMVC shows some raw use of Marionette's various view types, an application object, and the event aggregator. The objects that are created are added directly to the global namespace and are fairly straightforward. This is a great example of how Marionette can be used to augment existing code without having to re-write everything around Marionette.
 809
 810**The RequireJS version**: Using Marionette with RequireJS helps to create a modularized application architecture - a tremendously important concept in scaling JavaScript applications. RequireJS provides a powerful set of tools that can be leveraged to great advantage, making Marionette even more flexible than it already is.
 811
 812**The Marionette module version**: RequireJS isn't the only way to create a modularized application architecture, though. For those that wish to build applications in modules and namespaces, Marionette provides a built-in module and namespacing structure. This example application takes the simple version of the application and re-writes it into a namespaced application architecture, with an application controller (mediator / workflow object) that brings all of the pieces together.
 813
 814Marionette certainly provides its share of opinions on how a Backbone application should be architected. The combination of modules, view types, event aggregator, application objects, and more, can be used to create a very powerful and flexible architecture based on these opinions.
 815
 816But as you can see, Marionette isn't a completely rigid, "my way or the highway" framework. It provides many elements of an application foundation that can be mixed and matched with other architectural styles, such as AMD or namespacing, or provide simple augmentation to existing projects by reducing boilerplate code for rendering views.
 817
 818
 819This flexibility creates a much greater opportunity for Marionette to provide value to you and your projects, as it allows you to scale the use of Marionette with your application's needs.
 820
 821### And So Much More
 822
 823This is just the tip of the proverbial iceberg for Marionette, even for the `ItemView` and `Region` objects that we've explored. There is far more functionality, more features, and more flexibility and customizability that can be put to use in both of these objects. Then we have the other dozen or so components that Marionette provides, each with their own set of behaviors built in, customization and extension points, and more.
 824
 825To learn more about Marionette's components, the features they provide and how to use them, check out the Marionette documentation, links to the wiki, to the source code, the project core contributors, and much more at [http://marionettejs.com](http://marionettejs.com).
 826
 827
 828<p>&nbsp;</p>
 829<p>&nbsp;</p>
 830
 831
 832
 833## Thorax
 834
 835*By Ryan Eastridge & Addy Osmani*
 836
 837Part of Backbone's appeal is that it provides structure but is generally un-opinionated, in particular when it comes to views. Thorax makes an opinionated decision to use Handlebars as its templating solution. Some of the patterns found in Marionette are found in Thorax as well. Marionette exposes most of these patterns as JavaScript APIs while in Thorax they are often exposed as template helpers. This chapter assumes the reader has knowledge of Handlebars.
 838
 839
 840Thorax was created by Ryan Eastridge and Kevin Decker to create Walmart's mobile web application. This chapter is limited to Thorax's templating features and patterns implemented in Thorax that you can utilize in your application regardless of whether you choose to adopt Thorax. To learn more about other features implemented in Thorax and to download boilerplate projects visit the [Thorax website](http://thoraxjs.org).
 841
 842### Hello World
 843
 844In Backbone, when creating a new view, options passed are merged into any default options already present on a view and are exposed via `this.options` for later reference.
 845
 846`Thorax.View` differs from `Backbone.View` in that there is no `options` object. All arguments passed to the constructor become properties of the view, which in turn become available to the `template`:
 847
 848```javascript
 849    var view = new Thorax.View({
 850        greeting: 'Hello',
 851        template: Handlebars.compile('{{greeting}} World!')
 852    });
 853    view.appendTo('body');
 854```
 855
 856In most examples in this chapter a `template` property will be specified. In larger projects including the boilerplate projects provided on the Thorax website a `name` property would instead be used and a `template` of the same file name in your project would automatically be assigned to the view.
 857
 858 If a `model` is set on a view, its attributes also become available to the template:
 859
 860    var view = new Thorax.View({
 861        model: new Thorax.Model({key: 'value'}),
 862        template: Handlebars.compile('{{key}}')
 863    });
 864
 865### Embedding child views
 866
 867The view helper allows you to embed other views within a view. Child views can be specified as properties of the view:
 868
 869```javascript
 870    var parent = new Thorax.View({
 871        child: new Thorax.View(...),
 872        template: Handlebars.compile('{{view child}}')
 873    });
 874```
 875
 876Or the name of a child view to initialize as well as any optional properties you wish to pass. In this case the child view must have previously been created with `extend` and given a `name` property:
 877
 878```javascript
 879    var ChildView = Thorax.View.extend({
 880        name: 'child',
 881        template: ...
 882    });
 883  
 884    var parent = new Thorax.View({
 885        template: Handlebars.compile('{{view "child" key="value"}}')
 886    });
 887```
 888
 889The view helper may also be used as a block helper, in which case the block will be assigned as the `template` property of the child view:
 890
 891```handlebars
 892    {{#view child}}
 893        child will have this block
 894        set as its template property
 895    {{/view}}
 896```
 897
 898Handlebars is string based, while `Backbone.View` instances have a DOM `el`. Since we are mixing metaphors, the embedding of views works via a placeholder mechanism where the `view` helper in this case adds the view passed to the helper to a hash of `children`, then injects placeholder HTML into the template such as:
 899
 900```html
 901    <div data-view-placeholder-cid="view2"></div>
 902```
 903
 904Then once the parent view is rendered, we walk the DOM in search of all the placeholders we created, replacing them with the child views' `el`s:
 905
 906```javascript
 907    this.$el.find('[data-view-placeholder-cid]').forEach(function(el) {
 908        var cid = el.getAttribute('data-view-placeholder-cid'),
 909            view = this.children[cid];
 910        view.render();
 911        $(el).replaceWith(view.el);
 912    }, this);
 913```
 914
 915### View helpers
 916
 917One of the most useful constructs in Thorax is `Handlebars.registerViewHelper` (not to be confused with `Handlebars.registerHelper`). This method will register a new block helper that will create and embed a `HelperView` instance with its `template` set to the captured block. A `HelperView` instance is different from that of a regular child view in that its context will be that of the parent's in the template. Like other child views it will have a `parent` property set to that of the declaring view. Many of the built-in helpers in Thorax including the `collection` helper are created in this manner.
 918
 919A simple example would be an `on` helper that re-rendered the generated `HelperView` instance each time an event was triggered on the declaring / parent view:
 920
 921    Handlebars.registerViewHelper('on', function(eventName, helperView) {
 922        helperView.parent.on(eventName, function() {
 923            helperView.render();
 924        });
 925    });
 926
 927An example use of this would be to have a counter that would increment each time a button was clicked. This example makes use of the `button` helper in Thorax which simply makes a button that calls a method when clicked:
 928
 929```handlebars
 930    {{#on "incremented"}}{{i}}{/on}}
 931    {{#button trigger="incremented"}}Add{{/button}}
 932```
 933
 934And the corresponding view class:
 935
 936```javascript
 937    new Thorax.View({
 938        events: {
 939            incremented: function() {
 940                ++this.i;
 941            }
 942        },
 943        initialize: function() {
 944            this.i = 0;
 945        },
 946        template: ...
 947    });
 948```
 949
 950### collection helper
 951
 952The `collection` helper creates and embeds a `CollectionView` instance, creating a view for each item in a collection, updating when items are added, removed, or changed in the collection. The simplest usage of the helper would look like:
 953
 954```handlebars
 955    {{#collection kittens}}
 956      <li>{{name}}</li>
 957    {{/collection}}
 958```
 959
 960And the corresponding view:
 961
 962```javascript
 963    new Thorax.View({
 964      kittens: new Thorax.Collection(...),
 965      template: ...
 966    });
 967```
 968
 969The block in this case will be assigned as the `template` for each item view created, and the context will be the `attributes` of the given model. This helper accepts options that can be arbitrary HTML attributes, a `tag` option to specify the type of tag containing the collection, or any of the following:
 970
 971- `item-template` - A template to display for each model. If a block is specified it will become the item-template
 972- `item-view` - A view class to use when each item view is created
 973- `empty-template` - A template to display when the collection is empty. If an inverse / else block is specified it will become the empty-template
 974- `empty-view` - A view to display when the collection is empty
 975
 976Options and blocks can be used in combination, in this case creating a `KittenView` class with a `template` set to the captured block for each kitten in the collection:
 977
 978```handlebars
 979    {{#collection kittens item-view="KittenView" tag="ul"}}
 980      <li>{{name}}</li>
 981    {{else}}
 982      <li>No kittens!</li>
 983    {{/collection}}
 984```
 985
 986Note that multiple collections can be used per view, and collections can be nested. This is useful when there are models that contain collections that contain models that contain...
 987
 988```handlebars
 989    {{#collection kittens}}
 990      <h2>{{name}}</h2>
 991      <p>Kills:</p>
 992      {{#collection miceKilled tag="ul"}}
 993        <li>{{name}}</li>
 994      {{/collection}}
 995    {{/collection}}
 996```
 997
 998### Custom HTML data attributes
 999
1000Thorax makes heavy use of custom HTML data attributes to operate. While some make sense only within the context of Thorax, several are quite useful to have in any Backbone project for writing other functions against, or for general debugging. In order to add some to your views in non-Thorax projects, override the `setElement` method in your base view class:
1001
1002```javascript
1003  MyApplication.View = Backbone.View.extend({
1004    setElement: function() {
1005        var response = Backbone.View.prototype.setElement.apply(this, arguments);
1006        this.name && this.$el.attr('data-view-name', this.name);
1007        this.$el.attr('data-view-cid', this.cid);
1008        this.collection && this.$el.attr('data-collection-cid', this.collection.cid);
1009        this.model && this.$el.attr('data-model-cid', this.model.cid);
1010        return response;
1011    }
1012  });
1013```
1014
1015In addition to making your application more immediately comprehensible in the inspector, it's now possible to extend jQuery / Zepto with functions to lookup the closest view, model or collection to a given element. In order to make it work you have to save references to each view created in your base view class by overriding the `_configure` method:
1016
1017
1018```javascript
1019    MyApplication.View = Backbone.View.extend({
1020        _configure: function() {
1021            Backbone.View.prototype._configure.apply(this, arguments);
1022            Thorax._viewsIndexedByCid[this.cid] = this;
1023        },
1024        dispose: function() {
1025            Backbone.View.prototype.dispose.apply(this, arguments);
1026            delete Thorax._viewsIndexedByCid[this.cid];
1027        }
1028    });
1029```
1030
1031Then we can extend jQuery / Zepto:
1032
1033```javascript
1034    $.fn.view = function() {
1035        var el = $(this).closest('[data-view-cid]');
1036        return el && Thorax._viewsIndexedByCid[el.attr('data-view-cid')];
1037    };
1038
1039    $.fn.model = function(view) {
1040        var $this = $(this),
1041            modelElement = $this.closest('[data-model-cid]'),
1042            modelCid = modelElement && modelElement.attr('[data-model-cid]');
1043        if (modelCid) {
1044            var view = $this.view();
1045            return view && view.model;
1046        }
1047        return false;
1048    };
1049```
1050
1051Now instead of storing references to models randomly throughout your application to lookup when a given DOM event occurs you can use `$(element).model()`. In Thorax, this can particularly useful in conjunction with the `collection` helper which generates a view class (with a `model` property) for each `model` in the collection. An example template:
1052
1053```handlebars
1054    {{#collection kittens tag="ul"}}
1055      <li>{{name}}</li>
1056    {{/collection}}
1057```
1058
1059And the corresponding view class:
1060
1061```javascript
1062    Thorax.View.extend({
1063      events: {
1064        'click li': function(event) {
1065          var kitten = $(event.target).model();
1066          console.log('Clicked on ' + kitten.get('name'));
1067        }
1068      },
1069      kittens: new Thorax.Collection(...),
1070      template: ...
1071    });  
1072```
1073
1074A common anti-pattern in Backbone applications is to assign a `className` to a single view class. Consider using the `data-view-name` attribute as a CSS selector instead, saving CSS classes for things that will be used multiple times:
1075
1076
1077```css
1078  [data-view-name="child"] {
1079
1080  }
1081```
1082
1083### Thorax Resources
1084
1085No Backbone related tutorial would be complete without a todo application. A [Thorax implementation of TodoMVC](http://todomvc.com/labs/architecture-examples/thorax/) is available, in addition to this far simpler example composed of this single Handlebars template:
1086
1087
1088```handlebars
1089  {{#collection todos tag="ul"}}
1090    <li{{#if done}} class="done"{{/if}}>
1091      <input type="checkbox" name="done"{{#if done}} checked="checked"{{/if}}>
1092      <span>{{item}}</span>
1093    </li>
1094  {{/collection}}
1095  <form>
1096    <input type="text">
1097    <input type="submit" value="Add">
1098  </form>
1099```
1100
1101and the corresponding JavaScript:
1102
1103```javascript
1104  var todosView = Thorax.View({
1105      todos: new Thorax.Collection(),
1106      events: {
1107          'change input[type="checkbox"]': function(event) {
1108              var target = $(event.target);
1109              target.model().set({done: !!target.attr('checked')});
1110          },
1111          'submit form': function(event) {
1112              event.preventDefault();
1113              var input = this.$('input[type="text"]');
1114              this.todos.add({item: input.val()});
1115              input.val('');
1116          }
1117      },
1118      template: '...'
1119  });
1120  todosView.appendTo('body');
1121```
1122
1123To see Thorax in action on a large scale website visit walmart.com on any Android or iOS device. For a complete list of resources visit the [Thorax website](http://thoraxjs.org).
1124<p>&nbsp;</p>
1125<p>&nbsp;</p>