In a previous post I used an EditorFor template to display child objects correctly on a view. Now we are going to use some simple JavaScript templating to add child objects. We have a page display book details and want to add and save additional authors.

Demo app

The demo app is a simple bookshelf application. It has a view that uses EditorFor templates to display a book which we want to save. The book can have multiple authors. It is a complex object.

public class Book
{
 public int? BookID { get; set; }

 //.. lots of other properties 

 public List<Author> Authors { get; set; }
}
public class Author
{
 public int AuthorID { get; set; }
 public string DisplayName { get; set; }
}

The book is rendered onto the Book.cshtml view and the user sees a book then can be edited and saved as required.

The authors are rendered in this format

<input id="Authors_0__AuthorID" name="Authors[0].AuthorID" type="hidden" value="0">

<input id="Authors_0__DisplayName" name="Authors[0].DisplayName" type="text" value="Adam Freeman">

<input id="Authors_1__AuthorID" name="Authors[1].AuthorID" type="hidden" value="0">

<input id="Authors_1__DisplayName" name="Authors[1].DisplayName" type="text" value="Matthew MacDonald">

When this form is posted back, the default model binder in MVC uses the name attribute to correctly bind the authors as a child object of the book object. So we get a correctly populated book object passed through to the controller action.

[HttpPost]
[ValidateAntiForgeryToken]

