Stephen Walther

Metro Walkthrough: Creating a Task List with a ListView and IndexedDB

Stephen.Walther — Fri, 25 May 2012 00:34:48 +0000

The goal of this blog entry is to describe how you can work with data in a Metro style application written with JavaScript. In particular, we create a super simple Task List application which enables you to create and delete tasks.

Here’s a video which demonstrates how the Task List application works:

In order to build this application, I had to take advantage of several features of the WinJS library and technologies including:

IndexedDB – The Task List application stores data in an IndexedDB database.
HTML5 Form Validation – The Task List application uses HTML5 validation to ensure that a required field has a value.
ListView Control – The Task List application displays the tasks retrieved from the IndexedDB database in a WinJS ListView control.

Creating the IndexedDB Database

The Task List application stores all of its data in an IndexedDB database named TasksDB. This database is opened/created with the following code:

var db;
var req = window.msIndexedDB.open("TasksDB", 1);
req.onerror = function () {
    console.log("Could not open database");
};
req.onupgradeneeded = function (evt) {
    var newDB = evt.target.result;
    newDB.createObjectStore("tasks", { keyPath: "id", autoIncrement:true });
};

The msIndexedDB.open() method accepts two parameters: the name of the database to open and the version of the database to open. If a database with a matching version already exists, then calling the msIndexedDB.open() method opens a connection to the existing database. If the database does not exist then the upgradeneeded event is raised.

You handle the upgradeneeded event to create a new database. In the code above, the upgradeneeded event handler creates an object store named “tasks” (An object store roughly corresponds to a database table). When you add items to the tasks object store then each item gets an id property with an auto-incremented value automatically.

The code above also includes an error event handler. If the IndexedDB database cannot be opened or created, for whatever reason, then an error message is written to the Visual Studio JavaScript Console window.

Displaying a List of Tasks

The TaskList application retrieves its list of tasks from the tasks object store, which we created above, and displays the list of tasks in a ListView control. Here is how the ListView control is declared:

The ListView control is bound to the TaskList.tasks.dataSource data source. The TaskList.tasks.dataSource is created with the following code:

// Create the data source
var tasks = new WinJS.Binding.List();

// Open the database
var db;
var req = window.msIndexedDB.open("TasksDB", 1);
req.onerror = function () {
    console.log("Could not open database");
};
req.onupgradeneeded = function (evt) {
    var newDB = evt.target.result;
    newDB.createObjectStore("tasks", { keyPath: "id", autoIncrement:true });
};

// Load the data source with data from the database
req.onsuccess = function () {
    db = req.result;
    var tran = db.transaction("tasks");
    tran.objectStore("tasks").openCursor().onsuccess = function(event) {
        var cursor = event.target.result;
        tasks.dataSource.beginEdits();
        if (cursor) {
            tasks.dataSource.insertAtEnd(null, cursor.value);
            cursor.continue();
        } else {
            tasks.dataSource.endEdits();
        };
    };  

};

// Expose the data source and functions
WinJS.Namespace.define("TaskList", {
    tasks: tasks
});

Notice the success event handler. This handler is called when a database is successfully opened/created. In the code above, all of the items from the tasks object store are retrieved into a cursor and added to a WinJS.Binding.List object named tasks.

Because the ListView control is bound to the WinJS.Binding.List object, copying the tasks from the object store into the WinJS.Binding.List object causes the tasks to appear in the ListView:

Adding a New Task

You add a new task in the Task List application by entering the title of a new task into an HTML form and clicking the Add button. Here’s the markup for creating the form:

Notice that the INPUT element includes a required attribute. In a Metro application, you can take advantage of HTML5 Validation to validate form fields. If you don’t enter a value for the newTaskTitle field then the following validation error message is displayed:

For a brief introduction to HTML5 validation, see my previous blog entry:

http://stephenwalther.com/blog/archive/2012/03/13/html5-form-validation.aspx

When you click the Add button, the form is submitted and the form submit event is raised. The following code is executed in the default.js file:

// Handle Add Task
document.getElementById("addTaskForm").addEventListener("submit", function (evt) {
    evt.preventDefault();
    var newTaskTitle = document.getElementById("newTaskTitle");
    TaskList.addTask({ title: newTaskTitle.value });
    newTaskTitle.value = "";
});

The code above retrieves the title of the new task and calls the addTask() method in the tasks.js file. Here’s the code for the addTask() method which is responsible for actually adding the new task to the IndexedDB database:

// Add a new task
function addTask(taskToAdd) {
    var transaction = db.transaction("tasks", IDBTransaction.READ_WRITE);
    var addRequest = transaction.objectStore("tasks").add(taskToAdd);
    addRequest.onsuccess = function (evt) {
        taskToAdd.id = evt.target.result;
        tasks.dataSource.insertAtEnd(null, taskToAdd);
    }
}

The code above does two things. First, it adds the new task to the tasks object store in the IndexedDB database. Second, it adds the new task to the data source bound to the ListView. The dataSource.insertAtEnd() method is called to add the new task to the data source so the new task will appear in the ListView (with a nice little animation).

Deleting Existing Tasks

The Task List application enables you to select one or more tasks by clicking or tapping on one or more tasks in the ListView. When you click the Delete button, the selected tasks are removed from both the IndexedDB database and the ListView.

For example, in the following screenshot, two tasks are selected. The selected tasks appear with a teal background and a checkmark:

When you click the Delete button, the following code in the default.js file is executed:

// Handle Delete Tasks
document.getElementById("btnDeleteTasks").addEventListener("click", function (evt) {
    tasksListView.winControl.selection.getItems().then(function(items) {
        items.forEach(function (item) {
            TaskList.deleteTask(item);
        });
    });
});

The selected tasks are retrieved with the TaskList selection.getItem() method. In the code above, the deleteTask() method is called for each of the selected tasks.

Here’s the code for the deleteTask() method:

// Delete an existing task
function deleteTask(listViewItem) {
    // Database key != ListView key
    var dbKey = listViewItem.data.id;
    var listViewKey = listViewItem.key;

    // Remove item from db and, if success, remove item from ListView
    var transaction = db.transaction("tasks", IDBTransaction.READ_WRITE);
    var deleteRequest = transaction.objectStore("tasks").delete(dbKey);
    deleteRequest.onsuccess = function () {
        tasks.dataSource.remove(listViewKey);
    }
}

This code does two things: it deletes the existing task from the database and removes the existing task from the ListView. In both cases, the right task is removed by using the key associated with the task. However, the task key is different in the case of the database and in the case of the ListView.

In the case of the database, the task key is the value of the task id property. In the case of the ListView, on the other hand, the task key is auto-generated by the ListView.

When the task is removed from the ListView, an animation is used to collapse the tasks which appear above and below the task which was removed.

The Complete Code

Above, I did a lot of jumping around between different files in the application and I left out sections of code. For the sake of completeness, I want to include the entire code here: the default.html, default.js, and tasks.js files.

Here are the contents of the default.html file. This file contains the UI for the Task List application:




    
    Task List

    
    
    
    

    
    
    
    

    



    

        
        
            
                
            
        

        Super Task List

Here is the code for the default.js file. This code wires up the Add Task form and Delete button:

(function () {
    "use strict";

    var app = WinJS.Application;

    app.onactivated = function (eventObject) {
        if (eventObject.detail.kind === Windows.ApplicationModel.Activation.ActivationKind.launch) {

            WinJS.UI.processAll().then(function () {

                // Get reference to Tasks ListView
                var tasksListView = document.getElementById("tasksListView");

                // Handle Add Task
                document.getElementById("addTaskForm").addEventListener("submit", function (evt) {
                    evt.preventDefault();
                    var newTaskTitle = document.getElementById("newTaskTitle");
                    TaskList.addTask({ title: newTaskTitle.value });
                    newTaskTitle.value = "";
                });

                // Handle Delete Tasks
                document.getElementById("btnDeleteTasks").addEventListener("click", function (evt) {
                    tasksListView.winControl.selection.getItems().then(function(items) {
                        items.forEach(function (item) {
                            TaskList.deleteTask(item);
                        });
                    });

                });

            });
        }
    };

    app.start();
})();

Finally, here is the tasks.js file. This file contains all of the code for opening, creating, and interacting with IndexedDB:

(function () {
    "use strict";

    // Create the data source
    var tasks = new WinJS.Binding.List();

    // Open the database
    var db;
    var req = window.msIndexedDB.open("TasksDB", 1);
    req.onerror = function () {
        console.log("Could not open database");
    };
    req.onupgradeneeded = function (evt) {
        var newDB = evt.target.result;
        newDB.createObjectStore("tasks", { keyPath: "id", autoIncrement:true });
    };

    // Load the data source with data from the database
    req.onsuccess = function () {
        db = req.result;
        var tran = db.transaction("tasks");
        tran.objectStore("tasks").openCursor().onsuccess = function(event) {
            var cursor = event.target.result;
            tasks.dataSource.beginEdits();
            if (cursor) {
                tasks.dataSource.insertAtEnd(null, cursor.value);
                cursor.continue();
            } else {
                tasks.dataSource.endEdits();
            };
        };  

    };

    // Add a new task
    function addTask(taskToAdd) {
        var transaction = db.transaction("tasks", IDBTransaction.READ_WRITE);
        var addRequest = transaction.objectStore("tasks").add(taskToAdd);
        addRequest.onsuccess = function (evt) {
            taskToAdd.id = evt.target.result;
            tasks.dataSource.insertAtEnd(null, taskToAdd);
        }
    }

    // Delete an existing task
    function deleteTask(listViewItem) {
        // Database key != ListView key
        var dbKey = listViewItem.data.id;
        var listViewKey = listViewItem.key;

        // Remove item from db and, if success, remove item from ListView
        var transaction = db.transaction("tasks", IDBTransaction.READ_WRITE);
        var deleteRequest = transaction.objectStore("tasks").delete(dbKey);
        deleteRequest.onsuccess = function () {
            tasks.dataSource.remove(listViewKey);
        }
    }

    // Expose the data source and functions
    WinJS.Namespace.define("TaskList", {
        tasks: tasks,
        addTask: addTask,
        deleteTask: deleteTask
    });

})();

Summary

I wrote this blog entry because I wanted to create a walkthrough of building a simple database-driven application. In particular, I wanted to demonstrate how you can use a ListView control with an IndexedDB database to store and retrieve database data.

Metro: Dynamically Switching Templates with a WinJS ListView

Stephen.Walther — Wed, 23 May 2012 16:15:59 +0000

Imagine that you want to display a list of products using the WinJS ListView control. Imagine, furthermore, that you want to use different templates to display different products. In particular, when a product is on sale, you want to display the product using a special “On Sale” template.

In this blog entry, I explain how you can switch templates dynamically when displaying items with a ListView control. In other words, you learn how to use more than one template when displaying items with a ListView control.

Creating the Data Source

Let’s start by creating the data source for the ListView. Nothing special here – our data source is a list of products. Two of the products, Oranges and Apples, are on sale.

(function () {
    "use strict";

    var products = new WinJS.Binding.List([
            { name: "Milk", price: 2.44 },
            { name: "Oranges", price: 1.99, onSale: true },
            { name: "Wine", price: 8.55 },
            { name: "Apples", price: 2.44, onSale: true },
            { name: "Steak", price: 1.99 },
            { name: "Eggs", price: 2.44 },
            { name: "Mushrooms", price: 1.99 },
            { name: "Yogurt", price: 2.44 },
            { name: "Soup", price: 1.99 },
            { name: "Cereal", price: 2.44 },
            { name: "Pepsi", price: 1.99 }
    ]);

    WinJS.Namespace.define("ListViewDemos", {
        products: products
    });

})();

The file above is saved with the name products.js and referenced by the default.html page described below.

Declaring the Templates and ListView Control

Next, we need to declare the ListView control and the two Template controls which we will use to display template items. The markup below appears in the default.html file:

In the markup above, two Template controls are declared. The first template is used when rendering a normal product and the second template is used when rendering a product which is on sale. The second template, unlike the first template, includes the text “(On Sale!)”.

The ListView control is bound to the data source which we created in the previous section. The ListView itemDataSource property is set to the value ListViewDemos.products.dataSource. Notice that we do not set the ListView itemTemplate property. We set this property in the default.js file.

Switching Between Templates

All of the magic happens in the default.js file. The default.js file contains the JavaScript code used to switch templates dynamically.

Here’s the entire contents of the default.js file:

(function () {
    "use strict";

    var app = WinJS.Application;

    app.onactivated = function (eventObject) {
        if (eventObject.detail.kind === Windows.ApplicationModel.Activation.ActivationKind.launch) {

            WinJS.UI.processAll().then(function () {
                var productsListView = document.getElementById("productsListView");
                productsListView.winControl.itemTemplate = itemTemplateFunction;

            });;

        }
    };

    function itemTemplateFunction(itemPromise) {
        return itemPromise.then(function (item) {
            // Select either normal product template or on sale template
            var itemTemplate = document.getElementById("productItemTemplate");
            if (item.data.onSale) {
                itemTemplate = document.getElementById("productOnSaleTemplate");
            };

            // Render selected template to DIV container
            var container = document.createElement("div");
            itemTemplate.winControl.render(item.data, container);
            return container;
        });
    }

    app.start();
})();

In the code above, a function is assigned to the ListView itemTemplate property with the following line of code:

productsListView.winControl.itemTemplate = itemTemplateFunction;

The itemTemplateFunction returns a DOM element which is used for the template item. Depending on the value of the product onSale property, the DOM element is generated from either the productItemTemplate or the productOnSaleTemplate template.

Using Binding Converters instead of Multiple Templates

In the previous sections, I explained how you can use different templates to render normal products and on sale products. There is an alternative approach to displaying different markup for normal products and on sale products. Instead of creating two templates, you can create a single template which contains separate DIV elements for a normal product and an on sale product.

The following default.html file contains a single item template and a ListView control bound to the template.

The first DIV element is used to render a normal product:

The second DIV element is used to render an “on sale” product:


    
    
    (On Sale!)

Notice that both templates include a data-win-bind attribute. These data-win-bind attributes are used to show the “normal” template when a product is not on sale and show the “on sale” template when a product is on sale. These attributes set the Cascading Style Sheet display attribute to either “none” or “block”.

The data-win-bind attributes take advantage of binding converters. The binding converters are defined in the default.js file:

(function () {
    "use strict";

    var app = WinJS.Application;

    app.onactivated = function (eventObject) {
        if (eventObject.detail.kind === Windows.ApplicationModel.Activation.ActivationKind.launch) {
            WinJS.UI.processAll();
        }
    };

    WinJS.Namespace.define("ListViewDemos", {
        displayNormalProduct: WinJS.Binding.converter(function (onSale) {
            return onSale ? "none" : "block";
        }),

        displayOnSaleProduct: WinJS.Binding.converter(function (onSale) {
            return onSale ? "block" : "none";
        })

    });

    app.start();
})();

The ListViewDemos.displayNormalProduct binding converter converts the value true or false to the value “none” or “block”. The ListViewDemos.displayOnSaleProduct binding converter does the opposite; it converts the value true or false to the value “block” or “none” (Sadly, you cannot simply place a NOT operator before the onSale property in the binding expression – you need to create both converters).

The end result is that you can display different markup depending on the value of the product onSale property. Either the contents of the first or second DIV element are displayed:

Summary

In this blog entry, I’ve explored two approaches to displaying different markup in a ListView depending on the value of a data item property. The bulk of this blog entry was devoted to explaining how you can assign a function to the ListView itemTemplate property which returns different templates. We created both a productItemTemplate and productOnSaleTemplate and displayed both templates with the same ListView control.

We also discussed how you can create a single template and display different markup by using binding converters. The binding converters are used to set a DIV element’s display property to either “none” or “block”. We created a binding converter which displays normal products and a binding converter which displays “on sale” products.

Metro: Creating a Master/Detail View with a WinJS ListView Control

Stephen.Walther — Mon, 21 May 2012 15:12:09 +0000

The goal of this blog entry is to explain how you can create a simple master/detail view by using the WinJS ListView and Template controls. In particular, I explain how you can use a ListView control to display a list of movies and how you can use a Template control to display the details of the selected movie.

Creating a master/detail view requires completing the following four steps:

Create the data source – The data source contains the list of movies.
Declare the ListView control – The ListView control displays the entire list of movies. It is the master part of the master/detail view.
Declare the Details Template control – The Details Template control displays the details for the selected movie. It is the details part of the master/detail view.
Handle the selectionchanged event – You handle the selectionchanged event to display the details for a movie when a new movie is selected.

Creating the Data Source

There is nothing special about our data source. We initialize a WinJS.Binding.List object to represent a list of movies:

(function () {
    "use strict";

    var movies = new WinJS.Binding.List([
        { title: "Star Wars", director: "Lucas"},
        { title: "Shrek", director: "Adamson" },
        { title: "Star Trek", director: "Abrams" },
        { title: "Spiderman", director: "Raimi" },
        { title: "Memento", director: "Nolan" },
        { title: "Minority Report", director: "Spielberg" }
    ]);

    // Expose the data source
    WinJS.Namespace.define("ListViewDemos", {
        movies: movies
    });

})();

The data source is exposed to the rest of our application with the name ListViewDemos.movies.

Declaring the ListView Control

The ListView control is declared with the following markup:

The data-win-options attribute is used to set the following properties of the ListView control:

itemDataSource – The ListView is bound to the list of movies which we created in the previous section. Notice that the ListView is bound to ListViewDemos.movies.dataSource and not just ListViewDemos.movies.
itemTemplate – The item template contains the template used for rendering each item in the ListView. The markup for this template is included below.
tabBehavior – This enumeration determines what happens when you tap or click on an item in the ListView. The possible values are directSelect, toggleSelect, invokeOnly, none. Because we want to handle the selectionchanged event, we set tapBehavior to the value directSelect.
selectionMode – This enumeration determines whether you can select multiple items or only a single item. The possible values are none, single, multi. In the code above, this property is set to the value single.
layout – You can use ListLayout or GridLayout with a ListView. If you want to display a vertical ListView, then you should select ListLayout.

You must associate a ListView with an item template if you want to render anything interesting. The ListView above is associated with an item template named #masterItemTemplate. Here’s the markup for the masterItemTemplate:

This template simply renders the title of each movie.

Declaring the Details Template Control

The details part of the master/detail view is created with the help of a Template control. Here’s the markup used to declare the Details Template control:

The Details Template control displays the movie title and director.

Handling the selectionchanged Event

The ListView control can raise two types of events: the iteminvoked and selectionchanged events. The iteminvoked event is raised when you click on a ListView item. The selectionchanged event is raised when one or more ListView items are selected.

When you set the tapBehavior property of the ListView control to the value “directSelect” then tapping or clicking a list item raised both the iteminvoked and selectionchanged event. Tapping a list item causes the item to be selected and the item appears with a checkmark.

In our code, we handle the selectionchanged event to update the movie details Template when you select a new movie.

Here’s the code from the default.js file used to handle the selectionchanged event:

var movieList = document.getElementById("movieList");
var detailsTemplate = document.getElementById("detailsTemplate");
var movieDetails = document.getElementById("movieDetails");

// Setup selectionchanged handler
movieList.winControl.addEventListener("selectionchanged", function (evt) {
    if (movieList.winControl.selection.count() > 0) {
        movieList.winControl.selection.getItems().then(function (items) {
            // Clear the template container
            movieDetails.innerHTML = "";
            // Render the template
            detailsTemplate.winControl.render(items[0].data, movieDetails);
        });
    }
});

The code above sets up an event handler (listener) for the selectionchanged event. The event handler first verifies that an item has been selected in the ListView (selection.count() > 0). Next, the details for the movie are rendered using the movie details Template (we created this Template in the previous section).

The Complete Code

For the sake of completeness, I’ve included the complete code for the master/detail view below. I’ve included both the default.html, default.js, and movies.js files.

Here is the final code for the default.html file:




    
    ListViewMasterDetail

    
    
    
    

    
    
    
    

    



    
    
        
            
        
    

    
        
            
                Title:
                
            
            
                Director:

Here is the default.js file:

(function () {
    "use strict";

    var app = WinJS.Application;

    app.onactivated = function (eventObject) {
        if (eventObject.detail.kind === Windows.ApplicationModel.Activation.ActivationKind.launch) {
            WinJS.UI.processAll();

            var movieList = document.getElementById("movieList");
            var detailsTemplate = document.getElementById("detailsTemplate");
            var movieDetails = document.getElementById("movieDetails");

            // Setup selectionchanged handler
            movieList.winControl.addEventListener("selectionchanged", function (evt) {
                if (movieList.winControl.selection.count() > 0) {
                    movieList.winControl.selection.getItems().then(function (items) {
                        // Clear the template container
                        movieDetails.innerHTML = "";
                        // Render the template
                        detailsTemplate.winControl.render(items[0].data, movieDetails);
                    });
                }
            });

        }
    };

    app.start();
})();

Here is the movies.js file:

(function () {
    "use strict";

    var movies = new WinJS.Binding.List([
        { title: "Star Wars", director: "Lucas"},
        { title: "Shrek", director: "Adamson" },
        { title: "Star Trek", director: "Abrams" },
        { title: "Spiderman", director: "Raimi" },
        { title: "Memento", director: "Nolan" },
        { title: "Minority Report", director: "Spielberg" }
    ]);

    // Expose the data source
    WinJS.Namespace.define("ListViewDemos", {
        movies: movies
    });

})();

Summary

The purpose of this blog entry was to describe how to create a simple master/detail view by taking advantage of the WinJS ListView control. We handled the selectionchanged event of the ListView control to display movie details when you select a movie in the ListView.

Metro: Grouping Items in a ListView Control

Stephen.Walther — Sat, 19 May 2012 00:14:52 +0000

The purpose of this blog entry is to explain how you can group list items when displaying the items in a WinJS ListView control. In particular, you learn how to group a list of products by product category.

Displaying a grouped list of items in a ListView control requires completing the following steps:

Create a Grouped data source from a List data source
Create a Grouped Header Template
Declare the ListView control so it groups the list items

Creating the Grouped Data Source

Normally, you bind a ListView control to a WinJS.Binding.List object. If you want to render list items in groups, then you need to bind the ListView to a grouped data source instead.

The following code – contained in a file named products.js — illustrates how you can create a standard WinJS.Binding.List object from a JavaScript array and then return a grouped data source from the WinJS.Binding.List object by calling its createGrouped() method:

(function () {
    "use strict";

    // Create List data source
    var products = new WinJS.Binding.List([
            { name: "Milk", price: 2.44, category: "Beverages" },
            { name: "Oranges", price: 1.99, category: "Fruit" },
            { name: "Wine", price: 8.55, category: "Beverages" },
            { name: "Apples", price: 2.44, category: "Fruit" },
            { name: "Steak", price: 1.99, category: "Other" },
            { name: "Eggs", price: 2.44, category: "Other" },
            { name: "Mushrooms", price: 1.99, category: "Other" },
            { name: "Yogurt", price: 2.44, category: "Other" },
            { name: "Soup", price: 1.99, category: "Other" },
            { name: "Cereal", price: 2.44, category: "Other" },
            { name: "Pepsi", price: 1.99, category: "Beverages" }
        ]);

    // Create grouped data source
    var groupedProducts = products.createGrouped(
        function (dataItem) {
            return dataItem.category;
        },
        function (dataItem) {
            return { title: dataItem.category };
        },
        function (group1, group2) {
            return group1.charCodeAt(0) - group2.charCodeAt(0);
        }
    );

    // Expose the grouped data source
    WinJS.Namespace.define("ListViewDemos", {
        products: groupedProducts
    });
})();

Notice that the createGrouped() method requires three functions as arguments:

groupKey – This function associates each list item with a group. The function accepts a data item and returns a key which represents a group. In the code above, we return the value of the category property for each product.
groupData – This function returns the data item displayed by the group header template. For example, in the code above, the function returns a title for the group which is displayed in the group header template.
groupSorter – This function determines the order in which the groups are displayed. The code above displays the groups in alphabetical order: Beverages, Fruit, Other.

Creating the Group Header Template

Whenever you create a ListView control, you need to create an item template which you use to control how each list item is rendered. When grouping items in a ListView control, you also need to create a group header template. The group header template is used to render the header for each group of list items.

Here’s the markup for both the item template and the group header template:

You should declare the two templates in the same file as you declare the ListView control – for example, the default.html file.

Declaring the ListView Control

The final step is to declare the ListView control. Here’s the required markup:

In the markup above, six properties of the ListView control are set when the control is declared. First the itemDataSource and itemTemplate are specified. Nothing new here.

Next, the group data source and group header template are specified. Notice that the group data source is represented by the ListViewDemos.products.groups.dataSource property of the grouped data source.

Finally, notice that the layout of the ListView is changed to Grid Layout. You are required to use Grid Layout (instead of the default List Layout) when displaying grouped items in a ListView.

Here’s the entire contents of the default.html page:




    
    ListViewDemos

Notice that the default.html page includes a reference to the products.js file:

The default.html page also contains the declarations of the item template, group header template, and ListView control.

Summary

The goal of this blog entry was to explain how you can group items in a ListView control. You learned how to create a grouped data source, a group header template, and declare a ListView so that it groups its list items.

Metro: Introduction to the WinJS ListView Control

Stephen.Walther — Fri, 18 May 2012 17:15:57 +0000

The goal of this blog entry is to provide a quick introduction to the ListView control – just the bare minimum that you need to know to start using the control. When building Metro style applications using JavaScript, the ListView control is the primary control that you use for displaying lists of items. For example, if you are building a product catalog app, then you can use the ListView control to display the list of products.

The ListView control supports several advanced features that I plan to discuss in future blog entries. For example, you can group the items in a ListView, you can create master/details views with a ListView, and you can efficiently work with large sets of items with a ListView. In this blog entry, we’ll keep things simple and focus on displaying a list of products.

