If you have not heard of Meteor, Meteor is a new framework for building web applications which is built on top of Node.js. Meteor excels at building a new category of constantly-connected, real-time web applications. It has some jaw-dropping features which I described in a previous blog entry:

http://stephenwalther.com/archive/2013/03/18/an-introduction-to-meteor.aspx

So, I am super excited about Meteor. Unfortunately, because it is evolving so quickly, learning how to write Meteor applications can be challenging. The official documentation at Meteor.com is good, but it is too basic.

I’m happy to report that Discovering Meteor is a really good book:

· The book is a fun read. The writing is smooth and I read through the book from cover to cover in a single Saturday afternoon with pleasure.

· The book is well organized. It contains a walk-through of building a social media app (Microscope). Interleaved through the app building chapters, it contains tutorial chapters on Meteor features such as deployment and reactivity.

· The book covers several advanced topics which I have not seen covered anywhere else. The chapters on publications and subscriptions, routing, and animation are especially good. I came away from the book with a deeper understanding of all of these topics.

I wish that I had read Discover Meteor a couple of months ago and it would have saved me several weeks of reading Stack Overflow posts and struggling with the Meteor documentation

If you want to buy Discover Meteor, the authors gave me the following link which provides you with a 20% discount:

http://discovermeteor.com/orionids

You can download the latest release from CodePlex at http://AjaxControlToolkit.CodePlex.com or, better yet, you can execute the following NuGet command within Visual Studio 2010/2012:

There are three builds of the Ajax Control Toolkit: .NET 3.5, .NET 4.0, and .NET 4.5.

A Better AjaxFileUpload Control

We completely rewrote the AjaxFileUpload control for this release. We had two primary goals.

First, we wanted to support uploading really large files. In particular, we wanted to support uploading multi-gigabyte files such as video files or application files.

Second, we wanted to support showing upload progress on as many browsers as possible. The previous version of the AjaxFileUpload could show upload progress when used with Google Chrome or Mozilla Firefox but not when used with Apple Safari or Microsoft Internet Explorer. The new version of the AjaxFileUpload control shows upload progress when used with any browser.

Using the AjaxFileUpload Control

Let me walk-through using the AjaxFileUpload in the most basic scenario. And then, in following sections, I can explain some of its more advanced features.

Here’s how you can declare the AjaxFileUpload control in a page:

<ajaxToolkit:ToolkitScriptManager runat="server" />

<ajaxToolkit:AjaxFileUpload 
    ID="AjaxFileUpload1"
    AllowedFileTypes="mp4"
    OnUploadComplete="AjaxFileUpload1_UploadComplete" 
    runat="server" />

The exact appearance of the AjaxFileUpload control depends on the features that a browser supports. In the case of Google Chrome, which supports drag-and-drop upload, here’s what the AjaxFileUpload looks like:

Notice that the page above includes two Ajax Control Toolkit controls: the AjaxFileUpload and the ToolkitScriptManager control. You always need to include the ToolkitScriptManager with any page which uses Ajax Control Toolkit controls.

The AjaxFileUpload control declared in the page above includes an event handler for its UploadComplete event. This event handler is declared in the code-behind page like this:

protected void AjaxFileUpload1_UploadComplete(object sender, AjaxControlToolkit.AjaxFileUploadEventArgs e) {
    // Save uploaded file to App_Data folder
    AjaxFileUpload1.SaveAs(MapPath("~/App_Data/" + e.FileName));
} 

This method saves the uploaded file to your website’s App_Data folder. I’m assuming that you have an App_Data folder in your project – if you don’t have one then you need to create one or you will get an error.

There is one more thing that you must do in order to get the AjaxFileUpload control to work. The AjaxFileUpload control relies on an HTTP Handler named AjaxFileUploadHandler.axd. You need to declare this handler in your application’s root web.config file like this:

<configuration>
  <system.web>
    <compilation debug="true" targetFramework="4.5" />
    <httpRuntime targetFramework="4.5" maxRequestLength="42949672" />
    <httpHandlers>
      <add verb="*" path="AjaxFileUploadHandler.axd" type="AjaxControlToolkit.AjaxFileUploadHandler, AjaxControlToolkit"/>
    </httpHandlers>
  </system.web>
  <system.webServer>
    <validation validateIntegratedModeConfiguration="false"/>
    <handlers>
      <add name="AjaxFileUploadHandler" verb="*" path="AjaxFileUploadHandler.axd" type="AjaxControlToolkit.AjaxFileUploadHandler, AjaxControlToolkit"/>
    </handlers>
    <security>
      <requestFiltering>
        <requestLimits maxAllowedContentLength="4294967295"/>
      </requestFiltering>
    </security>
  </system.webServer>
</configuration>

Notice that the web.config file above also contains configuration settings for the maxRequestLength and maxAllowedContentLength. You need to assign large values to these configuration settings — as I did in the web.config file above — in order to accept large file uploads.

Supporting Chunked File Uploads

Because one of our primary goals with this release was support for large file uploads, we added support for client-side chunking. When you upload a file using a browser which fully supports the HTML5 File API — such as Google Chrome or Mozilla Firefox — then the file is uploaded in multiple chunks.

You can see chunking in action by opening F12 Developer Tools in your browser and observing the Network tab:

Notice that there is a crazy number of distinct post requests made (about 360 distinct requests for a 1 gigabyte file). Each post request looks like this:

http://localhost:24338/AjaxFileUploadHandler.axd?contextKey={DA8BEDC8-B952-4d5d-8CC2-59FE922E2923}&fileId=B7CCE31C-6AB1-BB28-2940-49E0C9B81C64

&fileName=Sita_Sings_the_Blues_480p_2150kbps.mp4&chunked=true&firstChunk=false

Each request posts another chunk of the file being uploaded. Notice that the request URL includes a chunked=true parameter which indicates that the browser is breaking the file being uploaded into multiple chunks.

Showing Upload Progress on All Browsers

The previous version of the AjaxFileUpload control could display upload progress only in the case of browsers which fully support the HTML5 File API. The new version of the AjaxFileUpload control can display upload progress in the case of all browsers.

If a browser does not fully support the HTML5 File API then the browser polls the server every few seconds with an Ajax request to determine the percentage of the file that has been uploaded. This technique of displaying progress works with any browser which supports making Ajax requests.

