Editor Templates 101

Editor templates are a great way to reduce duplicated code in your project. When you're writing an HTML form, a lot of your fields can be simple text boxes, but sometimes we want a bit more functionality. Instead of writing the same code over and over to customize our editors, we put all of that code in one location and refer to it from inside our view.

I'd like to note that there are many different ways to use editor templates -- I'm just going to focus on a couple basic ways in this post.

Let's consider a view that contains a form:

@model MvcApplication.Models.Document

<h2>Create</h2>

@using (Html.BeginForm()) {
    @Html.ValidationSummary(true)
    <fieldset>
        <legend>Document</legend>

        <div class="editor-label">
            @Html.LabelFor(model => model.Name)
        </div>
        <div class="editor-field">
            @Html.EditorFor(model => model.Name)
            @Html.ValidationMessageFor(model => model.Name)
        </div>

        <div class="editor-label">
            @Html.LabelFor(model => model.Author)
        </div>
        <div class="editor-field">
            @Html.EditorFor(model => model.Author)
            @Html.ValidationMessageFor(model => model.Author)
        </div>

        <div class="editor-label">
            @Html.LabelFor(model => model.FileType)
        </div>
        <div class="editor-field">
            @Html.EditorFor(model => model.FileType)
            @Html.ValidationMessageFor(model => model.FileType)
        </div>

        <div class="editor-label">
            @Html.LabelFor(model => model.DateUploaded)
        </div>
        <div class="editor-field">
            @Html.EditorFor(model => model.DateUploaded)
            @Html.ValidationMessageFor(model => model.DateUploaded)
        </div>

        <p>
            <input type="submit" value="Create" />
        </p>
    </fieldset>
}

<div>
    @Html.ActionLink("Back to List", "Index")
</div>

This is a standard view made using the "Create" template. It has taken all of the fields of our Document model and has stubbed out editors for them. Here is the controller action that backs it up:

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

Very simple. When the view is rendered to the browser, we see simple text boxes for each field.

But what if we want to do more than that? Let's say we want to be able to pick up our DateUploaded field with javascript so we can throw on a datepicker. Ok, how about this:

<div class="editor-label">
    @Html.LabelFor(model => model.DateUploaded)
</div>
<div class="editor-field">
    <input id="DateUploaded" name="DateUploaded" data-datepicker="true" value="@Model.DateUploaded" />
    @Html.ValidationMessageFor(model => model.DateUploaded)
</div>

Would this work? Yes, we can pick up on the data-datepicker tag with javascript. But this is beyond dirty. We have just lost a lot of the functional advantages we get by using the EditorFor method on the HTML helper. Sure, this would work... but what if you change the name of the DateUploaded field? If we used the EditorFor, we would see a big nasty error message when we tried to load the view. But using the raw HTML, it's still valid. The http POST won't even fail. We just won't have our DateUploaded field populated. So, how do we accomplish this?

Let's take a look at the overloads for EditorFor.

EditorFor<TModel, TValue>(this HtmlHelper<TModel> helper, Expression<Func<TModel, TValue>> expression)

EditorFor<TModel, TValue>(this HtmlHelper<TModel> helper, Expression<Func<TModel, TValue>> expression, object additionalViewData)

EditorFor<TModel, TValue>(this HtmlHelper<TModel> helper, Expression<Func<TModel, TValue>> expression, string templateName)

...

(There are more but I cut them out for brevity). Look at the third one in the list. What is templateName? Specifying a value for templateName is the most straightforward way to use editor templates. When you provide a template name, MVC will look in a few different locations for a view with a name matching the value you provide as templateName. It's very similar to how calling View() in a controller action looks for a view with a name matching the action name. The view engine checks these locations in order:

1. ~/Areas/[AreaName]/Views/[ControllerName]/EditorTemplates/[TemplateName].cshtml
2. ~/Areas/[AreaName]/Views/Shared/EditorTemplates/[TemplateName].cshtml
3. ~/Views/[ControllerName]/EditorTemplates/[TemplateName].cshtml
4. ~/Views/Shared/EditorTemplates/[TemplateName].cshtml

So, let's modify our view code to look for an editor template named "DatePicker":