There are three things that you need to do in order to display a list of items with a ListView:

Create a data source
Create an Item Template
Declare the ListView

Creating the ListView Data Source

The first step is to create (or retrieve) the data that you want to display with the ListView. In most scenarios, you will want to bind a ListView to a WinJS.Binding.List object.

The nice thing about the WinJS.Binding.List object is that it enables you to take a standard JavaScript array and convert the array into something that can be bound to the ListView. It doesn’t matter where the JavaScript array comes from. It could be a static array that you declare or you could retrieve the array as the result of an Ajax call to a remote server.

The following JavaScript file – named products.js – contains a list of products which can be bound to a ListView.

(function () {
    "use strict";

    var products = new WinJS.Binding.List([
            { name: "Milk", price: 2.44 },
            { name: "Oranges", price: 1.99 },
            { name: "Wine", price: 8.55 },
            { name: "Apples", price: 2.44 },
            { name: "Steak", price: 1.99 },
            { name: "Eggs", price: 2.44 },
            { name: "Mushrooms", price: 1.99 },
            { name: "Yogurt", price: 2.44 },
            { name: "Soup", price: 1.99 },
            { name: "Cereal", price: 2.44 },
            { name: "Pepsi", price: 1.99 }
        ]);

    WinJS.Namespace.define("ListViewDemos", {
        products: products
    });

})();

The products variable represents a WinJS.Binding.List object. This object is initialized with a plain-old JavaScript array which represents an array of products.

To avoid polluting the global namespace, the code above uses the module pattern and exposes the products using a namespace. The list of products is exposed to the world as ListViewDemos.products.

To learn more about the module pattern and namespaces in WinJS, see my earlier blog entry:

http://stephenwalther.com/blog/archive/2012/02/22/metro-namespaces-and-modules.aspx

Creating the ListView Item Template

The ListView control does not know how to render anything. It doesn’t know how you want each list item to appear. To get the ListView control to render something useful, you must create an Item Template.

Here’s what our template for rendering an individual product looks like:

This template displays the product name and price from the data source.

Normally, you will declare your template in the same file as you declare the ListView control. In our case, both the template and ListView are declared in the default.html file.

To learn more about templates, see my earlier blog entry:

http://stephenwalther.com/blog/archive/2012/02/27/metro-using-templates.aspx

Declaring the ListView

The final step is to declare the ListView control in a page. Here’s the markup for declaring a ListView:

You declare a ListView by adding the data-win-control to an HTML DIV tag. The data-win-options attribute is used to set two properties of the ListView.

The ListView is associated with its data source with the itemDataSource property. Notice that the data source is ListViewDemos.products.dataSource and not just ListViewDemos.products. You need to associate the ListView with the dataSoure property.

The ListView is associated with its item template with the help of the itemTemplate property. The ID of the item template — #productTemplate – is used to select the template from the page.

Here’s what the complete version of the default.html page looks like:




    
    ListViewDemos

Notice that the page above includes a reference to the products.js file:

The page above also contains a Template control which contains the ListView item template. Finally, the page includes the declaration of the ListView control.

Summary

The goal of this blog entry was to describe the minimal set of steps which you must complete to use the WinJS ListView control to display a simple list of items. You learned how to create a data source, declare an item template, and declare a ListView control.

Ajax Control Toolkit May 2012 Release

Stephen.Walther — Tue, 01 May 2012 16:46:46 +0000

I’m happy to announce the May 2012 release of the Ajax Control Toolkit. This newest release of the Ajax Control Toolkit includes a new file upload control which displays file upload progress. We’ve also added several significant enhancements to the existing HtmlEditorExtender control such as support for uploading images and Source View.

You can download and start using the newest version of the Ajax Control Toolkit by entering the following command in the Library Package Manager console in Visual Studio:

Install-Package AjaxControlToolkit

Alternatively, you can download the latest version of the Ajax Control Toolkit from CodePlex:

http://AjaxControlToolkit.CodePlex.com

The New Ajax File Upload Control

The most requested new feature for the Ajax Control Toolkit (according to the CodePlex Issue Tracker) has been support for file upload with progress. We worked hard over the last few months to create an entirely new file upload control which displays upload progress.

Here is a sample which illustrates how you can use the new AjaxFileUpload control:

<%@ Page Language="C#" AutoEventWireup="true" CodeBehind="01_FileUpload.aspx.cs" Inherits="WebApplication1._01_FileUpload" %>


    Simple File Upload

The page above includes a ToolkitScriptManager control. This control is required to use any of the controls in the Ajax Control Toolkit because this control is responsible for loading all of the scripts required by a control.

The page also contains an AjaxFileUpload control. The UploadComplete event is handled in the code-behind for the page:

namespace WebApplication1
{
    public partial class _01_FileUpload : System.Web.UI.Page
    {
        protected void ajaxUpload1_OnUploadComplete(object sender, AjaxControlToolkit.AjaxFileUploadEventArgs e)
        {
            // Generate file path
            string filePath = "~/Images/" + e.FileName;

            // Save upload file to the file system
            ajaxUpload1.SaveAs(MapPath(filePath));
        }
    }
}

The UploadComplete handler saves each uploaded file by calling the AjaxFileUpload control’s SaveAs() method with a full file path.

Here’s a video which illustrates the process of uploading a file:

Warning: in order to write to the Images folder on a production IIS server, you need Write permissions on the Images folder. You need to provide permissions for the IIS Application Pool account to write to the Images folder. To learn more, see:

http://learn.iis.net/page.aspx/624/application-pool-identities/

Showing File Upload Progress

The new AjaxFileUpload control takes advantage of HTML5 upload progress events (described in the XMLHttpRequest Level 2 standard). This standard is supported by Firefox 8+, Chrome 16+, Safari 5+, and Internet Explorer 10+. In other words, the standard is supported by the most recent versions of all browsers except for Internet Explorer which will support the standard with the release of Internet Explorer 10.

The AjaxFileUpload control works with all browsers, even browsers which do not support the new XMLHttpRequest Level 2 standard. If you use the AjaxFileUpload control with a downlevel browser – such as Internet Explorer 9 — then you get a simple throbber image during a file upload instead of a progress indicator.

Here’s how you specify a throbber image when declaring the AjaxFileUpload control:

<%@ Page Language="C#" AutoEventWireup="true" CodeBehind="02_FileUpload.aspx.cs" Inherits="WebApplication1._02_FileUpload" %>


    File Upload with Throbber

Notice that the page above includes an image with the Id MyThrobber. This image is displayed while files are being uploaded.

I use the website http://AjaxLoad.info to generate animated busy wait images.

Drag-And-Drop File Upload

If you are using an uplevel browser then you can drag-and-drop the files which you want to upload onto the AjaxFileUpload control. The following video illustrates how drag-and-drop works:

Remember that drag-and-drop will not work on Internet Explorer 9 or older.

Accepting Multiple Files

By default, the AjaxFileUpload control enables you to upload multiple files at a time. When you open the file dialog, use the CTRL or SHIFT key to select multiple files.

If you want to restrict the number of files that can be uploaded then use the MaximumNumberOfFiles property like this:

In the code above, the maximum number of files which can be uploaded is restricted to a single file.

Restricting Uploaded File Types

You might want to allow only certain types of files to be uploaded. For example, you might want to accept only image uploads. In that case, you can use the AllowedFileTypes property to provide a list of allowed file types like this:

The code above prevents any files except jpeg, gif, and png files from being uploaded.

Enhancements to the HTMLEditorExtender

Over the past months, we spent a considerable amount of time making bug fixes and feature enhancements to the existing HtmlEditorExtender control. I want to focus on two of the most significant enhancements that we made to the control: support for Source View and support for uploading images.

Adding Source View Support to the HtmlEditorExtender

When you click the Source View tag, the HtmlEditorExtender changes modes and displays the HTML source of the contents contained in the TextBox being extended. You can use Source View to make fine-grain changes to HTML before submitting the HTML to the server.

For reasons of backwards compatibility, the Source View tab is disabled by default. To enable Source View, you need to declare your HtmlEditorExtender with the DisplaySourceTab property like this:

<%@ Page Language="C#" AutoEventWireup="true" CodeBehind="05_SourceView.aspx.cs" Inherits="WebApplication1._05_SourceView" %>



    HtmlEditorExtender with Source View

The page above includes a ToolkitScriptManager, TextBox, and HtmlEditorExtender control. The HtmlEditorExtender extends the TextBox so that it supports rich text editing.

Notice that the HtmlEditorExtender includes a DisplaySourceTab property. This property causes a button to appear at the bottom of the HtmlEditorExtender which enables you to switch to Source View:

Note: when using the HtmlEditorExtender, we recommend that you set the DOCTYPE for the document. Otherwise, you can encounter weird formatting issues.

Accepting Image Uploads

