.NET classes provide only a limited amount of information about the data they contain. They specify the .NET types and names of a set of properties, but by default, that's all they say. They don't give user-friendly names for the properties, they don't say whether a property is only for the software's internal use or whether an end user would be interested in the value, and they don't declare which set of values would be considered valid.

To bridge this gap, ASP.NET MVC uses model metadata to let you provide extra information about the meaning of your models. Model metadata influences how templated view helpers produce displays and editors, and it influences how the framework validates incoming data.

Out of the box, ASP.NET MVC will detect and respond to metadata attributes from the standard .NET System.ComponentModel namespace. If these don't meet your needs, you can create custom metadata attributes, or you can make your own metadata provider by inheriting from the ModelMetadataProvider base class.

As a simple example, you could improve the UI shown in Figure 12-2 by applying metadata attributes to the Person class as follows:

public class Person
{
    [HiddenInput (DisplayValue = false)] // Don't want the user to see or edit this
    public int PersonId { get; set; }

    // [DisplayName] specifies user-friendly names for the properties
    [DisplayName("First name")] public string FirstName { get; set; }
    [DisplayName("Last name")] public string LastName { get; set; }

    [DataType(DataType.Date)] // Show only the date, ignoring any time data
    [DisplayName("Born")] public DateTime BirthDate { get; set; }

    public Address HomeAddress { get; set; }

    [DisplayName("May log in")] public bool IsApproved { get; set; }
}

With this metadata in place, the preceding view would render as shown in Figure 12-3. You'll learn about other standard metadata attributes shortly.

Figure 12-3. Example output from Html.EditorForModel() after applying metadata

Right now, if you were to look at the generated HTML, you'd find it references a useful set of CSS classes, so you could style it easily. Here's what the default object template renders for the FirstName model property (reformatted for readability):

<div class="editor-label">
    <label for="FirstName">First name</label>
</div>
<div class="editor-field">
    <input class="text-box single-line" id="FirstName"
           name="FirstName" type="text" value="Blaise" />
</div>

For example, you could use CSS to make the labels and the input controls appear on the same lines instead of having the labels appear above the input controls.

Instead of using Html.EditorForModel() to render an editor for an entire model object, it's also common to use Html.Editor() or Html.EditorFor() to place editors for individual properties at different locations in a view. This gives you much more control over the finished output, but still uses model metadata and templating conventions to influence the result.

For example, you could express the previous view as follows:

<% using(Html.BeginForm()) { %>
    <fieldset>
        <legend>Person</legend>

        <div class="field">
            <label>Name:</label>
            <%: Html.EditorFor(x => x.FirstName) %>
            <%: Html.EditorFor(x => x.LastName) %>
        </div>
        <div class="field">
            <label>Born:</label>
            <%: Html.EditorFor(x => x.BirthDate) %>
        </div>
        <div align="center"><%: Html.EditorFor(x => x.IsApproved) %>May log in</div>
        <fieldset>
            <legend>Home address</legend>
            <div class="addressEditor">
                <%: Html.EditorFor(x => x.HomeAddress) %>
            </div>
        </fieldset>
    </fieldset>

    <p><input type="submit" value="Save" /></p>
<% } %>

This would render as shown in Figure 12-4.

Figure 12-4. Using Html.EditorFor() to add editors to a view

This is now very similar to using simple HTML helpers such as Html.TextBoxFor() and Html.CheckBoxFor(), but with a few advantages:

If you prefer to generate the input control labels directly from model metadata, you can use Html.Label() or Html.LabelFor(). For example, you could render the text label for the IsApproved property as follows:

<%: Html.LabelFor(x => x.IsApproved) %>

This will render as follows:

<label for="IsApproved">May log in</label>

This time, the phrase "May log in" is taken from the [DisplayName("May log in")] metadata attribute instead of being specified in the view. If there was no such metadata, it would fall back on displaying the actual property name.

This isn't necessarily any better than writing the label text directly into a view. After all, views are the normal place in MVC architecture for UI details such as label text. The most likely reason to use Html.Label() or Html.LabelFor() is if you're using the same model class on multiple data entry views—you may want to define the label texts in one central place (i.e., in a [DisplayName] attribute on the model) so it's consistent across all the views.

When you use Html.EditorFor() or a similar helper, ASP.NET MVC needs to choose a suitable template to render. It does so by considering each of the following template names, in this order of priority:

For each of these possible template names, the framework will first try to find a template by asking your active view engine for a partial called EditorTemplates/templateName. If one is found, it gets invoked, and the process is complete. You learned in Chapter 9 how the view engine searches for views and partials in the folders /Areas/areaName/Views/controllerName, /Areas/areaName/Views/Shared, /Views/controllerName, and /Views/Shared. Note that these view lookups are cached within each HTTP request, so the scanning process is not as expensive as you might imagine.

If the view engine can't find any partial matching the requested name, the framework will consider using a built-in default editor template. Table 12-2 lists all of the built-in editor templates.

The Object template deserves special attention because it's a little more sophisticated. This is the ultimate fallback template, and is typically what's used during scaffolding, because you'll call Html.EditorFor(x => x.SomeComplexProperty) or Html.EditorForModel() without having defined an editor template for your property or model type.

The Object template iterates over each of your type's properties, rendering a label, an editor, and a validation message for each one (you'll learn more about validation later in this chapter). For each property, it produces HTML of the following form:

<div class="editor-label"><label for="propertyName">property label</label></div>
<div class="editor-field">propertyeditor template goes here</div>

So far, we've only considered the templated view helpers for editing data: Html.Editor(), Html.EditorFor(), and Html.EditorForModel(). Those are the most commonly used, but there are also read-only display equivalents: Html.Display(), Html.DisplayFor(), and Html.DisplayForModel(). The display helpers behave exactly like the editor helpers, except they use a different set of default templates, and they look for template partials in a different folder (they look for partials called DisplayTemplates/templateNameinstead of EditorTemplates/templateName).

The framework's built-in default display templates are listed in Table 12-3.

The built-in Object display template works almost exactly like the equivalent editor template, in that it iterates over simple properties and produces a display for each one. For each property, it generates HTML of the following form:

<div class="display-label">property label</div>
<div class="display-field">property value</div>

Again, it isn't recursive: it won't iterate over your properties if you call it from inside another template.

Continuing the previous example, an action method could render an instance of Person by invoking a strongly typed view inherited from System.Web.Mvc.ViewPage<Person>. If the view contained the following:

<h2>Examine this person</h2>
<%: Html.DisplayForModel() %>

then it would render each of the properties as shown in Figure 12-5.

Figure 12-5. Output from Html.DisplayForModel()

Clearly, this is not a very attractive user interface. You could improve it by applying CSS styles, or by calling Html.DisplayFor() for each property within a more well-structured page instead of calling Html.DisplayForModel(), just like we did with Html.EditorFor().

A further option is to create a custom template for the Person type. Let's move on and consider how to do that.

You're not limited to defining templates for your own custom model types; you can also define templates for standard .NET types or templates that overwrite the built-in defaults that you saw in Tables 12-3 and 12-4.

For example, you could create a standard editor template for DateTime properties by creating a partial at /Views/Shared/EditorTemplates/DateTime.ascx, containing the following:

<%@ Control Language="C#" Inherits="ViewUserControl<DateTime?>" %>
<%: Html.TextBox("",                                        /* Name suffix     */
                 ViewData.TemplateInfo.FormattedModelValue, /* Initial value   */
                 new { @class = "date-picker" }             /* HTML attributes */
    ) %>

Now that this partial exists, all DateTime and DateTime? property editors (everywhere in your application, except where overridden using an explicit template name or a [UIHint] attribute ) will be rendered as text boxes with the CSS class date-picker. We're passing an empty string for the name parameter because the framework will automatically prefix this with the field name corresponding to the model item being rendered; you only need to specify a nonempty value if your editor is for a child property (HTML field prefixes are covered in the next section).

The resulting HTML will be similar to the following:

<input class="date-picker" id="PropertyName" name="PropertyName"
type="text" value="PropertyValue" />

You could then associate all such elements with client-side date picker widgets using a client-side toolkit such as jQuery UI by putting the following script into a site-wide master page:

<script type="text/javascript">
    $(function() {
        $(".date-picker").datepicker(); // Turns matching elements into date pickers
    });
</script>

See jQuery UI's web site at http://jqueryui.com/ for more details about how to install and use it.

Since custom display or editor templates are usually implemented as strongly typed partial views, you can access the view's Model property to obtain the value of the current model item. But when you want to render that model item as a string, don't directly call Model.ToString(), as that would bypass any formatting metadata on the model. Instead, notice how the preceding sample code for DateTime.ascx represents the model item as a string using ViewData.TemplateInfo.FormattedModelValue—this respects formatting metadata, so this custom template behaves correctly when combined with [DataType(DataType.Date)] or the [DisplayFormat] attribute .

As a convenient simplification, ASP.NET MVC offers a specialized base class for display and editor templates. If you edit a partial view's Inherits directive so that the partial inherits from ViewTemplateUserControl<modelType>, then you'll have access to a new property, FormattedModelValue, which is shorthand for ViewData.TemplateInfo.FormattedModelValue.

For example, the preceding DateTime.ascx sample could be rewritten as follows:

<%@ Control Language="C#" Inherits="ViewTemplateUserControl<DateTime?>" %>
<%: Html.TextBox("",                             /* Name suffix     */
                 FormattedModelValue,            /* Initial value   */
                 new { @class = "date-picker" }  /* HTML attributes */
    ) %>

Sometimes you might want to pass more than just the model to your custom template; you might also want to pass some additional parameters that influence how it should render the model.

This is easy—all the template-rendering helper methods (Editor, EditorFor, EditorForModel, Display, DisplayFor, DisplayForModel) have overloads that let you pass a parameter called additionalViewData. If you pass an anonymously typed object for this parameter, the framework will extract your object's properties and use them to populate your custom template's ViewData dictionary.

For example, you might have a special date picker that handles time zones in some way. You could render a date editor as follows:

<%: Html.EditorFor(x => x.BirthDate, new { timezone = "PST" }) %>

and then your custom DateTime.ascx template would be able to receive the time zone parameter by reading it from ViewData["timezone"].

When editing data (as opposed to displaying a read-only view of it), there is a further benefit that comes with using templates rather than merely invoking partials directly. Templates introduce a notion of HTML field prefixes. When you render a hierarchy of templates nested inside other templates, the framework automatically builds up a string expression that uniquely describes your current location in the hierarchy. This provides two main benefits:

With ASP.NET MVC 1.0, you had to manage HTML field prefixes manually. With the new templating system, it happens automatically. As a basic example of this feature at work, refer back a few pages to Figure 12-4, which shows a Person editor that contains an Address editor. The text box labeled "City" was rendered as the following HTML:

<input class="text-box single-line" id="HomeAddress_City
       name="HomeAddress.City" type="text" value="Paris" />

As you can see, the framework has prefixed the element's name with HomeAddress. The same applies to its id, except that to satisfy the HTML 4.01 specification, it replaces characters other than letters, digits, dashes, underscores, and colons with HtmlHelper.IdAttributeDotReplacement, which equals underscore (_) unless you overwrite it.

When you're creating custom templates, you may want to follow these element name prefixing conventions. You can do that easily by using the properties and methods on ViewData.TemplateInfo, as listed in Table 12-4.

At the risk of duplicating information that you could find online on MSDN, Table 12-6 gives a complete list of the writable properties you can set on a ModelMetadata instance to influence the templating system. You can write to these properties either from a custom metadata provider, as shown in the previous example, or in many cases using built-in System.ComponentModel attributes, as described in the following table.

The reason I include this complete list is that, at the time of writing, MSDN does not provide such clear information about how each property affects ASP.NET MVC's behavior. As you will see, not all of these properties are actively used by ASP.NET MVC 2.

In the previous example, the default binder expected to populate the myperson parameter by asking the value provider for myperson.Name, myperson.Email, and myperson.DateOfBirth (which in turn requests data from the value providers listed in Table 12-7). As you can guess, the prefix myperson is determined by the name of the action method parameter.

If you wish, you can specify an alternative prefix using the [Bind] attribute —for example:

public ActionResult RegisterMember([Bind(Prefix = "newuser")]Person myperson)
{
    // ...
}

Now the value provider will be asked for newuser.Name, newuser.Email, and newuser.DateOfBirth. This facility is mainly useful if you don't want your HTML element names to be constrained by what's appropriate for C# method parameter names.

If you prefer, you can avoid using prefixes altogether. In other words, simplify your view markup by removing the myperson. prefix from each text box name, or if you're using a strongly typed view, use the strongly typed Html.TextBoxFor() helper instead:

<% using(Html.BeginForm("RegisterMember", "Home")) { %>
    <div>Name: <%: Html.TextBoxFor(x => x.Name) %></div>
    <div>Email address: <%: Html.TextBoxFor(x => x.Email) %></div>
    <div>Date of birth: <%: Html.TextBoxFor(x => x.DateOfBirth) %></div>

    <input type="submit" />
<% } %>

The e-mail input text box will now be named Email rather than myperson.Email (and likewise for the other input controls). The incoming values will successfully bind against an action method defined as follows:

public ActionResult RegisterMember(Person myperson)
{
    // ...
}

This works because DefaultModelBinder first looks for values with prefixes inferred from the method parameter name (or from any [Bind] attribute, if present). In this example, that means it will look for incoming key/value pairs whose key is prefixed by myperson. If no such incoming values can be found—and in this example they won't be—then it will try looking for incoming values again, but this time without using any prefix at all.

Imagine that the Person class, as used in the last few examples, had a bool property called IsAdmin. You might want to protect this property from unwanted interference. However, if your action method uses model binding to receive a parameter of type Person, then a malicious user could simply append ?IsAdmin=true to the URL used when submitting the member registration form, and the framework would happily apply this property value to the new Person object created.

Clearly, that would be a bad situation. And besides security, there are plenty of other reasons why you might want to control exactly which subset of properties are subject to model binding. There are two main ways to do this.

First, you can specify a list of properties to include in binding by using a [Bind] attribute on your action method parameter—for example:

public ActionResult RegisterMember([Bind(Include = "Name, Email")]Person myperson)
{
    // ...
}

Or you can specify a list of properties to exclude from binding:

public ActionResult RegisterMember([Bind(Exclude = "DateOfBirth")]Person myperson)
{
    // ...
}

Second, you can apply a [Bind] attribute to the target type itself. This rule will then apply globally, across all your action methods, whenever that type is model bound—for example:

[Bind(Include = "Email, DateOfBirth")]
public class Person
{
    public string Name { get; set; }
    public string Email { get; set; }
    public DateTime DateOfBirth { get; set; }
}

Which of these strategies you use will depend on whether you're establishing a global rule or a rule that applies just to one particular model binding occasion.

In either case, using an Include rule sets up a whitelist: only the specified properties will be bound. Using an Exclude rule sets up a blacklist: all properties will be bound, except those specifically excluded. It rarely makes sense to specify both Include and Exclude, but if you do, properties will be bound only if they are present in the include list and are not present in the exclude list.

If you use [Bind] on both the action method parameter and the target type itself, properties will be bound only if they're allowed by both filters. So, if you exclude IsAdmin on the target type, that can't be overridden by any action method. Phew!

Sometimes users will supply values that can't be assigned to the corresponding model properties, such as invalid dates, or text for int properties. To understand how the MVC Framework deals with such errors, consider the following design goals:

To comply with the first principle, the framework needs a temporary storage area for invalid attempted values. Otherwise, since invalid dates can't be assigned to a .NET DateTime property, invalid attempted values would be lost. This is why the framework has a temporary storage area known as ModelState. ModelState also helps to comply with the second principle: each time the model binder tries to apply a value to a property, it records the name of the property, the incoming attempted value (always as a string), and any errors caused by the assignment. Finally, to comply with the third principle, if ModelState has recorded any errors, then UpdateModel() finishes by throwing an InvalidOperationException saying, "The model of type typename could not be updated."

