Forloop Blog

Managing Scripts for Razor Partial Views and Templates in ASP.NET MVC

Wed, 13 Mar 2013 00:20:34 GMT

UPDATE 13-03-2013: I've created a nuget package for the helpers. The original ScriptContext scope had to be brought back in for MVC 4 as the TemplateStack approach no longer worked.

UPDATE 21-11-2011: After some digging through the MVC framework code, I've come up with a slightly cleaner solution that doesn't require ScriptContext to implement IDisposable and therefore removes the need to create a "scope" for the scripts. Skip to the end to see the update.

The view engine in ASP.NET MVC is flexible, very flexible. With great flexibility comes great responsibility however, and managing JavaScript files and code blocks can be particularly cumbersome in conjunction with partial views and templates.

“It’s my script!,” “No, it’s my script!”

It’s a good idea to split discrete sections of page markup into their own partial views and templates, not only to support reuse but also to support the creation of richer interactive applications that take advantage of AJAX, fetching only the markup that is required from the server at any particular time.

If discrete sections of markup require JavaScript for client-side functionality, in my opinion, it’s good to keep the script near to where it’s needed i.e. declared in the partial view or template. Herein lies a problem; putting JavaScript in the middle of page markup will block subsequent rendering of the page until that script has been executed. To avoid this, YSlow recommends putting scripts near the end of the document, just before the closing </body> tag. Doing this however may cause another problem; the partial view script may be reliant on other script to have been executed before it runs, for example, if it is dependent on a JavaScript library. The question is then, how do we render scripts from partials and templates near the end of the document and control the order of rendering?

I get by with a little help from my friends

I’ve put together some HtmlHelper extension methods and a small class that aid in managing scripts and rendering them at the correct time. Note that I have only tried this with the Razor View Engine; the order of execution of the view hierarchies is different between Razor and WebForms views, so I wouldn’t expect this to work with the latter.

public static class HtmlHelperExtensions
{
    public static ScriptContext BeginScriptContext(this HtmlHelper htmlHelper)
    {
        var scriptContext = new ScriptContext(htmlHelper.ViewContext.HttpContext);
        htmlHelper.ViewContext.HttpContext.Items[ScriptContext.ScriptContextItem] = scriptContext;
        return scriptContext;
    }

    public static void EndScriptContext(this HtmlHelper htmlHelper)
    {
        var items = htmlHelper.ViewContext.HttpContext.Items;
        var scriptContext = items[ScriptContext.ScriptContextItem] as ScriptContext;

        if (scriptContext != null)
        {
            scriptContext.Dispose();
        }
    }

    public static void AddScriptBlock(this HtmlHelper htmlHelper, string script)
    {
        var scriptGroup = htmlHelper.ViewContext.HttpContext.Items[ScriptContext.ScriptContextItem] as ScriptContext;

        if (scriptGroup == null)
            throw new InvalidOperationException("cannot add a script block without a script context. Call Html.BeginScriptContext() beforehand.");

        scriptGroup.ScriptBlocks.Add(script);
    }

    public static void AddScriptFile(this HtmlHelper htmlHelper, string path)
    {
        var scriptGroup = htmlHelper.ViewContext.HttpContext.Items[ScriptContext.ScriptContextItem] as ScriptContext;

        if (scriptGroup == null)
            throw new InvalidOperationException("cannot add a script file without a script context. Call Html.BeginScriptContext() beforehand.");

        scriptGroup.ScriptFiles.Add(path);
    }

    public static IHtmlString RenderScripts(this HtmlHelper htmlHelper)
    {
        var scriptContexts = htmlHelper.ViewContext.HttpContext.Items[ScriptContext.ScriptContextItems] as Stack<ScriptContext>;

        if (scriptContexts != null)
        {
            var count = scriptContexts.Count;
            var builder = new StringBuilder();
            var script = new List<string>();
            var urlHelper = new UrlHelper(htmlHelper.ViewContext.RequestContext, htmlHelper.RouteCollection);

            for (int i = 0; i < count; i++)
            {
                var scriptContext = scriptContexts.Pop();

                foreach (var scriptFile in scriptContext.ScriptFiles)
                {
                    builder.AppendLine("<script type='text/javascript' src='" + urlHelper.Content(scriptFile) + "'></script>");
                }

                script.AddRange(scriptContext.ScriptBlocks);

                // render out all the scripts in one block on the last loop iteration
                if (i == count - 1)
                {
                    builder.AppendLine("<script type='text/javascript'>");
                    foreach (var s in script)
                    {
                        builder.AppendLine(s);
                    }
                    builder.AppendLine("</script>");
                }
            }

            return new MvcHtmlString(builder.ToString());
        }

        return MvcHtmlString.Empty;
    }
}

public class ScriptContext : IDisposable
{
    internal const string ScriptContextItems = "ScriptContexts";
    internal const string ScriptContextItem = "ScriptContext";

    private readonly HttpContextBase _httpContext;
    private readonly IList<string> _scriptBlocks = new List<string>();
    private readonly HashSet<string> _scriptFiles = new HashSet<string>();

    public ScriptContext(HttpContextBase httpContext)
    {
        if (httpContext == null)
            throw new ArgumentNullException("httpContext");

        _httpContext = httpContext;
    }

    public IList<string> ScriptBlocks { get { return _scriptBlocks; } }

    public HashSet<string> ScriptFiles { get { return _scriptFiles; } }

    public void Dispose()
    {
        var items = _httpContext.Items;
        var scriptContexts = items[ScriptContextItems] as Stack<ScriptContext> ?? new Stack<ScriptContext>();

        // remove any script files already the same as the ones we're about to add
        foreach (var scriptContext in scriptContexts)
        {
            scriptContext.ScriptFiles.ExceptWith(ScriptFiles);
        }

        scriptContexts.Push(this);

        items[ScriptContextItems] = scriptContexts;
    }
}

These can be used in your layout, view or partial view in one of three ways (all with the same outcome):

@{
    Html.BeginScriptContext();
    Html.AddScriptBlock(@"$(function() { if (console) { console.log('rendered from the view'); } });");
    Html.AddScriptFile("~/Scripts/jquery-ui-1.8.11.js");
    Html.EndScriptContext(); 
}

@{ 
  using (Html.BeginScriptContext())
  {
    Html.AddScriptFile("~/Scripts/jquery.validate.js");
    Html.AddScriptFile("~/Scripts/jquery-ui-1.8.11.js");
    Html.AddScriptBlock(@"$(function() { 
        $('#someField').datepicker();
    });");
  }
}

or using the ScriptContext directly

@{
  using (var context = Html.BeginScriptContext())
  {
    context.ScriptFiles.Add("~/Scripts/jquery-1.5.1.min.js");
    context.ScriptFiles.Add("~/Scripts/modernizr-1.7.min.js");
  }   
}

If you reference a script more than once, the helpers will ensure that it is rendered only once and in the ordinal position that matches the expected rendering order of views i.e.

Layout
View
Partial View / Template

All that remains is to call @Html.RenderScripts() in your base layout, before the closing </body> tag.

<!DOCTYPE html>
<html>
<head>
    <meta charset="utf-8" />
    <title>@ViewBag.Title</title>
    <link href="@Url.Content("~/Content/Site.css")" rel="stylesheet" type="text/css" />
    <link href="@Url.Content("~/Content/themes/base/jquery.ui.all.css")" rel="stylesheet" type="text/css" />
</head>
<body>
    @RenderBody()
    @Html.RenderScripts()
</body>
</html>

I’ve put up an example up on Bitbucket – let me know what you think

An Updated Solution

After digging through the MVC 3 framework code looking for a way to determine when the razor template currently being rendered changes, I came across TemplateStack and the static method GetCurrentTemplate(HttpContext). Using this method, we can do away with creating a scope for a ScriptContext and simply use

@{
    Html.ScriptFile("~/Scripts/jquery-ui-1.8.11.js");
    Html.ScriptBlock(@"$(function() { if (console) { console.log('rendered from the view'); } });");
}

inside of any view, partial view or template. As a more elaborate example, take the following view

@model HomeModel
@{
    ViewBag.Title = "Index";
    Layout = "~/Views/Shared/_Layout.cshtml";
}

<h2>ScriptContext Example</h2>

<p>4 datepickers rendered from an editor template. The jQuery UI script that contains the datepicker plugin is 
    added inside of the editor template using the script context Html Helpers and rendered out at the end of the page.</p>

@{ Html.RenderPartial("Partial", "partial 1"); }

@Html.EditorFor(m => m.Date1, "DatePicker")
@Html.EditorFor(m => m.Date2, "DatePicker")
@Html.EditorFor(m => m.Date3, "DatePicker")
@Html.EditorFor(m => m.Date4, "DatePicker")

@Html.Partial("Partial", "partial 2")

@{
    Html.ScriptFile("~/Scripts/jquery-ui-1.8.11.js");
    Html.ScriptBlock(@"$(function() { if (console) { console.log('rendered from the view'); } });");
}

This view is using the following Layout (_Layout.cshtml in the shared folder)

<!DOCTYPE html>
<html>
    <head>
        <meta charset="utf-8" />
        <title>@ViewBag.Title</title>
        <link href="@Url.Content("~/Content/Site.css")" rel="stylesheet" type="text/css" />
        <link href="@Url.Content("~/Content/themes/base/jquery.ui.all.css")" rel="stylesheet" type="text/css" />
    </head>
    <body>
        @RenderBody()
        @{
            Html.ScriptFile("~/Scripts/jquery-1.5.1.min.js");
            Html.ScriptFile("~/Scripts/modernizr-1.7.min.js");
        }
        @Html.RenderScripts()
    </body>
</html>

With the following editor template (DatePicker.cshtml in the shared folder)

@model DateTime
@Html.TextBox("", ViewContext.ViewData.TemplateInfo.FormattedModelValue)
@{
    Html.ScriptFile("~/Scripts/jquery-ui-1.8.11.js");
    Html.ScriptBlock(
        @"$(function() { 
    $('#" + ViewContext.ViewData.TemplateInfo.GetFullHtmlFieldName("") + @"').datepicker();
    if (console) { console.log('rendered from the editor template'); }
});");
}

and finally, the following partial (Partial.cshtml in the shared folder)

@model string
@{
    Html.ScriptBlock(@"$(function() { if (console) { console.log('rendered from " + Model + "'); } });");
}

Looking at the output with Firebug, we see the following

We can see that the external JavaScript file <script> elements have been added first, followed by the script from each of the razor templates involved in rendering the response. In both cases, the order of rendering is bottom-up i.e. those scripts added using the Html helpers near the end of the page have been rendered first.

I've updated the example source code up on bitbucket if you want to have a play

Nuget Package for Managing Scripts in ASP.NET MVC 4

Tue, 12 Mar 2013 23:32:52 GMT

As per the comments on my previous post about Managing Scripts for Razor Partial Views and Templates in ASP.NET MVC, I've created a Nuget package for the HtmlHelpers used. Go take a look and leave a comment if you find them useful; I plan to add additional helpers to the package over time for general functionality that is useful in any ASP.NET MVC application.

Web API – Binding Complex types from the URI by default for HTTP GET requests

Mon, 11 Mar 2013 23:13:29 GMT

The model binding implementation in ASP.NET Web Api shares some similarities to the model binding you find in ASP.NET MVC and at the same time has some striking differences. For a more detailed discussion on web api parameter binding, check out Mike Stall’s excellent post on the topic. The topic of today’s post is how we define our own convention for parameter binding complex types when the request is a HTTP GET request.

Body Check

The IActionValueBinder interface is the contract for getting the binding information for a web api controller action

// Copyright (c) Microsoft Open Technologies, Inc. All rights reserved. See License.txt in the project root for license information.

namespace System.Web.Http.Controllers
{
    public interface IActionValueBinder
    {
        HttpActionBinding GetBinding(HttpActionDescriptor actionDescriptor);
    }
}

and DefaultActionValueBinder is the default implementation of IActionValueBinder within a web api application. The route it takes to determine where model binding should attempt to bind values for a parameter action is as follows:

Does the parameter type have a ParameterBindingAttribute? If so, use this for binding
Look in the ParameterBindingRulesCollection on the HttpConfigurationfor the application. Is there a binding specified for the parameter in the collection? If so, use this for binding
Look at the parameter type. Is it a simple type i.e. a primitive, string, DateTime, Decimal, Guid, DateTimeOffset or TimeSpan (or an applicable Nullable version of these)? If so, look at the URI for binding
Does the parameter type have a string converter defined for it? If so, look at the URI for binding
Default to looking in the request body for binding