We also enhanced the HtmlEditorExtender to support image uploads (another very highly requested feature at CodePlex). The following video illustrates the experience of adding an image to the editor:

Once again, for backwards compatibility reasons, support for image uploads is disabled by default. Here’s how you can declare the HtmlEditorExtender so that it supports image uploads:

There are two things that you should notice about the code above. First, notice that an InsertImage toolbar button is added to the HtmlEditorExtender toolbar. This HtmlEditorExtender will render toolbar buttons for bold, italic, underline, and insert image.

Second, notice that the HtmlEditorExtender includes an event handler for the ImageUploadComplete event. The code for this event handler is below:

using System.Web.UI;
using AjaxControlToolkit;

namespace WebApplication1
{
    public partial class _06_ImageUpload : System.Web.UI.Page
    {

        protected void MyHtmlEditorExtender_ImageUploadComplete(object sender, AjaxFileUploadEventArgs e)
        {
            // Generate file path
            string filePath = "~/Images/" + e.FileName;

            // Save uploaded file to the file system
            var ajaxFileUpload = (AjaxFileUpload)sender;
            ajaxFileUpload.SaveAs(MapPath(filePath));

            // Update client with saved image path
            e.PostedUrl = Page.ResolveUrl(filePath);
        }
    }
}

Within the ImageUploadComplete event handler, you need to do two things:

1) Save the uploaded image (for example, to the file system, a database, or Azure storage)

2) Provide the URL to the saved image so the image can be displayed within the HtmlEditorExtender

In the code above, the uploaded image is saved to the ~/Images folder. The path of the saved image is returned to the client by setting the AjaxFileUploadEventArgs PostedUrl property.

Not surprisingly, under the covers, the HtmlEditorExtender uses the AjaxFileUpload. You can get a direct reference to the AjaxFileUpload control used by an HtmlEditorExtender by using the following code:

void Page_Load()
{
    var ajaxFileUpload = MyHtmlEditorExtender.AjaxFileUpload;
    ajaxFileUpload.AllowedFileTypes = "jpg,jpeg";
}

The code above illustrates how you can restrict the types of images that can be uploaded to the HtmlEditorExtender. This code prevents anything but jpeg images from being uploaded.

Summary

This was the most difficult release of the Ajax Control Toolkit to date. We iterated through several designs for the AjaxFileUpload control – with each iteration, the goal was to make the AjaxFileUpload control easier for developers to use. My hope is that we were able to create a control which Web Forms developers will find very intuitive.

I want to thank the developers on the Superexpert.com team for their hard work on this release.

ASP.NET Connections Spring 2012 Talks and Code

Stephen.Walther — Mon, 09 Apr 2012 12:13:57 +0000

Thank you everyone who attended my ASP.NET Connections talks last week in Las Vegas. I’ve attached the slides and code for the three talks that I delivered:

Using jQuery to interact with the Server through Ajax – In this talk, I discuss the different ways to communicate information between browser and server using Ajax. I explain the difference between the different types of Ajax calls that you can make with jQuery. I also discuss the differences between the JavaScriptSerializer, the DataContractJsonSerializer, and the JSON.NET serializer.
ASP.NET Validation In-Depth – In this talk, I distinguish between View Model Validation and Domain Model Validation. I demonstrate how you can use the validation attributes (including the new .NET 4.5 validation attributes), the jQuery Validation library, and the HTML5 input validation attributes to perform View Model Validation. I then demonstrate how you can use the IValidatableObject interface with the Entity Framework to perform Domain Model Validation.
Using the MVVM Pattern with JavaScript Views – In this talk, I discuss how you can create single page applications (SPA) by taking advantage of the open-source KnockoutJS library and the ASP.NET Web API.

Be warned that the sample code is contained in Visual Studio 11 Beta projects. If you don’t have this version of Visual Studio, then you will need to open the code samples in Notepad.

Also, I apologize for getting the code for these talks posted so slowly. I’ve been down with a nasty case of the flu for the past week and haven’t been able to get to a computer.

Metro: Introduction to CSS 3 Grid Layout

Stephen.Walther — Tue, 20 Mar 2012 00:01:22 +0000

The purpose of this blog post is to provide you with a quick introduction to the new W3C CSS 3 Grid Layout standard. You can use CSS Grid Layout in Metro style applications written with JavaScript to lay out the content of an HTML page. CSS Grid Layout provides you with all of the benefits of using HTML tables for layout without requiring you to actually use any HTML table elements.

Doing Page Layouts without Tables

Back in the 1990’s, if you wanted to create a fancy website, then you would use HTML tables for layout. For example, if you wanted to create a standard three-column page layout then you would create an HTML table with three columns like this:



  
    Left Column, Left Column, Left Column,
    Left Column, Left Column, Left Column,
    Left Column, Left Column, Left Column
  
  
    Middle Column, Middle Column, Middle Column,
    Middle Column, Middle Column, Middle Column,
    Middle Column, Middle Column, Middle Column
  
  
    Right Column, Right Column, Right Column,
    Right Column, Right Column, Right Column,
    Right Column, Right Column, Right Column

When the table above gets rendered out to a browser, you end up with the following three-column layout:

The width of the left and right columns is fixed – the width of the middle column expands or contracts depending on the width of the browser.

Sometime around the year 2005, everyone decided that using tables for layout was a bad idea. Instead of using tables for layout — it was collectively decided by the spirit of the Web — you should use Cascading Style Sheets instead.

Why is using HTML tables for layout bad? Using tables for layout breaks the semantics of the TABLE element. A TABLE element should be used only for displaying tabular information such as train schedules or moon phases. Using tables for layout is bad for accessibility (The Web Content Accessibility Guidelines 1.0 is explicit about this) and using tables for layout is bad for separating content from layout (see http://CSSZenGarden.com).

Post 2005, anyone who used HTML tables for layout were encouraged to hold their heads down in shame.

That’s all well and good, but the problem with using CSS for layout is that it can be more difficult to work with CSS than HTML tables. For example, to achieve a standard three-column layout, you either need to use absolute positioning or floats. Here’s a three-column layout with floats:




  
    Right Column, Right Column, Right Column,
    Right Column, Right Column, Right Column,
    Right Column, Right Column, Right Column
  
  
    Left Column, Left Column, Left Column,
    Left Column, Left Column, Left Column,
    Left Column, Left Column, Left Column
  
  
    Middle Column, Middle Column, Middle Column,
    Middle Column, Middle Column, Middle Column,
    Middle Column, Middle Column, Middle Column

The page above contains four DIV elements: a container DIV which contains a leftColumn, middleColumn, and rightColumn DIV. The leftColumn DIV element is floated to the left and the rightColumn DIV element is floated to the right. Notice that the rightColumn DIV appears in the page before the middleColumn DIV – this unintuitive ordering is necessary to get the floats to work correctly (see http://stackoverflow.com/questions/533607/css-three-column-layout-problem).

The page above (almost) works with the most recent versions of most browsers. For example, you get the correct three-column layout in both Firefox and Chrome:

And the layout mostly works with Internet Explorer 9 except for the fact that for some strange reason the min-width doesn’t work so when you shrink the width of your browser, you can get the following unwanted layout:

Notice how the middle column (the green column) bleeds to the left and right.

People have solved these issues with more complicated CSS. For example, see:

http://matthewjamestaylor.com/blog/holy-grail-no-quirks-mode.htm

But, at this point, no one could argue that using CSS is easier or more intuitive than tables. It takes work to get a layout with CSS and we know that we could achieve the same layout more easily using HTML tables.

Using CSS Grid Layout

CSS Grid Layout is a new W3C standard which provides you with all of the benefits of using HTML tables for layout without the disadvantage of using an HTML TABLE element. In other words, CSS Grid Layout enables you to perform table layouts using pure Cascading Style Sheets. The CSS Grid Layout standard is still in a “Working Draft” state (it is not finalized) and it is located here:

http://www.w3.org/TR/css3-grid-layout/

The CSS Grid Layout standard is only supported by Internet Explorer 10 and there are no signs that any browser other than Internet Explorer will support this standard in the near future. This means that it is only practical to take advantage of CSS Grid Layout when building Metro style applications with JavaScript.

Here’s how you can create a standard three-column layout using a CSS Grid Layout:










  
    Left Column, Left Column, Left Column,
    Left Column, Left Column, Left Column,
    Left Column, Left Column, Left Column
  
  
    Middle Column, Middle Column, Middle Column,
    Middle Column, Middle Column, Middle Column,
    Middle Column, Middle Column, Middle Column
  
  
    Right Column, Right Column, Right Column,
    Right Column, Right Column, Right Column,
    Right Column, Right Column, Right Column

When the page above is rendered in Internet Explorer 10, you get a standard three-column layout:

The page above contains four DIV elements: a container DIV which contains a leftColumn DIV, middleColumn DIV, and rightColumn DIV.

The container DIV is set to Grid display mode with the following CSS rule:

#container {
  display: -ms-grid;
  -ms-grid-columns: 300px auto 300px;
  -ms-grid-rows: 100%;
}

The display property is set to the value “-ms-grid”. This property causes the container DIV to lay out its child elements in a grid.

(Notice that you use “-ms-grid” instead of “grid”. The “-ms-“ prefix is used because the CSS Grid Layout standard is still preliminary. This implementation only works with IE10 and it might change before the final release.)

The grid columns and rows are defined with the “-ms-grid-columns” and “-ms-grid-rows” properties. The style rule above creates a grid with three columns and one row. The left and right columns are fixed sized at 300 pixels. The middle column sizes automatically depending on the remaining space available.

The leftColumn, middleColumn, and rightColumn DIVs are positioned within the container grid element with the following CSS rules:

#leftColumn {
  -ms-grid-column: 1;
  background-color:red;
}