So, if binding errors are a possibility, you should catch and deal with the exception—for example:

public ActionResult RegisterMember()
{
    var person = new Person();
    try
    {
        UpdateModel(person);

// ... now do something with person
    }
    catch (InvalidOperationException ex)
    {
        // To do: Provide some UI feedback based on ModelState
    }
}

This is a fairly sensible use of exceptions. In .NET, exceptions are the standard way to signal the inability to complete an operation (and are not reserved for critical, infrequent, or "exceptional" events, whatever that might mean^[74]). However, if you prefer not to deal with an exception, you can use TryUpdateModel() instead. It doesn't throw an exception, but returns a bool status code—for example:

public ActionResult RegisterMember()
{
    var person = new Person();
    if (TryUpdateModel(person))
    {
        // ... now do something with person
    }
    else
    {
        // To do: Provide some UI feedback based on ModelState
    }
}

You'll learn how to provide suitable UI feedback in the "Validation" section later in this chapter.

When you use model binding implicitly—that is, receiving model objects as method parameters rather than using UpdateModel() or TryUpdateModel()—then it will go through the same process, but it won't signal problems by throwing an InvalidOperationException. You can check ModelState.IsValid to determine whether there were any binding problems, as I'll explain in more detail shortly.

So far, so good. But what about when you want to bind an array or collection of some custom type that has multiple properties? For this, you'll need some way of putting clusters of related input controls into groups—one group for each collection entry. DefaultModelBinder expects you to follow a certain naming convention that is best understood through an example.

Consider the following view markup:

<% using(Html.BeginForm()) { %>
    <h2>First person</h2>
    <div>Name: <%: Html.TextBox("people[0].Name") %></div>
    <div>Email address: <%: Html.TextBox("people[0].Email")%></div>
    <div>Date of birth: <%: Html.TextBox("people[0].DateOfBirth")%></div>

    <h2>Second person</h2>
    <div>Name: <%: Html.TextBox("people[1].Name")%></div>
    <div>Email address: <%: Html.TextBox("people[1].Email")%></div>
    <div>Date of birth: <%: Html.TextBox("people[1].DateOfBirth")%></div>

    ...
    <input type="submit" />
<% } %>

Check out the input control names. The first group of input controls all have a [0] index in their name; the second all have [1]. To receive this data, simply bind to a collection or array of Person objects, using the parameter name people—for example:

[HttpPost]
public ActionResult RegisterPersons(IList<Person> people)
{
    // ...
}

Because you're binding to a collection type, DefaultModelBinder will go looking for groups of incoming values prefixed by people[0], people[1], people[2], and so on, stopping when it reaches some index that doesn't correspond to any incoming value. In this example, people will be populated with two Person instances bound to the incoming data.

An easier way of generating input controls with correctly indexed names is to use a for loop and lambda-based HTML helpers. For example, if your Model object has a property called People of type IList<People>, you can render a series of input control groups as follows:

<% for (var i = 0; i < Model.People.Count; i++) { %>
    <h2>Some person</h2>
    <div>Name: <%: Html.TextBoxFor(x => x.People[i].Name)%></div>
    <div>Email address: <%: Html.TextBoxFor(x => x.People[i].Email)%></div>
    <div>Date of birth: <%: Html.TextBoxFor(x => x.People[i].DateOfBirth)%></div>
<% } %>

If you want an even easier way to do it, you can use templated view helpers. The built-in Collection template automatically iterates over collections and renders a suitably indexed display or editor for each item. If you define a partial at /Views/controllerName/EditorTemplates/Person.ascx containing the following:

<%@ Control Language="C#"
            Inherits="System.Web.Mvc.ViewUserControl<Namespace.Person>" %>
<h2>Some person</h2>
<div>Name: <%: Html.TextBoxFor(x => x.Name)%></div>
<div>Email address: <%: Html.TextBoxFor(x => x.Email)%></div>
<div>Date of birth: <%: Html.TextBoxFor(x => x.DateOfBirth)%></div>

then you can render a correctly indexed series of editors with a single line:

<%: Html.EditorFor(x => x.People) %>

You've just seen how to use sequential, zero-based indexes (i.e., 0, 1, 2, etc.) to define collection items. A more flexible option is to use arbitrary string keys to define collection items. This can be beneficial if you might dynamically add or remove groups of controls using JavaScript on the client, and don't want to worry about keeping the indexes sequential.^[75]

To use this option, each collection item needs to declare a special extra value called index that specifies the arbitrary string key you've chosen. For example, you could rewrite the previous example's view markup as follows:

<% using(Html.BeginForm()) { %>
    <h2>First person</h2>
    <input type="hidden" name="people.index" value="someKey" />
    <div>Name: <%: Html.TextBox("people[someKey].Name")%></div>
    <div>Email address: <%: Html.TextBox("people[someKey].Email")%></div>
    <div>Date of birth: <%: Html.TextBox("people[someKey].DateOfBirth")%></div>

    <h2>Second person</h2>
    <input type="hidden" name="people.index" value="anotherKey" />

<div>Name: <%: Html.TextBox("people[anotherKey].Name")%></div>
    <div>Email address: <%: Html.TextBox("people[anotherKey].Email")%></div>
    <div>Date of birth: <%: Html.TextBox("people[anotherKey].DateOfBirth")%></div>

    ...
    <input type="submit" />
<% } %>