The fallback option of looking in the request body seems like an odd action to take for a HTTP GET request, with some much better well informed suggesting that a body has no semantic meaning for a HTTP GET request

Yes. In other words, any HTTP request message is allowed to contain
a message body, and thus must parse messages with that in mind.
Server semantics for GET, however, are restricted such that a body,
if any, has no semantic meaning to the request. The requirements
on parsing are separate from the requirements on method semantics.
So, yes, you can send a body with GET, and no, it is never useful
to do so.
This is part of the layered design of HTTP/1.1 that will become
clear again once the spec is partitioned (work in progress).
....Roy

Purism aside, I’d like model binding to default to looking at the URI for GET requests when an binding attribute or rule is not specified for the parameter. It’s actually straightforward to do by leveraging the DefaultActionValueBinder and overriding the GetParameterBinding method

public class CustomActionValueBinder : DefaultActionValueBinder
{
    protected override HttpParameterBinding GetParameterBinding(HttpParameterDescriptor parameter)
    {
        // Attribute has the highest precedence
        // Presence of a model binder attribute overrides.
        var bindingAttribute = parameter.ParameterBinderAttribute;
        if (bindingAttribute != null)
        {
            return bindingAttribute.GetBinding(parameter);
        }

        // No attribute, so lookup in global map.
        var parameterBindingRules = parameter.Configuration.ParameterBindingRules;
        if (parameterBindingRules != null)
        {
            var binding = parameterBindingRules.LookupBinding(parameter);
            if (binding != null)
            {
                return binding;
            }
        }

        // if we're dealing with a method that supports HTTP Gets, Assume the model is in the URI
        // otherwise fallback to the defaults.
        return parameter.ActionDescriptor.SupportedHttpMethods.Contains(HttpMethod.Get)
                    ? parameter.BindWithAttribute(new FromUriAttribute())
                    : base.GetParameterBinding(parameter);
    }
}

To hook this up for the application, we need to replace the default IActionValueBinder registered. This can be done in Application_Start in global.asax

public class WebApiApplication : System.Web.HttpApplication
{
    protected void Application_Start()
    {
        // replace the default IActionValueBinder
        GlobalConfiguration.Configuration.Services.Replace(typeof(IActionValueBinder), new CustomActionValueBinder());
    }
}

Alternatively, if you’re using an Inversion of Control Container for wiring up dependencies then you simply need to register the IActionValueBinder with your container to allow your IDependencyResolver to resolve and use it.

CSV ValueProvider for model binding to collections

Sat, 02 Mar 2013 22:11:06 GMT

TL;DR

I have written a ValueProvider for binding model collections from records in a CSV file. The source code is available on BitBucket.

Model binding in ASP.NET MVC is responsible for binding values to the models that form the parameter arguments to the controller action matched to the route. But where do model binders get these values from? That’s where Value Providers come in; A ValueProvider provides values for model binding and there are ValueProviders for providing values from

Design Patterns in action

The interface for a ValueProvider is straightforward, comprising only two methods:

// Copyright (c) Microsoft Open Technologies, Inc. All rights reserved. See License.txt in the project root for license information.

namespace System.Web.Mvc
{
    public interface IValueProvider
    {
        bool ContainsPrefix(string prefix);
        ValueProviderResult GetValue(string key);
    }
}

ContainsPrefix determines whether the provider contains a value with the passed prefix and GetValue returns a ValueProviderResult for a given key (or null if the provider cannot provide a result for the key).

A provider is constructed by a… ValueProviderFactory! The factory method pattern is used to construct a provider, with each different framework provider constructed by a different factory class deriving from ValueProviderFactory. The MVC framework has a place to register new factories using the static ValueProviderFactories.Factories property which is an instance of ValueProviderFactoryCollection. This collection has a GetValueProvider method that returns ValueProviderCollection, a composite provider that implements IValueProvider and internally works with an instance of each IValueProvider constructed by each ValueProviderFactory registered. That’s a lot of detail to describe there and my reason for doing so is because of an important detail that rises from this implementation -

The first instance of ValueProviderResult returned from a GetValue call on an IValueProvider will be the result used in model binding. The order of IValueProvider implementations in ValueProviderFactories.Factories is important if more than one can provide a value for model binding.

We'll see a little later why this is important.

Providing values for model binding from a CSV file

CSV (comma/character separated values) are a file format for passing tabular data around in structured plain text and are regularly used to upload collections of records to web applications. In ASP.NET MVC, the HttpFileCollectionValueProvider provides access to uploaded files by specifying the model property to bind to as HttpPostedFileBase. The problem that I find with this approach however is that the responsibility for reading the file, transforming it into something more meaningful such as a collection of types to work with and handling validation errors now usually happens in one of two places

the controller action
a custom model binder

If your application allows users to upload CSV files for creating multiple records for different purposes this can be a lot of repetition. If we know that a file contains CSV data, it would be good if these values were provided for model binding; this way, the mechanism could be re-used anywhere where CSV files are used and more importantly, by being exposed as values for model binding the values will also be validated against the data annotations on the model. Let’s go ahead an implement a CSV Value Provider.

public class CsvValueProvider : IValueProvider
{
    public static readonly CsvConfiguration Configuration = new CsvConfiguration { AllowComments = true };

    private readonly Lazy<PrefixContainer> _prefixContainer;
    private readonly NameValueCollection _values = new NameValueCollection();

    public CsvValueProvider(ControllerContext controllerContext)
    {
        _prefixContainer = new Lazy<PrefixContainer>(() => new PrefixContainer(_values.AllKeys), true);

        var files = controllerContext.HttpContext.Request.Files;

        if (files.Count == 0)
        {
            return;
        }

        var mapping = new List<KeyValuePair<string, HttpPostedFileBase>>();
        for (var i = 0; i < files.Count; i++)
        {
            var key = files.AllKeys[i];
            if (key != null)
            {
                HttpPostedFileBase file = PostedFileHelper.ChooseFileOrNull(files[i]);

                // we only care about csv files
                if (file != null && !file.FileName.EndsWith(".csv"))
                {
                    continue;
                }

                mapping.Add(new KeyValuePair<string, HttpPostedFileBase>(key, file));
            }
        }

        var fileGroups = mapping.GroupBy(el => el.Key, el => el.Value, StringComparer.OrdinalIgnoreCase);

        foreach (var fileGroup in fileGroups)
        {
            foreach (var file in fileGroup)
            {
                using (var reader = new CsvReader(new StreamReader(file.InputStream), Configuration))
                {
                    int index = 0;
                    long previousCharPosition = 0;
                    while (reader.Read())
                    {
                        long charPosition = reader.Parser.CharPosition;

                        for (var j = 0; j < reader.CurrentRecord.Length; j++)
                        {
                            var subPropertyName = reader.FieldHeaders[j].Trim();
                            var value = reader.CurrentRecord[j];
                            _values.Add(string.Format("{0}[{1}].{2}", fileGroup.Key, index, subPropertyName), value);
                        }

                        // naive way of determining if the file is *really* a csv file.
                        // the csv parser's character position does not change when it can't read
                        // the file as a csv.
                        if (charPosition == previousCharPosition)
                        {
                            return;
                        }

                        previousCharPosition = charPosition;
                        index++;
                    }
                }
            }
        }
    }

    public bool ContainsPrefix(string prefix)
    {
        return _prefixContainer.Value.ContainsPrefix(prefix);
    }

    public ValueProviderResult GetValue(string key)
    {
        if (key == null)
        {
            throw new ArgumentNullException("key");
        }

        if (!_values.AllKeys.Contains(key, StringComparer.OrdinalIgnoreCase))
        {
            return null;
        }

        var rawValue = _values.GetValues(key);
        var attemptedValue = _values[key];
        return new ValueProviderResult(rawValue, attemptedValue, CultureInfo.InvariantCulture);
    }
}

The provider is using the great CsvHelper nuget package from Josh Close. It looks at the incoming files on the request and for any files with the *.csv file extension, it will open them in turn and attempt to read the records out of the file. For each record that it finds in the CSV, it will take the value and add it to a NameValueCollection keyed against the header name followed by an indexer indicating the position of the record, and prefixed with the name of the file as posted in the request. It uses a NameValueCollection so that multiple columns with the same header name can be specified thereby allowing binding to simple property collections on a model.

In order to create the provider, a factory is required:

public class CsvValueProviderFactory : ValueProviderFactory
{
    public static void AddToValueProviderFactoryCollection()
    {
        AddToValueProviderFactoryCollection(ValueProviderFactories.Factories);
    }

    public static void AddToValueProviderFactoryCollection(ValueProviderFactoryCollection collection)
    {
        var postedFileValueProviderFactory =
            collection.SingleOrDefault(x => x is System.Web.Mvc.HttpFileCollectionValueProviderFactory);

        if (postedFileValueProviderFactory != null)
        {
            var index = collection.IndexOf(postedFileValueProviderFactory);
            collection.Insert(index, new CustomHttpFileCollectionValueProviderFactory());
            collection.Remove(postedFileValueProviderFactory);
        }

        collection.Add(new CsvValueProviderFactory());
    }

    public override IValueProvider GetValueProvider(ControllerContext controllerContext)
    {
        return new CsvValueProvider(controllerContext);
    }
}

The factory is fairly straightforward, with the addition of a couple of static methods that can be used to add the provider to the factories collection.

Fightin’ the Framework

The static methods on CsvValueProviderFactory are there to not only add the factory to the factories collection, but also to remove the System.Web.Mvc.HttpFileCollectionValueProviderFactory and replace it with our own custom value provider for getting values from posted files. Why do we need to do this I hear you ask? Well, let’s go back to the point raised earlier.

The first instance of ValueProviderResult returned from a GetValue call on an IValueProvider will be the result used in model binding. The order of IValueProvider implementations in ValueProviderFactories.Factories is important if more than one can provide a value for model binding.

Let’s imagine we have a view model that has a collection of users on it that we wish to bind that looks like so:

using System.ComponentModel.DataAnnotations;

public class UsersModel
{
    public UsersModel()
    {
        Users = new List<User>();
    }

    public IList<User> Users { get; set; } 
}

public class User
{
    public User()
    {
        Roles = new string[0];
    }

    [Required]
    public string FullName { get; set; }

    [Required]
    public string Username { get; set; }

    [Required]
    [EmailAddress]
    public string Email { get; set; }

    [Required]
    public int? Age { get; set; }

    public string[] Roles { get; set; }
}

Now, we have a controller where users can submit a CSV file:

public class HomeController : Controller
{
    [HttpGet]
    public ActionResult Index()
    {
        return View(new UsersModel());
    }

    [HttpPost]
    public ActionResult Index(UsersModel model)
    {
        return View(model);
    }
}

and a corresponding view with the following form:

@using (Html.BeginForm("Index", "Home", FormMethod.Post, new { enctype = "multipart/form-data" }))
{
    @Html.TextBoxFor(m => m.Users, new { type = "file" })
    <button type="submit">Submit</button>
}

Here’s what happens when we have the CsvValueProviderFactory hooked up in addition to System.Web.Mvc.HttpFileCollectionValueProviderFactory

A user submits a file for the Users property on UsersModel
The HttpFileCollectionValueProvider finds the file in the request and puts it into a dictionary against the string key “Users”
The CSVValueProviderfinds the file in the request, determines it’s a csv file and reads the records out
For each record, the provider creates keys named “Users[index].FieldHeader” where Users is the filename, index is the record row index and FieldHeader is a column in the csv file that corresponds to a property on the Usertype
When model binding is taking place, the default model binder asks the value providers if they contain the prefix “model” first (this is the parameter name on the action; none of the providers have a value for this) and then asks if they contain the prefix “Users” (which both HttpFileCollectionValueProvider and CsvValueProviderwill return true for)
binding calls GetValue on each of the ValueProviders passing in the key “Users”
The HttpFileCollectionValueProvider returns an instance of HttpPostedFileBase for “Users” that will fail to be bound to the IList<User> type for the property Users on the UsersModel
Binding will not ask the ValueProviders for any keys further down the property chain for “Users” and so the values for CSVValueProvider will not be used in model binding

On the basis of this knowledge, all the CustomHttpFileCollectionValueProvider constructed by CustomHttpFileCollectionValueProviderFactory does is to ignore csv files so that they cannot be provided as values for model binding and do not interfere with the function of CSVValueProvider.

Where did the errors happen?