#middleColumn {
  -ms-grid-column: 2;
  background-color:green;
}

#rightColumn {
  -ms-grid-column: 3;
  background-color:blue;
}

The “-ms-grid-column” property is used to specify the column associated with the element selected by the style sheet selector. The leftColumn DIV is positioned in the first grid column, the middleColumn DIV is positioned in the second grid column, and the rightColumn DIV is positioned in the third grid column.

I find using CSS Grid Layout to be just as intuitive as using an HTML table for layout. You define your columns and rows and then you position different elements within these columns and rows. Very straightforward.

Creating Multiple Columns and Rows

In the previous section, we created a super simple three-column layout. This layout contained only a single row. In this section, let’s create a slightly more complicated layout which contains more than one row:

The following page contains a header row, a content row, and a footer row. The content row contains three columns:










  
    Header, Header, Header
  

  
    Left Column, Left Column, Left Column,
    Left Column, Left Column, Left Column,
    Left Column, Left Column, Left Column
  
  
    Middle Column, Middle Column, Middle Column,
    Middle Column, Middle Column, Middle Column,
    Middle Column, Middle Column, Middle Column
  
  
    Right Column, Right Column, Right Column,
    Right Column, Right Column, Right Column,
    Right Column, Right Column, Right Column
  
  
    Footer, Footer, Footer

In the page above, the grid layout is created with the following rule which creates a grid with three rows and three columns:

#container {
  display: -ms-grid;
  -ms-grid-columns: 300px auto 300px;
  -ms-grid-rows: 100px 1fr 100px;
}

The header is created with the following rule:

#header {
  -ms-grid-column: 1;
  -ms-grid-column-span: 3;
  -ms-grid-row: 1;
  background-color: yellow;
}

The header is positioned in column 1 and row 1. Furthermore, notice that the “-ms-grid-column-span” property is used to span the header across three columns.

CSS Grid Layout and Fractional Units

When you use CSS Grid Layout, you can take advantage of fractional units. Fractional units provide you with an easy way of dividing up remaining space in a page.

Imagine, for example, that you want to create a three-column page layout. You want the size of the first column to be fixed at 200 pixels and you want to divide the remaining space among the remaining three columns. The width of the second column is equal to the combined width of the third and fourth columns.

The following CSS rule creates four columns with the desired widths:

#container {
  display: -ms-grid;
  -ms-grid-columns: 200px 2fr 1fr 1fr;
  -ms-grid-rows: 1fr;
}

The fr unit represents a fraction. The grid above contains four columns. The second column is two times the size (2fr) of the third (1fr) and fourth (1fr) columns. When you use the fractional unit, the remaining space is divided up using fractional amounts.

Notice that the single row is set to a height of 1fr. The single grid row gobbles up the entire vertical space.

Here’s the entire HTML page:










  
  First Column, First Column, First Column
  
  
  Second Column, Second Column, Second Column
  
  
  Third Column, Third Column, Third Column
  
  
  Fourth Column, Fourth Column, Fourth Column

Summary

There is more in the CSS 3 Grid Layout standard than discussed in this blog post. My goal was to describe the basics. If you want to learn more than you can read through the entire standard at http://www.w3.org/TR/css3-grid-layout/

In this blog post, I described some of the difficulties that you might encounter when attempting to replace HTML tables with Cascading Style Sheets when laying out a web page. I explained how you can take advantage of the CSS 3 Grid Layout standard to avoid these problems when building Metro style applications using JavaScript. CSS 3 Grid Layout provides you with all of the benefits of using HTML tables for laying out a page without requiring you to use HTML table elements.

HTML5 Form Validation

Stephen.Walther — Wed, 14 Mar 2012 03:27:59 +0000

The latest versions of Google Chrome (16+), Mozilla Firefox (8+), and Internet Explorer (10+) all support HTML5 client-side validation. It is time to take HTML5 validation seriously.

The purpose of the blog post is to describe how you can take advantage of HTML5 client-side validation regardless of the type of application that you are building. You learn how to use the HTML5 validation attributes, how to perform custom validation using the JavaScript validation constraint API, and how to simulate HTML5 validation on older browsers by taking advantage of a jQuery plugin. Finally, we discuss the security issues related to using client-side validation.

Using Client-Side Validation Attributes

The HTML5 specification discusses several attributes which you can use with INPUT elements to perform client-side validation including the required, pattern, min, max, step, and maxlength attributes.

For example, you use the required attribute to require a user to enter a value for an INPUT element. The following form demonstrates how you can make the firstName and lastName form fields required:




    Required Demo



    
        
            First Name:
            
        
        
            Last Name:

If you attempt to submit this form without entering a value for firstName or lastName then you get the validation error message:

Notice that the value of the title attribute is used to display the validation error message “First Name is Required!”. The title attribute does not work this way with the current version of Firefox. If you want to display a custom validation error message with Firefox then you need to include an x-moz-errormessage attribute like this:

The pattern attribute enables you to validate the value of an INPUT element against a regular expression. For example, the following form includes a social security number field which includes a pattern attribute:




    Pattern



    
        
            Social Security Number:

The regular expression in the form above requires the social security number to match the pattern ###-##-####:

Notice that the input field includes both a pattern and a required validation attribute. If you don’t enter a value then the regular expression is never triggered. You need to include the required attribute to force a user to enter a value and cause the value to be validated against the regular expression.

Custom Validation

You can take advantage of the HTML5 constraint validation API to perform custom validation. You can perform any custom validation that you need. The only requirement is that you write a JavaScript function.

For example, when booking a hotel room, you might want to validate that the Arrival Date is in the future instead of the past:




    Constraint Validation API



    
        
            Arrival Date:

The form above contains an input field named arrivalDate. Entering a value into the arrivalDate field triggers the input event.

The JavaScript code adds an event listener for the input event and checks whether the date entered is greater than the current date. If validation fails then the validation error message “Arrival date must be after now!” is assigned to the arrivalDate input field by calling the setCustomValidity() method of the validation constraint API. Otherwise, the validation error message is cleared by calling setCustomValidity() with an empty string.

HTML5 Validation and Older Browsers

But what about older browsers? For example, what about Apple Safari and versions of Microsoft Internet Explorer older than Internet Explorer 10?

What the world really needs is a jQuery plugin which provides backwards compatibility for the HTML5 validation attributes. If a browser supports the HTML5 validation attributes then the plugin would do nothing. Otherwise, the plugin would add support for the attributes.

Unfortunately, as far as I know, this plugin does not exist. I have not been able to find any plugin which supports both the required and pattern attributes for older browsers, but does not get in the way of these attributes in the case of newer browsers.

There are several jQuery plugins which provide partial support for the HTML5 validation attributes including:

· jQuery Validation — http://docs.jquery.com/Plugins/Validation

· html5Form — http://www.matiasmancini.com.ar/jquery-plugin-ajax-form-validation-html5.html

· h5Validate — http://ericleads.com/h5validate/

The jQuery Validation plugin – the most popular JavaScript validation library – supports the HTML5 required attribute, but it does not support the HTML5 pattern attribute. Likewise, the html5Form plugin does not support the pattern attribute.

The h5Validate plugin provides the best support for the HTML5 validation attributes. The following page illustrates how this plugin supports both the required and pattern attributes:




    h5Validate
    


    
        
            First Name:
            
        
        
            Social Security Number:

When an input field fails validation, the validationError CSS class is applied to the field and the field appears with a red border. When an input field passes validation, the validationValid CSS class is applied to the field and the field appears with a green border.

From the perspective of HTML5 validation, the h5Validate plugin is the best of the plugins. It adds support for the required and pattern attributes to browsers which do not natively support these attributes such as IE9. However, this plugin does not include everything in my wish list for a perfect HTML5 validation plugin.

