Ivan Zlatev » jQuery

Editing Variable Length Reorderable Collections in ASP.NET MVC – Part 3: Knockout JS

Ivan Zlatev — Wed, 29 Jun 2011 16:48:27 +0000

In Part 2 of this series I began moving some aspects of the collection editing to the client-side with jQuery Templates, but we realized that it’s not good enough, because instead of dealing with data we are juggling with our ASP.NET MVC views generated HTML.

In this final Part 3 of the series I want to move the collection editing completely to the client-side using the Knockout JS library JavaScript library. I will look at:

Knockout JS data-binding and tempalting
JSON Form (data really – no form) submission
jQuery Client-Side Validation

I will re-implement our sample collection editor and it is going to look exactly the same as it did before. Before I begin just a reminder that all of the source code is available on GitHub as a Visual Studio solution.

What is Knockout JS?

I am going to quote its creator (Steven Sanderson) from his introductory post, where he provides a very good overview:

Knockout is a JavaScript library that makes it easier to create rich, desktop-like user interfaces with JavaScript and HTML, using observers to make your UI automatically stay in sync with an underlying data model. It works particularly well with the MVVM pattern, offering declarative bindings somewhat like Silverlight but without the browser plugin.

I suggest you read the above linked post or checkout the Knockout JS web site to learn more about it, but to quickly summarize how it works:

A JavaScipt view model is defined that holds all the data. All the data properties are initialized as (or wrapped in) observable values and arrays.
HTML elements can be data-bound to a property (similar to WinForms/XAML(WPF/Silverlight)) from the view model using the data-bind attribute syntax. We can bind an input’s value, a span’s text, etc. to a view model property.
Whenever a value/or array changes the data-binding kicks in and the HTML element are automatically updated.
Knockout uses jQuery and supports templating via jQuery Templates.

Our Sample

To understand this lets jump straight into our sample app.

I have added a third edit option to our sample:

which surprise, surprise looks exactly the same as in the previous iteration. Apart from one extra feature – the favourite movies counter I’ve added to give you a hint of the power of Knockout JS:

View and ViewModel

Let’s firstly look at the first iteration of our view model implementation:

We:

Serialize our ASP.NET MVC User Model to JSON (Id, Name, FavouriteMovies). Html.Json is a custom Html helper that simply wraps a JSON serializer – you can see it in the source code.
Wrap its values in Knockout observables and then once the page is loaded we initialize Knockout JS with our model
Define some add/remove movie methods to edit the FavouriteMovies collection

What’s crucial here is that we are not dealing with nor manipulating HTML markup, which is something that we were doing heavily in the previous parts.

When processed server-side the above view model will look like roughly like this in the browser:

var viewModel = {
        Id: ko.observable(1),
        Name: ko.observable("Ivan Zlatev"),
        FavouriteMovies: ko.observableArray([{"Title":"Movie 1","Rating":5},
                                                           {"Title":"Movie 2","Rating":10},
                                                           {"Title":"Movie 3","Rating":12}] || []),

        maxMovies: 10,

        addMovie: function() {
            viewModel.FavouriteMovies.push({"Title":null,"Rating":0});
        },

        removeMovie: function(movie) {
            ko.utils.arrayRemoveItem(viewModel.FavouriteMovies, movie);
        }
}

Let’s look at the first iteration of our edit view (EditKnockoutJS.cshtml) to better understand how does Knockout help us:

@model CollectionEditing.Models.User
@{ ViewBag.Title = "Edit My Account With Knockout JS"; }






Edit

@using (Html.BeginForm("EditKnockoutJS", "User", FormMethod.Post, new { id = "profileEditorForm" })) {
    @Html.ValidationSummary(false)
    
        My Details

        

        Name:
        
    

    
        My Favourite Movies

        
        
        You have  favourite movies.

        

        

        
    

    
        
        Cancel
    
}

In our view we use Knockout JS to data-bind our HTML input fields to the data in the viewModel (notice the “data-bind” attributes).

For the collection editor:

Similar to Part 2, we have a movie jQuery template, which defines the HTML fields of a movie, but this time we don’t use any ASP.NET MVC helpers.
We make the HTML list reorderable via Drag and Drop with the two special sortableList and sortableItem bindings.This is a custom Knockout JS binding I’ve created and hosted on GitHub here. Behind the scenes it magically creates a JQuery UI Sortable keeps our viewModel.FavouriteMovies collection in sync when the widget changes.
We limit the number of favourite movies a user can add via the “Add Another” button to ten by using a “enabled” binding with a boolean expression. Behind the scenes Knockout JS will manage the state of the button and toggle between enabled/disabled depending on the evaluated value of the expression.
Finally we data-bind a span element to display the current number of favourite movies the user has added. Again, this is something that Knockout will keep up to date for us.

Right now with this viewModel and that view we have a working drag and drop add/remove favourite movies editor. What we are still missing however is:

Form submission and server-side handling
Form validation

Form Submission and Handling

Let’s add some more code to our view model and view to handle form submission.

