A few days ago, I gave a talk on building Single Page Apps on the Microsoft Stack. In that talk, I recommended that people use Knockout, Sammy, and RequireJS to build their presentation layer and use the ASP.NET Web API to expose data from their server.

After I gave the talk, several people contacted me and suggested that I investigate a new open-source JavaScript library named Durandal. Durandal stitches together Knockout, Sammy, and RequireJS to make it easier to use these technologies together.

In this blog entry, I want to provide a brief walkthrough of using Durandal to create a simple Single Page App. I am going to demonstrate how you can create a simple Movies App which contains (virtual) pages for viewing a list of movies, adding new movies, and viewing movie details. The goal of this blog entry is to give you a sense of what it is like to build apps with Durandal.

Installing Durandal

First things first. How do you get Durandal?

The GitHub project for Durandal is located here:

https://github.com/BlueSpire/Durandal

The Wiki — located at the GitHub project — contains all of the current documentation for Durandal. Currently, the documentation is a little sparse, but it is enough to get you started.

Instead of downloading the Durandal source from GitHub, a better option for getting started with Durandal is to install one of the Durandal NuGet packages.

I built the Movies App described in this blog entry by first creating a new ASP.NET MVC 4 Web Application with the Basic Template. Next, I executed the following command from the Package Manager Console:

Install-Package Durandal.StarterKit

As you can see from the screenshot of the Package Manager Console above, the Durandal Starter Kit package has several dependencies including:

· jQuery

· Knockout

· Sammy

· Twitter Bootstrap

The Durandal Starter Kit package includes a sample Durandal application. You can get to the Starter Kit app by navigating to the Durandal controller.

Unfortunately, when I first tried to run the Starter Kit app, I got an error because the Starter Kit is hard-coded to use a particular version of jQuery which is already out of date. You can fix this issue by modifying the App_Start\DurandalBundleConfig.cs file so it is jQuery version agnostic like this:

      bundles.Add(
        new ScriptBundle("~/scripts/vendor")
          .Include("~/Scripts/jquery-{version}.js")
          .Include("~/Scripts/knockout-{version}.js")
          .Include("~/Scripts/sammy-{version}.js")
//          .Include("~/Scripts/jquery-1.9.0.min.js")
//          .Include("~/Scripts/knockout-2.2.1.js")
//          .Include("~/Scripts/sammy-0.7.4.min.js")
          .Include("~/Scripts/bootstrap.min.js")
        );

The recommendation is that you create a Durandal app in a folder off your project root named App. The App folder in the Starter Kit contains the following subfolders and files:

· durandal – This folder contains the actual durandal JavaScript library.

· viewmodels – This folder contains all of your application’s view models.

· views – This folder contains all of your application’s views.

· main.js — This file contains all of the JavaScript startup code for your app including the client-side routing configuration.

· main-built.js – This file contains an optimized version of your application. You need to build this file by using the RequireJS optimizer (unfortunately, before you can run the optimizer, you must first install NodeJS).

For the purpose of this blog entry, I wanted to start from scratch when building the Movies app, so I deleted all of these files and folders except for the durandal folder which contains the durandal library.

Creating the ASP.NET MVC Controller and View

A Durandal app is built using a single server-side ASP.NET MVC controller and ASP.NET MVC view. A Durandal app is a Single Page App. When you navigate between pages, you are not navigating to new pages on the server. Instead, you are loading new virtual pages into the one-and-only-one server-side view.

For the Movies app, I created the following ASP.NET MVC Home controller:

public class HomeController : Controller {

    public ActionResult Index() {
        return View();
    }

}

There is nothing special about the Home controller – it is as basic as it gets.

Next, I created the following server-side ASP.NET view. This is the one-and-only server-side view used by the Movies app:

@{
    Layout = null;
}
<!DOCTYPE html>
<html>
<head>
    <title>Index</title>
</head>
<body>
    <div id="applicationHost">
        Loading app....
    </div>
        
    @Scripts.Render("~/scripts/vendor") 
    <script type="text/javascript" src="~/App/durandal/amd/require.js" 
        data-main="/App/main"></script>
        