I’ve put up the source code and a demo web project on bitbucket for those interested. What remains is to provide more meaningful error messages back to the user for any rows in the CSV file that fail model validation; at the moment, we can do something simple like:

for (int i = 0; i < Model.Users.Count; i++)
{
    if (!ViewContext.ViewData.ModelState.IsValidField("Users[" + i + "]"))
    {
        <p class="field-validation-error">Invalid values in row @i</p>
        @Html.ValidationMessageFor(m => m.Users[i].Age)
        @Html.ValidationMessageFor(m => m.Users[i].Email)
        @Html.ValidationMessageFor(m => m.Users[i].FullName)
        @Html.ValidationMessageFor(m => m.Users[i].Username)
        @Html.ValidationMessageFor(m => m.Users[i].Roles)        
    }
}

which will tell the user which row was invalid and write out the corresponding error messages. I’ll look to make something more generic that can be reused for other models and update the source on bitbucket.

Presentations from NDC 2012

Sun, 24 Feb 2013 21:40:06 GMT

The Norwegian Developers Conference is one of the largest .NET Developer conferences of the year, running over several days and including presentations on topics as wide-ranging as software architecture, SOLID principles, Test-Driven Development and more specific introductions to technologies such as ASP.NET 4.5, Web API, NodeJS and NServiceBus. Sufficed to say, there is something there for every .NET developer. Interested in seeing what SignalR is all about? Check out the following presentation from Damian Edwards:

One of the best things about the conference if you're not fortunate to go is that all of the presentations are recorded and can be viewed on the site; take a look at the agenda to see which ones pique your interest. If you just have to watch them all then take a look at the torrent that NDC has created to easily download all of the videos to watch as and when.

Learn something new today and, if you can, get yourself to next year's event on June 12-14 2013!

Resolving IoC container services for Validation Attributes in ASP.NET MVC

Fri, 03 Aug 2012 10:14:04 GMT

I'm a fan of the Data Annotation Validation attributes to validate user input on both the client and server side for ASP.NET MVC applications. I'm also a fan of Inversion of Control and Dependency Injection to create loosely coupled and flexible applications. There are certain situations where one would wish to inject services into a validation attribute to use during validation; a (somewhat contrived and security cautious) example of this might be providing the user with a <select> element and ask them to choose an option from it and then validate that the option that they have chosen is one that actually exists for the type of items represented in the dropdown. Sure, the RemoteAttribute would allow you to call a server side method via AJAX to perform validation but it does not provide any server side validation, making it more of a convenience solution than a complete and robust one. What would be good is if we could

provide services to a validation attribute that could be used in the process of validation
Not have to explicitly resolve services from the container à la the Service Locator (Anti-)Pattern

What the framework giveth...

By default, the MVC framework uses the DataAnnotationsModelValidator to provide a ValidationContext and Model object to a Validation attribute:

/* ****************************************************************************
 *
 * Copyright (c) Microsoft Corporation. All rights reserved.
 *
 * This software is subject to the Microsoft Public License (Ms-PL). 
 * A copy of the license can be found in the license.htm file included 
 * in this distribution.
 *
 * You must not remove this notice, or any other, from this software.
 *
 * ***************************************************************************/
 
namespace System.Web.Mvc {
    using System;
    using System.Collections.Generic;
    using System.ComponentModel.DataAnnotations;
    using System.Linq;
 
    public class DataAnnotationsModelValidator : ModelValidator {
        public DataAnnotationsModelValidator(ModelMetadata metadata, ControllerContext context, ValidationAttribute attribute)
            : base(metadata, context) {
 
            if (attribute == null) {
                throw new ArgumentNullException("attribute");
            }
 
            Attribute = attribute;
        }
 
        protected internal ValidationAttribute Attribute { get; private set; }
 
        protected internal string ErrorMessage {
            get {
                return Attribute.FormatErrorMessage(Metadata.GetDisplayName());
            }
        }
 
        public override bool IsRequired {
            get {
                return Attribute is RequiredAttribute;
            }
        }
 
        internal static ModelValidator Create(ModelMetadata metadata, ControllerContext context, ValidationAttribute attribute) {
            return new DataAnnotationsModelValidator(metadata, context, attribute);
        }
 
        public override IEnumerable<ModelClientValidationRule> GetClientValidationRules() {
            IEnumerable<ModelClientValidationRule> results = base.GetClientValidationRules();
 
            IClientValidatable clientValidatable = Attribute as IClientValidatable;
            if (clientValidatable != null) {
                results = results.Concat(clientValidatable.GetClientValidationRules(Metadata, ControllerContext));
            }
 
            return results;
        }
 
        public override IEnumerable<ModelValidationResult> Validate(object container) {
            // Per the WCF RIA Services team, instance can never be null (if you have
            // no parent, you pass yourself for the "instance" parameter).
            ValidationContext context = new ValidationContext(container ?? Metadata.Model, null, null);
            context.DisplayName = Metadata.GetDisplayName();
 
            ValidationResult result = Attribute.GetValidationResult(Metadata.Model, context);
            if (result != ValidationResult.Success) {
                yield return new ModelValidationResult {
                    Message = result.ErrorMessage
                };
            }
        }
    }
}

The Validate method creates a new ValidationContext instance and passes this, along with the model object to the Attribute via the GetValidationResult(object, ValidationContext) method on the attribute. See those other null parameter arguments passed to the ValidationContext constructor? Those are for an IServiceProvider and IDictionary<object, object>, respectively. The former is a contract for one method, GetService(Type), that takes a type and returns an object. On this basis, MVC provides a hook for being able to resolve services inside of a validation attribute, but that hook isn't used by default. Luckily, the default can be replaced with our own implementation.

A crude solution

Let's write our own ModelValidator. Using Castle Windsor IoC container, the IKernel implements IServiceProvider already, so we could go with something like this:

public class WindsorModelValidator : DataAnnotationsModelValidator
{
    public IKernel Kernel { get; set; }

    public WindsorModelValidator(
        ModelMetadata metadata,
        ControllerContext context,
        ValidationAttribute attribute)
        : base(metadata, context, attribute)
    {
    }

    public override IEnumerable<ModelValidationResult> Validate(object container)
    {
        ValidationContext context = CreateValidationContext(container);

        ValidationResult result = Attribute.GetValidationResult(Metadata.Model, context);

        if (result != ValidationResult.Success)
        {
            yield return new ModelValidationResult
                {
                    Message = result.ErrorMessage
                };
        }
    }

    protected virtual ValidationContext CreateValidationContext(object container)
    {
        var context = new ValidationContext(container ?? Metadata.Model, Kernel, null);
        context.DisplayName = Metadata.GetDisplayName();
        return context;
    }
}

Then in Application_Start, register our WindsorModelValidator with the container and hook it up to be used as the ModelValidator for the application:

protected void Application_Start()
{
    // superfluous code here like route registration, etc...

    var container = new WindsorContainer();

    container.Register(AllTypes.FromThisAssembly()
                    .BasedOn<IController>()
                    .If(Component.IsInSameNamespaceAs<HomeController>())
                    .If(t => t.Name.EndsWith("Controller"))
                    .Configure(c => c.LifeStyle.Transient));


    container.Register(
        Component.For<ICategoryRepository>().ImplementedBy<CategoryRepository>(),
        Component.For<ModelValidator>().ImplementedBy<WindsorModelValidator>().LifeStyle.Transient);

    ControllerBuilder.Current.SetControllerFactory(new WindsorControllerFactory(container.Kernel));

    // hook up our WindsorModelValidator here
    DataAnnotationsModelValidatorProvider.RegisterDefaultAdapterFactory(
         (metadata, context, attribute) => container.Resolve<ModelValidator>(new { metadata, context, attribute }));
}

Now, inside of validation attributes we can resolve services from the IServiceProvider (provided by the Kernel) on the ValidationContext:

public class ValidCategoryAttribute : ValidationAttribute
{
    private const string DefaultErrorMessage = "'{0}' does not contain a valid category";

    public ValidCategoryAttribute() : base(DefaultErrorMessage)
    {
    }

    protected override ValidationResult IsValid(object value, ValidationContext validationContext)
    {
        var input = Convert.ToString(value, CultureInfo.CurrentCulture);

        // let the Required attribute take care of this validation
        if (string.IsNullOrWhiteSpace(input))
        {
            return null;
        }

        // resolve our ICategoryRepository using IServiceProvider on the ValidationContext
        var categories = validationContext.GetService(typeof(ISettingsRepository)) as ICategoryRepository;
 
        int categoryId;
        if (!int.TryParse(input, out categoryId))
        {
            return new ValidationResult(FormatErrorMessage(validationContext.DisplayName));
        }
      
        return categories.Where(c => c.Id == categoryId).FirstOrDefault() == null ? 
            new ValidationResult(FormatErrorMessage(validationContext.DisplayName)) : null;
    }
}

This satisfies Point 1 above, but not Point 2. We don't want to have to explicitly get the service, we want it to be provided to us (i.e. the Hollywood Principle).

A better solution

Quite a while ago, Jeremy Skinner wrote an article about Dependency Injection with Action Filters where he created his own IActionInvoker that could inject services into ActionFilter attributes. We can do something similar here for Validation attributes. Here is an improved WindsorModelValidator:

public class WindsorModelValidator : DataAnnotationsModelValidator
{
    public IKernel Kernel { get; set; }

    public WindsorModelValidator(
        ModelMetadata metadata,
        ControllerContext context,
        ValidationAttribute attribute)
        : base(metadata, context, attribute)
    {
    }

    public override IEnumerable<ModelValidationResult> Validate(object container)
    {
        // inject the services from the container that
        // the Validation attribute requires
        Kernel.InjectProperties(Attribute);

        ValidationContext context = CreateValidationContext(container);

        ValidationResult result = Attribute.GetValidationResult(Metadata.Model, context);

        if (result != ValidationResult.Success)
        {
            yield return new ModelValidationResult
                {
                    Message = result.ErrorMessage
                };
        }
    }

    protected virtual ValidationContext CreateValidationContext(object container)
    {
        var context = new ValidationContext(container ?? Metadata.Model, Kernel, null);
        context.DisplayName = Metadata.GetDisplayName();
        return context;
    }
}

Keeping the registration in Application_Start the same as before, we can now write our ValidCategoryAttribute like so:

public class ValidCategoryAttribute : ValidationAttribute
{
    private const string DefaultErrorMessage = "{0} is not a valid category";

    public ValidCategoryAttribute() : base(DefaultErrorMessage)
    {
    }

    public ICategoryRepository Categories { get; set; }

    public override bool IsValid(object value)
    {
        var input = Convert.ToString(value, CultureInfo.CurrentCulture);

        // let the Required attribute take care of this validation
        if (string.IsNullOrWhiteSpace(input))
        {
            return null;
        }

        int categoryId;
        if (!int.TryParse(input, out categoryId))
        {
            return new ValidationResult(FormatErrorMessage(validationContext.DisplayName));
        }
      
        return Categories.Where(c => c.Id == categoryId).FirstOrDefault() == null ? 
            new ValidationResult(FormatErrorMessage(validationContext.DisplayName)) : null;
    }
}

Much cleaner, yes? The InjectProperties extension method implementation can be found on Jeremy's blog.

C# 5 asynchronous programming

Fri, 03 Aug 2012 10:07:00 GMT

If you missed Anders Hejlsberg talk on the Future directions for C# and Visual Basic, go check it out now, I’ll wait.

I hope you'll agree that asynchronous programming just got a whole lot easier to do. The point that Anders made that really cemented in my mind how the new async and await C# keywords work in practice was this:

public async Task<XElement> GetXmlAsync(string url)
{
    var client = new HttpClient();
    var response = await client.GetAsync(url);
    var text = response.Content.ReadAsString();
    return XElement.Parse(text);
}

which is effectively translated to the following

public Task<XElement> GetXmlAsync(string url)
{
    var tcs = TaskCompletionSource<XElement>();
    var client = new HttpClient();
    client.GetAsync(url).ContinueWith(task =>
        {
            var response = task.Result;
            var text = response.Content.ReadAsString();
            tcs.SetResult(XElement.Parse(text));
        });

    return tcs.Task;
}

Something about this feels particularly familiar. If you’ve written any type of web application that utilizes AJAX, writing callback functions in JavaScript (or more likely, using a JavaScript library) happens all over the place. You know that when you see this