There are multiple hidden fields called people.index, so ASP.NET will receive all their values combined into a single array. DefaultModelBinder will then use this as a hint for what indexes it should expect when binding to a collection called people.

If for some reason you'd like your action method to receive a dictionary rather than an array or a list, then you have to follow a modified naming convention that's more explicit about keys and values—for example:

<% using(Html.BeginForm()) { %>
    <h2>First person</h2>
    <input type="hidden" name="people[0].key" value="firstKey" />
    <div>Name: <%: Html.TextBox("people[0].value.Name")%></div>
    <div>Email address: <%: Html.TextBox("people[0].value.Email")%></div>
    <div>Date of birth: <%: Html.TextBox("people[0].value.DateOfBirth")%></div>

    <h2>Second person</h2>
    <input type="hidden" name="people[1].key" value="secondKey" />
    <div>Name: <%: Html.TextBox("people[1].value.Name")%></div>
    <div>Email address: <%: Html.TextBox("people[1].value.Email")%></div>
    <div>Date of birth: <%: Html.TextBox("people[1].value.DateOfBirth")%></div>

    ...
    <input type="submit" />
<% } %>

When bound to a Dictionary<string, Person> or IDictionary<string, Person>, this form data will yield two entries, under the keys firstKey and secondKey, respectively. You could receive the data as follows:

public ActionResult RegisterPersons(IDictionary<string, Person> people)
{
    // ...
}

The MVC Framework won't use your new custom model binder unless you tell it to do so. If you own the source code to XDocument, you could associate your binder with the XDocument type by applying an attribute as follows:

[ModelBinder(typeof(XDocumentBinder))]
public class XDocument
{
    // ...
}

This attribute tells the MVC Framework that whenever it needs to bind an XDocument, it should use your custom binder class, XDocumentBinder. However, you probably can't change the source code to XDocument, so you need to use one of the following two alternative configuration mechanisms instead.

The first option is to register your binder with ModelBinders.Binders. You only need to do this once, during application initialization. For example, in Global.asax.cs, add the following:

protected void Application_Start()
{
    RegisterRoutes(RouteTable.Routes);
    ModelBinders.Binders.Add(typeof(XDocument), new XDocumentBinder());
}

The second option is to specify which model binder to use on a case-by-case basis. When binding action method parameters, you can use [ModelBinder], as follows:

public ActionResult MyAction([ModelBinder(typeof(XDocumentBinder))] XDocument xml)
{
    // ...
}

Unfortunately, if you're invoking model binding explicitly, it's somewhat messier to specify a particular model binder, because for some reason UpdateModel() has no overload to let you do so. Here's a utility method that you might want to add to your controller:

private void UpdateModelWithCustomBinder<TModel>(TModel model, string prefix,
                    IModelBinder binder, string include, string exclude)

{
    var modelType = typeof(TModel);
    var bindAttribute = new BindAttribute { Include = include, Exclude = exclude };
    var metadata = ModelMetadataProviders.Current.GetMetadataForType(() => model,
                                                                     modelType);
    var bindingContext = new ModelBindingContext
    {
        ModelMetadata = metadata,
        ModelName = prefix,
        ModelState = ModelState,
        ValueProvider = ValueProvider,
        PropertyFilter = bindAttribute.IsPropertyAllowed
    };
    binder.BindModel(ControllerContext, bindingContext);
    if (!ModelState.IsValid)
        throw new InvalidOperationException("Error binding " + modelType.FullName);
}

With this, you can now easily invoke your custom binder, as follows:

public ActionResult MyAction()
{
    var doc = new XDocument();
    UpdateModelWithCustomBinder(doc, "xml", new XDocumentBinder(), null, null);

    // ...
}

So, there are several ways of nominating a model binder. How does the framework resolve conflicting settings? It selects model binders according to the following priority order:

The easiest way to tell your view to render error messages is as follows. Just place a call to Html.ValidationSummary() somewhere inside the view—for example:

<h1>Book an appointment</h1>
<%: Html.ValidationSummary() %>
... all else unchanged ...

This helper simply produces a bulleted list of errors recorded in ModelState. If you submit a blank form, you'll now get the output shown in Figure 12-9.

Figure 12-9. Validation messages rendered by Html.ValidationSummary

There are two things to notice about this screen:

Controlling Where Validation Messages Appear

Alternatively, you can choose not to use Html.ValidationSummary(), and instead to use a series of Html.ValidationMessage() or Html.ValidationMessageFor() helpers to place specific potential error messages at different positions in your view. For example, update MakeBooking.aspx as follows:

<% using(Html.BeginForm()) { %>
    <p>
        Your name: <%: Html.EditorFor(x => x.ClientName) %>
        <%: Html.ValidationMessageFor(x => x.ClientName) %>
    </p>
    <p>
        Appointment date:
        <%: Html.EditorFor(x => x.AppointmentDate)%>
        <%: Html.ValidationMessageFor(x => x.AppointmentDate) %>
    </p>
    <p>
        <%: Html.CheckBox("acceptsTerms") %>
        <label for="acceptsTerms">I accept the Terms of Booking</label>
        <%: Html.ValidationMessage("acceptsTerms") %>
    </p>

    <input type="submit" value="Place booking" />
<% } %>

Now, a blank form submission would produce the display shown in Figure 12-10.

Figure 12-10. Validation messages rendered by the validation message helpers

