Application Infrastructure

Marionette applications are built around modules and submodules that allow greater reuse and composability. At the center of all of this is the Marionette.Application object, which organizes your entire app. There is also a dedicated Controller object, which controls the workflow and process of modules and therefore the entire application.

Views

Marionette introduces some specific view objects to cater for the differing requirements in applications. An ItemView is provided for rendering single items, and a CollectionView iterates over a collection and renders individual ItemView instances. The Layout object allows complex user interfaces to be laid out into a set of Region objects.

View Management

A number of mechanisms are available to manage regions and subviews within the framework. There is also a renderer, which allows templates to be rendered in a consistent manner. Your views can also be sped up by utilizing the TemplateCache.

Messaging

Marionette provides a request-response framework and a command execution framework to allow better decoupling of application code. Both of these components allow one part of the application to request work to be done without needing to be tied to the component that performs the work.

Put together, the features that Marionette provides brings Backbone into a new league. Developers with a background in more traditional languages and web application frameworks will find these features more familiar, and it makes the JavaScript code more manageable.

Create an Application

The Backbone.Marionette.Application object is at the center of any Marionette app. This application is the first thing that is created and can be extended with many options if you want. The simplest invocation of this object is as follows:

$(function() {

    //create a new Marionette Application
    MApp = new Backbone.Marionette.Application();
});

From here, you will be able to add regions, set up initializers to prepare the application in a particular way, or set up application-level event listeners.

Adding Regions

The Marionette.Region object provides functions to manage your views within your application. Regions can be added in any one of three forms: by using a jQuery selector, by creating your own custom Region object, or by using a combination of both methods.

An application can contain multiple Region objects, and later we’ll see how Layout objects can be added to encapsulate a number of regions.

To add the main content area of the page as a region to this application, simply add the following lines:

MApp.addRegions({
     mainRegion: '#app'
});

An equivalent way to achieve this would be to create your own Region object and set the root element for that Region.

AppRegion = Marionette.Region.extend({
el: '#app'
});
MApp.addRegions({
     mainRegion: AppRegion
});

Both of the following code snippets will create a Region as part of the application, using a div with an ID of content as the area to render within.

The region can be accessed through the Backbone.Marionette.Application reference, by using the region name (in this case mainRegion). You can access the region directly as an attribute.

var region = MApp.mainRegion;

Alternatively, you can use the getRegion function.

var region = MApp.getRegion('mainRegion'),

Adding Views to a Region

Marionette has a number of different view types defined, including ItemView, which is ideally used to render a single item, and CollectionView, which should be used to render a number of ItemViews when dealing with collections.

For a simple example, the TimelineView that was previously defined as a Backbone.View could be refactored to extend Backbone.Marionette.ItemView. A copy of the original Timeline.js can be renamed to MarionetteTimeline and adjusted as follows:

var com = com || {};
com.apress = com.apress || {};
com.apress.view = com.apress.view || {};