function updatePerson() {
  var returnedMessage;

  $.ajax({
     type: "POST",
     url: "people/update/2",
     data: { firstName : 'John', secondName : 'Smith'  },
     success: function(msg){
       returnedMessage = msg;
     }
   });

  return returnedMessage;
}

that returnedMessage will be undefined until the request made via AJAX returns and returnedMessage is set to the value of msg returned from the server. This is a common mistake that people make when first using JavaScript to make AJAX requests and may have been some of the impetus behind the introduction of $.Deferred() in jQuery 1.5. If you wanted the above to work as intended and perhaps be a little clearer, you could rewrite it as

function updatePerson() {
  return $.ajax({
     type: "POST",
     url: "/people/update/2",
      data: { firstName : 'John', secondName : 'Smith' }
   }).promise();
}

updatePerson().done(function(msg) {
   // do something with msg
});

This returns a promise that provides a view onto the current state of the task and allows the addition of further callbacks. Here’s a demo from jsfiddle:

Continuation Passing Style, as it is known, is not a new topic and is one that is most familiar to those engrossed in functional programming languages. If you want to read more about it, Eric Lippert wrote a great series of posts on the subject some time ago and if you’re interested in knowing more about how the new C#5 asynchronous programming works under the hood, go check out Jon Skeet’s Eduasync series. Understanding these well now will mean that one will be able to put them to good use as soon as they’re officially released to market.

Event Messaging on the client side with jQuery

Fri, 03 Aug 2012 10:06:13 GMT

How many times have you come across the following kind of code in JavaScript

// code in script-1.js

// eek, two global variables!
var dialog, 
    updateMessage = function updateMessage (message) {        
      dialog.text(message);    
    }

// function to run when the DOM has loaded
$(function () {
    // #dialog is just a simple <p> element
    dialog = $('#dialog');
});

then in another script file

// code in script-2.js

// function to run when the DOM has loaded
$(function () {
    $('select').change(function () {
        // update the dialog with the new selection
        updateMessage('the new value is ' + this.value);
    });
});

All we’re doing here is updating the text of a <p> element in the DOM whenever the value of a <select> element changes. It’s a contrived and trivial example but it perfectly demonstrates the tight coupling between these two script files; if the updateMessage function is renamed, removed or modified to reorder the parameters (let’s put aside the use of arguments for a moment), this is going to break script-2 at runtime. What’s more, usually with these kinds of changes, it’s too easy to forget to search through all script and markup-related files for function usages and modify accordingly. And further still, it's polluted the global namespace with two additional variables (a big no no in JavaScript development), dialog and updateMessage, to allow script-2 access to the updateMessage function (which needs access to the dialog variable). There has to be a better way, and there is.

Custom Events

Custom events have been in jQuery core for as long as I can remember, at least back as far as 1.2.6 in 2008. They are similar to an event bus for sending messages (read: objects) when something happens on the client side and subscribing to knowing when that something happens. Let’s look at a revised version of the previous code, using jQuery custom events

// code in script-1.js

// function to run when the DOM has loaded
$(function () {
   // #dialog is just a simple <p> element
    var dialog  = $('#dialog');

    // bind a handler to the custom namespaced event "dialog.updateMessage"
    $(document).on('dialog.updateMessage',  function (e, message) {
        dialog.text(message);
    });
});

and now in script 2,

// code in script-2.js

// function to run when the DOM has loaded
$(function () {
    $('select').change(function () {
        // raise the dialog.updateMessage and pass it a message
        $(document).triggerHandler('dialog.updateMessage', ['the new value is ' + this.value]);
    });
});

In script 1, we set up an event handler function on document to listen for the namespaced event ‘dialog.updateMessage’. This takes the event object, e, and an additional parameter, message, which it uses to update the text of dialog. In script 2, we set up an event handler on <select> elements so that whenever the change event is raised, the ‘dialog.updateMessage’ event is triggered, passing in a string that includes the new values as the first item in an array of additional data arguments. The end result? See for yourselves (hit the play icon on the right of the jsfiddle window):

Behaviourally, we can see no difference at all. From a development and maintenance point of view however we have kept our scripts loosely coupled and avoided any runtime errors that may occur from refactoring our code. We’ve also made it easier to extend our code and bind additional handler functions to events, something that can be particularly useful for implementing multiple callbacks. Granted, we can still make changes to the code that could cause things to cease functioning as expected, such as renaming the custom event in one location and not in others, but such a change will not throw an error as in the previous example, potentially halting execution of any JavaScript code that follows.

Implement Recaptcha properly in ASP.NET MVC

Sun, 30 Oct 2011 13:18:20 GMT

Love them or hate them, the humble CAPTCHA is a tried and trusted approach to mitigating spam content from infiltrating your beautifully crafted application and flooding it with adverts selling all kinds of nefarious goods. Whilst their effectiveness is debatable and the frustration that they bring about in some high, they are relatively simple to use and catch the bulk of user defined content one would want to filter from their site.

Recaptcha to the rescue

Recaptcha is pretty much the de-facto CAPTCHA implementation and using it helps in digitizing books too! A Nuget package is available that provides the ability to render a CAPTCHA and validate it. It's as simple to use as

@Html.GenerateCaptcha("id", "white")

where “id” is the id of the control to generate and “white” is the theme colour to use. This will render code in the response that results in the following displayed in the browser:

If this is rendered inside of a <form> element, two additional values are posted back to the server; a value keyed against the name “recaptcha_challenge_field” which is an identifier for the CAPTCHA served to the user and a value keyed against the name "recaptcha_response_field" which holds the value that the user entered. These values can be used to validate the user response and are nicely wrapped up for us in an ActionFilterAttribute:

public class CaptchaValidatorAttribute : ActionFilterAttribute
{
    private const string CHALLENGE_FIELD_KEY = "recaptcha_challenge_field";
    private const string RESPONSE_FIELD_KEY = "recaptcha_response_field";
    private RecaptchaResponse recaptchaResponse;

    public override void OnActionExecuting(ActionExecutingContext filterContext)
    {
        RecaptchaValidator recaptchaValidator = new RecaptchaValidator();
        recaptchaValidator.PrivateKey = RecaptchaControlMvc.PrivateKey;
        recaptchaValidator.RemoteIP = filterContext.HttpContext.Request.UserHostAddress;
        recaptchaValidator.Challenge = filterContext.HttpContext.Request.Form["recaptcha_challenge_field"];
        recaptchaValidator.Response = filterContext.HttpContext.Request.Form["recaptcha_response_field"];
        this.recaptchaResponse = !string.IsNullOrEmpty(recaptchaValidator.Challenge) ? (!string.IsNullOrEmpty(recaptchaValidator.Response) ? recaptchaValidator.Validate() : RecaptchaResponse.InvalidResponse) : RecaptchaResponse.InvalidChallenge;
        filterContext.ActionParameters["captchaValid"] = (object)(bool)(this.recaptchaResponse.IsValid ? 1 : 0);
        filterContext.ActionParameters["captchaErrorMessage"] = (object)this.recaptchaResponse.ErrorMessage;
        base.OnActionExecuting(filterContext);
    }
}

We can see that we are given the response and an error message (if the response indicates that what the user entered is invalid or some other error, such as invalid keys) as Action parameters. We can supply two parameters with names matching “captchaValid” and “captchaErrorMessage” to our controller action to capture these values

public class DemoContoller : Controller
{
    [CaptchaValidator]
    public ActionResult Index(PostedModel model, bool captchaValid, string captchaErrorMessage)
    {
        if (!captchaValid)
        {
            // do something to indicate that the user entered the wrong reponse for the CAPTCHA
        }
    }
}

pretty neat and not a lot of effort on our part.

So what’s wrong?

The main problem with the ReCaptcha component as provided is that it will only render a CAPTCHA in response to a full HTTP request i.e. it won’t render a CAPTCHA in the response to a request made with AJAX. If you look deep down in the code the ReCaptcha HtmlHelper extension method generates, it renders a <script> element that makes a request and returns a block of JavaScript used to render the CAPTCHA and provide various settings. The script response looks like so

var RecaptchaState = {
site : '****************************************',
challenge : '03AHJ_VuuAojIMHVd4xlTwTqaPxlDDTHu7dI-GNpOnNMsn9-6QUCtPnDs00KcEUmllKVC8aTM8QnVqczDLB3MxR7QdJSB7GZ45C1vWUz8K9RUczrww4FzAAkpZ8BjbJeKG_-UDusddk-gkJL1NG-b9RurjTDKXmXmtaw',
is_incorrect : false,
programming_error : '',
error_message : '',
server : 'http://www.google.com/recaptcha/api/',
timeout : 18000
};

document.write('<scr'+'ipt type="text/javascript" s'+'rc="' + RecaptchaState.server + 'js/recaptcha.js"></scr'+'ipt>');

See the problem? No, it’s not the site id that has been masked, it’s that document.write() call made to write another <script> element into the document. I would highly recommend avoiding document.write() as it can produce different outcomes depending on when it is called. But don’t take my word for it, here’s what Doug Crockford has to say about it:

The document.write method provides a way of incorporating strings into the HTML content of the page. There are better ways to do that, such as .innerHTML and .createElement or HTML cloning patterns. Use of document.write should be avoided.

document.write is recklessly dependent on timing. If document.write is called before the onload event, it appends or inserts text into the page. If it is called after onload, it completely replaces the page, destroying what came before.

document.write encourages bad structure, in which script and markup are intermingled. A cleaner structure has minimal interaction between markup and script.

In this case, the document.write() does not cause the script to be written into the page, whose contents contain the markup to render the CAPTCHA*.

ReCaptcha, Refined

Here is an improved implementation of the ReCaptcha component that will work no matter how the request has been made:

public static class HtmlHelperExtensions
{
    /// <summary>
    /// Renders a ReCaptcha to validate that the user is human
    /// </summary>
    /// <param name="helper">The helper.</param>
    /// <param name="id">The id.</param>
    /// <returns>an <see cref="IHtmlString"/> containing the recaptcha</returns>
    public static IHtmlString Captcha(this HtmlHelper helper, string id)
    {
        return Captcha(helper, id, "white");
    }

    /// <summary>
    /// Renders a ReCaptcha to validate that the user is human
    /// </summary>
    /// <param name="helper">The helper.</param>
    /// <param name="id">The id.</param>
    /// <param name="theme">The theme.</param>
    /// <returns>an <see cref="IHtmlString"/> containing the recaptcha</returns>
    public static IHtmlString Captcha(this HtmlHelper helper, string id, string theme)
    {
        string captcha;

        // we can't use the standard Captcha if injecting via an AJAX request so 
        // we need to use the AJAX one instead
        if (helper.ViewContext.HttpContext.Request.IsAjaxRequest())
        {
            var builder = new StringBuilder();
            builder.AppendLine("<div id=\"" + id + "\"></div>");
            builder.AppendLine("<script type=\"text/javascript\" src=\"http://www.google.com/recaptcha/api/js/recaptcha_ajax.js\"></script>");
            builder.AppendLine("<script type=\"text/javascript\">");        
            builder.AppendLine("(function() { ");
            builder.AppendLine("var recaptcha_load = setInterval(function() { ");
            builder.AppendLine("if (Recaptcha != undefined) {"); 
            builder.AppendLine("clearInterval(recaptcha_load); Recaptcha.create('" + RecaptchaControlMvc.PublicKey + "', '" + id + "', {");
            builder.AppendLine("theme: '" + theme + "',");
            builder.AppendLine("callback: Recaptcha.focus_response_field");
            builder.AppendLine("}); } }, 10); })();");
            builder.AppendLine("</script>");

            captcha = builder.ToString();
        }
        else
        {
            captcha = helper.GenerateCaptcha(id, theme);
        }
        
        return new HtmlString(captcha);
    }
}

If the request has been made with AJAX, the response returns a <div> element with an id matching the one supplied and two <script> elements; the first <script> element will get JavaScript code that can be used to create a CAPTCHA on the client side, the second <script> element renders code that waits until the first script has been executed (using the global setInterval function) and then creates a CAPTCHA on the client side in the defined <div> element. If the request hasn’t been made with AJAX, the ReCaptcha’s GenerateCaptcha method is called as before. The end result is that a CAPTCHA is rendered no matter how a request is made.

Cleaning up Validation

I’m not too keen on having to specify two additional parameters for an action method that is going to be called including ReCaptcha data. I’d prefer to use ModelState as is used for model property binding and validation, so here is an ActionFilter attribute that allows us to use that:

public sealed class ValidateCaptchaAttribute : ActionFilterAttribute
{
    private const string CHALLENGE_FIELD_KEY = "recaptcha_challenge_field";
    private const string RESPONSE_FIELD_KEY = "recaptcha_response_field";

    public override void OnActionExecuting(ActionExecutingContext filterContext)  
    {  
        var captchaChallengeValue = filterContext.HttpContext.Request.Form[CHALLENGE_FIELD_KEY];  
        var captchaResponseValue = filterContext.HttpContext.Request.Form[RESPONSE_FIELD_KEY];  
        var captchaValidator = new RecaptchaValidator  
                                  {
                                      PrivateKey = RecaptchaControlMvc.PrivateKey,  
                                      RemoteIP = filterContext.HttpContext.Request.UserHostAddress,  
                                      Challenge = captchaChallengeValue,  
                                      Response = captchaResponseValue  
                                  };  
  
        var recaptchaResponse = captchaValidator.Validate();  
  
        if (!recaptchaResponse.IsValid)
        {
            filterContext.Controller.ViewData.ModelState.AddModelError("recaptcha", ValidationResources.InvalidRecaptcha);
        }
  
        base.OnActionExecuting(filterContext);  
    }
}

Now we just need to assess whether ModelState is valid in our controller action:

public class DemoContoller : Controller
{
    [ValidateCaptcha]
    public ActionResult Index(PostedModel model)
    {
        if (!ModelState.IsValid)
        {
            // send the user back to the view
           return View(model);
        }
    }
}

We could optionally render a validation message next to the ReCaptcha too using the model key “recaptcha”

@Html.ValidationMessage("recaptcha")
@Html.Captcha("recaptcha")

Hope this helps!

* My testing has been with jQuery to make an AJAX request to return html that contains the markup rendered by the Captcha HtmlHelper. Looking through jQuery 1.6.1 source code, I can see nothing special in there that would cause document.write() to be sanitized in any way, so can only assume that the browser is simply ignoring it as a request is neither being made nor is the document replaced. If you know anything more, please leave a comment!

ASP.NET MVC Permanent 301 redirects for legacy routes

Sun, 30 Oct 2011 13:17:51 GMT

Having a good url routing scheme is extremely important when developing an application. Urls should be canonical to aid in search engine optimization and discoverable in order to aid users in learning where to find application functionality for particular tasks. But there are points in an applications lifecycle where one wishes to change the url routing scheme in order to employ a better one. In such instances, URL redirection can be used to preserve search engine rankings, user bookmarks to specific pages or to allow more than one URL to serve up the same content, as is the case when employing URL shortening.

ASP.NET MVC has the RedirectResult to perform a 302 temporarily moved redirection response from one URL to another, but it does not have any built in way to handle permanent "301 moved permanently" redirections. This is the topic of today's post.

Dude, Where's my Content?

Using an ActionResult to perform redirections works great for the Post-Redirect-Get pattern in conjunction with 302 temporary redirections, but doesn't fit particularly well for 301 permanent redirections. In the latter case, it would be better if we could let our routing handle this for us and not require a controller action in conjunction with a route as exists in the former case. For permanent redirections then, let's define a LegacyRoute:

/// <summary>
/// Represents a legacy route to a resource 
/// that has been superceded by a new route
/// </summary>
public class LegacyRoute : Route
{
    /// <summary>
    /// Initializes a new instance of the <see cref="LegacyRoute"/> class.
    /// </summary>
    /// <param name="url">The URL.</param>
    /// <param name="routeHandler">The route handler.</param>
    public LegacyRoute(string url, IRouteHandler routeHandler)
        : base(url, routeHandler)
    {
    }

    /// <summary>
    /// Initializes a new instance of the <see cref="LegacyRoute"/> class.
    /// </summary>
    /// <param name="url">The URL.</param>
    /// <param name="defaults">The defaults.</param>
    /// <param name="routeHandler">The route handler.</param>
    public LegacyRoute(string url, RouteValueDictionary defaults, IRouteHandler routeHandler)
        : base(url, defaults, routeHandler)
    {
    }

    /// <summary>
    /// Initializes a new instance of the <see cref="LegacyRoute"/> class.
    /// </summary>
    /// <param name="url">The URL.</param>
    /// <param name="defaults">The defaults.</param>
    /// <param name="constraints">The constraints.</param>
    /// <param name="routeHandler">The route handler.</param>
    public LegacyRoute(string url, RouteValueDictionary defaults, RouteValueDictionary constraints, IRouteHandler routeHandler)
        : base(url, defaults, constraints, routeHandler)
    {
    }

    /// <summary>
    /// Initializes a new instance of the <see cref="LegacyRoute"/> class.
    /// </summary>
    /// <param name="url">The URL pattern for the route.</param>
    /// <param name="defaults">The values to use if the URL does not contain all the parameters.</param>
    /// <param name="constraints">A regular expression that specifies valid values for a URL parameter.</param>
    /// <param name="dataTokens">Custom values that are passed to the route handler, but which are not used to determine whether the route matches a specific URL pattern. These values are passed to the route handler, where they can be used for processing the request.</param>
    /// <param name="routeHandler">The object that processes requests for the route.</param>
    public LegacyRoute(string url, RouteValueDictionary defaults, RouteValueDictionary constraints, RouteValueDictionary dataTokens, IRouteHandler routeHandler)
        : base(url, defaults, constraints, dataTokens, routeHandler)
    {
    }

    /// <summary>
    /// Returns information about the URL that is associated with the route.
    /// </summary>
    /// <param name="requestContext">An object that encapsulates information about the requested route.</param>
    /// <param name="values">An object that contains the parameters for a route.</param>
    /// <returns>
    /// An object that contains information about the URL that is associated with the route.
    /// </returns>
    public override VirtualPathData GetVirtualPath(RequestContext requestContext, RouteValueDictionary values)
    {
        // legacy routes NEVER generate outbound URLs
        return null;
    }
}

We inherit from Route and override GetVirtualPath, a method called when generating outbound URLs. Since we don't ever want legacy routes to take part in outbound URL generation, we simply return null. The plan is to register the legacy routes before other more generic routes, so we don't want legacy routes providing a match for a URL pattern over other routes.

Now that we have a route class to use, an IRouteHandler is also needed to process the request for a URL pattern matched by a legacy route. Enter LegacyRouteHandler:

/// <summary>
/// Handles legacy routes
/// </summary>
public class LegacyRouteHandler : IRouteHandler
{
    /// <summary>
    /// Gets or sets the route values.
    /// </summary>
    /// <value>The route values.</value>
    public RouteValueDictionary RouteValues { get; set; }

    /// <summary>
    /// Initializes a new instance of the <see cref="LegacyRouteHandler"/> class.
    /// </summary>
    /// <param name="routeValues">the route values</param>
    public LegacyRouteHandler(object routeValues)
    {
        RouteValues = new RouteValueDictionary(routeValues);
    }

    /// <summary>
    /// Provides the object that processes the request.
    /// </summary>
    /// <param name="requestContext">An object that encapsulates information about the request.</param>
    /// <returns>An object that processes the request.</returns>
    public IHttpHandler GetHttpHandler(RequestContext requestContext)
    {
        var urlHelper = new UrlHelper(requestContext);
        var url = urlHelper.Action(null, RouteValues);

        var absoluteUrl = requestContext.HttpContext.Request.Url.Scheme + "://" +
                          requestContext.HttpContext.Request.Url.Authority + url;

        return new RedirectHandler(absoluteUrl);
    }
}

When the LegacyRouteHandler is instantiated, it is passed route values in the constructor. These will be used when GetHttpHandler is called to construct the new URL that the old URL should be redirected to. An absolute URL (technically, URI) is constructed and passed to a RedirectHandler which will be used to set the Location HTTP Header on the response. Whilst most web browsers will support a relative URI, RFC 2616 mandates that the URI should be absolute. The RedirectHandler looks like so:

/// <summary>
/// Handles requests with a 301 Moved Permanently response
/// </summary>
public class RedirectHandler : IHttpHandler
{
    /// <summary>
    /// backing field for the redirect url
    /// </summary>
    private readonly string _redirectUrl;

    /// <summary>
    /// Initializes a new instance of the <see cref="RedirectHandler"/> class.
    /// </summary>
    /// <param name="redirectUrl">The redirect URL.</param>
    public RedirectHandler(string redirectUrl)
    {
        _redirectUrl = redirectUrl;
    }

    /// <summary>
    /// Gets a value indicating whether another request
    /// can use the <see cref="T:System.Web.IHttpHandler"/> instance.
    /// </summary>
    /// <value></value>
    /// <returns>returns false.</returns>
    public bool IsReusable
    {
        get { return false; }
    }

    /// <summary>
    /// Processes the request.
    /// </summary>
    /// <param name="httpContext">The HTTP context.</param>
    public void ProcessRequest(HttpContext httpContext)
    {
        httpContext.Response.Clear();
        httpContext.Response.Status = "301 Moved Permanently";
        httpContext.Response.StatusCode = 301;
        httpContext.Response.AppendHeader("Location", _redirectUrl);
        httpContext.Response.Flush();
        httpContext.Response.End();
    }
}

RedirectHandler implements IHttpHandler. When the ProcessRequest method is called by the framework, the handler uses the absolute URL passed to it in the constructor to set the Location HTTP header on the response and returns a 301 HTTP status code with accompanying status message.

With the classes defined above, one can start implementing redirections for legacy routes immediately using the following inside of RegisterRoutes(RouteCollection routes) in Global.asax.cs

routes.Add(new LegacyRoute("old-route", new LegacyRouteHandler(new { controller = "Home", action = "Index", area = "" })));

It's much cleaner to define some extension methods on RouteCollection for mapping legacy routes instead:

/// <summary>
/// Houses extension methods for <see cref="RouteCollection"/>
/// </summary>
public static class RouteCollectionExtensions
{
    /// <summary>
    /// Maps a legacy route.
    /// </summary>
    /// <param name="routes">The routes.</param>
    /// <param name="url">The old URL.</param>
    /// <param name="routeValues">The route values.</param>
    /// <returns></returns>
    public static Route MapLegacyRoute(this RouteCollection routes, string url, object routeValues)
    {
        return MapLegacyRoute(routes, null, url, routeValues);
    }


    /// <summary>
    /// Maps a legacy route.
    /// </summary>
    /// <param name="routes">The routes.</param>
    /// <param name="name">The name.</param>
    /// <param name="url">The old URL.</param>
    /// <param name="routeValues">The route values.</param>
    /// <returns>the <see cref="LegacyRoute"/> created</returns>
    public static Route MapLegacyRoute(this RouteCollection routes, string name, string url, object routeValues)
    {
        if (routes == null)
        {
            throw new ArgumentNullException("routes");
        }

        if (url == null)
        {
            throw new ArgumentNullException("url");
        }

        var route = new LegacyRoute(url, new LegacyRouteHandler(routeValues))
            {
                Defaults =  new RouteValueDictionary(routeValues),
                DataTokens = new RouteValueDictionary()             
            };

        routes.Add(name, route);

        return route;
    } 
}

Now our RegisterRoutes method looks like

public class MvcApplication : System.Web.HttpApplication
{
    public static void RegisterGlobalFilters(GlobalFilterCollection filters)
    {
        filters.Add(new HandleErrorAttribute());
    }

    public static void RegisterRoutes(RouteCollection routes)
    {
        routes.IgnoreRoute("{resource}.axd/{*pathInfo}");

        // map the legacy route above the more generic Default route
        routes.MapLegacyRoute(null, "old-route", new { controller = "Home", action = "Index", area="" });

        routes.MapRoute(
            "Default",
            "{controller}/{action}/{id}",
            new { controller = "Home", action = "Index", area="", id = UrlParameter.Optional }
        );

    }

    protected void Application_Start()
    {
        AreaRegistration.RegisterAllAreas();

        RegisterGlobalFilters(GlobalFilters.Filters);
        RegisterRoutes(RouteTable.Routes);
    }
}

The above will permanently redirect requests to /old-route to /Home/Index (well, in fact they would redirect to / as the HomeController and Index action are the default values of the Default route).

What about Areas?

We can see above that areas get registered before RegisterRoutes is called. This means that areas have the opportunity to register routes before the main application does. Since the order of routes in the application's RouteTable is important for route matching (a top to bottom operation that stops as soon as a match is found), we would want to register any legacy routes for URLs that may be matched by generic routes registered by areas before those generic routes. The following AreaRegistrationContext extension methods can be used for this purpose