Some validation error messages may relate to specific properties, while others may relate to the entire model object and not any single specific property. You've already seen how to register property-level errors by passing the property name as a parameter (e.g., ModelState.AddModelError("ClientName", message)). You can register model-level errors by passing an empty string for the key parameter—for example:

bool isSaturday = appt.AppointmentDate.DayOfWeek == DayOfWeek.Saturday;
if (appt.ClientName == "Steve" && isSaturday)
    ModelState.AddModelError("" /* key */, "Steve can't book on Saturdays");

By default, Html.ValidationSummary() shows both model- and property-level errors. But if you're rendering property-level errors in other places using Html.ValidationMessage() or Html.ValidationMessageFor(), you probably don't want property-level errors to be duplicated in the validation summary.

To fix this, you can instruct Html.ValidationSummary() to display only model-level errors (i.e., those registered with an empty key) so that the user sees no duplication. Just pass true for its excludePropertyErrors parameter—that is, call Html.ValidationSummary(true). You can see example output in Figure 12-11.

Figure 12-11. When instructed to exclude property-level errors, the validation summary will not duplicate property-level messages that may be displayed elsewhere.

To create the preceding screenshot (Figure 12-11), I entered the values shown and clicked "Place booking." When the form reappeared with validation error messages, the data I previously entered (in this case a name and a date) was still present in the form fields.

ASP.NET Web Forms achieves a kind of statefulness using its ViewState mechanism, but there's no such mechanism in ASP.NET MVC. So how was the state retained?

Once again, it's because of a convention. The convention is that input controls should populate themselves using data taken from the following locations, in this order of priority:

Since model binders record all attempted values in ModelState, regardless of validity, the built-in HTML helpers naturally redisplay attempted values after a validation or model binding failure. And because this takes top priority, even overriding explicitly provided values, then any explicitly provided values are really just initial control values.

By default, ASP.NET MVC applications are configured to use DataAnnotationsModelValidationFactory, which recognizes the Data Annotations attributes listed in Table 12-9.

When you use any of the Data Annotations validation attributes, you can supply a custom error message as a parameter in either of the following two ways:

[AttributeName(ErrorMessage = "Your custom error message")]

or

[AttributeName(ErrorMessageResourceName = "YourResourceEntryName",
               ErrorMessageResourceType = typeof(YourResources))]

The second option is intended to work with RESX localization files—you need to give the .NET type name corresponding to the RESX file, and at runtime the framework will extract the named resource string according to the active thread culture. You'll learn more about working with RESX files and localization in Chapter 17.

Continuing the previous example, you could apply these attributes to the Appointment model class as follows:

public class Appointment
{
    [Required(ErrorMessage = "Please enter your name")] [StringLength(50)]
    public string ClientName { get; set; }

    [DataType(DataType.Date)] [Required(ErrorMessage = "Please choose a date")]
    public DateTime AppointmentDate { get; set; }
}

These rules will now be applied during model binding, and any violations will be registered in ModelState automatically, so it's no longer necessary for your controller to check whether ClientName was provided. Of course, you can still implement further validation logic directly inside your controller, which in this example is necessary to validate that the booking date falls within the next week, and that the Terms of Booking check box was checked.

public class ValidEmailAddressAttribute : ValidationAttribute
{
    public ValidEmailAddressAttribute()
    {
        // Default message unless declared on the attribute
        ErrorMessage = "{0} must be a valid email address.";
    }

    public override bool IsValid(object value)
    {
        // You might want to enhance this logic...
        string stringValue = value as string;
        if (stringValue != null)
            return stringValue.Contains("@");
        return true;
    }
}

As well as DataAnnotationsModelValidationFactory, the framework also includes DataErrorInfoModelValidatorProvider. This provides a more awkward and less powerful way of implementing custom validation logic, and is mainly intended for backward compatibility with ASP.NET MVC 1, where DefaultModelBinder was hard-coded to recognize an interface called IDataErrorInfo.

To use this, make your model class implement the IDataErrorInfo interface. This requires you to implement two methods—one to return property-level errors, and another to return object-level errors—for example:

public class Appointment : IDataErrorInfo
{
    public string ClientName { get; set; }
    public DateTime AppointmentDate { get; set; }

    public string this[string columnName]
    {
        get {
            if (columnName == "ClientName") {
                if (string.IsNullOrEmpty(ClientName))
                    return "Please enter a name.";
            }
            if (columnName == "AppointmentDate")
            {
                if (AppointmentDate < DateTime.Now.Date)
                    return "Bookings cannot be placed in the past";
            }
            return null; // No property-level errors
        }
    }

    public string Error
    {
        get {
            if (ClientName == "Steve"
                && AppointmentDate.DayOfWeek == DayOfWeek.Saturday)
                return "Steve can't book on Saturdays.";
            return null; // No object-level errors
        }
    }
}

Now you can simplify the MakeBooking action as follows:

[HttpPost]
public ActionResult MakeBooking(Appointment appt, bool acceptsTerms)
{
    if (!acceptsTerms)
        ModelState.AddModelError("acceptsTerms", "You must accept the terms");

    if (ModelState.IsValid) {
        // To do: Actually save the appointment to the database or whatever

return View("Completed", appt);
    }
    else
        return View(); // Re-renders the same view so the user can fix the errors
}

DataErrorInfoModelValidatorProvider will call your IDataErrorInfo methods and populate ModelState as part of model binding. You can still add extra validation logic, as in this example with the Accepts Terms check box, directly inside your action method.