com.apress.view.MarionetteTimelineView = Backbone.Marionette.ItemView.extend({

This new view needs to be included in the list of scripts on the main HTML page.

<script src="js/app/view/MarionetteTimelineView.js"></script>

Finally, the view can be added to the Region. There are two ways to do this; one is to include the view when creating the region by using the currentView attribute.

var timelineView = new com.apress.view.MarionetteTimelineView();
AppRegion = Marionette.Region.extend({
     el: '#app',
    currentView: timelineView
     
    });

This causes the view to be rendered as soon as the Region is displayed. You can also attach a view after the Region has been created using the attachView function.

var timelineView = new com.apress.view.MarionetteTimelineView();
MApp.mainRegion.attachView(timelineView);

As Region objects manage views, it follows that there are methods available to show or hide a particular view. A Region also has the benefit of including a reset function that will completely clear all views that have been displayed within.

MApp.getRegion('mainRegion').reset();

You can also close individual views within a Region using the close function.

MApp.mainRegion.close(timelineView);

MApp.mainRegion.on("show", function(view){
    console.log( ' View has been displayed '),
});
MApp.mainRegion.on("close", function(view){
    console.log( ' View has been closed '),
});

MApp.mainRegion.show(timelineView);
MApp.mainRegion.close(timelineView);

AppRegion = Marionette.Region.extend({
 el: '#app',
 onShow: function(view){
     console.log('View is shown'),
 },

 onClose: function(view){
     console.log('View is closed'),
 }
});

Marionette CollectionView

Strictly speaking, it would be better to utilize the CollectionView as the type of Marionette view because the Twitter timeline is really a series of Tweet objects. In the previous section when we used ItemView, the same render function from Chapter 6 was still in use, so Marionette’s rendering was not used.

Marionette actually provides a default rendering for ItemViews, based on their templates, and the Model object that can be provided from its collection. Figure 10-3 illustrates how the CollectionView and ItemView can be used together.

As you can see from Figure 10-3, a CollectionView represents a single Backbone.Collection. For each of the Backbone.Model objects present in that collection, an ItemView is created to render that model.

Creating an ItemView is usually a simple task, where the template required is passed, with no rendering function required. The showProfile event listener and handler from Chapter 6 are also added to the ItemView because it is an event that relates to each of these subviews.

To represent the model objects correctly, you can create a new JavaScript file in the view directory named TimelineItemView.

Note that the template parameter, which is required in all ItemViews, references the compiled version of our Handlebars template. If your Marionette application is utilizing Underscore templates, this would not be necessary. Instead, you could pass the ID of that Underscore template.

var com = com || {};
com.apress = com.apress || {};
com.apress.view = com.apress.view || {};

com.apress.view.TimelineItemView = Backbone.Marionette.ItemView.extend({

    template: Handlebars.compile($("#timeline-item-template").html()),

    events: {
        'click .profile': 'showDialog'
    },

    showDialog: function(options) {
        var self = this,
            $target = $(options.currentTarget),
            username = $target.data('user'),

        var profileView = new com.apress.view.ProfilePopupView({
            user: username
        });
    }
});

Previously the template that was being used to render timeline information iterated over an entire collection. We are now dealing with individual items, so the template will need to reflect this in the main HTML page, m.html.

<!-- Template for timeline items -->
<script type="text/x-handlebars-template" id="timeline-item-template">
       <li>
         <div class='icon'>
                 <img src='{{user.profile_image_url}}'></img>
           </div>
           <div class='data'>
               <h4>{{user.name}}</h4>
               <p>{{format text}}</p>
               <p class="timestamp"><i>{{friendlyDate}}</i></p>
           </div>
       </li>
</script>

While in the HTML page, we should update the root element of the timeline to be a ul tag by adding this under the div with the timeline identifier.

<div id='timeline' class='timeline-view'>
   <h2>My Tweets</h2>
    <ul id='timeline-list' class='listview fluid'>
    </ul>
</div>

The next step is to build a CollectionView that will use the newly created TimelineItemView. Once again, the amount of refactoring required from the previous TimelineView, which utilized the Backbone.View class, will be minimal. To remove any ambiguity, this JavaScript object should be named MarionetteTimelineView. It can also be placed in the view directory of the application.

Rather than extending Backbone.View, it will need to extend Backbone.Marionette.CollectionView.

var com = com || {};
com.apress = com.apress || {};
com.apress.view = com.apress.view || {};

    com.apress.view.MarionetteTimelineView = Backbone.Marionette.CollectionView.extend({
});

The most important attribute in a CollectionView is the ItemView that is used to render the Model objects.

com.apress.view.MarionetteTimelineView = Backbone.Marionette.CollectionView.extend({

    itemView : com.apress.view.TimelineItemView,
});

Note that the itemView refers to the class that is used rather than an instance of the view that would be created using the new operator. It is essential that you refer to the ItemView in this manner to avoid confusing errors in your application.

The other important attribute in the CollectionView is the collection attribute, which refers to the Backbone.Collection to use. The initalize function that previously existed can be kept because all it was responsible for was fetching the collection and calling render when the collection reset. If you wanted, you could build the Backbone.Collection outside of this view and pass it as a parameter.

The event handlers for clicking a user’s profile link have been moved to the TimelineItemView, and the root element has been updated to the ul identified with timeline-list, rather than using the higher-level div element.

var com = com || {};
com.apress = com.apress || {};
com.apress.view = com.apress.view || {};

com.apress.view.MarionetteTimelineView = Backbone.Marionette.CollectionView.extend({

    el: '#timeline-list',
    itemView : com.apress.view.TimelineItemView,

    initialize: function(options) {
        var self = this;
        //create a collection for this view to render
        self.collection = new com.apress.collection.Timeline();

        //force the fetch to fire a reset event
        self.collection.fetch({
            reset: true
        });
        self.listenTo(self.collection, 'reset', self.render);
    }

});

To get everything running, ensure that the new view is included correctly in the main HTML page.

<script src="js/app/view/TimelineItemView.js"></script>
<script src="js/app/view/MarionetteTimelineView.js"></script>

Now, in app.js, the region can use the MarionetteTimelineView in place of the old view.

var timelineView = new com.apress.view.MarionetteTimelineView();
MApp.mainRegion.show(timelineView);

When the application is run, you should see the Twitter timeline rendered once again, as in Figure 10-4.

Later in this chapter when we look at the Marionette Layout object, we will see how to incorporate the profile view that appeared on the right side in the Chapter 6 example.

Marionette Composite View

Marionette has one other type of view, in addition to ItemView and CollectionView, named CompositeView. This view extends the functionality that is provided by CollectionView. For more complex user interfaces that require collections, this can be a good choice because it allows you to provide a template to be used for the overall collection as well as using a template for the individual model objects in the collection.

To illustrate this, let’s take a look at the previous example where CollectionView was used to render the collection contents. The HTML had to be altered to include the ul container tags for the list of TimelineItemView objects to be rendered. The following code snippet shows how this looks in our main HTML page:

<div id='timeline' class='timeline-view'>
            <h2>My Tweets</h2>
                <ul id='timeline-list' class='listview fluid'>
                    </ul>
</div>

Using the CompositeView, we can get rid of this additional ul declaration and move it into a template, to be used only when the collection is being rendered.

<script type="text/x-handlebars-template" id="timeline-template">
 <ul id='timeline-list' class='listview fluid'>
 </ul>
</script>

This results in the timeline div returning to a simpler form.

<div id='timeline' class='timeline-view'>
         <h2>My Tweets</h2>
 </div>

To utilize this change, a new CompositeView version of the previous MarionetteTimelineView will need to be created. In this example, we’ll call this MarionetteCompositeTimelineView. Start by making a copy of MarionetteTimelineView, and change the declaration to use the correct view.

var com = com || {};
com.apress = com.apress || {};
com.apress.view = com.apress.view || {};

com.apress.view.MarionetteCompositeTimelineView = Backbone.Marionette.CompositeView.extend({
    });

You can also add a template attribute that will use the new timeline-template created previously. The root element attribute, el, will need to change to the higher-level timeline div, but the itemView can stay the same.

com.apress.view.MarionetteCompositeTimelineView = Backbone.Marionette.CompositeView.extend({
    el: '#timeline',
    template: Handlebars.compile($("#timeline-template").html()),
    itemView : com.apress.view.TimelineItemView,
}

Finally, the appendHtml function should be overridden so that each item that is added to the view is placed under the ul tag. The default implementation would have added it to the root el instead, which would have resulted in incorrect rendering in our case.

appendHtml: function(compositeView, itemView){
        compositeView.$('#timeline-list').append(itemView.el);
}

The complete code listing for MarionetteCompositeView would look as follows:

var com = com || {};
com.apress = com.apress || {};
com.apress.view = com.apress.view || {};

com.apress.view.MarionetteCompositeTimelineView = Backbone.Marionette.CompositeView.extend({
    el: '#timeline',
    template: Handlebars.compile($("#timeline-template").html()),

    itemView : com.apress.view.TimelineItemView,

    initialize: function(options) {
        var self = this;

        self.itemView =  com.apress.view.TimelineItemView;

        //create a collection for this view to render
        self.collection = new com.apress.collection.Timeline();
        //initial render
        //self.render();

        //force the fetch to fire a reset event
        self.collection.fetch({
            reset: true
        });

        self.listenTo(self.collection, 'reset', self.render);
    },

    appendHtml: function(compositeView, itemView){
        compositeView.$('#timeline-list').append(itemView.el);
    }
});

There are two minor changes required to have this work with the TimelineItemView object. First, add a tagName attribute to TimelineItemView with the value li. This instructs Backbone to wrap the HTML for this view in an li tag. Without this, the default would have been to wrap the HTML in a div.

com.apress.view.TimelineItemView = Backbone.Marionette.ItemView.extend({

    //el: '#timeline',
    template: Handlebars.compile($("#timeline-item-template").html()),
    tagName: 'li',

    //other TimelineItemView source
});

This will require the timeline-item-template to be changed so that it no longer contains the li tag.

<!-- Template for timeline -->
<script type="text/x-handlebars-template" id="timeline-item-template">
        <div class='icon'>
                 <img src='{{user.profile_image_url}}'></img>
           </div>
           <div class='data'>
               <h4>{{user.name}}</h4>
               <p>{{format text}}</p>
               <p class="timestamp"><i>{{friendlyDate}}</i></p>
           </div>
</script>

Finally, to use this new view in the application, simply change the declaration of timelineView in app.js to use the new MarionetteCompositeView.

var timelineView = new com.apress.view.MarionetteCompositeTimelineView();
MApp.mainRegion.attachView(timelineView);
               

Depending on your preference, either the simpler CollectionView or the CompositeView can be used in the application. In our application example, to switch between both, you just need to remember to set up that initial ul within the timeline div.

Marionette Views in More Detail

All views in Marionette extend a base Marionette.View class, although you will never use this view directly. Instead, it provides common functionality to be used across all three view types.

initialize: function(options){
    console.log('Initialized with ' + JSON.stringify(options));
   },

var timelineView = new com.apress.view.MarionetteTimelineView({itemViewOptions: {parameter: 'hello itemview'}});

Nested Regions

Marionette provides a Layout object that allows you to create multiple regions in an application and control the overall app layout. A Layout object consists of a number of Region objects and extends from ItemView. This means you can provide a template for the overall application layout structure and then use the regions attribute to specify the areas within the application that will be filled out with other views, or even other nested layouts.

The definition of a layout has two key attributes: the template that will be used and the regions marked inside that template. An example of a Layout definition follows:

MyLayout = Backbone.Marionette.Layout.extend({
 template: '#layout-template',
 regions: {
   main: '#main',
   nav: '#nav'
 }
});

Just as with the main Backbone.Marionette.Application object, regions can be added and removed using the appropriate functions (addRegion, removeRegion). Deferring the management of regions to the Layout object rather than the overall Application object leads to a cleaner code base.

As Layout extends ItemView, it also inherits the close functionality. This means you can switch layouts by closing one and replacing it with a new one.

Using Layout in Our Example

We can extend our current example to use the Layout object, creating separate regions for the timeline view and the profile. First, we’ll need to change the existing ProfileView to be a Marionette ItemView. As we’ve done before, a simple copy of ProfileView will suffice, renaming it to MarionetteProfileView. To make this an ItemView, we’ll just change the type from Backbone.View to Backbone.Marionette.ItemView.

com.apress.view.MarionetteProfileView = Backbone.Marionette.ItemView.extend({
//existing source
});
 

Next, the template for the overall application needs to be created. This is simply a matter of moving everything that was within the body tag, bar the other templates, into a new template with an ID of app-layout-template.

<!-- Template for entire app-->
<script type="text/template" id="app-layout-template">
<div id="app" class="grid">
       <div class="row">
           <div class="span8">
               <div id='timeline' class='timeline-view'>
                <h2>My Tweets</h2>
                <div id="timeline-area">
                   <ul id='timeline-list' class='listview fluid'>
                   </ul>
                 </div>
             </div>
           </div>

           <div class="span4" id="side">
               <div id="profile" class="profile-view">
               </div>

                 <div id="search" class="search-view">
                   <form>
                         <div class="input-control text">
                              <input type="text" id="searchbox" autofocus="" placeholder="I'm looking for..">
                           </div>
                             <button class="bg-color-blue" id="searchbutton">Search</button>
                   </form>
                 </div>
             </div>
       </div>
   </div>
</script>

 

Previously, the Application object used the div with an ID of app as its main region. We’ll change this now to be the body tag.

AppRegion = Marionette.Region.extend({
 el: 'body',
});

The creation of the layout now is simply a matter of defining the template to use and the regions that are marked for the views to be added. This code can be placed directly in app.js.

AppLayout = Backbone.Marionette.Layout.extend({
    //template: Handlebars.compile($("#app-layout-template").html()),
    template: "#app-layout-template",
    regions: {
        timeline: '#timeline-area',
        profile: '#side'
    }
});

The Layout must be instantiated and added into the mainRegion of the application.

var layout = new AppLayout();
MApp.mainRegion.show(layout);

Finally, each of the views can be created and added to the appropriate region.

layout.timeline.show(new com.apress.view.MarionetteTimelineView({itemViewOptions: {parameter: 'hello itemview'}}));
layout.profile.show(new com.apress.view.MarionetteProfileView({user: 'sugrue'}));

Layout affords a little extra control over the application user interface, without the need to create a number of levels of complicated subviews throughout the application. While it may seem that Application and Layout are similar, you should consider that a Layout has a visual representation, while the Application should be used as a lightweight object for managing the life cycle of your app.

Views

Thorax includes extensions to the standard Backbone.View, which utilizes Handlebars templates. Just as with Marionette, there is a CollectionView that helps deal with displaying complete lists of items.

View Management

Views can be easily embedded within other views and are managed properly by Thorax so as to avoid any memory leaks, or zombie views.

There is also a LayoutView that acts as a container for another view and allows this contained view to be replaced easily.

Specialized Versions of Model and Collection

When passing through models or collections to your views, Thorax expects these to use the wrappers provided in the framework.