<div class="editor-label">
    @Html.LabelFor(model => model.DateUploaded)
</div>
<div class="editor-field">
    @Html.EditorFor(model => model.DateUploaded, "DatePicker")
    @Html.ValidationMessageFor(model => model.DateUploaded)
</div>

Perfect! Now we need to add a "DatePicker" partial view. But what do we put there? It's important to note that using this EditorFor overload is very similar to calling PartialView. Whatever editor template it finds, it will render that in place like a partial view. So, everything we put inside the DatePicker editor template is exactly what we get rendered. Let's try something simple to test.

@model DateTime?
@Html.TextBox("txtDatePicker")

We will save that as ~/Views/Shared/EditorTemplates/DatePicker.cshtml. Notice what we have declared as our model type. DateTime makes sense, but why nullable? Well, if we load our "Create" view with a null model (as is the case with our Create action), then it doesn't have a value for DateUploaded. We have to account for a null value in this case, even if the type on the model is not nullable. 

Let's take a look at the HTML this generates:

<div class="editor-field">
    <input id="DateUploaded_txtDatePicker" name="DateUploaded.txtDatePicker" type="text" value="">
    <span class="field-validation-valid" data-valmsg-for="DateUploaded" data-valmsg-replace="true"></span>
</div>

Notice how it changed the name and id attributes? When you provide a name for an element inside an editor template, what you're really doing is supplying the name of the property you're using inside the editor template. Thus, you get DateUploaded.txtDatePicker. If DateUploaded was an object that had its own properties, this would be perfect. But in our case we just want a textbox that refers to itself. We can accomplish that by passing in an empty string for the name.

@model DateTime?
@Html.TextBox("")

This may seem strange at first, but the truth is we don't actually need to supply a name for our textbox. That name is picked up from the name of the property specified on our Create view.

<div class="editor-field">
    <input data-val="true" data-val-required="The DateUploaded field is required." id="DateUploaded" name="DateUploaded" type="text" value="">
    <span class="field-validation-valid" data-valmsg-for="DateUploaded" data-valmsg-replace="true"></span>
</div>

This looks much better, and we've even picked up on the validation attributes. One thing we're not picking up on is the value of the field. You can't tell in the above HTML because we're using a null model, but even if we had a value, it would not get rendered because we're just spitting out a blank textbox right now. Let's fill in the value parameter by using the ViewData object:

@model DateTime?
@Html.TextBox("", ViewData.TemplateInfo.FormattedModelValue)

By this point, we now have a correctly functioning textbox that will be populated with a value from the model, and will submit the correctly named field. So it functions exactly as it did before we started with this editor template nonsense, minus a few CSS classes. Given this, is there even a point to making a custom editor template? If you stop now, then no. But let's tweak our editor template code just a bit further:

@model DateTime?
@Html.TextBox("", string.Format("{0:MM/dd/yyyy}", ViewData.TemplateInfo.FormattedModelValue), new { data_datepicker = true })

Now we've got something. Instead of just using the FormattedModelValue, we're calling string.Format to show the date portion of the DateTime. Since we don't care about the time for DateUploaded, we don't need to see it. We also have included an anonymous object, setting data_datepicker to true. For this overload of the TextBox method, the third parameter is an object that will be used to set attributes on the HTML element that gets generated. Here is the HTML output:

<div class="editor-field">
    <input data-datepicker="True" data-val="true" data-val-required="The DateUploaded field is required." id="DateUploaded" name="DateUploaded" type="text" value="">
    <span class="field-validation-valid" data-valmsg-for="DateUploaded" data-valmsg-replace="true"></span>
</div>

Notice the addition of the "data-datepicker" field. (aside: the view engine has converted our underscore to a hypen -- this is because hypens aren't allowed in identifiers in C#.) We can pick up on this in javascript and assign datepickers to our field:

$(function() {
    $("[data-datepicker]").datepicker();
});

As simple as that. If we add that javascript to our _Layout.cshtml file, it will show up on every single page. With our DatePicker editor template, we can now instantly attach a jQuery UI datepicker to an editor, simply by setting the template name parameter to "DatePicker".

For more information, check out our website.