This whole technique is much less useful than using Data Annotations attributes or a custom validation provider for several reasons:

It's good that ASP.NET MVC 2 supports IDataErrorInfo as a matter of backward compatibility, but most developers will not want to use it now that better alternatives exist.

If you want to go in a different direction from Data Annotations attributes, you can create a custom validation provider by inheriting a class from either of the following base classes:

Either way, you must override a method called GetValidators() and return a set of ModelValidator instances. This lets you hook into the validation system at a lower level than a Data Annotations ValidationAttribute, so you get more control over what happens.

Why would you want to do this? As an example, you might want to validate that two model properties must be equal. The ASP.NET MVC 2 Web Application project template includes its own custom validation attribute, PropertiesMustMatchAttribute, which you can apply to a model class and specify the names of the two properties that must match. But what if you want to apply a validation attribute to a property (not to the whole model class) and say that its value must match the value of another property?

You can't easily do this by inheriting from ValidationAttribute, because Data Annotations is mainly intended for validating objects in isolation, and its API doesn't provide any way for you to access sibling properties. In situations like this, you'll need to step away from Data Annotations and implement a totally separate custom validation provider.

To get started, define the following custom attribute:

public class EqualToPropertyAttribute : Attribute
{
    public readonly string CompareProperty;

    public EqualToPropertyAttribute(string compareProperty)

{
        CompareProperty = compareProperty;
    }
}

Using this attribute, you could declare that two password fields have to match.

public class UserRegistrationViewModel
{
    // ... other properties ...

    [Required] [DataType(DataType.Password)]
    public string Password { get; set; }

    [Required] [DataType(DataType.Password)] [EqualToProperty("Password")]
    public string ConfirmPassword { get; set; }
}

Next, you need to define a custom validator provider that can detect [EqualToProperty] attributes and convert them into instances of a ModelValidator subclass. Here's one such class that returns instances of a new class, EqualToPropertyValidator, which we'll define in a moment:

public class MyValidatorProvider : AssociatedValidatorProvider
{
    protected override IEnumerable<ModelValidator> GetValidators(
        ModelMetadata metadata, ControllerContext context,
        IEnumerable<Attribute> attributes)
    {
        foreach (var attrib in attributes.OfType<EqualToPropertyAttribute>())
            yield return new EqualToPropertyValidator(metadata, context,
                                                      attrib.CompareProperty);
    }
}

You need to tell ASP.NET MVC to use your new validator provider by registering it in the static ModelValidatorProviders.Providers collection. For example, update Application_Start() in Global.asax.cs as follows:

protected void Application_Start()
{
    AreaRegistration.RegisterAllAreas();
    RegisterRoutes(RouteTable.Routes);
    ModelValidatorProviders.Providers.Add(new MyValidatorProvider());
}

Of course, before any of this will compile, you'll also need to implement the EqualToPropertyValidator class previously referenced by the validator provider. This is where all the real validation logic lives.

public class EqualToPropertyValidator : ModelValidator
{
   private readonly string compareProperty;

   public EqualToPropertyValidator(ModelMetadata metadata,
       ControllerContext context, string compareProperty) : base(metadata, context)
   {

this.compareProperty = compareProperty;
   }

   public override IEnumerable<ModelValidationResult> Validate(object container)
   {
      if (Metadata.Model == null)
          yield break;

      var propertyInfo = container.GetType().GetProperty(compareProperty);
      if (propertyInfo == null)
          throw new InvalidOperationException("Unknown property:"+compareProperty);
      var valueToCompare = propertyInfo.GetValue(container, null);

      if (!Metadata.Model.Equals(valueToCompare))
          yield return new ModelValidationResult {
              Message = "This value must equal the value of " + compareProperty
          };
   }
}

As you can see, custom ModelValidator instances get access to the property's complete set of ModelMetadata information, as well as the container object of which the property is part. Your validator provider can supply any collection of ModelMetadata instances, so you're not limited just to using .NET attributes—you can obtain your configuration from any source.

The MicrosoftMvcValidation.js script is smart enough to notice if your form contains a validation summary rendered using Html.ValidationSummary(), and if it does, the script will dynamically show and hide messages in the summary list as needed. Here's how you could update the MakeBooking.aspx view to do client-side validation with a validation summary:

<% Html.EnableClientValidation(); %>
<% using(Html.BeginForm()) { %>
    <%: Html.ValidationSummary() %>
    <% Html.ValidateFor(x => x.ClientName); %>
    <% Html.ValidateFor(x => x.AppointmentDate); %>

    <p>Your name: <%: Html.EditorFor(x => x.ClientName) %></p>
    <p>Appointment date: <%: Html.EditorFor(x => x.AppointmentDate)%></p>
    <p>
        <%: Html.CheckBox("acceptsTerms") %>
        <label for="acceptsTerms">I accept the Terms of Booking</label>
    </p>

    <input type="submit" value="Place booking" />
<% } %>

This is different from the previous version of the view in two main ways:

Not surprisingly, the string-based equivalent of Html.ValidateFor() is called Html.Validate(). But even with this, we still can't validate the acceptsTerms check box on the client, because it doesn't correspond to any model property, so there's no metadata associated with it.

As you learned earlier in this chapter, ASP.NET MVC's built-in HTML helpers use certain CSS classes, such as input-validation-error, to highlight themselves when they correspond to validation errors in ModelState. To fit in with this convention, MicrosoftMvcValidation.js will dynamically add and remove these CSS classes on your input controls while the user is entering data into the form.