public ActionResult Create(Book book)
{

The book parameter is populated will the correct authors. Nice. In general, to work with child objects the correct format for the name attribute in the HTML form element is ..

name="PropertyName[index].ChildPropertyName"

We’ll need to bear that in mind when we are creating a control to add new authors.

The Problem

The authors display correctly and work well but what if we want to add additional authors to the book before saving? Perhaps the book is missing authors. Perhaps I’m a rampant egotist and want to add myself as an author to every book in my virtual bookshelf. Let’s use Handlerbars.js and some JQuery goodness to do this.

The Solution

Handlebars.js

Handlebars.js is one of many JavaScript templating engines that bind fragments of HTML and produce data driven templates. Handlebars takes a template such as

<div class="entry">
   <h1>{{title}}</h1>
 </div>

And binds it against some JSON

{ title: "My great page" }

To produce HTML

<div class="entry">
   <h1>My great page</h1>
 </div>

That’s going to be good for us. We’ve got some pretty chunky fragments of HTML and we want to work with it in the cleanest way we can.

Integrating Handlerbars.js into MVC

Install the package using nuget

Install-Package Handlebars.js

In it goes to the application. Now create a script bundle in BundleConfig.cs

bundles.Add(new ScriptBundle("~/bundles/handlebars").Include("~/Scripts/handlebars.js"));

and reference that bundle in the view

@Scripts.Render("~/bundles/handlebars")

Creating the HandleBar template

Let’s dive straight in and create the template. We want a HTML fragment that will generate us a new author. HandlerBar templates need to be in script tags with the type

text/x-handlebars-template

our full template is

<script id="author-template" type="text/x-handlebars-template">
        <div class="form-group shelf-author">
            <div class="col-md-10">
                <input id="Authors_{{index}}__AuthorID" name="Authors[{{index}}].AuthorID" type="hidden" value="0">
                <input class="form-control text-box single-line"
                        id="Authors_{{index}}__DisplayName"
                        name="Authors[{{index}}].DisplayName"
                        type="text"
                        value="{{authorName}}">
            </div>
        </div>
    </script>

This gives us a hidden field for the AuthorID and a text field for the author name. The curly brackets tell us where the holes in the template are so

{{authorName}}

[{{index}}

Are the two pieces of data that the template needs. Handlebars will replace these with the data we supply it.

Constructing the Author add control

Now we need a HTML control to add the author. We want something like this

So a textbox and a button with a squirt of CSS

div class="col-md-4 col-md-offset-2 form-inline">
  @Html.TextBox("txtNewAuthor", null, new { @class = "form-control" })
  <input type="button" id="btnAddAuthor" value="Add" class="btn btn-primary" />
</div>

Let’s assume that JQuery is already reference and available. Next job is to wire up the click event to the button

$(document).ready(function () {
    $('#btnAddAuthor').on('click', function () {

    //.. templating code will go here 
   });
});

Which is standard stuff.

Obtaining the data for the template

Next we need to construct the JSON data that Handlebars will use to generate the HTML. We need two pieces of information

1. The authors name as inputted by the user
2. The next index of the author elements

Grabbing the author name is straightforward

var authorName = $('#txtNewAuthor').val();

However to get the next index we need find the current highest index. First we need to navigate the DOM to find the last author. The authors are all wrapped in the ‘shelf-authors’ class to facilitate this

var lastAuthor = $('.shelf-author:last');

then we want the name attribute

var lastAuthorFormName = $(lastAuthor).find(':text').attr('name');

Then we want the last index. If there are 3 authors then lastAuthorFormName will contain

Authors[2].DisplayName

So some regex the current index i.e. the number in square brackets

lastAuthorFormName.match(/\[(\d*)\]/)

The entire regex matches “[2]” and the first and only group (\d*) matches the digit itself. The output for this is an array. The first element of the array is the full match. All subsequent elements are the matches for the containing groups (defined in regex by parenthesis). So

lastAuthorFormName.match(/\[(\d*)\]/)[0]

would equal “[2]” and

lastAuthorFormName.match(/\[(\d*)\]/)[1]

would equal “2”.  So to get the next index we need

var index = parseInt(lastAuthorFormName.match(/\[(\d*)\]/)[1]) + 1;

Now we have all the information we need to construct the data for the handlebar template

var data = {
  index: index,
  authorName: authorName
};

Gluing the template together

Gluing the data into the template is pretty much boilerplate code

var source = $("#author-template").html();
var template = Handlebars.compile(source);

var renderedHTML = template(data)

Grab the template with a CSS selector then compile and combine. The HTML is now correct and can be inserted into the DOM

The Complete Solution

So combining all the steps together we get

  @Scripts.Render("~/bundles/handlebars")

 <script id="author-template" type="text/x-handlebars-template">
   <div class="form-group shelf-author">
     <div class="col-md-10">
       <input id="Authors_{{index}}__AuthorID" name="Authors[{{index}}].AuthorID" type="hidden" value="0">
       <input class="form-control text-box single-line" id="Authors_{{index}}__DisplayName" name="Authors[{{index}}].DisplayName"  type="text" value="{{authorName}}">
     </div>
   </div>
 </script>
 <script type="text/javascript">

 $(document).ready(function () {

 $('#btnAddAuthor').on('click', function () {

 //..don’t insert blank authors
 if ($('#txtNewAuthor').val() == '') return; 

 //.. get the author name 
 var authorName = $('#txtNewAuthor').val();

 //.. get the index
 var lastAuthor = $('.shelf-author:last');
 var lastAuthorFormName = $(lastAuthor).find(':text').attr('name');
 var index = parseInt(lastAuthorFormName.match(/\[(\d*)\]/)[1]) + 1;

 //.. format data as JSON
 var data = {
 index: index,
 authorName: authorName
 };

 //.. combine data with template
 var source = $("#author-template").html();
 var template = Handlebars.compile(source);
 
 //.. insert new author HTML into DOM 
 lastAuthor.after(template(data));

 //.. clear the input textbox
 $('#txtNewAuthor').val('');

 });
 });
</script>

The HTML element is now correct and when this is posted back the new author will be present in the action method i.e.

[HttpPost]
[ValidateAntiForgeryToken]
public ActionResult Create(Book book)
{

The book parameter will have a fourth author which will be saved.

So I can now add myself as an author to every book in my library which goes some way into feeding my monstrous and uncontrolled ego – which is what it’s all about really.

Useful Links

Project page for handlebars
http://handlebarsjs.com/

Nuget page for handlebars
https://www.nuget.org/packages/Handlebars.js/

Demo application source
https://github.com/timbrownls20/BookShelf/

I’ve a habit of declaring things magical when I don’t fully understand how they work and haven’t the time to look into them any further. One of the things I’ve often declared magical is model binding with MVC. It just works. Magical.

Recently though I found model binding with child objects a bit on the difficult side of things. The magic was failing to sparkle correctly and needed a little bit of extra developer sprinkles to work. Perhaps it even needs developer understanding.

Demo Application

I’m going to demonstrate the problem and solution using a demo library application. The application queries Google Books API and allows users to edit and add those books to their own virtual bookshelf. The book shelf app can be found here

https://github.com/timbrownls20/BookShelf/

 Workflow

The relevant part of the application is adding of books to the library. The work flow is …

1. User searches for a book
2. Application queries GoogleBooks and displays a list of matches
3. User selects a book
4. Application displays the selected book.
5. The user amends the book record as required
6. The application saves the book

So once the user has typed in a search term they are presented with a list of books which they can select.

Once selected a view showing the detail of the book is present to the user. The user is invited to save the book into his or her book shelf.

The problem is that the authors are not saved correctly. It’s pretty obvious that the authors aren’t displayed correctly. The HTML output looks fairly nonsensical.

We are going to have to dig into the application a bit further to fully understand this.

The Model

The model of the application is

public class Book
{
    public int? BookID { get; set; }
 
    [Required]
    public string Title { get; set; }

    [AllowHtml]
    [DataType(DataType.Html)]
    public string Description { get; set; }

    [DataType(DataType.ImageUrl)]
    public string Thumbnail { get; set; }

    public List<Author> Authors { get; set; }
}

public class Author
{
    public int AuthorID { get; set; }

    public string DisplayName { get; set; }
}

So a book can have multiple authors. It is a complex object. It is the complex object and how that is rendered on the Book.cshtml view that causes us the problem. When it is posted back the book object lacks authors. The binding of the complex model has failed.

Book Create Action

When the user selects a book from this list this action is called. It displays the book ready for a save. We pass in an id (from the list selection) then the service goes away and grabs the full details of the book.

public ActionResult Create(string id)
{
   var book = bookService.Get(id);
   return View("Save", book);
}

The book is then displayed on the view Save.cshtml. The user presses submit which posts the book back to the server.

<div class="form-group">
   <!-- the other properties are displayed here -->
   <div class="form-group">
      @Html.LabelFor(model => model.Authors, htmlAttributes: new { @class = "control-label col-md-2" })
      <div class="col-md-10">
         @Html.EditorFor(model => model.Authors, new { htmlAttributes = new { @class = "form-control" } })
      </div>
   </div>
   <!--- rest of the form, submit buttons etc.. -->
</div>

Book Save Action

This action is called when the user saves a book to his or her bookshelf. The posted back book is saved.

[HttpPost]
[ValidateAntiForgeryToken]
public ActionResult Create(Book book)
{
   if (ModelState.IsValid)
   {
      db.Books.Add(book);
      db.SaveChanges();
      return RedirectToAction("Index");
   }
   return View("Save", book);
}

This action takes the book object and it is here that we want form data to bind and produce the complex object. We want the model binding to produce the book object as a parameter. We want the magic. The magic fails us.

The Problem

It doesn’t just magically work much to my disappointment. What is displayed is not helpful.

Posting this page doesn’t binding the child object and the authors aren’t there. The HTML is just not there. So how can I easily, and with as much magic as possible, change the view so that the authors are present and the form elements are named correctly? What does the default model binder actually want and how can I provide it?

The Solution

EditorFor Templates

The view needs to know how to display the author object. I could loop through in in the view but a better solution is the EditorFor template.

In View/Shared/EditorTemplates create a file called Author.cshtml. By convention MVC will find this and use it to display the Author property. We are telling it what to write out when the author property is edited i.e. what HTML to write out when the following call is made in the view

@Html.EditorFor(model => model.Authors, new { htmlAttributes = new { @class = "form-control" } })

The Author.cshtml is pretty simple

<div class="form-group">
    <div class="col-md-10">
        @Html.HiddenFor(model => model.AuthorID)
        @Html.EditorFor(model => model.DisplayName, new { htmlAttributes = new { @class = "form-control" } })
    </div>
</div>

The Corrected View

Now this is in place the view looks a lot better and it works.

When save is pressed the full object is passed to the Save Action and the object included authors can be persisted

What is interesting is the rendered output. Viewing the page source (stripping out the validation data elements, styling etc..) we see this

<input id="Authors_0__AuthorID" name="Authors[0].AuthorID" type="hidden" value="0">

<input id="Authors_0__DisplayName" name="Authors[0].DisplayName" type="text" value="Adam Freeman">

<input id="Authors_1__AuthorID" name="Authors[1].AuthorID" type="hidden" value="0">

<input id="Authors_1__DisplayName" name="Authors[1].DisplayName" type="text" value="Matthew MacDonald">

<input id="Authors_2__AuthorID" name="Authors[2].AuthorID" type="hidden" value="0">

<input id="Authors_2__DisplayName" name="Authors[2].DisplayName" type="text" value="Mario Szpuszta">

So the convention that the default model binding requires is revealed. I wouldn’t have just guessed it but the EditorFor Template does it for us.

Although both the id and name look like reasonable candidates for model binding, it is the name attribute that is used. The format for child objects is

name=”PropertyName[index].ChildPropertyName”

so more complex objects are perfectly possible

name=”PropertyName[index].ChildPropertyName[index].GrandchildPropertyName”

and so on until you gone down a complex rabbit hole of 7 nested objects from which you might never return.

Adding New Authors (child objects)

One of the things we might want to do is enable a user to add new authors. Perhaps the retrieved book doesn’t have all the authors and the user is a stickler for detail. Knowing the required format of the child object html is going to help us with that. In its very simplest form it could a bit of jQuery based on this idea

var index = getLastIndex() + 1;
var newAuthor = $(“#authorTextBox”).val();

$( ".container" ).after("<input id="Authors_" + index + "__AuthorID" name="Authors[" + index + "].AuthorID" type="hidden" value=0>" );

$( ".container" ).after ("<input id=’Authors_" + index + "__DisplayName' name='Authors[" + index + "].DisplayName' type=text value='"+ newAuthor + "'>" );

But we would need to bit cleverer, use templating, work out the next index etc… But this gives us the starting point to be able to provide that functionality. An exercise for another day perhaps.

Note
I’ve now implemented a solution using Handlebars.js to add authors into the complex object. See this post for details.

DisplayFor Templates

As an aside we could/should also do a template for displaying a read version of the model i.e. when the following call is made in a view.

@Html.DisplayFor(model => model.Author)

It’s not needed to get this to work but it seems like a generally good and wholesome thing to provide this as well. The display template can be very simple..

@model Author

@Html.DisplayFor(model => model.DisplayName, new { htmlAttributes = new { @class = "form-control" } })

 Useful Links

More detail about EditorFor and DisplayFor templates
http://www.codeguru.com/csharp/.net/net_asp/mvc/using-display-templates-and-editor-templates-in-asp.net-mvc.htm

Some more insight into how complex data binding works
http://blog.codeinside.eu/2012/09/17/modelbinding-with-complex-objects-in-asp-net-mvc/

How to manipulate the DOM through JQuery which we would need to dig into a bit to implement adding an author
http://api.jquery.com/category/manipulation/

Google Books API reference in the blog post
https://developers.google.com/books/