/// <summary>
/// Houses extension methods for <see cref="AreaRegistrationContext"/>
/// </summary>
public static class AreaRegistrationContextExtensions
{
    /// <summary>
    /// Maps a legacy route.
    /// </summary>
    /// <param name="areaRegistrationContext">The area registration context.</param>
    /// <param name="url">The old URL.</param>
    /// <param name="routeValues">The route values.</param>
    /// <returns>the <see cref="LegacyRoute"/> created</returns>
    public static Route MapLegacyRoute(this AreaRegistrationContext areaRegistrationContext, string url, object routeValues)
    {
        return MapLegacyRoute(areaRegistrationContext, null, url, routeValues);
    } 

    /// <summary>
    /// Maps a legacy route.
    /// </summary>
    /// <param name="areaRegistrationContext">The area registration context.</param>
    /// <param name="name">The name.</param>
    /// <param name="url">The old URL.</param>
    /// <param name="routeValues">The route values.</param>
    /// <returns>the <see cref="LegacyRoute"/> created</returns>
    public static Route MapLegacyRoute(this AreaRegistrationContext areaRegistrationContext, string name, string url, object routeValues)
    {
        if (areaRegistrationContext == null)
        {
            throw new ArgumentNullException("areaRegistrationContext");
        }

        if (url == null)
        {
            throw new ArgumentNullException("url");
        }

        var route = areaRegistrationContext.Routes.MapLegacyRoute(name, url, routeValues);
        route.DataTokens["area"] = areaRegistrationContext.AreaName; 

        return route;
    } 
}

As an example, inside of our application's Account area, we would now have

public class AccountAreaRegistration : AreaRegistration
{
    public override string AreaName
    {
        get
        {
            return "Account";
        }
    }

    public override void RegisterArea(AreaRegistrationContext context)
    {
        context.MapLegacyRoute("Account/Home/old-route", new { controller = "Home", action = "Index", area = "" });

        context.MapRoute(
            "Account_default",
            "Account/{controller}/{action}/{id}",
            new { controller="Home" , action = "Index", id = UrlParameter.Optional }
        );
    }
}

The above will redirect the URL /Account/Home/old-route to /Home/Index (which, if using the routing in Global.asax.cs defined above would route to /).

If you're using T4MVC (which I highly recommend you do) then you can replace all of the magic string properties with the generated class properties inside of the anonymous objects passed as route values in MapLegacyRoute. One could go even further and define extension methods that take an ActionResult instead of a route values object, much like the way T4MVC overloads the common HtmlHelper methods.

ASP.NET MVC 3 IMetadataAware and custom ModelMetadata attributes

Sun, 30 Oct 2011 13:17:21 GMT

UPDATE: I've added a simple example project up on bitbucket to demonstrate the ColorPicker attribute

ASP.NET MVC 3 introduces a new interface, IMetadataAware, for providing additional values to the model metadata at creation time:

/* ****************************************************************************
 *
 * Copyright (c) Microsoft Corporation. All rights reserved.
 *
 * This software is subject to the Microsoft Public License (Ms-PL). 
 * A copy of the license can be found in the license.htm file included 
 * in this distribution.
 *
 * You must not remove this notice, or any other, from this software.
 *
 * ***************************************************************************/

namespace System.Web.Mvc {
    // This interface is implemented by attributes which wish to contribute to the
    // ModelMetadata creation process without needing to write a custom metadata
    // provider. It is consumed by AssociatedMetadataProvider, so this behavior is
    // automatically inherited by all classes which derive from it (notably, the
    // DataAnnotationsModelMetadataProvider).
    public interface IMetadataAware {
        void OnMetadataCreated(ModelMetadata metadata);
    }
}

The default ModelMetadataProvider, DataAnnotationsModelMetadataProvider, derives from AssociatedMetadataProvider, which, after creating the metadata for a type or type property, runs through all of the IMetadataAware types (i.e. attributes) applied to the type or property type, passing it the created metadata and allowing each IMetadataAware type to add additional values to the metadata. This is a nice change in MVC 3 as it means that you no longer need to write your own ModelMetadataProvider deriving from DataAnnotationsModelMetadataProvider to add in this functionality as you needed to in MVC 2.

The framework uses this new interface for two new model metadata attributes, AllowHtmlAttribute and AdditionalMetadataAttribute; AllowHtmlAttribute can be applied to a property to prevent that property from going through request validation, which can be very handy if you are receiving HTML or XML from the client and only want to white-list certain model/viewmodel properties to prevent request validation from being applied to them. AdditionalMetadataAttribute does pretty much what it's name implies; that is to allow you to add additional values to the modelmetadata's additional values dictionary.

Creating a custom ColourPicker ModelMetadataAttribute

We're going to look at creating our own jQuery ColourPicker ModelMetadata attribute using the IMetadataAware interface. This will allow us to attribute our model / viewmodel property and automagically hook up a jQuery colour picker to the text box in the rendered view. For this, I'll be using the awesome colorpicker plugin by Stefan Petre. Note that I will be using the american spelling of colour to align with the script :)

First off, the ColorPickerAttribute

[AttributeUsage(AttributeTargets.Property, AllowMultiple = false)]
public sealed class ColorPickerAttribute : Attribute, IMetadataAware
{
    private const string Template =
        "$('#{0}').ColorPicker({{onSubmit: function(hsb, hex, rgb, el) {{" + 
        "var self = $(el); self.val(hex);self.ColorPickerHide();}}, onBeforeShow: function () " + 
        "{{$(this).ColorPickerSetColor(this.value);}}}}).bind('keyup', function(){{ $(this).ColorPickerSetColor(this.value); }});";
        
    public const string ColorPicker = "_ColorPicker";

    private int _count;

    // if using IoC container, you could inject this into the attribute
    internal HttpContextBase Context
    {
        get { return new HttpContextWrapper(HttpContext.Current); }
    }

    public string Id
    {
        get { return "jquery-colorpicker-" + _count;  }
    }

    public void OnMetadataCreated(ModelMetadata metadata)
    {
        var list = Context.Items["Scripts"] as IList<string> ?? new List<string>();
        _count = list.Count;

        metadata.TemplateHint = ColorPicker;
        metadata.AdditionalValues[ColorPicker] = Id;

        list.Add(string.Format(CultureInfo.InvariantCulture, Template, Id));

        Context.Items["Scripts"] = list;
    }
}

Now let's say we have a simple controller:

public class HomeController : Controller
{
    public ActionResult Index()
    {
        return View(new HomeModel());
    }

}

and view model:

public class HomeModel
{
    [ColorPicker]
    public string ColorPicker { get; set; }
}

In order to get this all hooked up, we're going to use an EditorTemplate named _ColorPicker.cshtml:

@model System.String

@{ var picker = ViewData.GetModelAttribute<ColorPickerAttribute>(); 
   if (picker != null) {  
      @Html.LabelForModel()
      @Html.TextBoxFor(m => m, new { id = ViewData.ModelMetadata.AdditionalValues[ColorPickerAttribute.ColorPicker] }) 
   }
}

EditorTemplates should be put in a location where they will be accessible to the corresponding view engine. In this example, the _ColorPicker razor partial view is in Views/Shared/EditorTemplates. The template uses an extension method on ViewDataDictionary, GetModelAttribute to keep the view clean and allow us to get an attribute of a particular type back. The extension method is defined as so:

public static class ViewDataDictionaryExtensions
{
    public static TAttribute GetModelAttribute<TAttribute>(this ViewDataDictionary viewData, bool inherit = false) where TAttribute : Attribute
    {
        if (viewData == null) throw new ArgumentNullException("viewData");

        var containerType = viewData.ModelMetadata.ContainerType;

        return ((TAttribute[])containerType.GetProperty(viewData.ModelMetadata.PropertyName)
                                            .GetCustomAttributes(typeof (TAttribute), inherit)).FirstOrDefault();
    }
}

To make this extension method available in the view, we need to add the namespace to the system.web.webPages.razor section (if using the razor view engine, which I assume you would be with MVC 3!) in the web.config that can be found in the Views folder:

  
  <system.web.webPages.razor>
    <host factoryType="System.Web.Mvc.MvcWebRazorHostFactory, System.Web.Mvc, Version=3.0.0.0, Culture=neutral, PublicKeyToken=31BF3856AD364E35" />
    <pages pageBaseType="System.Web.Mvc.WebViewPage">
      <namespaces>
        <add namespace="Namespace.For.ViewDataDictionaryExtensions" />
      </namespaces>
    </pages>
  </system.web.webPages.razor>

And finally the view:

<h2>Index</h2>
@Html.EditorFor(m => m.ColorPicker)

And the _Layout that the view is using:

<!DOCTYPE html>
<html>
<head>
    <title>@ViewBag.Title</title>
    <link href="@Url.Content("~/Content/css/Site.css")" rel="stylesheet" type="text/css" />
    <link href="@Url.Content("~/Content/css/colorpicker.css")" rel="stylesheet" type="text/css" />
    <script src="@Url.Content("~/Scripts/jquery-1.4.4.min.js")" type="text/javascript"></script>
    <script src="@Url.Content("~/Scripts/colorpicker.js")" type="text/javascript"></script>
</head>
<body>
    @RenderBody()
    @Html.RenderScripts()
</body>
</html>

A HtmlHelper extension method runs after the body is rendered and this is responsible for writing out all of the scripts:

public static IHtmlString RenderScripts(this HtmlHelper htmlHelper)
{
    var scripts = htmlHelper.ViewContext.HttpContext.Items["Scripts"] as IList<string>;

    if (scripts != null)
    {
        var builder = new StringBuilder();

        builder.AppendLine("<script type='text/javascript'>");
        builder.AppendLine("$(function() {");
        foreach (var script in scripts)
        {
            builder.AppendLine(script);
        }
        builder.AppendLine("});");
        builder.AppendLine("</script>");

        return new MvcHtmlString(builder.ToString());
    }
    return null;
}

The end result and markup are as follows:

Putting the script into HttpContext.Items means that we can write the script out at the very end of the view before the closing body tag, which works for when scripts are put in both the head section of the document or before the closing body tag (so long as the call to RenderScripts comes after any required scripts, such as jQuery and the colorpicker script in this case). It also plays well when you have partial views that have markup requiring client side script and can be used for other plugins too, such as jQuery DatePicker.

Wrap child elements in groups in jQuery

Tue, 26 Jul 2011 22:33:09 GMT

A while ago, I answered a Stack Overflow question about how to wrap child elements matching some selector into groups of a specified size. I had a need for this again recently so I went back to the code, tidied it up and have come up with a slightly more refined plugin.

// Copyright (c) 2011 Russ Cam
// -------------------------------------------------------
// Dual licensed under the MIT and GPL licenses.
//   - http://www.opensource.org/licenses/mit-license
//   - http://www.opensource.org/licenses/gpl-3.0
(function($){
    $.fn.wrapChildren = function(options) {

        options = $.extend({
                              childElem : undefined,
                              groupSize : 1,
                              wrapper : '<div>'
                            }, options || {});
                            
        if (options.childElem === undefined) return this;

        return this.each(function() {
            var elems = $(this).children(),
                len = pos = 0;
            
            elems.each(function(i,value) {
                len += $(value).is(options.childElem)? 1 : 0;                    
                if (len > 0 && (len % options.groupSize === 0) || (i === elems.length - 1)) {          
                  elems.slice(pos,i + 1).wrapAll(options.wrapper);
                  len = 0;
                  pos = i + 1;
                }
            });
        }); 
        
    }
})(jQuery);

You call the plugin on a matched set and pass it a selector for the child element you wish to group along with a number for how many of the matching child elements should be in a group and a string representing the element in which you wish to group them. Child elements that do not match the passed child element selector will be ignored and will be placed into a group that matches their contiguous position within the child elements.

Take a look at an example up on js fiddle, or copy/paste the code below into a file and run locally. Hope this helps :)

<!DOCTYPE html>
<html lang="en">
<head>
<script src="http://ajax.googleapis.com/ajax/libs/jquery/1.5/jquery.min.js"></script>
<title>wrapChildren Demo</title>
<meta http-equiv="Content-type" content="text/html; charset=utf-8" />
<style type="text/css" media="screen">
	.wrapper { background-color: red; margin: 5px; }
