Building Single Page Apps with ASP.NET MVC4 - Part 1 - Basic Desktop Application

This blog entry is mainly based on the presentation given by Steven Sanderson on TechDays 2012 called “Building Single Page Apps for desktop, mobile and tablet with ASP.NET MVC 4”. Steven’s talk consisted of a large demo that immediately got me interested and made me want to try it out.
There was one big disappointment however. With the latest beta version of ASP.NET MVC 4 and information from the official pages, it was not possible to recreate Steven’s demo. In the following post, I’ll show what I had to do to get things to work. This is the first post of a series

1. Single Page Applications - Part 1 - Basic Desktop application
2. Single Page Applications - Part 2 - Advanced Desktop Application
3. Single Page Applications - Part 3 - Basic Mobile Application
4. Single Page Applications - Part 4 - Sorting, Filtering and Manipulation data with upshot.js
5. Single Page Applications - Part 5 - With MVC4 RC

New Project Template

The ASP.NET MVC 4 beta adds a new project template in Visual Studio 2010 called “The “Single Page Application" (SPA). When creating a new project and starting it up, you’ll get some guidance about completing a first demo application for adding ToDoItems using a new TasksController. I will not do this but instead I will follow the same sequence as Steve did in his presentation and create a new SPA application called “DeliveryTracker”

Server side Domain Model

Since this demo application is a tool to track deliveries we will be using the following datamodel. The Customer class shows how to define a one-to-many relationship.

namespace DeliveryTracker.Models
{
    public class Customer
    {
        public int CustomerId { get; set; }

        public string Name { get; set; }
        public string Address { get; set; }
    }

    public class Delivery
    {
        public int DeliveryId { get; set; }
        public virtual int CustomerId { get; set; }
        public virtual Customer Customer { get; set; }

        public string Description { get; set; }
        public bool IsDelivered { get; set; }
    }
}

In order to store delivery information in the database, we are using the Entity Framework Code First approach

namespace DeliveryTracker.Models
{
    public class AppDbContext : DbContext
    {
        public DbSet<Customer> Customers { get; set; }
        public DbSet<Delivery> Deliveries { get; set; }
    }
}

Web API Data Service

The data for the application is loaded from a DbDataController which was introduced with the new Web API feature. In the solution explorer, right-click the controller folder and add a new controller called “DataServiceController” based on the “Empty Controller” template. The purpose here is to show what is happening behind the scenes and not rely on scaffolding too much. Replace the parent Controller class by DbDataController using the AppDbContext as generic parameter.

namespace DeliveryTracker.Controllers
{
    public class DataServiceController : DbDataController<AppDbContext>
    {

        public IQueryable<Delivery> GetDeliveriesForToday() 
        {
            return DbContext.Deliveries.Include("Customer")
                            .OrderBy(x => x.DeliveryId);
        }

        public void InsertDelivery(Delivery delivery) 
                  { InsertEntity(delivery); }
        public void UpdateDelivery(Delivery delivery) 
                  { UpdateEntity(delivery); }
        public void DeleteDelivery(Delivery delivery) 
                  { DeleteEntity(delivery); }
    }
}

The GetDeliveriesForToday will be used by the page to load the data. The IQueryable type allows sorting, paging, filtering and passing in custom parameters. The other methods are necessary for inserting, updating and deleting entities. If you build and run now, you could run OData queries against the service on http://localhost/api/DataService/GetDeliveriesForToday

Client Side ViewModel -  upshot.js & knockout.js

In order to use this data, the page will use the upshot.js javascript library that knows how to talk to a DbDataController. It will want to map your server side C# model in to a client-side javascript model. Steven has hidden this step behind his mysterious and undocumented Html.UpshotContext class.

Add a new “App” subfolder inside the “Scripts” folder and create a new script there called “DeliveryViewModel.js”. In the constructor of the DeliveriesViewModel, we are using upshot to make a connection to the GetDeliveriesForToday method in the DbDataController class. The results from the query are stored in the self.deliveries property.