What's less well known is that MicrosoftMvcValidation.js also dynamically applies a further CSS class, input-validation-valid, to input elements once they've been detected as valid. This means you can highlight "good" values, reassuring the user that their data will be accepted. Validation doesn't always have to be negative!

For example, if you add the following rule to your CSS file:

.input-validation-valid { border: 1px solid green; background-color: #CCFFCC; }

then for any form that has client-side validation enabled, whenever the user types a valid value into a text box, that text box will turn green.

By default, client-side validation prevents the user from submitting a form while one or more validation errors are present. Normally that's exactly what you want. If for some reason you want a button to be able to submit a form regardless of whether it's displaying any validation errors, you can assign a value to a property called disableValidation on that button's DOM node.

For example, if you have a submit button defined as follows:

<input id="submitBooking" type="submit" value="Place booking" />

then the following JavaScript allows it to bypass client-side validation:

<script type="text/javascript">
    document.getElementById("submitBooking").disableValidation = true;
</script>

If you look at the HTML source code for your view once rendered in a browser, you'll notice that just after the closing </form> tag, the MVC Framework has emitted a JavaScript block that describes and applies your client-side validation rules:

...
</form><script type="text/javascript">
//<![CDATA[
     window.mvcClientValidationMetadata=[];
 }
 window.mvcClientValidationMetadata.push({"Fields":[{ "FieldName":"ClientName", ...
//]]>
</script>

To get an overview of how this information has reached the browser in JavaScript form, see Figure 12-13. We'll use this understanding in a moment when implementing client-side validation logic for a custom validation rule.

Figure 12-13. How client-side validation metadata is collected and emitted

The ModelValidator base class exposes a virtual method, GetClientValidationRules(), that can return a set of ModelClientValidationRule instances. Each ModelClientValidationRule instance is a description of how that rule should be represented in the client-side JavaScript Object Notation (JSON) block. The framework's JavaScript libraries understand the JSON descriptions of standard Data Annotations validators such as [Required] and [StringLength], plus they let you register your own JavaScript functions to implement custom validation logic for other rules.

Currently, if you use the [EqualToProperty] custom validation rule (which we created earlier in the chapter) in a form with client-side validation enabled, rules from Data Annotations may be validated on the client, but [EqualToProperty] will not—it will only be validated on the server. It's hardly surprising—ASP.NET MVC can't automatically translate arbitrary server-side .NET code into JavaScript. Let's see how to use ModelValidator's GetClientValidationRules(), plus some JavaScript code, to run [EqualToProperty] on the client too.

First, update EqualToPropertyValidator by overriding its GetClientValidationRules() method. You can return any ValidationType and ValidationParameters values—these will be made available on the client as part of the rule's JSON description.

public class EqualToPropertyValidator : ModelValidator
{
   // ... rest as before

  public override IEnumerable<ModelClientValidationRule> GetClientValidationRules()
  {
     var clientValidationRule = new ModelClientValidationRule {
         ValidationType = "EqualToProperty",
         ErrorMessage = "This value must equal the value of " + compareProperty
     };
     clientValidationRule.ValidationParameters["compareTo"] = compareProperty;
     yield return clientValidationRule;
  }
}

Next, add some JavaScript code directly after wherever you've referenced MicrosoftMvcValidation.js, adding a new custom validator to the client-side validation registry. Note that your new client-side validator must be named to match whatever ValidationType you declare in your ModelClientValidationRule, which in this case is EqualToProperty.

<script type="text/javascript">
    Sys.Mvc.ValidatorRegistry.validators.EqualToProperty = function (rule) {
        // Prepare by extracting any parameters sent from the server
        var compareProperty = rule.ValidationParameters.compareTo;

        // Return a function that tests a value for validity

return function (value, context) {
            // Find the comparison element by working out what its name must be
            var thisElement = context.fieldContext.elements[0];
            var compareName = thisElement.name.replace(/[^.]*$/, compareProperty);
            var compareElement = document.getElementsByName(compareName)[0];

            // Check that their values match
            return value == compareElement.value;
        }
    };
</script>

This is an unusually complicated client-side validator, because it has to locate another element in the HTML DOM to compare against. If you only need to validate a single value in isolation, your client-side validator would be simpler:

<script type="text/javascript">
    Sys.Mvc.ValidatorRegistry.validators.MyValidationType= function (rule) {
        return function (value, context) {
            // Return true if 'value' is acceptable; otherwise false.
            // Alternatively, return a non-null string to show a custom message
        }
    };
</script>

When the framework calls your custom validation function, it passes two parameters: value, which of course is the value to be validated, and context, which has the properties listed in Table 12-10.

public class ValidEmailAddressAttribute : RegularExpressionAttribute
{
    private const string EmailPattern = ".+@.+\..+";

    public ValidEmailAddressAttribute() : base(EmailPattern)
    {
        // Default message unless declared on the attribute
        ErrorMessage = "{0} must be a valid email address.";
    }
}

protected void Application_Start()
{
    AreaRegistration.RegisterAllAreas();
    RegisterRoutes(RouteTable.Routes);
    DataAnnotationsModelValidatorProvider.RegisterAdapter(
        typeof(ValidEmailAddressAttribute),
        typeof(RegularExpressionAttributeAdapter)
    );
}