There is one catch. Be warned that this new feature only works with the .NET 4.0 and .NET 4.5 versions of the AjaxControlToolkit. To show upload progress, we are taking advantage of the new ASP.NET HttpRequest.GetBufferedInputStream() and HttpRequest.GetBufferlessInputStream() methods which are not supported by .NET 3.5.

For example, here is what the Network tab looks like when you use the AjaxFileUpload with Microsoft Internet Explorer:

Here’s what the requests in the Network tab look like:

GET /WebForm1.aspx?contextKey={DA8BEDC8-B952-4d5d-8CC2-59FE922E2923}&poll=1&guid=9206FF94-76F9-B197-D1BC-EA9AD282806B HTTP/1.1

Notice that each request includes a poll=1 parameter. This parameter indicates that this is a polling request to get the size of the file buffered on the server. Here’s what the response body of a request looks like when about 20% of a file has been uploaded:

Buffering to a Temporary File

When you upload a file using the AjaxFileUpload control, the file upload is buffered to a temporary file located at Path.GetTempPath(). When you call the SaveAs() method, as we did in the sample page above, the temporary file is copied to a new file and then the temporary file is deleted.

If you don’t call the SaveAs() method, then you must ensure that the temporary file gets deleted yourself. For example, if you want to save the file to a database then you will never call the SaveAs() method and you are responsible for deleting the file. The easiest way to delete the temporary file is to call the AjaxFileUploadEventArgs.DeleteTemporaryData() method in the UploadComplete handler:

protected void AjaxFileUpload1_UploadComplete(object sender, AjaxControlToolkit.AjaxFileUploadEventArgs e) {
    // Save uploaded file to a database table
   e.DeleteTemporaryData();
}

You also can call the static AjaxFileUpload.CleanAllTemporaryData() method to delete all temporary data and not only the temporary data related to the current file upload. For example, you might want to call this method on application start to ensure that all temporary data is removed whenever your application restarts.

A Better MaskedEdit Extender

This release of the Ajax Control Toolkit contains bug fixes for the top-voted issues related to the MaskedEdit control. We closed over 25 MaskedEdit issues. Here is a complete list of the issues addressed with this release:

· 17302 MaskedEditExtender MaskType=Date, Mask=99/99/99 Undefined JS Error

· 11758 MaskedEdit causes error in JScript when working with 2-digits year

· 18810 Maskededitextender/validator Date validation issue

· 23236 MaskEditValidator does not work with date input using format dd/mm/yyyy

· 23042 Webkit based browsers (Safari, Chrome) and MaskedEditExtender

· 26685 MaskedEditExtender@(ClearMaskOnLostFocus=false) adds a zero character when you each focused to target textbox

· 16109 MaskedEditExtender: Negative amount, followed by decimal, sets value to positive

· 11522 MaskEditExtender of AjaxtoolKit-1.0.10618.0 does not work properly for Hungarian Culture

· 25988 MaskedEditExtender – CultureName (HU-hu) > DateSeparator

· 23221 MaskedEditExtender date separator problem

· 15233 Day and month swap in Dynamic user control

· 15492 MaskedEditExtender with ClearMaskOnLostFocus and with MaskedEditValidator with ClientValidationFunction

· 9389 MaskedEditValidator – when on no entry

· 11392 MaskedEdit Number format messed up

· 11819 MaskedEditExtender erases all values beyond first comma separtor

· 13423 MaskedEdit(Extender/Validator) combo problem

· 16111 MaskedEditValidator cannot validate date with DayMonthYear in UserDateFormat of MaskedEditExtender

· 10901 MaskedEdit: The months and date fields swap values when you hit submit if UserDateFormat is set.

· 15190 MaskedEditValidator can’t make use of MaskedEditExtender’s UserDateFormat property

· 13898 MaskedEdit Extender with custom date type mask gives javascript error

· 14692 MaskedEdit error in “yy/MM/dd” format.

· 16186 MaskedEditExtender does not handle century properly in a date mask

· 26456 MaskedEditBehavior. ConvFmtTime : function(input,loadFirst) fails if this._CultureAMPMPlaceholder == “”

· 21474 Error on MaskedEditExtender working with number format

· 23023 MaskedEditExtender’s ClearMaskOnLostFocus property causes problems for MaskedEditValidator when set to false

· 13656 MaskedEditValidator Min/Max Date value issue

Conclusion

This latest release of the Ajax Control Toolkit required many hours of work by a team of talented developers. I want to thank the members of the Superexpert team for the long hours which they put into this release.

What is special about Meteor? Meteor has two jaw-dropping features:

Live HTML – If you make any changes to the HTML, CSS, JavaScript, or data on the server then every client shows the changes automatically without a browser refresh. For example, if you change the background color of a page to yellow then every open browser will show the new yellow background color without a refresh. Or, if you add a new movie to a collection of movies, then every open browser will display the new movie automatically.

With Live HTML, users no longer need a refresh button. Changes to an application happen everywhere automatically without any effort. The Meteor framework handles all of the messy details of keeping all of the clients in sync with the server for you.

Latency Compensation – When you modify data on the client, these modifications appear as if they happened on the server without any delay. For example, if you create a new movie then the movie appears instantly. However, that is all an illusion. In the background, Meteor updates the database with the new movie. If, for whatever reason, the movie cannot be added to the database then Meteor removes the movie from the client automatically.

Latency compensation is extremely important for creating a responsive web application. You want the user to be able to make instant modifications in the browser and the framework to handle the details of updating the database without slowing down the user.

Installing Meteor

Meteor is licensed under the open-source MIT license and you can start building production apps with the framework right now. Be warned that Meteor is still in the “early preview” stage. It has not reached a 1.0 release. According to the Meteor FAQ, Meteor will reach version 1.0 in “More than a month, less than a year.”

Don’t be scared away by that. You should be aware that, unlike most open source projects, Meteor has financial backing. The Meteor project received an $11.2 million round of financing from Andreessen Horowitz. So, it would be a good bet that this project will reach the 1.0 mark. And, if it doesn’t, the framework as it exists right now is still very powerful.