Here’s my wish list for the perfect back compat HTML5 validation plugin:

1. The plugin would disable itself when used with a browser which natively supports HTML5 validation attributes. The plugin should not be too greedy – it should not handle validation when a browser could do the work itself.

2. The plugin should simulate the same user interface for displaying validation error messages as the user interface displayed by browsers which natively support HTML5 validation. Chrome, Firefox, and Internet Explorer all display validation errors in a popup. The perfect plugin would also display a popup.

3. Finally, the plugin would add support for the setCustomValidity() method and the other methods of the HTML5 validation constraint API. That way, you could implement custom validation in a standards compatible way and you would know that it worked across all browsers both old and new.

Security

It would be irresponsible of me to end this blog post without mentioning the issue of security. It is important to remember that any client-side validation — including HTML5 validation — can be bypassed.

You should use client-side validation with the intention to create a better user experience. Client validation is great for providing a user with immediate feedback when the user is in the process of completing a form. However, client-side validation cannot prevent an evil hacker from submitting unexpected form data to your web server.

You should always enforce your validation rules on the server. The only way to ensure that a required field has a value is to verify that the required field has a value on the server. The HTML5 required attribute does not guarantee anything.

Summary

The goal of this blog post was to describe the support for validation contained in the HTML5 standard. You learned how to use both the required and the pattern attributes in an HTML5 form. We also discussed how you can implement custom validation by taking advantage of the setCustomValidity() method.

Finally, I discussed the available jQuery plugins for adding support for the HTM5 validation attributes to older browsers. Unfortunately, I am unaware of any jQuery plugin which provides a perfect solution to the problem of backwards compatibility.

Introduction to the ASP.NET Web API

Stephen.Walther — Mon, 05 Mar 2012 23:16:52 +0000

I am a huge fan of Ajax. If you want to create a great experience for the users of your website – regardless of whether you are building an ASP.NET MVC or an ASP.NET Web Forms site — then you need to use Ajax. Otherwise, you are just being cruel to your customers.

We use Ajax extensively in several of the ASP.NET applications that my company, Superexpert.com, builds. We expose data from the server as JSON and use jQuery to retrieve and update that data from the browser.

One challenge, when building an ASP.NET website, is deciding on which technology to use to expose JSON data from the server. For example, how do you expose a list of products from the server as JSON so you can retrieve the list of products with jQuery? You have a number of options (too many options) including ASMX Web services, WCF Web Services, ASHX Generic Handlers, WCF Data Services, and MVC controller actions.

Fortunately, the world has just been simplified. With the release of ASP.NET 4 Beta, Microsoft has introduced a new technology for exposing JSON from the server named the ASP.NET Web API. You can use the ASP.NET Web API with both ASP.NET MVC and ASP.NET Web Forms applications.

The goal of this blog post is to provide you with a brief overview of the features of the new ASP.NET Web API. You learn how to use the ASP.NET Web API to retrieve, insert, update, and delete database records with jQuery. We also discuss how you can perform form validation when using the Web API and use OData when using the Web API.

Creating an ASP.NET Web API Controller

The ASP.NET Web API exposes JSON data through a new type of controller called an API controller. You can add an API controller to an existing ASP.NET MVC 4 project through the standard Add Controller dialog box.

Right-click your Controllers folder and select Add, Controller. In the dialog box, name your controller MovieController and select the Empty API controller template:

A brand new API controller looks like this:

using System;
using System.Collections.Generic;
using System.Linq;
using System.Net.Http;
using System.Web.Http;

namespace MyWebAPIApp.Controllers
{
    public class MovieController : ApiController
    {
    }
}

An API controller, unlike a standard MVC controller, derives from the base ApiController class instead of the base Controller class.

Using jQuery to Retrieve, Insert, Update, and Delete Data

Let’s create an Ajaxified Movie Database application. We’ll retrieve, insert, update, and delete movies using jQuery with the MovieController which we just created. Our Movie model class looks like this:

namespace MyWebAPIApp.Models
{
    public class Movie
    {
        public int Id { get; set; }
        public string Title { get; set; }
        public string Director { get; set; }
    }
}

Our application will consist of a single HTML page named Movies.html. We’ll place all of our jQuery code in the Movies.html page.

Getting a Single Record with the ASP.NET Web API

To support retrieving a single movie from the server, we need to add a Get method to our API controller:

using System;
using System.Collections.Generic;
using System.Linq;
using System.Net;
using System.Net.Http;
using System.Web.Http;
using MyWebAPIApp.Models;

namespace MyWebAPIApp.Controllers
{
    public class MovieController : ApiController
    {

        public Movie GetMovie(int id)
        {
            // Return movie by id
            if (id == 1)
            {
                return new Movie
                {
                    Id = 1,
                    Title = "Star Wars",
                    Director = "Lucas"
                };
            }

            // Otherwise, movie was not found
            throw new HttpResponseException(HttpStatusCode.NotFound);
        }

    }
}

In the code above, the GetMovie() method accepts the Id of a movie. If the Id has the value 1 then the method returns the movie Star Wars. Otherwise, the method throws an exception and returns 404 Not Found HTTP status code.

After building your project, you can invoke the MovieController.GetMovie() method by entering the following URL in your web browser address bar: http://localhost:[port]/api/movie/1 (You’ll need to enter the correct randomly generated port).

In the URL api/movie/1, the first “api” segment indicates that this is a Web API route. The “movie” segment indicates that the MovieController should be invoked. You do not specify the name of the action. Instead, the HTTP method used to make the request – GET, POST, PUT, DELETE — is used to identify the action to invoke.

The ASP.NET Web API uses different routing conventions than normal ASP.NET MVC controllers. When you make an HTTP GET request then any API controller method with a name that starts with “GET” is invoked. So, we could have called our API controller action GetPopcorn() instead of GetMovie() and it would still be invoked by the URL api/movie/1.

The default route for the Web API is defined in the Global.asax file and it looks like this:

routes.MapHttpRoute(
    name: "DefaultApi",
    routeTemplate: "api/{controller}/{id}",
    defaults: new { id = RouteParameter.Optional }
);

We can invoke our GetMovie() controller action with the jQuery code in the following HTML page:




    Get Movie



    
        Title: 
    
    
        Director:

In the code above, the jQuery $.ajax() method is used to invoke the GetMovie() method. Notice that the Ajax call handles two HTTP response codes. When the GetMove() method successfully returns a movie, the method returns a 200 status code. In that case, the details of the movie are displayed in the HTML page.

Otherwise, if the movie is not found, the GetMovie() method returns a 404 status code. In that case, the page simply displays an alert box indicating that the movie was not found (hopefully, you would implement something more graceful in an actual application).

You can use your browser’s Developer Tools to see what is going on in the background when you open the HTML page (hit F12 in the most recent version of most browsers). For example, you can use the Network tab in Google Chrome to see the Ajax request which invokes the GetMovie() method:

Getting a Set of Records with the ASP.NET Web API

Let’s modify our Movie API controller so that it returns a collection of movies. The following Movie controller has a new ListMovies() method which returns a (hard-coded) collection of movies:

using System;
using System.Collections.Generic;
using System.Linq;
using System.Net;
using System.Net.Http;
using System.Web.Http;
using MyWebAPIApp.Models;

namespace MyWebAPIApp.Controllers
{
    public class MovieController : ApiController
    {

        public IEnumerable ListMovies()
        {
            return new List {
                new Movie {Id=1, Title="Star Wars", Director="Lucas"},
                new Movie {Id=1, Title="King Kong", Director="Jackson"},
                new Movie {Id=1, Title="Memento", Director="Nolan"}
            };
        }

    }
}

Because we named our action ListMovies(), the default Web API route will never match it. Therefore, we need to add the following custom route to our Global.asax file (at the top of the RegisterRoutes() method):

routes.MapHttpRoute(
    name: "ActionApi",
    routeTemplate: "api/{controller}/{action}/{id}",
    defaults: new { id = RouteParameter.Optional }
);

This route enables us to invoke the ListMovies() method with the URL /api/movie/listmovies.

Now that we have exposed our collection of movies from the server, we can retrieve and display the list of movies using jQuery in our HTML page:




    List Movies

Inserting a Record with the ASP.NET Web API

Now let’s modify our Movie API controller so it supports creating new records:

public HttpResponseMessage PostMovie(Movie movieToCreate)
{
    // Add movieToCreate to the database and update primary key
    movieToCreate.Id = 23;

    // Build a response that contains the location of the new movie
    var response = new HttpResponseMessage(movieToCreate, HttpStatusCode.Created);
    var relativePath = "/api/movie/" + movieToCreate.Id;
    response.Headers.Location = new Uri(Request.RequestUri, relativePath);
    return response;
}

The PostMovie() method in the code above accepts a movieToCreate parameter. We don’t actually store the new movie anywhere. In real life, you will want to call a service method to store the new movie in a database.