Firstly we are going to implement a save function in our view model. Because we are no longer using ASP.NET model views, we can’t simply submit the form as is – the “standard” form values based ASP.NET MVC model binding won’t work properly and especially so for the collection editing part.

Thankfully starting from version 3 ASP.NET MVC supports out of the box JSON model binding. It kicks in if the HTTP request Content-Type is set to “application/json”. So instead of using form submission we are going to post our view model data via an AJAX post request to our MVC action, containing the data in JSON serialized form:

 var viewModel = {
       ... snip ...

        saveFailed: ko.observable(false),

        // Returns true if successful
        save: function()
        {
            var saveSuccess = false;
            viewModel.saveFailed(false);

            // Executed synchronously for simplicity
            jQuery.ajax({
                type: "POST",
                url: "@Url.Action("EditKnockoutJS", "User")",
                data: ko.toJSON(viewModel),
                dataType: "json",
                contentType: "application/json",
                success: function(returnedData) {
                    saveSuccess = returnedData.Success || false;
                    viewModel.saveFailed(!saveSuccess);
                },
                async: false
            });

            return saveSuccess;
        }
};

Then we will suppress the default form submission behaviour and replace it with our own:

Cancel

A problem occurred saving the data.

Note that I have added a new “saveFailed” property in the viewModel which is set by save(). I have also used a “visible” data binding on the value of that property to display the error message paragraph only if the save operation has failed.

Now let’s also look at the MVC action to handle the form submission:

[HttpPost]
public ActionResult EditKnockoutJS(User user)
{
    FormResponseData responseData = new FormResponseData() {
        Success = false
    };

    if (this.ModelState.IsValid) {
        CurrentUser = user;
        responseData.Success = true;
    }

    return Json(responseData);
}

class FormResponseData {
    public bool Success { get; set; }
}

Pretty simple action, which just validates the Model using our validation rules/data annotations and returns a FormReponseData object serialized to JSON, which contains a Success flag expected by the client side.

We can now persist our view model and also use our server-side model validation to prevent the client from doing nasty things:

We are not done just yet. Because we no longer use the ASP.NET html helpers we no longer pull the server-side validation error messages and are currently left with the generic “Something went wrong.” error message. This isn’t exactly nice nor user friendly. We can solve this by the use of client-side JavaScript based validation. Remember that we should never ever rely solely on the client-side (and we don’t in our case).

Client-Side Validation

Unfortunately at the time of writing I couldn’t find anything that validates against the Knockout JS viewModel instead of the HTML markup, so I had to resort to jQuery Validation for the client-side validation. The problem with that is that we need to ensure that we have set proper unique “name” attributes on our form fields and especially so for our collection editor elements.

Fortunately Knockout JS already has a binding for that called the “uniqueName binding”, so all we have to do is add that to our favourite movie collection editor fields like I’ve showed below and don’t worry about generating them ourselves. This is great, because as you saw in Part 2 injecting a unique name during jQuery template evaluation is relatively tricky.

There are multiple ways we can use jQuery Validation and I have decided to go for the simplest declarative one, where we decorate our fields with extra attributes to describe the value constraints that we want to enforce. Let’s update the above fields to make the Title and Rating required:

Title:


Rating:

Finally let’s plug-in jQuery Validation. To do that we will remove the previous submit button handler and use jQuery Validation instead:

... snip... 

        

... snip...

Which gives us nice per-field validation error messages as we type:

Wrapping up

Download all of the source code from GitHub as a Visual Studio solution.

In this part we looked at Knockout JS and how great it is in terms of helping us avoid manipulation of HTML markup among many other things. This is generally something that can get really messy quickly and become hard to maintain and track. We also looked at how it helps us neatly solve our collection editing problem without having to worry about practically anything. In the expense of the sacrifice of our Html helpers and partial views, etc we get a lot of flexibility on the client side to add more interactivity in a neat and clean way.

Final Words

If you have a simple collection editing scenario and you are heavily reliant on your ASP.NET MVC views, partial views, editors and displays the approach documented in Part 1 should be sufficient. And if pulling in new entries/rows via AJAX is not an option (e.g. for speed, performance or any other reasons) you can pull in Part 2. However IMHO the better solution most of the time is to use Knockout JS and what I have described in this part as it opens the doors for more complex client-side interactions in a neat and clean way.

Thank you for reading the series. I will appreciate your feedback in the comments!

Custom Knockout JS binding for jQuery UI Sortable

Ivan Zlatev — Mon, 27 Jun 2011 20:23:24 +0000

For the work in progress Part 3 of my Editing Variable Length Reorderable Collections in ASP.NET MVC blog series I have created a custom Knockout JS binding that keeps a Knockout JS observable array in sync with a jQuery UI sortable.

It’s available here:

Basic usage is to use a sortableList binding on the ul which you want to make a jQuery Sortable and then a sortableItem binding for each sortable item (li) in the list like that:


    {{each(i, arrayItem) yourObservableArray}}
        
    {{/each}}

Live example (if you are reading this in a feed reader you will need to open the blog post properly to see this):