</style>
<script type="text/javascript">
(function($){
    $.fn.wrapChildren = function(options) {

        options = $.extend({
                              childElem : undefined,
                              groupSize : 1,
                              wrapper : '<div>'
                            }, options || {});
                            
        if (options.childElem === undefined) return this;

        return this.each(function() {
            var elems = $(this).children(),
                len = pos = 0;
            
            elems.each(function(i,value) {
                len += $(value).is(options.childElem)? 1 : 0;                    
                if (len > 0 && (len % options.groupSize === 0) || (i === elems.length - 1)) {          
                  elems.slice(pos,i + 1).wrapAll(options.wrapper);
                  len = 0;
                  pos = i + 1;
                }
            });
        }); 
        
    }
})(jQuery);
$(function() {
  $('div').wrapChildren({ childElem : 'a' , groupSize: 4, wrapper : '<div class="wrapper">'});
});
</script>
</head>
<body>
	<p>anchors wrapped in groups of 4 including non-matching child elements</p>
	<div>
		<a href="#">1</a>
		<a href="#">2</a>
		<p>Child element that will be ignored</p>
		<a href="#">3</a>
		<a href="#">4</a>
		<p>Another that will be ignored</p>
		<a href="#">5</a>
		<a href="#">6</a>
		<a href="#">7</a>
		<p>Yet another that will be ignored</p>
		<a href="#">8</a>
		<p>And another</p>
		<a href="#">9</a>
		<a href="#">10</a>
	</div>
	<br/>
	<p>anchors wrapped in groups of 4</p>
	<div>
		 <a href="#">1</a>
		 <a href="#">2</a>
		 <a href="#">3</a>
		 <a href="#">4</a>
		 <a href="#">5</a>
		 <a href="#">6</a>
		 <a href="#">7</a>
		 <a href="#">8</a>
		 <a href="#">9</a>
		 <a href="#">10</a>
	 </div>
</body>
</html>

This Developer's Life

Tue, 26 Jul 2011 22:33:09 GMT

I'm probably a little late to the party on this one, but I have just started listening to This Developer's Life, a podcast presented by Rob Conery and Scott Hanselman. Each episode focuses on a particular topic in the realm of development and technology in general and involves interviews and stories from some of the most well known faces in the industry. There are some genuine legends, both past and more recent, shooting the breeze for our listening pleasure. These stories are interspersed with some great choices of music and short stories from the two presenters. I think there's something in there for everyone interested in technology and, like me, you'll probably find yourself relating to more than one of the topics brought up.

In all, it makes for a slightly lighter and refreshing change to other technology-focused podcasts out there. Go listen now, if you haven't already! I highly recommend starting with the first episode that contains some of the funniest and also darkest stories so far.

Event Internals in jQuery - Part One

Tue, 26 Jul 2011 22:33:09 GMT

I’ve been using jQuery for a number of years now and think it’s an awesome JavaScript library for providing a rich client experience to web applications with little effort. Whilst I advocate the use of jQuery to quickly and effectively build your client side solutions, I also think that it’s important to understand what’s going on under the hood, particularly as it can help to quickly pinpoint a bug in your own code (and on the rarest of occasions, a bug in the library code).

In a series of posts, I’m going to be peeking under the covers of the jQuery event system. I’ve never seen a comprehensive write-up looking into the internals of the event system before, so I thought that this might be a good topic to cover. This first post will provide a little background to browser based events and will look at the root event binding function in jQuery, bind().

Why have an event system?

You may be wondering, why does jQuery even need an event system at all? After all, modern browsers have the ability to bind event handlers to events raised in the DOM, don’t they? Whilst this is true, the event model that each of the myriad of browsers uses to achieve this can be very different indeed. The two main event models are so different in fact that, if you’re doing any cross browser client side JavaScript programming, you end up writing an abstraction yourself to smooth out these browser differences. The way that jQuery achieves this is really quite elegant, but first a brief history lesson.

DOM Level 0 events

In the beginning, browsers had basic support for DOM events in the W3C DOM level 0 events (part of the DOM level 1 specification). With this event model, event handlers can be bound in two ways:

Inline

<a href=”#” onclick=”alert(‘hello world!’);return false;”>
    Clicking me will show an alert dialog box with the message ‘hello world!’
</a>

With event handlers inline, the browser creates an anonymous function with the function body set to the contents of the string assigned to an element’s event attribute value. Ultimately this results in a call to window.eval() to evaluate the string and execute as JavaScript.

Setting the Attribute value

<a id=”my-anchor” href=”#”> Clicking me will show an alert dialog box with the message ‘hello world!’</a>
<script type=”text/javascript”>
    var a = document.getElementById(‘my-anchor’);
    a.onclick = function() { alert(‘hello world!’); return false; };
</script>

With an event attribute on the element set, the anonymous function needs to be bound to the element once it exists in the DOM.

The DOM level 0 events are still the most widely supported across browsers, however, they lack the ability to bind more than one event handler to an event without jumping through hoops (defining an event handler function that calls all of the event handler functions you want to bind to the event) and binding events inline does little to promote Unobtrusive JavaScript, which strives for separation of content and behaviour.

DOM level 2 events (and Internet Explorer’s proprietary event model)

With the limitations of DOM level 0 events in mind, modern versions of Mozilla, Opera, Safari, Chrome and Konqueror browsers use the standard W3C DOM level 2 events for binding handlers to events raised in the DOM. Internet Explorer on the other hand, uses a proprietary event model with some fundamental differences which we’ll touch on briefly in a moment (side note: Internet Explorer 9 is expected to support the W3C DOM level 3 events draft specification – this would be very good news indeed).

addEventListener and removeEventListener

With the DOM level 2 events, there are two functions for binding and unbinding event handlers to events, addEventListener and removeEventListener, respectively

<a id=”my-anchor” href=”#”> Clicking me will show an alert dialog box with the message ‘hello world!’</a>
<script type=”text/javascript”>
    var a = document.getElementById(‘my-anchor’);
    function handler(e) { /* do something */  }

    // to bind<
    a.addEventListener(‘click’, handler , false);

    //to unbind
    a.removeEventListener(‘click’, handler, false);
</script>

I won’t go into a whole load of detail around these as the Mozilla Developer Reference and W3C specifications are both comprehensive. Of particular note however is that the signature for binding an event handler takes a string argument for the event name, an event handler function to execute when the event is raised and a Boolean flag to indicate whether the capture phase of the event should be used.

See that e parameter in the function that gets bound as the handler? In this event model, an event object containing properties related to the event raised is passed as the first argument to each bound event handler. This is often useful as depending on the event, it can contain useful properties that can be used to perform logic inside of the event handler. For example, a keypress event causes an event object to be passed to an event handler that contains a charCode property which can be used to determine the key that was pressed.

attachEvent and detachEvent

Similarly to the w3c event model, the Internet Explorer model also has two functions for binding and unbinding event handlers to events, attachEvent and detachEvent, respectively

<a id=”my-anchor” href=”#”> Clicking me will show an alert dialog box with the message ‘hello world!’</a>
<script type=”text/javascript”>
    var a = document.getElementById(‘my-anchor’);
    function handler(e) { /* do something */ }

    // to bind
    a.attachEvent(‘onclick’, handler );

    //to unbind
    a.detachEvent(‘onclick’, handler);
</script>

The first major difference is that the function names used to perform the binding and unbinding are different in IE’s model to that used in the DOM level 2 events model. Secondly, the string name of the DOM event to which to attach the handler includes the prefix ‘on’. Thirdly, this model does not support using the capture phase of an event to execute a handler function, only the bubbling phase. Peter-Paul Koch (ppk) has a great write-up over at quirksmode on event order.

What is this inside the handler function?

One of the biggest differences between the W3C and IE models is what the this keyword (the function context) refers to inside the event handler function; in the W3C model, this is a reference to the element on which the event handler is bound but in IE, this refers to the global object (the window object in browsers). This can really trip you up (pun intended) if you're not paying attention!

Event object

Equally as important as this, event handler functions do not receive an event object as the first argument (the argument for the e parameter will always be undefined) in IE's model; in IE, the event object is populated on a property named event on the global object. Some of the properties that exist on this event object are different to the ones that exist on the W3C event object, that is, different property names may be used that have a value that purports to the same piece of event data in each case. As an example, the W3C event object contains a property, target, that contains a reference to the element that the event was originally raised on. This same piece of data on IE’s event object is assigned to a property named srcElement. Other properties may purport to the same piece of event data across event models but be calculated differently in different browsers and some event data is implemented in some event models but not others! Enter jQuery.

jQuery's Event Model

jQuery has done the hard work in abstracting away as many browser differences as possible. There are a number of objects and utility functions involved in the model, starting with .bind()

jQuery.fn.bind() and friends

When you call .bind() (or one of the specific event handler functions such as .click(), .change(), .keypress(), etc. which internally will call .bind() generally), the event handler function that is passed in, along with each element in the matched set of the jQuery object on which bind is called and any additional data that may also be passed in to bind (and available inside of the handler function) are all used in a call to a utility function, jQuery.event.add.

the bind function looks like the following:

jQuery.each(["bind", "one"], function( i, name ) {
    jQuery.fn[ name ] = function( type, data, fn ) {
        // Handle object literals
        if ( typeof type === "object" ) {
            for ( var key in type ) {
                this[ name ](key, data, type[key], fn);
            }
            return this;
        }

        if ( jQuery.isFunction( data ) || data === false ) {
            fn = data;
            data = undefined;
        }

        var handler = name === "one" ? jQuery.proxy( fn, function( event ) {
            jQuery( this ).unbind( event, handler );
            return fn.apply( this, arguments );
        }) : fn;

        if ( type === "unload" && name !== "one" ) {
            this.one( type, data, fn );

        } else {
            for ( var i = 0, l = this.length; i < l; i++ ) {
                jQuery.event.add( this[i], type, handler, data );
            }
        }

        return this;
    };
});

We can see here that an array of strings is iterated over using the $.each() function. There's a quick check to see if we've been handed an object literal as the first argument and if so, to go through all of the properties of that object and bind the property value in each case to the event identified by the property name.

Both bind() and one() are declared as properties on jQuery.fn; this is an alias for the jQuery.prototype object, although in very early versions of the library, this was not the case. Mike Koss has a great introduction to the prototype object in JavaScript in discussing Object Oriented Programming in JavaScript if you're interested in more detail.

Next, there's a check to see if we've been passed an object as an argument for the data parameter; if data is a function or false, then data is assigned to fn and it is assumed that this is the event handler function that is to be bound to the event.

Now comes an interesting part. Since the source code deals with setting up both bind and one functions, if the one function is being set up, the $.proxy() is used so that the event handler function can be executed when the event to which it is being registered is raised and then can be unbound, using the context of an anonymous function that is also passed to the $.proxy function. $.proxy() returns a function, which in this case is fn with the context of this (which is the element on which the event handler function is being bound) and is passed the arguments of the anonymous function in which it is scoped. This returned function is assigned to the variable handler. In the case of bind, the fn function is simply assigned to handler.

Following on, if the event is unload and hasn't been bound with one(), then one() is used to register the event handler so that the function is removed from the internal cache after execution (more on the internal $.cache in the next part).

Finally, all of the matched elements in the jQuery object are iterated over and a call to the internal jQuery.event.add function is made to actually perform the subscription of the handler to the event.

In the next part we'll look at jQuery.event and its functions that underpin the jQuery Event Model.

Event Internals in jQuery - Part Two

Tue, 26 Jul 2011 22:33:09 GMT

Part one of jQuery Event internals looked at the DOM Event specifications, the history of the Document Object Model (DOM) event models and reasoning behind why jQuery has an event system. In the second part of this series, we'll be looking at the jQuery.event object and jQuery.Event constructor function, both of which play a pivotal role in managing events. Previously, we looked at the bind() method (and the related specific event handler binding methods such as click(), keyup(), etc) and saw that bind() eventually calls jQuery.event.add, so let's start by looking at that.

jQuery.event.add

It helps to have the source to hand when discussing the internals, so here is the source for jQuery.event.add from jQuery 1.6.1:

/*!
 * jQuery JavaScript Library v1.6.1
 * http://jquery.com/
 *
 * Copyright 2011, John Resig
 * Dual licensed under the MIT or GPL Version 2 licenses.
 * http://jquery.org/license
 *
 * Includes Sizzle.js
 * http://sizzlejs.com/
 * Copyright 2011, The Dojo Foundation
 * Released under the MIT, BSD, and GPL Licenses.
 *
 * Date: Thu May 12 15:04:36 2011 -0400
 */

// ... other code omitted, starting at line 2511 of source 
 