When you create a new resource, such as a new movie, you should return the location of the new resource. In the code above, the URL where the new movie can be retrieved is assigned to the Location header returned in the PostMovie() response.

Because the name of our method starts with “Post”, we don’t need to create a custom route. The PostMovie() method can be invoked with the URL /Movie/PostMovie – just as long as the method is invoked within the context of a HTTP POST request.

The following HTML page invokes the PostMovie() method.




    Create Movie

This page creates a new movie (the Hobbit) by calling the createMovie() method. The page simply displays the Id of the new movie:

The HTTP Post operation is performed with the following call to the jQuery $.ajax() method:

$.ajax({
    url: "/api/Movie",
    data: JSON.stringify( movieToCreate ),
    type: "POST",
    contentType: "application/json;charset=utf-8",
    statusCode: {
        201: function (newMovie) {
            callback(newMovie);
        }
    }
});

Notice that the type of Ajax request is a POST request. This is required to match the PostMovie() method.

Notice, furthermore, that the new movie is converted into JSON using JSON.stringify(). The JSON.stringify() method takes a JavaScript object and converts it into a JSON string.

Finally, notice that success is represented with a 201 status code. The HttpStatusCode.Created value returned from the PostMovie() method returns a 201 status code.

Updating a Record with the ASP.NET Web API

Here’s how we can modify the Movie API controller to support updating an existing record. In this case, we need to create a PUT method to handle an HTTP PUT request:

public void PutMovie(Movie movieToUpdate)
{
    if (movieToUpdate.Id == 1) {
        // Update the movie in the database
        return;
    }

    // If you can't find the movie to update
    throw new HttpResponseException(HttpStatusCode.NotFound);
}

Unlike our PostMovie() method, the PutMovie() method does not return a result. The action either updates the database or, if the movie cannot be found, returns an HTTP Status code of 404.

The following HTML page illustrates how you can invoke the PutMovie() method:




    Put Movie

Deleting a Record with the ASP.NET Web API

Here’s the code for deleting a movie:

public HttpResponseMessage DeleteMovie(int id)
{
    // Delete the movie from the database

    // Return status code
    return new HttpResponseMessage(HttpStatusCode.NoContent);
}

This method simply deletes the movie (well, not really, but pretend that it does) and returns a No Content status code (204).

The following page illustrates how you can invoke the DeleteMovie() action:




    Delete Movie

Performing Validation

How do you perform form validation when using the ASP.NET Web API? Because validation in ASP.NET MVC is driven by the Default Model Binder, and because the Web API uses the Default Model Binder, you get validation for free.

Let’s modify our Movie class so it includes some of the standard validation attributes:

using System.ComponentModel.DataAnnotations;
namespace MyWebAPIApp.Models
{
    public class Movie
    {
        public int Id { get; set; }

        [Required(ErrorMessage="Title is required!")]
        [StringLength(5, ErrorMessage="Title cannot be more than 5 characters!")]
        public string Title { get; set; }

        [Required(ErrorMessage="Director is required!")]
        public string Director { get; set; }
    }
}

In the code above, the Required validation attribute is used to make both the Title and Director properties required. The StringLength attribute is used to require the length of the movie title to be no more than 5 characters.

Now let’s modify our PostMovie() action to validate a movie before adding the movie to the database:

public HttpResponseMessage PostMovie(Movie movieToCreate)
{
    // Validate movie
    if (!ModelState.IsValid)
    {
        var errors = new JsonArray();
        foreach (var prop in ModelState.Values)
        {
            if (prop.Errors.Any())
            {
                errors.Add(prop.Errors.First().ErrorMessage);
            }
        }
        return new HttpResponseMessage(errors, HttpStatusCode.BadRequest);
    }

    // Add movieToCreate to the database and update primary key
    movieToCreate.Id = 23;

    // Build a response that contains the location of the new movie
    var response = new HttpResponseMessage(movieToCreate, HttpStatusCode.Created);
    var relativePath = "/api/movie/" + movieToCreate.Id;
    response.Headers.Location = new Uri(Request.RequestUri, relativePath);
    return response;
}

If ModelState.IsValid has the value false then the errors in model state are copied to a new JSON array. Each property – such as the Title and Director property — can have multiple errors. In the code above, only the first error message is copied over. The JSON array is returned with a Bad Request status code (400 status code).

The following HTML page illustrates how you can invoke our modified PostMovie() action and display any error messages:




    Create Movie

The createMovie() function performs an Ajax request and handles either a 201 or a 400 status code from the response. If a 201 status code is returned then there were no validation errors and the new movie was created.

If, on the other hand, a 400 status code is returned then there was a validation error. The validation errors are retrieved from the XmlHttpRequest responseText property. The error messages are displayed in an alert:

(Please don’t use JavaScript alert dialogs to display validation errors, I just did it this way out of pure laziness)

This validation code in our PostMovie() method is pretty generic. There is nothing specific about this code to the PostMovie() method. In the following video, Jon Galloway demonstrates how to create a global Validation filter which can be used with any API controller action:

http://www.asp.net/web-api/overview/web-api-routing-and-actions/video-custom-validation

His validation filter looks like this:

using System.Json;
using System.Linq;
using System.Net;
using System.Net.Http;
using System.Web.Http.Controllers;
using System.Web.Http.Filters;

namespace MyWebAPIApp.Filters
{
    public class ValidationActionFilter:ActionFilterAttribute
    {
        public override void OnActionExecuting(HttpActionContext actionContext)
        {
            var modelState = actionContext.ModelState;
            if (!modelState.IsValid)
            {
                dynamic errors = new JsonObject();
                foreach (var key in modelState.Keys)
                {
                    var state = modelState[key];
                    if (state.Errors.Any())
                    {
                        errors[key] = state.Errors.First().ErrorMessage;
                    }
                }
                actionContext.Response = new HttpResponseMessage(errors, HttpStatusCode.BadRequest);
            }
        }
    }
}

And you can register the validation filter in the Application_Start() method in the Global.asax file like this:

GlobalConfiguration.Configuration.Filters.Add(new ValidationActionFilter());

After you register the Validation filter, validation error messages are returned from any API controller action method automatically when validation fails. You don’t need to add any special logic to any of your API controller actions to take advantage of the filter.

Querying using OData

The OData protocol is an open protocol created by Microsoft which enables you to perform queries over the web. The official website for OData is located here:

http://odata.org

For example, here are some of the query options which you can use with OData:

· $orderby – Enables you to retrieve results in a certain order.

· $top – Enables you to retrieve a certain number of results.

· $skip – Enables you to skip over a certain number of results (use with $top for paging).

· $filter – Enables you to filter the results returned.

The ASP.NET Web API supports a subset of the OData protocol. You can use all of the query options listed above when interacting with an API controller. The only requirement is that the API controller action returns its data as IQueryable.

For example, the following Movie controller has an action named GetMovies() which returns an IQueryable of movies:

public IQueryable GetMovies()
{
    return new List {
        new Movie {Id=1, Title="Star Wars", Director="Lucas"},
        new Movie {Id=2, Title="King Kong", Director="Jackson"},
        new Movie {Id=3, Title="Willow", Director="Lucas"},
        new Movie {Id=4, Title="Shrek", Director="Smith"},
        new Movie {Id=5, Title="Memento", Director="Nolan"}
    }.AsQueryable();
}

If you enter the following URL in your browser:

/api/movie?$top=2&$orderby=Title

Then you will limit the movies returned to the top 2 in order of the movie Title. You will get the following results:

By using the $top option in combination with the $skip option, you can enable client-side paging. For example, you can use $top and $skip to page through thousands of products, 10 products at a time.

The $filter query option is very powerful. You can use this option to filter the results from a query. Here are some examples:

Return every movie directed by Lucas:

/api/movie?$filter=Director eq ‘Lucas’

Return every movie which has a title which starts with ‘S’:

/api/movie?$filter=startswith(Title,’S')

Return every movie which has an Id greater than 2:

/api/movie?$filter=Id gt 2

The complete documentation for the $filter option is located here:

http://www.odata.org/developers/protocols/uri-conventions#FilterSystemQueryOption

Summary

The goal of this blog entry was to provide you with an overview of the new ASP.NET Web API introduced with the Beta release of ASP.NET 4. In this post, I discussed how you can retrieve, insert, update, and delete data by using jQuery with the Web API.

I also discussed how you can use the standard validation attributes with the Web API. You learned how to return validation error messages to the client and display the error messages using jQuery.

Finally, we briefly discussed how the ASP.NET Web API supports the OData protocol. For example, you learned how to filter records returned from an API controller action by using the $filter query option.

I’m excited about the new Web API. This is a feature which I expect to use with almost every ASP.NET application which I build in the future.