</body>
</html>

Notice that I set the Layout property for the view to the value null. If you neglect to do this, then the default ASP.NET MVC layout will be applied to the view and you will get the <!DOCTYPE> and opening and closing <html> tags twice.

Next, notice that the view contains a DIV element with the Id applicationHost. This marks the area where virtual pages are loaded. When you navigate from page to page in a Durandal app, HTML page fragments are retrieved from the server and stuck in the applicationHost DIV element.

Inside the applicationHost element, you can place any content which you want to display when a Durandal app is starting up. For example, you can create a fancy splash screen. I opted for simply displaying the text “Loading app…”:

Next, notice the view above includes a call to the Scripts.Render() helper. This helper renders out all of the JavaScript files required by the Durandal library such as jQuery and Knockout. Remember to fix the App_Start\DurandalBundleConfig.cs as described above or Durandal will attempt to load an old version of jQuery and throw a JavaScript exception and stop working.

Your application JavaScript code is not included in the scripts rendered by the Scripts.Render helper. Your application code is loaded dynamically by RequireJS with the help of the following SCRIPT element located at the bottom of the view:

<script type="text/javascript" src="~/App/durandal/amd/require.js" 
     data-main="/App/main"></script> 

The data-main attribute on the SCRIPT element causes RequireJS to load your /app/main.js JavaScript file to kick-off your Durandal app.

Creating the Durandal Main.js File

The Durandal Main.js JavaScript file, located in your App folder, contains all of the code required to configure the behavior of Durandal. Here’s what the Main.js file looks like in the case of the Movies app:

require.config({
    paths: {
        'text': 'durandal/amd/text'
    }
});

define(function (require) {
    var app = require('durandal/app'),
        viewLocator = require('durandal/viewLocator'),
        system = require('durandal/system'),
        router = require('durandal/plugins/router');

    //>>excludeStart("build", true);
    system.debug(true);
    //>>excludeEnd("build");

    app.start().then(function () {
        //Replace 'viewmodels' in the moduleId with 'views' to locate the view.
        //Look for partial views in a 'views' folder in the root.
        viewLocator.useConvention();

        //configure routing
        router.useConvention();
        router.mapNav("movies/show");
        router.mapNav("movies/add");
        router.mapNav("movies/details/:id");

        app.adaptToDevice();

        //Show the app by setting the root view model for our application with a transition.
        app.setRoot('viewmodels/shell', 'entrance');
    });
});

There are three important things to notice about the main.js file above. First, notice that it contains a section which enables debugging which looks like this:

//>>excludeStart(“build”, true);

system.debug(true);

//>>excludeEnd(“build”);

This code enables debugging for your Durandal app which is very useful when things go wrong. When you call system.debug(true), Durandal writes out debugging information to your browser JavaScript console. For example, you can use the debugging information to diagnose issues with your client-side routes:

(The funny looking //> symbols around the system.debug() call are RequireJS optimizer pragmas).

The main.js file is also the place where you configure your client-side routes. In the case of the Movies app, the main.js file is used to configure routes for three page: the movies show, add, and details pages.

//configure routing 

router.useConvention(); 

router.mapNav("movies/show"); 

router.mapNav("movies/add"); 

router.mapNav("movies/details/:id");

The route for movie details includes a route parameter named id. Later, we will use the id parameter to lookup and display the details for the right movie.

Finally, the main.js file above contains the following line of code:

//Show the app by setting the root view model for our application with a transition. 
app.setRoot('viewmodels/shell', 'entrance'); 

This line of code causes Durandal to load up a JavaScript file named shell.js and an HTML fragment named shell.html. I’ll discuss the shell in the next section.

Creating the Durandal Shell

You can think of the Durandal shell as the layout or master page for a Durandal app. The shell is where you put all of the content which you want to remain constant as a user navigates from virtual page to virtual page. For example, the shell is a great place to put your website logo and navigation links.

The Durandal shell is composed from two parts: a JavaScript file and an HTML file. Here’s what the HTML file looks like for the Movies app:

<h1>Movies App</h1> 

<div class="container-fluid page-host"> 

<!--ko compose: { 

model: router.activeItem, //wiring the router 

afterCompose: router.afterCompose, //wiring the router 

transition:'entrance', //use the 'entrance' transition when switching views 

cacheViews:true //telling composition to keep views in the dom, and reuse them (only a good idea with singleton view models) 

}--><!--/ko--> 

</div>

And here is what the JavaScript file looks like:

define(function (require) {
    var router = require('durandal/plugins/router');

    return {
        router: router,
        activate: function () {
            return router.activate('movies/show');
        }
    };
});

The JavaScript file contains the view model for the shell. This view model returns the Durandal router so you can access the list of configured routes from your shell.

Notice that the JavaScript file includes a function named activate(). This function loads the movies/show page as the first page in the Movies app. If you want to create a different default Durandal page, then pass the name of a different age to the router.activate() method.

Creating the Movies Show Page

Durandal pages are created out of a view model and a view. The view model contains all of the data and view logic required for the view. The view contains all of the HTML markup for rendering the view model.

Let’s start with the movies show page. The movies show page displays a list of movies. The view model for the show page looks like this:

define(function (require) {

    var moviesRepository = require("repositories/moviesRepository");

    return {
        movies: ko.observable(),

        activate: function() {
            this.movies(moviesRepository.listMovies());
        }
    };
});

You create a view model by defining a new RequireJS module (see http://requirejs.org). You create a RequireJS module by placing all of your JavaScript code into an anonymous function passed to the RequireJS define() method.

A RequireJS module has two parts. You retrieve all of the modules which your module requires at the top of your module. The code above depends on another RequireJS module named repositories/moviesRepository.

Next, you return the implementation of your module. The code above returns a JavaScript object which contains a property named movies and a method named activate.

The activate() method is a magic method which Durandal calls whenever it activates your view model. Your view model is activated whenever you navigate to a page which uses it. In the code above, the activate() method is used to get the list of movies from the movies repository and assign the list to the view model movies property.

The HTML for the movies show page looks like this:

<table>
    <thead>
        <tr>
            <th>Title</th><th>Director</th>
        </tr>
    </thead>
    <tbody data-bind="foreach:movies">
        <tr>
            <td data-bind="text:title"></td>
            <td data-bind="text:director"></td>
            <td><a data-bind="attr:{href:'#/movies/details/'+id}">Details</a></td>
        </tr>        
    </tbody>
</table>

<a href="#/movies/add">Add Movie</a>

Notice that this is an HTML fragment. This fragment will be stuffed into the page-host DIV element in the shell.html file which is stuffed, in turn, into the applicationHost DIV element in the server-side MVC view.

The HTML markup above contains data-bind attributes used by Knockout to display the list of movies (To learn more about Knockout, visit http://knockoutjs.com). The list of movies from the view model is displayed in an HTML table.

Notice that the page includes a link to a page for adding a new movie. The link uses the following URL which starts with a hash: #/movies/add. Because the link starts with a hash, clicking the link does not cause a request back to the server. Instead, you navigate to the movies/add page virtually.

Creating the Movies Add Page

The movies add page also consists of a view model and view. The add page enables you to add a new movie to the movie database.

Here’s the view model for the add page:

define(function (require) {
    var app = require('durandal/app');
    var router = require('durandal/plugins/router');
    var moviesRepository = require("repositories/moviesRepository");

    return {
        movieToAdd: {
            title: ko.observable(),
            director: ko.observable()
        },
 
        activate: function () {
            this.movieToAdd.title("");
            this.movieToAdd.director("");
            this._movieAdded = false;
        },

        canDeactivate: function () {
            if (this._movieAdded == false) {
                return app.showMessage('Are you sure you want to leave this page?', 'Navigate', ['Yes', 'No']);
            } else {
                return true;
            }
        },

        addMovie: function () {
            // Add movie to db
            moviesRepository.addMovie(ko.toJS(this.movieToAdd));

            // flag new movie
            this._movieAdded = true;

            // return to list of movies
            router.navigateTo("#/movies/show");
        }
    };

});

The view model contains one property named movieToAdd which is bound to the add movie form. The view model also has the following three methods:

1. activate() – This method is called by Durandal when you navigate to the add movie page. The activate() method resets the add movie form by clearing out the movie title and director properties.

2. canDeactivate() – This method is called by Durandal when you attempt to navigate away from the add movie page. If you return false then navigation is cancelled.

3. addMovie() – This method executes when the add movie form is submitted. This code adds the new movie to the movie repository.

I really like the Durandal canDeactivate() method. In the code above, I use the canDeactivate() method to show a warning to a user if they navigate away from the add movie page – either by clicking the Cancel button or by hitting the browser back button – before submitting the add movie form:

The view for the add movie page looks like this:

<form data-bind="submit:addMovie">
<fieldset>
    <legend>Add Movie</legend>
    <div>   
        <label>
            Title:
            <input data-bind="value:movieToAdd.title" required />
        </label>
    </div>
    <div>
        <label>
            Director:
            <input data-bind="value:movieToAdd.director" required />
        </label>
    </div>
    <div>
        <input type="submit" value="Add" />
        <a href="#/movies/show">Cancel</a>
    </div>
</fieldset>
</form>

I am using Knockout to bind the movieToAdd property from the view model to the INPUT elements of the HTML form. Notice that the FORM element includes a data-bind attribute which invokes the addMovie() method from the view model when the HTML form is submitted.

Creating the Movies Details Page

You navigate to the movies details Page by clicking the Details link which appears next to each movie in the movies show page:

The Details links pass the movie ids to the details page:

#/movies/details/0

#/movies/details/1

#/movies/details/2

Here’s what the view model for the movies details page looks like:

define(function (require) {
    var router = require('durandal/plugins/router');
    var moviesRepository = require("repositories/moviesRepository");

    return {
        movieToShow: {
            title: ko.observable(),
            director: ko.observable()
        },

        activate: function (context) {
            // Grab movie from repository
            var movie = moviesRepository.getMovie(context.id);

            // Add to view model
            this.movieToShow.title(movie.title);
            this.movieToShow.director(movie.director);
        }
    };

});

Notice that the view model activate() method accepts a parameter named context. You can take advantage of the context parameter to retrieve route parameters such as the movie Id.

In the code above, the context.id property is used to retrieve the correct movie from the movie repository and the movie is assigned to a property named movieToShow exposed by the view model.

The movie details view displays the movieToShow property by taking advantage of Knockout bindings:

<div>
    <h2 data-bind="text:movieToShow.title"></h2>
    directed by <span data-bind="text:movieToShow.director"></span>
</div>

Summary

The goal of this blog entry was to walkthrough building a simple Single Page App using Durandal and to get a feel for what it is like to use this library. I really like how Durandal stitches together Knockout, Sammy, and RequireJS and establishes patterns for using these libraries to build Single Page Apps.

Having a standard pattern which developers on a team can use to build new pages is super valuable. Once you get the hang of it, using Durandal to create new virtual pages is dead simple. Just define a new route, view model, and view and you are done.

I also appreciate the fact that Durandal did not attempt to re-invent the wheel and that Durandal leverages existing JavaScript libraries such as Knockout, RequireJS, and Sammy. These existing libraries are powerful libraries and I have already invested a considerable amount of time in learning how to use them. Durandal makes it easier to use these libraries together without losing any of their power.

Durandal has some additional interesting features which I have not had a chance to play with yet. For example, you can use the RequireJS optimizer to combine and minify all of a Durandal app’s code. Also, Durandal supports a way to create custom widgets (client-side controls) by composing widgets from a controller and view.

You can download the code for the Movies app by clicking the following link (this is a Visual Studio 2012 project):

Durandal Movie App