Meteor runs on top of Node.js. You write Meteor apps by writing JavaScript which runs both on the client and on the server. You can build Meteor apps on Windows, Mac, or Linux (Although the support for Windows is still officially unofficial).

If you want to install Meteor on Windows then download the MSI from the following URL:

http://win.meteor.com/

If you want to install Meteor on Mac/Linux then run the following CURL command from your terminal:

curl https://install.meteor.com | /bin/sh

Meteor will install all of its dependencies automatically including Node.js. However, I recommend that you install Node.js before installing Meteor by installing Node.js from the following address:

http://nodejs.org/

If you let Meteor install Node.js then Meteor won’t install NPM which is the standard package manager for Node.js. If you install Node.js and then you install Meteor then you get NPM automatically.

Creating a New Meteor App

To get a sense of how Meteor works, I am going to walk through the steps required to create a simple Movie database app. Our app will display a list of movies and contain a form for creating a new movie.

The first thing that we need to do is create our new Meteor app. Open a command prompt/terminal window and execute the following command:

Meteor create MovieApp

After you execute this command, you should see something like the following:

Follow the instructions: execute cd MovieApp to change to your MovieApp directory, and run the meteor command.

Executing the meteor command starts Meteor on port 3000. Open up your favorite web browser and navigate to http://localhost:3000 and you should see the default Meteor Hello World page:

Open up your favorite development environment to see what the Meteor app looks like. Open the MovieApp folder which we just created. Here’s what the MovieApp looks like in Visual Studio 2012:

Notice that our MovieApp contains three files named MovieApp.css, MovieApp.html, and MovieApp.js. In other words, it contains a Cascading Style Sheet file, an HTML file, and a JavaScript file.

Just for fun, let’s see how the Live HTML feature works. Open up multiple browsers and point each browser at http://localhost:3000. Now, open the MovieApp.html page and modify the text “Hello World!” to “Hello Cruel World!” and save the change. The text in all of the browsers should update automatically without a browser refresh. Pretty amazing, right?

Controlling Where JavaScript Executes

You write a Meteor app using JavaScript. Some of the JavaScript executes on the client (the browser) and some of the JavaScript executes on the server and some of the JavaScript executes in both places.

For a super simple app, you can use the Meteor.isServer and Meteor.isClient properties to control where your JavaScript code executes. For example, the following JavaScript contains a section of code which executes on the server and a section of code which executes in the browser:

if (Meteor.isClient) {
    console.log("Hello Browser!");
}

if (Meteor.isServer) {
    console.log("Hello Server!");
}

console.log("Hello Browser and Server!");

When you run the app, the message “Hello Browser!” is written to the browser JavaScript console. The message “Hello Server!” is written to the command/terminal window where you ran Meteor. Finally, the message “Hello Browser and Server!” is execute on both the browser and server and the message appears in both places.

For simple apps, using Meteor.isClient and Meteor.isServer to control where JavaScript executes is fine. For more complex apps, you should create separate folders for your server and client code. Here are the folders which you can use in a Meteor app:

· client – This folder contains any JavaScript which executes only on the client.

· server – This folder contains any JavaScript which executes only on the server.

· common – This folder contains any JavaScript code which executes on both the client and server.

· lib – This folder contains any JavaScript files which you want to execute before any other JavaScript files.

· public – This folder contains static application assets such as images.

For the Movie App, we need the client, server, and common folders.

Delete the existing MovieApp.js, MovieApp.html, and MovieApp.css files. We will create new files in the right locations later in this walkthrough.

Combining HTML, CSS, and JavaScript Files

Meteor combines all of your JavaScript files, and all of your Cascading Style Sheet files, and all of your HTML files automatically. If you want to create one humongous JavaScript file which contains all of the code for your app then that is your business. However, if you want to build a more maintainable application, then you should break your JavaScript files into many separate JavaScript files and let Meteor combine them for you.

Meteor also combines all of your HTML files into a single file. HTML files are allowed to have the following top-level elements:

<head> — All <head> files are combined into a single <head> and served with the initial page load.

<body> — All <body> files are combined into a single <body> and served with the initial page load.

<template> — All <template> files are compiled into JavaScript templates.

Because you are creating a single page app, a Meteor app typically will contain a single HTML file for the <head> and <body> content. However, a Meteor app typically will contain several template files. In other words, all of the interesting stuff happens within the <template> files.

Displaying a List of Movies

Let me start building the Movie App by displaying a list of movies.

In order to display a list of movies, we need to create the following four files:

· client\movies.html – Contains the HTML for the <head> and <body> of the page for the Movie app.

· client\moviesTemplate.html – Contains the HTML template for displaying the list of movies.

· client\movies.js – Contains the JavaScript for supplying data to the moviesTemplate.

· server\movies.js – Contains the JavaScript for seeding the database with movies.

After you create these files, your folder structure should looks like this:

Here’s what the client\movies.html file looks like:

<head>
    <title>My Movie App</title>
</head>

<body>
    <h1>Movies</h1>
    {{> moviesTemplate }}
</body>

Notice that it contains <head> and <body> top-level elements. The <body> element includes the moviesTemplate with the syntax {{> moviesTemplate }}.

The moviesTemplate is defined in the client/moviesTemplate.html file:

<template name="moviesTemplate">
    <ul>
    {{#each movies}}
    <li>
        {{title}}
    </li>
    {{/each}}
    </ul>
</template>

By default, Meteor uses the Handlebars templating library. In the moviesTemplate above, Handlebars is used to loop through each of the movies using {{#each}}…{{/each}} and display the title for each movie using {{title}}.

The client\movies.js JavaScript file is used to bind the moviesTemplate to the Movies collection on the client. Here’s what this JavaScript file looks like:

// Declare client Movies collection
Movies = new Meteor.Collection("movies");

// Bind moviesTemplate to Movies collection
Template.moviesTemplate.movies = function () {
    return Movies.find();
};

The Movies collection is a client-side proxy for the server-side Movies database collection. Whenever you want to interact with the collection of Movies stored in the database, you use the Movies collection instead of communicating back to the server.

The moviesTemplate is bound to the Movies collection by assigning a function to the Template.moviesTemplate.movies property. The function simply returns all of the movies from the Movies collection.

The final file which we need is the server-side server\movies.js file:

// Declare server Movies collection
Movies = new Meteor.Collection("movies");

// Seed the movie database with a few movies
Meteor.startup(function () {
    if (Movies.find().count() == 0) {
        Movies.insert({ title: "Star Wars", director: "Lucas" });
        Movies.insert({ title: "Memento", director: "Nolan" });
        Movies.insert({ title: "King Kong", director: "Jackson" });
    }
});

The server\movies.js file does two things. First, it declares the server-side Meteor Movies collection. When you declare a server-side Meteor collection, a collection is created in the MongoDB database associated with your Meteor app automatically (Meteor uses MongoDB as its database automatically).

Second, the server\movies.js file seeds the Movies collection (MongoDB collection) with three movies. Seeding the database gives us some movies to look at when we open the Movies app in a browser.

Creating New Movies

Let me modify the Movies Database App so that we can add new movies to the database of movies. First, I need to create a new template file – named client\movieForm.html – which contains an HTML form for creating a new movie:

<template name="movieForm">
    <fieldset>
    <legend>Add New Movie</legend>
    <form>
        <div>
            <label>
                Title:
                <input id="title" />
            </label>
        </div>
        <div>
            <label>
                Director:
                <input id="director" />
            </label>
        </div>
        <div>
            <input type="submit" value="Add Movie" />
        </div>
    </form>
    </fieldset>
</template>

In order for the new form to show up, I need to modify the client\movies.html file to include the movieForm.html template. Notice that I added {{> movieForm }} to the client\movies.html file:

<head>
    <title>My Movie App</title>
</head>

<body>
    <h1>Movies</h1>
    {{> moviesTemplate }}
    {{> movieForm }}
</body>

After I make these modifications, our Movie app will display the form:

The next step is to handle the submit event for the movie form. Below, I’ve modified the client\movies.js file so that it contains a handler for the submit event raised when you submit the form contained in the movieForm.html template:

// Declare client Movies collection
Movies = new Meteor.Collection("movies");

// Bind moviesTemplate to Movies collection
Template.moviesTemplate.movies = function () {
    return Movies.find();
};

// Handle movieForm events
Template.movieForm.events = {
    'submit': function (e, tmpl) {
        // Don't postback
        e.preventDefault();

        // create the new movie
        var newMovie = {
            title: tmpl.find("#title").value,
            director: tmpl.find("#director").value
        };

        // add the movie to the db
        Movies.insert(newMovie);
    }
};

The Template.movieForm.events property contains an event map which maps event names to handlers. In this case, I am mapping the form submit event to an anonymous function which handles the event.

In the event handler, I am first preventing a postback by calling e.preventDefault(). This is a single page app, no postbacks are allowed!

Next, I am grabbing the new movie from the HTML form. I’m taking advantage of the template find() method to retrieve the form field values.

Finally, I am calling Movies.insert() to insert the new movie into the Movies collection. Here, I am explicitly inserting the new movie into the client-side Movies collection. Meteor inserts the new movie into the server-side Movies collection behind the scenes. When Meteor inserts the movie into the server-side collection, the new movie is added to the MongoDB database associated with the Movies app automatically.

If server-side insertion fails for whatever reasons – for example, your internet connection is lost – then Meteor will remove the movie from the client-side Movies collection automatically. In other words, Meteor takes care of keeping the client Movies collection and the server Movies collection in sync.

If you open multiple browsers, and add movies, then you should notice that all of the movies appear on all of the open browser automatically. You don’t need to refresh individual browsers to update the client-side Movies collection. Meteor keeps everything synchronized between the browsers and server for you.

Removing the Insecure Module

To make it easier to develop and debug a new Meteor app, by default, you can modify the database directly from the client. For example, you can delete all of the data in the database by opening up your browser console window and executing multiple Movies.remove() commands.

Obviously, enabling anyone to modify your database from the browser is not a good idea in a production application. Before you make a Meteor app public, you should first run the meteor remove insecure command from a command/terminal window:

Running meteor remove insecure removes the insecure package from the Movie app. Unfortunately, it also breaks our Movie app. We’ll get an “Access denied” error in our browser console whenever we try to insert a new movie. No worries. I’ll fix this issue in the next section.

Creating Meteor Methods

By taking advantage of Meteor Methods, you can create methods which can be invoked on both the client and the server. By taking advantage of Meteor Methods you can:

1. Perform form validation on both the client and the server. For example, even if an evil hacker bypasses your client code, you can still prevent the hacker from submitting an invalid value for a form field by enforcing validation on the server.

2. Simulate database operations on the client but actually perform the operations on the server.

Let me show you how we can modify our Movie app so it uses Meteor Methods to insert a new movie. First, we need to create a new file named common\methods.js which contains the definition of our Meteor Methods:

Meteor.methods({
    addMovie: function (newMovie) {
        // Perform form validation
        if (newMovie.title == "") {
            throw new Meteor.Error(413, "Missing title!");
        }
        if (newMovie.director == "") {
            throw new Meteor.Error(413, "Missing director!");
        }

        // Insert movie (simulate on client, do it on server)
        return Movies.insert(newMovie);
    }

});

The addMovie() method is called from both the client and the server. This method does two things. First, it performs some basic validation. If you don’t enter a title or you don’t enter a director then an error is thrown.

Second, the addMovie() method inserts the new movie into the Movies collection. When called on the client, inserting the new movie into the Movies collection just updates the collection. When called on the server, inserting the new movie into the Movies collection causes the database (MongoDB) to be updated with the new movie.

You must add the common\methods.js file to the common folder so it will get executed on both the client and the server. Our folder structure now looks like this:

We actually call the addMovie() method within our client code in the client\movies.js file. Here’s what the updated file looks like:

// Declare client Movies collection
Movies = new Meteor.Collection("movies");

// Bind moviesTemplate to Movies collection
Template.moviesTemplate.movies = function () {
    return Movies.find();
};

// Handle movieForm events
Template.movieForm.events = {
    'submit': function (e, tmpl) {
        // Don't postback
        e.preventDefault();

        // create the new movie
        var newMovie = {
            title: tmpl.find("#title").value,
            director: tmpl.find("#director").value
        };

        // add the movie to the db
        Meteor.call(
            "addMovie",
            newMovie,
            function (err, result) {
                if (err) {
                    alert("Could not add movie " + err.reason);
                }
            }
       );

    }
};

The addMovie() method is called – on both the client and the server – by calling the Meteor.call() method. This method accepts the following parameters:

· The string name of the method to call.

· The data to pass to the method (You can actually pass multiple params for the data if you like).

· A callback function to invoke after the method completes.

In the JavaScript code above, the addMovie() method is called with the new movie retrieved from the HTML form. The callback checks for an error. If there is an error then the error reason is displayed in an alert (please don’t use alerts for validation errors in a production app because they are ugly!).

Summary

The goal of this blog post was to provide you with a brief walk through of a simple Meteor app. I showed you how you can create a simple Movie Database app which enables you to display a list of movies and create new movies.

I also explained why it is important to remove the Meteor insecure package from a production app. I showed you how to use Meteor Methods to insert data into the database instead of doing it directly from the client.

I’m very impressed with the Meteor framework. The support for Live HTML and Latency Compensation are required features for many real world Single Page Apps but implementing these features by hand is not easy. Meteor makes it easy.

In this blog entry, I discuss two areas in which you need to exercise extra caution when building a Single Page App. I discuss how Single Page Apps are extra vulnerable to both Cross-Site Scripting (XSS) attacks and Cross-Site Request Forgery (CSRF) attacks.

This goal of this blog post is NOT to persuade you to avoid writing Single Page Apps. I’m a big fan of Single Page Apps. Instead, the goal is to ensure that you are fully aware of some of the security issues related to Single Page Apps and ensure that you know how to guard against them.

Cross-Site Scripting (XSS) Attacks

According to WhiteHat Security, over 65% of public websites are open to XSS attacks. That’s bad. By taking advantage of XSS holes in a website, a hacker can steal your credit cards, passwords, or bank account information.

Any website that redisplays untrusted information is open to XSS attacks. Let me give you a simple example.

Imagine that you want to display the name of the current user on a page. To do this, you create the following server-side ASP.NET page located at http://MajorBank.com/SomePage.aspx:

<%@Page Language="C#"  %>
<html>
<head>
    <title>Some Page</title>
</head>
<body>

    Welcome <%= Request["username"] %>

</body>
</html>

Nothing fancy here. Notice that the page displays the current username by using Request[“username”]. Using Request[“username”] displays the username regardless of whether the username is present in a cookie, a form field, or a query string variable.

Unfortunately, by using Request[“username”] to redisplay untrusted information, you have now opened your website to XSS attacks. Here’s how.

Imagine that an evil hacker creates the following link on another website (hackers.com):

<a href="/SomePage.aspx?username=<script src=Evil.js></script>">Visit MajorBank</a>

Notice that the link includes a query string variable named username and the value of the username variable is an HTML <SCRIPT> tag which points to a JavaScript file named Evil.js. When anyone clicks on the link, the <SCRIPT> tag will be injected into SomePage.aspx and the Evil.js script will be loaded and executed.

What can a hacker do in the Evil.js script? Anything the hacker wants. For example, the hacker could display a popup dialog on the MajorBank.com site which asks the user to enter their password. The script could then post the password back to hackers.com and now the evil hacker has your secret password.

ASP.NET Web Forms and ASP.NET MVC have two automatic safeguards against this type of attack: Request Validation and Automatic HTML Encoding.

Protecting Coming In (Request Validation)

In a server-side ASP.NET app, you are protected against the XSS attack described above by a feature named Request Validation. If you attempt to submit “potentially dangerous” content — such as a JavaScript <SCRIPT> tag — in a form field or query string variable then you get an exception.

Unfortunately, Request Validation only applies to server-side apps. Request Validation does not help in the case of a Single Page App. In particular, the ASP.NET Web API does not pay attention to Request Validation. You can post any content you want – including <SCRIPT> tags – to an ASP.NET Web API action.

For example, the following HTML page contains a form. When you submit the form, the form data is submitted to an ASP.NET Web API controller on the server using an Ajax request:

<!DOCTYPE html>
<html xmlns="http://www.w3.org/1999/xhtml">
<head>
    <title></title>
</head>
<body>

    <form data-bind="submit:submit">
    <div>
        <label>
            User Name:
            <input data-bind="value:user.userName" />
        </label>
    </div>
    <div>
        <label>
            Email:
            <input data-bind="value:user.email" />
        </label>
    </div>
    <div>
        <input type="submit" value="Submit" />
    </div>
    </form>

    <script src="Scripts/jquery-1.7.1.js"></script>
    <script src="Scripts/knockout-2.1.0.js"></script>

    <script>

        var viewModel = {

            user: {
                userName: ko.observable(),
                email: ko.observable()
            },

            submit: function () {
                $.post("/api/users", ko.toJS(this.user));
            }
        };

        ko.applyBindings(viewModel);

    </script>

</body>
</html>

The form above is using Knockout to bind the form fields to a view model. When you submit the form, the view model is submitted to an ASP.NET Web API action on the server.

Here’s the server-side ASP.NET Web API controller and model class:

public class UsersController : ApiController
{

    public HttpResponseMessage Post(UserViewModel user) {
        var userName = user.UserName;
        return Request.CreateResponse(HttpStatusCode.OK);
    }

}


public class UserViewModel {
    public string UserName { get; set; }
    public string Email { get; set; }
}

If you submit the HTML form, you don’t get an error. The “potentially dangerous” content is passed to the server without any exception being thrown. In the screenshot below, you can see that I was able to post a username form field with the value “<script>alert(‘boo’)</script”.

So what this means is that you do not get automatic Request Validation in the case of a Single Page App. You need to be extra careful in a Single Page App about ensuring that you do not display untrusted content because you don’t have the Request Validation safety net which you have in a traditional server-side ASP.NET app.

Protecting Going Out (Automatic HTML Encoding)

Server-side ASP.NET also protects you from XSS attacks when you render content. By default, all content rendered by the razor view engine is HTML encoded. For example, the following razor view displays the text “<b>Hello!</b>” instead of the text “Hello!” in bold:

@{
    var message = "<b>Hello!</b>";
}

@message

If you don’t want to render content as HTML encoded in razor then you need to take the extra step of using the @Html.Raw() helper.

In a Web Form page, if you use <%: %> instead of <%= %> then you get automatic HTML Encoding:

<%@ Page Language="C#" %> 

<% 

var message = "<b>Hello!</b>"; 

%> 

<%: message %> 

This automatic HTML Encoding will prevent many types of XSS attacks. It prevents <script> tags from being rendered and only allows &lt;script&gt; tags to be rendered which are useless for executing JavaScript.

(This automatic HTML encoding does not protect you from all forms of XSS attacks. For example, you can assign the value “javascript:alert(‘evil’)” to the Hyperlink control’s NavigateUrl property and execute the JavaScript).

The situation with Knockout is more complicated. If you use the Knockout TEXT binding then you get HTML encoded content. On the other hand, if you use the HTML binding then you do not:

<!-- This JavaScript DOES NOT execute -->
<div data-bind="text:someProp"></div>

<!-- This Javacript DOES execute -->
<div data-bind="html:someProp"></div>


<script src="Scripts/jquery-1.7.1.js"></script>
<script src="Scripts/knockout-2.1.0.js"></script>

<script>    

    var viewModel = {
        someProp : "<script>alert('Evil!')<" + "/script>"
    };

    ko.applyBindings(viewModel);

</script>

So, in the page above, the DIV element which uses the TEXT binding is safe from XSS attacks. According to the Knockout documentation:

“Since this binding sets your text value using a text node, it’s safe to set any string value without risking HTML or script injection.”

Just like server-side HTML encoding, Knockout does not protect you from all types of XSS attacks. For example, there is nothing in Knockout which prevents you from binding JavaScript to a hyperlink like this:

<a data-bind="attr:{href:homePageUrl}">Go</a>

<script src="Scripts/jquery-1.7.1.min.js"></script>
<script src="Scripts/knockout-2.1.0.js"></script>

<script>    

    var viewModel = {
        homePageUrl: "javascript:alert('evil!')"
    };


    ko.applyBindings(viewModel);

</script>

In the page above, the value “javascript:alert(‘evil’)” is bound to the HREF attribute using Knockout. When you click the link, the JavaScript executes.

Cross-Site Request Forgery (CSRF) Attacks

Cross-Site Request Forgery (CSRF) attacks rely on the fact that a session cookie does not expire until you close your browser. In particular, if you visit and login to MajorBank.com and then you navigate to Hackers.com then you will still be authenticated against MajorBank.com even after you navigate to Hackers.com.

Because MajorBank.com cannot tell whether a request is coming from MajorBank.com or Hackers.com, Hackers.com can submit requests to MajorBank.com pretending to be you. For example, Hackers.com can post an HTML form from Hackers.com to MajorBank.com and change your email address at MajorBank.com. Hackers.com can post a form to MajorBank.com using your authentication cookie.

After your email address has been changed, by using a password reset page at MajorBank.com, a hacker can access your bank account.

To prevent CSRF attacks, you need some mechanism for detecting whether a request is coming from a page loaded from your website or whether the request is coming from some other website. The recommended way of preventing Cross-Site Request Forgery attacks is to use the “Synchronizer Token Pattern” as described here:

https://www.owasp.org/index.php/Cross-Site_Request_Forgery_%28CSRF%29_Prevention_Cheat_Sheet

When using the Synchronizer Token Pattern, you include a hidden input field which contains a random token whenever you display an HTML form. When the user opens the form, you add a cookie to the user’s browser with the same random token. When the user posts the form, you verify that the hidden form token and the cookie token match.

Preventing Cross-Site Request Forgery Attacks with ASP.NET MVC

ASP.NET gives you a helper and an action filter which you can use to thwart Cross-Site Request Forgery attacks. For example, the following razor form for creating a product shows how you use the @Html.AntiForgeryToken() helper:

@model MvcApplication2.Models.Product

<h2>Create Product</h2>

@using (Html.BeginForm()) {

    @Html.AntiForgeryToken();
    
    <div>
        @Html.LabelFor( p => p.Name, "Product Name:")
        @Html.TextBoxFor( p => p.Name)
    </div>

    <div>
        @Html.LabelFor( p => p.Price, "Product Price:")
        @Html.TextBoxFor( p => p.Price)
    </div>
    
    <input type="submit" />

}

The @Html.AntiForgeryToken() helper generates a random token and assigns a serialized version of the same random token to both a cookie and a hidden form field. (Actually, if you dive into the source code, the AntiForgeryToken() does something a little more complex because it takes advantage of a user’s identity when generating the token).

Here’s what the hidden form field looks like:

<input name=”__RequestVerificationToken” type=”hidden” value=”NqqZGAmlDHh6fPTNR_mti3nYGUDgpIkCiJHnEEL59S7FNToyyeSo7v4AfzF2i67Cv0qTB1TgmZcqiVtgdkW2NnXgEcBc-iBts0x6WAIShtM1″ />

And here’s what the cookie looks like using the Google Chrome developer toolbar:

You use the [ValidateAntiForgeryToken] action filter on the controller action which is the recipient of the form post to validate that the token in the hidden form field matches the token in the cookie. If the tokens don’t match then validation fails and you can’t post the form:

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

[ValidateAntiForgeryToken]
[HttpPost]
public ActionResult Create(Product productToCreate) {
    if (ModelState.IsValid) {
        // save product to db
        return RedirectToAction("Index");
    }
    return View();
}

How does this all work? Let’s imagine that a hacker has copied the Create Product page from MajorBank.com to Hackers.com – the hacker grabs the HTML source and places it at Hackers.com. Now, imagine that the hacker trick you into submitting the Create Product form from Hackers.com to MajorBank.com. You’ll get the following exception:

The Cross-Site Request Forgery attack is blocked because the anti-forgery token included in the Create Product form at Hackers.com won’t match the anti-forgery token stored in the cookie in your browser. The tokens were generated at different times for different users so the attack fails.

Preventing Cross-Site Request Forgery Attacks with a Single Page App

In a Single Page App, you can’t prevent Cross-Site Request Forgery attacks using the same method as a server-side ASP.NET MVC app. In a Single Page App, HTML forms are not generated on the server. Instead, in a Single Page App, forms are loaded dynamically in the browser.

Phil Haack has a blog post on this topic where he discusses passing the anti-forgery token in an Ajax header instead of a hidden form field. He also describes how you can create a custom anti-forgery token attribute to compare the token in the Ajax header and the token in the cookie. See:

http://haacked.com/archive/2011/10/10/preventing-csrf-with-ajax.aspx

Also, take a look at Johan’s update to Phil Haack’s original post:

http://johan.driessen.se/posts/Updated-Anti-XSRF-Validation-for-ASP.NET-MVC-4-RC

(Other server frameworks such as Rails and Django do something similar. For example, Rails uses an X-CSRF-Token to prevent CSRF attacks which you generate on the server – see http://excid3.com/blog/rails-tip-2-include-csrf-token-with-every-ajax-request/#.UTFtgDDkvL8 ).

For example, if you are creating a Durandal app, then you can use the following razor view for your one and only server-side page:

@{
    Layout = null;
}
<!DOCTYPE html>
<html>
<head>
    <title>Index</title>
</head>
<body>

    @Html.AntiForgeryToken()

    <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 this page includes a call to @Html.AntiForgeryToken() to generate the anti-forgery token.

Then, whenever you make an Ajax request in the Durandal app, you can retrieve the anti-forgery token from the razor view and pass the token as a header:

var csrfToken = $("input[name='__RequestVerificationToken']").val(); 
$.ajax({
    headers: { __RequestVerificationToken: csrfToken },
    type: "POST",
    dataType: "json",
    contentType: 'application/json; charset=utf-8',
    url: "/api/products",
    data: JSON.stringify({ name: "Milk", price: 2.33 }),
    statusCode: {
        200: function () {
            alert("Success!");
        }
    }
});

Use the following code to create an action filter which you can use to match the header and cookie tokens:

using System.Linq;
using System.Net.Http;
using System.Web.Helpers;
using System.Web.Http.Controllers;

namespace MvcApplication2.Infrastructure {

    public class ValidateAjaxAntiForgeryToken : System.Web.Http.AuthorizeAttribute {

        protected override bool IsAuthorized(HttpActionContext actionContext) {

            var headerToken = actionContext
                .Request
                .Headers
                .GetValues("__RequestVerificationToken")
                .FirstOrDefault(); ;

            var cookieToken = actionContext
                .Request
                .Headers
                .GetCookies()
                .Select(c => c[AntiForgeryConfig.CookieName])
                .FirstOrDefault();

            // check for missing cookie or header
            if (cookieToken == null || headerToken == null) {
                return false;
            }

            // ensure that the cookie matches the header
            try {
                AntiForgery.Validate(cookieToken.Value, headerToken);
            } catch {
                return false;
            }
            
            return base.IsAuthorized(actionContext);
        }
 
    }
}

Notice that the action filter derives from the base AuthorizeAttribute. The ValidateAjaxAntiForgeryToken only works when the user is authenticated and it will not work for anonymous requests.

Add the action filter to your ASP.NET Web API controller actions like this:

[ValidateAjaxAntiForgeryToken]
public HttpResponseMessage PostProduct(Product productToCreate) {
    // add product to db
    return Request.CreateResponse(HttpStatusCode.OK);
}

After you complete these steps, it won’t be possible for a hacker to pretend to be you at Hackers.com and submit a form to MajorBank.com. The header token used in the Ajax request won’t travel to Hackers.com.

This approach works, but I am not entirely happy with it. The one thing that I don’t like about this approach is that it creates a hard dependency on using razor. Your single page in your Single Page App must be generated from a server-side razor view. A better solution would be to generate the anti-forgery token in JavaScript.

Unfortunately, until all browsers support a way to generate cryptographically strong random numbers – for example, by supporting the window.crypto.getRandomValues() method — there is no good way to generate anti-forgery tokens in JavaScript. So, at least right now, the best solution for generating the tokens is the server-side solution with the (regrettable) dependency on razor.

Conclusion

The goal of this blog entry was to explore some ways in which you need to handle security differently in the case of a Single Page App than in the case of a traditional server app. In particular, I focused on how to prevent Cross-Site Scripting and Cross-Site Request Forgery attacks in the case of a Single Page App.

I want to emphasize that I am not suggesting that Single Page Apps are inherently less secure than server-side apps. Whatever type of web application you build – regardless of whether it is a Single Page App, an ASP.NET MVC app, an ASP.NET Web Forms app, or a Rails app – you must constantly guard against security vulnerabilities.

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

Here’s a quick summary of the talk. I argued that Single Page Apps are better than traditional Server Side Apps because:

1. Single Page Apps are Stateful – In a traditional server-side app, whenever you navigate to a new page, all of your previous state is lost. It is like rebooting your computer whenever you perform any action

2. In a Single Page App, Your Presentation Layer is Not Miles Away – In a traditional server-side app, because everything happens on the server, your presentation layer is separated from the user by space and time. In a Single Page App, the presentation layer is in the browser and not the server (which is the right place for a presentation layer).

3. A Single Page App Respects the Web – It is easier to take advantage of HTML5 and related standards when building a Single Page App.

Next, I recommended using the following four technologies when building a web application:

1. Knockout – This is how you create your presentation layer.

2. ASP.NET Web API – This is how you expose JSON data from your web server and perform server-side validation.

3. HTML5 – This is how you implement client-side validation.

4. Sammy – This is how you implement client-side routing and create a Single Page App with multiple virtual pages.

There are code samples in the download (look in the Samples folder) which demonstrate how all of these technologies work when building Single Page Apps.

• Powerpoint
• Sample Code

You can download the new release directly from http://AjaxControlToolkit.CodePlex.com – or, just fire the following command from the Visual Studio Library Package Manager Console Window (NuGet):

You also can view the new chart controls by visiting the “live” Ajax Control Toolkit Sample Site.

5 New Ajax Control Toolkit Chart Controls

The Ajax Control Toolkit contains five new chart controls: the AreaChart, BarChart, BubbleChart, LineChart, and PieChart controls.

Here is a sample of each of the controls:

AreaChart:

BarChart:

BubbleChart:

LineChart:

PieChart:

We realize that people love to customize the appearance of their charts so all of the chart controls include properties such as color properties.

The chart controls render the chart on the browser using SVG. The chart controls are compatible with any browser which supports SVG including Internet Explorer 9 and new and recent versions of Google Chrome, Mozilla Firefox, and Apple Safari. (If you attempt to display a chart on a browser which does not support SVG then you won’t get an error – you just won’t get anything).

Updates to the HTML Sanitizer

If you are using the HtmlEditorExtender on a public-facing website then it is really important that you enable the HTML Sanitizer to prevent Cross-Site Scripting (XSS) attacks. The HtmlEditorExtender uses the HTML Sanitizer by default.

The HTML Sanitizer strips out any suspicious content (like JavaScript code and CSS expressions) from the HTML submitted with the HtmlEditorExtender. We followed the recommendations of OWASP and ha.ckers.org to identify suspicious content.

We updated the HTML Sanitizer with this release to protect against new types of XSS attacks. The HTML Sanitizer now has over 220 unit tests. The Ajax Control Toolkit team would like to thank Gil Cohen who helped us identify and block additional XSS attacks.

Change in Ajax Control Toolkit Version Format

We ran out of numbers. The Ajax Control Toolkit was first released way back in 2006. In previous releases, the version of the Ajax Control Toolkit followed the format: Release Year + Date. So, the previous release was 60919 where 6 represented the 6^th release year and 0919 represent September 19.

Unfortunately, the AssembyVersion attribute uses a UInt16 data type which has a maximum size of 65,534. The number 70123 is bigger than 65,534 so we had to change our version format with this release.

Fortunately, the AssemblyVersion attribute actually accepts four UInt16 numbers so we used another one. This release of the Ajax Control Toolkit is officially version 7.0123. This new version format should work for another 65,000 years.

And yes, I realize that 7.0123 is less than 60,919, but we ran out of numbers.

Summary

I hope that you find the chart controls included with this latest release of the Ajax Control Toolkit useful. Let me know if you use them in applications that you build. And, let me know if you run into any issues using the new chart controls. Next month, back to improving the File Upload control – more exciting stuff.

Why build Windows 8 apps? When you create a Windows 8 app, you can put your app in the Windows 8 Store. In other words, customers can buy your app directly from Windows. Think iPhone apps, but for a much larger market.

In my book, I explain how you can create both game apps and simple productivity apps by creating Windows 8 apps with JavaScript. The book is a short read and I include plenty of code samples that have been tested against the final release of Windows 8.

You can buy the book by going to your local Barnes & Noble bookstore or you can buy the book through Amazon by using the following link:

It looks like the book is also available for the Kindle:

Kindle: Windows 8 Apps with HTML5 and JavaScript Unleashed

The Brain Eaters app is a sample app from my soon to be released book Windows 8 Apps with HTML5 and JavaScript. The game illustrates several important programming concepts which you need when building Windows 8 games with JavaScript such as using HTML5 Canvas and the new requestAnimationFrame() method.

If you are looking for Halo or Call of Duty then you will be disappointed. If you are looking for PAC-MAN then you will be disappointed. I created the simplest arcade game that I could imagine so I could explain it in the book. All of the code for the game is included with the book.

The goal of the game is to eat the food pellets while avoiding the zombies while running around a maze. Every time you get eaten by a zombie, you can hear my six year old son saying “Oh No!”.

Here’s the link to the game:

http://apps.microsoft.com/webpdp/app/brain-eaters/e283c8d0-1fed-4b26-a8bf-464584c9de6d

The book focuses on building apps using HTML5 and JavaScript. If you are already comfortable building websites, then building Windows Store apps is not a huge leap.  I explain how you can create productivity apps, like a Task List app, and games, like a simple arcade game. I also explain how you can publish your app to the Windows Store and make money.

To celebrate the release of Windows 8, my publisher is offering a huge 40% discount on the book until November 30, 2012. If you want to take advantage of this discount, follow the link below and enter the discount code WINDEV40 during checkout.

http://www.informit.com/promotions/promotion.aspx?promo=139036&walther

So what’s in the book?  Here’s an overview of each of the chapters:

Chapter 1 – Building Windows Store Apps

Contains a walkthrough of creating a super simple Windows app for taking pictures from your webcam. Explains how to publish your app to the Windows Store.

Chapter 2 – WinJS Fundamentals

Provides an overview of the Windows Library for JavaScript which is the Microsoft library for creating Windows Store apps with JavaScript.

Chapter 3 – Observables, Bindings, and Templates

You learn how to display a list of items using a template. For example, you learn how to create a template which can be used to display a list of products.

Chapter 4 – Using WinJS Controls

Overview of the core set of JavaScript controls included with the WinJS library. You learn how to use the Tooltip, ToggleSwitch, Rating, DatePicker, TimePicker, and FlipView controls.

Chapter 5 – Creating Forms

This chapter explains how to take advantage of HTML5 forms to display specialized keyboards and perform form validation.

Chapter 6 – Menus and Flyouts

You learn how to display popups, menus, and toolbars using the JavaScript controls included with the WinJS library.

Chapter 7 – Using the ListView Control

This entire chapter is devoted to the ListView control which is the most important control in the WinJS library. You can use the ListView control to display, sort, filter, and edit a list of items.

Chapter 8 – Creating Data Sources

Learn how to use a ListView control to display data from the file system, a web service, and IndexedDB.

Chapter 9 – App Events and States

This chapter explains the standard application events which are raised in a Windows Store app such as the activated and checkpoint events. You also learn how to build apps which adapt automatically to different view states such as portrait and landscape.

Chapter 10 – Page Fragments and Navigation

This chapter discusses two subjects: You learn how to create custom WinJS controls with Page Controls and you learn how to build apps with multiple pages. 

Chapter 11 – Using the Live Connect API

Learn how to use Windows Live Services to authenticate users, interact with SkyDrive, and retrieve user profile information (such as a user’s birthday or profile picture).

Chapter 12 – Graphics and Games

This chapter is devoted to building the Brain Eaters app which is a simple arcade game. Navigate a maze and eat all of the food pellets while avoiding the brain-eating zombies to win the game. Learn how to create the game using HTML5 Canvas.

If you want to buy the book, remember to use the magic discount code WINDEV40 and visit the following link:

http://www.informit.com/promotions/promotion.aspx?promo=139036&walther