Editing Variable Length Reorderable Collections in ASP.NET MVC – Part 2: jQuery Templates

Ivan Zlatev — Mon, 20 Jun 2011 19:21:44 +0000

In Part 1 of this series I discussed the problems that we face when implementing an editor for a variable length, reorderable collection and reuse our server-side ASP.NET MVC views, model binding and validation. And while the solution provided in Part 1 is nice and clean (and I personally use it in a few projects) one field for improvement in true Agile Blogging fashion is to find a way to remove the AJAX request we use for fetching new editor rows.

One way to bring this completely to the client side is by the use of jQuery Template (or any other JavaScript templating engine/library).

A reminder of what our editor looks like before I begin and a second remind that the source code is available on GitHub:

To start with I have added a second link to our sample’s home page titled “Edit with jQuery templates”:

Corresponding controller actions:

public ActionResult EditJQueryTemplate()
{
    return View(CurrentUser);
}

[HttpPost]
public ActionResult EditJQueryTemplate(User user)
{
    if (!this.ModelState.IsValid)
        return View(user);

    CurrentUser = user;
    return RedirectToAction("Display");
}

And a new editor view (EditJQueryTemplate.cshtml) which is exactly the same as the one from Part 1 apart from the core editor bit:

My Favourite Movies

@if (Model.FavouriteMovies == null || Model.FavouriteMovies.Count == 0) {
    None.
}

    @if (Model.FavouriteMovies != null) {
        foreach (Movie movie in Model.FavouriteMovies) {
            Html.RenderPartial("MovieEntryEditor", movie);
        }
    }







Add another

Note the new @Html.CollectionItemJQueryTemplate helper, which takes a collection item instance with default values and the unchanged partial view MovieEntryEditor from Part 1:

@model CollectionEditing.Models.Movie


    @using (Html.BeginCollectionItem("FavouriteMovies")) {
        

        @Html.LabelFor(model => model.Title)
        @Html.EditorFor(model => model.Title)
        @Html.ValidationMessageFor(model => model.Title)

        @Html.LabelFor(model => model.Rating)
        @Html.EditorFor(model => model.Rating)
        @Html.ValidationMessageFor(model => model.Rating)

        Delete
    }

Basically the helper renders the partial with an ${$index} jQuery template placeholder for which we supply a GUID at run-time on the client-side when we render the template. The output of the helper looks like this:

Everytime the “Add another” button is pressed this template is rendered using a new GUID index value supplied by the viewModel class.

Here is the code of the @Html.CollectionItemJQueryTemplate helper:

public static MvcHtmlString CollectionItemJQueryTemplate(this HtmlHelper html,
                                                                                    string partialViewName,
                                                                                    TCollectionItem modelDefaultValues)
{
    ViewDataDictionary viewData = new ViewDataDictionary(modelDefaultValues);
    viewData.Add(JQueryTemplatingEnabledKey, true);
    return html.Partial(partialViewName, modelDefaultValues, viewData);
}

It renders the supplied partial view, but before that it sets a flag on the ViewContext’s ViewData dictionary to indicate that the view is to be rendered as jQuery collection item template. This is then handled by the @Html.BeginCollectionItem by generating an index template placeholder based .Index hidden field for model binding instead of one with an actual GUID value:

public static IDisposable BeginCollectionItem(this HtmlHelper html, string collectionName)
{
    string collectionIndexFieldName = String.Format("{0}.Index", collectionName);

    string itemIndex = null;
    if (html.ViewData.ContainsKey(JQueryTemplatingEnabledKey)) {
        itemIndex = "${index}";
    } else {
        itemIndex = GetCollectionItemIndex(collectionIndexFieldName);
    }

    string collectionItemName = String.Format("{0}[{1}]", collectionName, itemIndex);

    TagBuilder indexField = new TagBuilder("input");
    indexField.MergeAttributes(new Dictionary() {
        { "name", collectionIndexFieldName },
        { "value", itemIndex },
        { "type", "hidden" },
        { "autocomplete", "off" }
    });
// snip---

That’s it! We are still reusing our ASP.NET views, model binding and validation, but no longer require an AJAX request to fetch a new editor row!.

In Part 3 I will look at Knockout JS templating, data binding and moving variable length reorderable collection editing completely on the client side with the MVVM pattern and using JavaScript form serialization and JSON data submission and model binding.

Next: Part 3 and Knockout JS client-side collection editing, JSON model binding and client-side validation.

Visual Studio 2008 jQuery IntelliSense Fix

Ivan Zlatev — Wed, 01 Jul 2009 21:25:16 +0000

I am tinkering with ASP.NET MVC and jQuery and making my first baby steps in a whole new horrible world of web development. I found out that the JavaScript IntelliSense in Visual Studio 2008 is broken out of the box. The error is:

Warning    2    Error updating JScript IntelliSense: jquery-1.3.2.js:
   Object doesn't support this property or method @ 2173:1

The fix for Visual Studio 2008 SP1 by Microsoft can be found here:

KB958502 – JScript Editor support for “-vsdoc.js” IntelliSense doc. files