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