jQuery.event = {

	add: function( elem, types, handler, data ) {
		if ( elem.nodeType === 3 || elem.nodeType === 8 ) {
			return;
		}

		if ( handler === false ) {
			handler = returnFalse;
		} else if ( !handler ) {
			return;
		}

		var handleObjIn, handleObj;

		if ( handler.handler ) {
			handleObjIn = handler;
			handler = handleObjIn.handler;
		}

		if ( !handler.guid ) {
			handler.guid = jQuery.guid++;
		}

		var elemData = jQuery._data( elem );

		if ( !elemData ) {
			return;
		}

		var events = elemData.events,
			eventHandle = elemData.handle;

		if ( !events ) {
			elemData.events = events = {};
		}

		if ( !eventHandle ) {
			elemData.handle = eventHandle = function( e ) {
				return typeof jQuery !== "undefined" && (!e || jQuery.event.triggered !== e.type) ?
					jQuery.event.handle.apply( eventHandle.elem, arguments ) :
					undefined;
			};
		}

		eventHandle.elem = elem;

		types = types.split(" ");

		var type, i = 0, namespaces;

		while ( (type = types[ i++ ]) ) {
			handleObj = handleObjIn ?
				jQuery.extend({}, handleObjIn) :
				{ handler: handler, data: data };

			if ( type.indexOf(".") > -1 ) {
				namespaces = type.split(".");
				type = namespaces.shift();
				handleObj.namespace = namespaces.slice(0).sort().join(".");

			} else {
				namespaces = [];
				handleObj.namespace = "";
			}

			handleObj.type = type;
			if ( !handleObj.guid ) {
				handleObj.guid = handler.guid;
			}

			var handlers = events[ type ],
				special = jQuery.event.special[ type ] || {};

			if ( !handlers ) {
				handlers = events[ type ] = [];

				if ( !special.setup || special.setup.call( elem, data, namespaces, eventHandle ) === false ) {
					if ( elem.addEventListener ) {
						elem.addEventListener( type, eventHandle, false );

					} else if ( elem.attachEvent ) {
						elem.attachEvent( "on" + type, eventHandle );
					}
				}
			}

			if ( special.add ) {
				special.add.call( elem, handleObj );

				if ( !handleObj.handler.guid ) {
					handleObj.handler.guid = handler.guid;
				}
			}

			handlers.push( handleObj );

			jQuery.event.global[ type ] = true;
		}

		elem = null;
	},
    
    // ...

The function kicks off with checking the nodeType of the element to which the event handler will be bound. If the element is a text node (nodeType 3) or a comment node (nodeType 8) then no handler will be bound and the function simply exits at this point. Then follows a check to detect if the element is the window object and to set it to window if true to prevent Internet Explorer from erroneously cloning it when passing it around. If false is passed in for the handler function then the handler is set to a function that returns false; if no handler is passed in, the add function simply returns. Essentially, there are a number of defensive steps here to avoid doing work unnecessaily and to handle various shorthands for setting up a handler function.

Next comes a check for handler.handler. The handler function is given a unique id using jQuery.guid, a number counter that is held in a closure and incremented on each call. jQuery._data(elem) is used to initialize the internal event structure for the element. Internally, this uses jQuery.data to initialize a cache for the element; if the element is a JavaScript object, then a cache object is initialized on the object itself using a property name that is constructed by the instance of the jQuery script that runs, using the jQuery.expando: property. That's defined as such

// line 1384 from the source
jQuery.extend({
	cache: {}, // this is the internal cache object

	uuid: 0,

        // this is essentially a unique id for the instance of jQuery
        // such that two instances of jQuery on the same page do not have the 
        // same expando
	expando: "jQuery" + ( jQuery.fn.jquery + Math.random() ).replace( /\D/g, "" ),

        //...

jQuery.expando serves the purpose of allowing more than once instance of the jQuery library to run on the page, by giving each instance of jQuery a key to use when adding properties to objects and element nodes.

In the event structure initialization, If the element for which we're setting up event handling is not a JavaScript object but a DOM node then values are assigned to properties on an object created inside of $.cache; the DOM node is given a unique id using jQuery.uuid, another number counter that is incremented on each call.

Once all of the event structure initialization has been done, jQuery._data returns the cache object for the element. If no object is returned, this indicates that the element in question is not one that can have events bound to it and so the code simply returns at this point. Here comes the interesting part. Two items are retrieved from the cache object (or created if they don't already exist), events and handle; events is an object with properties that match bound event types, with each property assigned an array of event handler functions to run in response to that event type being raised on the element in question. The structure of events is as follows

events = {
    click :     [{ handler : function (e) { /* click event handler 1 */ }, data : { item: 'item' } },
                 { handler : function (e) { /* click event handler 2 */ }, data : undefined }],
    keyup:      [{ handler : function (e) { /* keyup event handler 1 */ }, data : { additionalData: [1, 2, 3] } }],
    mouseover:  [{ handler : function (e) { /* mouseover event handler 1 */ }, data : undefined }],
    mouseout :  [{ handler : function (e) { /* mouseout event handler 1 */ }, data : undefined }]
};

handle is a function that, under normal circumstances (i.e. we're not dealing with special events or cross-browser workarounds for specific events), returns the result of applying the jQuery.event.handle function with the context set to the element on which the event is bound. This is what enables the this keyword to refer to the element on which the event is raised inside of the event handler function. We'll look at the jQuery.event.handle function shortly.

Once the events object is retrieved from the cache, the space separated event types string passed in the bind() function call is split and iterated over; in each iteration, a new object containing a handler property with a value set to the function passed into the bind() call and a data property set to the data passed into the bind() call is pushed onto an array set against the property name matching the event type on the events object from the cache. Namespaced events are handled by the addition of a namespace property on the object pushed onto the array. If this is the first event handler being bound for the element for the event type, then the handle function is registered with the browser as an event listener using element.addEventListener if supported, or element.attachEvent otherwise.

The important point to take away here is that only one function is registered as an event handler with the browser per element, per event type. If I were to guess as to why this is done it would be to

allow better control over the function context (what this refers to) inside event handler functions
allow patching/augmentation of the browser event object before passing to event handlers to normalize event properties across browsers.
keep track of how many event handler functions have been bound and allow for easier clean up when a new page is requested, to avoid browser memory leaks (here's looking mainly at you, IE).

Finally, a property matching the event type is set to true on the jQuery.event.global object. This is to allow global triggering of event handlers for specific event types.

With all of this in mind, one can inspect the events set up on an element using jQuery using

    
    var events = $('selector-for-element').data('events');
    // events now contains a reference to the events object held in the cache for “selector-for-element”, 
    // or undefined if there are no event handlers bound (via jQuery) for the element

This will return the event object referred to earlier, the one containing properties with names that match the event types to which event handler functions have been bound. If you’re a fan of Firefox, there is a add-on for Firebug called FireQuery that shows what is in the cache for each element in the HTML tab of Firebug. What’s nice about this is that the cache object links can be clicked, which will take you to the DOM tab and allow you to inspect the object further.

A word of caution here - This internal event structure is undocumented in the jQuery source documentation and hence makes it subject to change. So, be particularly careful if you intend to rely on internal event structure inspection in production code as this may break when upgrading to a newer version of the jQuery library.

Now we know how jQuery.event.add works, let's look at the function that performs the opposite operation.

jQuery.event.remove

Once you know how jQuery.event.add works, there's not really much to discuss with jQuery.event.remove; it is a function called by unbind() and does pretty much the reverse of jQuery.event.add, removing handlers in the cache for the element(s) on which unbind() is called. If there are no more handler functions in the cache for a particular event type for an element, then the event listener registered with the browser is removed via element.removeEventListener if supported, element.detachEvent otherwise.

jQuery.event = {

    //... starting at line 2640 in the source

    remove: function( elem, types, handler, pos ) {
        if ( elem.nodeType === 3 || elem.nodeType === 8 ) {
            return;
        }

        if ( handler === false ) {
            handler = returnFalse;
        }

        var ret, type, fn, j, i = 0, all, namespaces, namespace, special, eventType, handleObj, origType,
            elemData = jQuery.hasData( elem ) && jQuery._data( elem ),
            events = elemData && elemData.events;

        if ( !elemData || !events ) {
            return;
        }

        if ( types && types.type ) {
            handler = types.handler;
            types = types.type;
        }

        if ( !types || typeof types === "string" && types.charAt(0) === "." ) {
            types = types || "";

            for ( type in events ) {
                jQuery.event.remove( elem, type + types );
            }

            return;
        }

        types = types.split(" ");

        while ( (type = types[ i++ ]) ) {
            origType = type;
            handleObj = null;
            all = type.indexOf(".") < 0;
            namespaces = [];

            if ( !all ) {
                namespaces = type.split(".");
                type = namespaces.shift();

                namespace = new RegExp("(^|\\.)" +
                    jQuery.map( namespaces.slice(0).sort(), fcleanup ).join("\\.(?:.*\\.)?") + "(\\.|$)");
            }

            eventType = events[ type ];

            if ( !eventType ) {
                continue;
            }

            if ( !handler ) {
                for ( j = 0; j < eventType.length; j++ ) {
                    handleObj = eventType[ j ];

                    if ( all || namespace.test( handleObj.namespace ) ) {
                        jQuery.event.remove( elem, origType, handleObj.handler, j );
                        eventType.splice( j--, 1 );
                    }
                }

                continue;
            }

            special = jQuery.event.special[ type ] || {};

            for ( j = pos || 0; j < eventType.length; j++ ) {
                handleObj = eventType[ j ];

                if ( handler.guid === handleObj.guid ) {
                    if ( all || namespace.test( handleObj.namespace ) ) {
                        if ( pos == null ) {
                            eventType.splice( j--, 1 );
                        }

                        if ( special.remove ) {
                            special.remove.call( elem, handleObj );
                        }
                    }

                    if ( pos != null ) {
                        break;
                    }
                }
            }

            if ( eventType.length === 0 || pos != null && eventType.length === 1 ) {
                if ( !special.teardown || special.teardown.call( elem, namespaces ) === false ) {
                    jQuery.removeEvent( elem, type, elemData.handle );
                }

                ret = null;
                delete events[ type ];
            }
        }

        if ( jQuery.isEmptyObject( events ) ) {
            var handle = elemData.handle;
            if ( handle ) {
                handle.elem = null;
            }

            delete elemData.events;
            delete elemData.handle;

            if ( jQuery.isEmptyObject( elemData ) ) {
                jQuery.removeData( elem, undefined, true );
            }
        }
    }
}

There's not really much more to discuss here, so we'll move on.

jQuery.event.handle

As highlighted before, only one handler function is registered with the browser per element, per event type. The handler function in question is jQuery.event.handle and its responsibility is to execute each of the handler functions in the array assigned to the property name on the events object held in the cache for the element in question, whose name matches the name of the event raised.

    
jQuery.event = {    

    //... starting at line 2903 in the source

    handle: function( event ) {
        event = jQuery.event.fix( event || window.event );

        var handlers = ((jQuery._data( this, "events" ) || {})[ event.type ] || []).slice(0),
            run_all = !event.exclusive && !event.namespace,
            args = Array.prototype.slice.call( arguments, 0 );

        args[0] = event;
        event.currentTarget = this;

        for ( var j = 0, l = handlers.length; j < l; j++ ) {
            var handleObj = handlers[ j ];

            if ( run_all || event.namespace_re.test( handleObj.namespace ) ) {

                event.handler = handleObj.handler;
                event.data = handleObj.data;
                event.handleObj = handleObj;

                var ret = handleObj.handler.apply( this, args );

                if ( ret !== undefined ) {
                    event.result = ret;
                    if ( ret === false ) {
                        event.preventDefault();
                        event.stopPropagation();
                    }
                }

                if ( event.isImmediatePropagationStopped() ) {
                    break;
                }
            }
        }
        return event.result;
    },

    //...
}

This function simply goes through each handler function in the events object and executes each one in turn. First, the native browser event passed to jQuery.event.handle is passed into jQuery.event.fix to normalize the event properties across different browsers. A check is then performed to see if we're dealing with a namespaced event or an exclusive event (event handers that trigger only for the exact event i.e. no namespaces), and to use this information to filter the handle functions that will be executed accordingly. If a particular handler function returns a boolean result, then this is used to set the result on the event. A return value of false is shorthand for setting both event.preventDefault() and event.stopPropagation(), which are W3C event properties that are normalized to work the same across all browsers by the jQuery.event.fix method. We'll look at this function in the next part of the series.

Please leave a comment if this information has been useful :)