Notice that the properties of the Customer and Delivery classes are knockout observables. Knockout keeps the data on your views and viewmodel synchronized. Upshot synchronizes with the data service. The bufferChanges option is set to false, meaning that any data that is changed on the web page will also be submitted to the server and saved directly in the database.

/// <reference path="_references.js" />

function DeliveriesViewModel() {
    // Private
    var self = this;
    var dataSourceOptions = {
        providerParameters: { 
          url: "/api/DataService", 
          operationName: "GetDeliveriesForToday"
        },
        entityType: "Delivery:#DeliveryTracker.Models",
        bufferChanges: false,
        mapping : Delivery
    };

    // Public Properties
    self.dataSource = new upshot.RemoteDataSource(dataSourceOptions)
                                .refresh();
    self.deliveries = self.dataSource.getEntities();   
}

function Customer (data) {
    var self = this;

    self.CustomerId = ko.observable(data.CustomerId);
    self.Name = ko.observable(data.Name);
    self.Address = ko.observable(data.Address);
    upshot.addEntityProperties(self, "Customer:#DeliveryTracker.Models");
}

function Delivery (data) {
    var self = this;

    self.DeliveryId = ko.observable(data.DeliveryId);
    self.CustomerId = ko.observable(data.CustomerId);
    self.Customer = ko.observable(data.Customer);
    self.Description = ko.observable(data.Description);
    self.IsDelivered = ko.observable(data.IsDelivered);
    upshot.addEntityProperties(self, "Delivery:#DeliveryTracker.Models");
}

Index View

In order to trigger the upshot call to the service when the index.cshtml page is loaded, add this code below the title section. All the rest of the code is not needed and can be removed. The Html.MetaData function provides the structure of the types to upshot. Knockout applies the bindings to the DeliveriesViewModel

<script src="~/Scripts/upshot.js" 
          type="text/javascript"></script>
<script src="~/Scripts/knockout-2.0.0.js" 
          type="text/javascript"></script>
<script src="~/Scripts/nav.js" 
          type="text/javascript"></script>
<script src="~/Scripts/native.history.js" 
          type="text/javascript"></script>
<script src="~/Scripts/upshot.compat.knockout.js"
          type="text/javascript"></script>
<script src="~/Scripts/upshot.knockout.extensions.js" 
          type="text/javascript"></script>
<script src="~/Scripts/App/DeliveriesViewModel.js" 
          type="text/javascript"></script>

<script type="text/javascript">
    $(function () {
        upshot.metadata(@(Html.Metadata
            <DeliveryTracker.Controllers.DataServiceController>()));

        ko.applyBindings( new DeliveriesViewModel( ));
    });
</script>

We can now use the data that is loaded and bound to the DeliveriesViewModel in the HTML. Add this code below the javascript call

<section>
<div>
    <h3>Deliveries</h3>
    <ol data-bind="foreach: deliveries">
        <li data-bind="css: { highlight: IsDelivered}">
            <strong data-bind="text: Description"></strong>
            is for <em data-bind="text: Customer().Name"></em>
            <label>
               <input data-bind="checked: IsDelivered" 
                           type="checkbox"/>
               Delivered</label>
        </li>
    </ol>
</div>
</section>

Routing

If you run this code, you will noticed that loading data from the database and displaying it on page works fine but submitting changes to the services fails. Investigating with Fiddler shows that the service responds to the submit request with the error “The service does not support the POST verb”

What Steven Sanderson also failed to mention is that you need to correct the 'MapHttpRoute' route in the routing table in global.asax.cs like this:

            routes.MapHttpRoute(
                "DataService", // Route name
                "api/DataService/{action}", // URL with parameters
                new { controller = "DataService" } // Parameter defaults
            );

So with the code above you can list the deliveries in the database and update the "IsDelivered" properties in real-time from a single page. All communication consists of AJAX calls handled by the upshot framework.

Download the source code

You can download the code (Visual Studio 2010 project) from my Skydrive