ASP.NET MVC and jQuery Part 4 – Advanced Model Binding

This is the fourth post in a series about jQuery and ASP.NET MVC 2 in Visual Studio 2010.

In my last post I covered the simple scenario of a Person object getting POSTed to an MVC controller using jQuery.  In this article, I’m going to look at three other, more complex examples of real-world model binding and where jQuery might fit in the mix.

The model binding scenarios I’ll cover are:

• Sorting a list with jQuery UI support and submitting IDs to the controller for processing.
• Using jQuery to augment the user experience on a list of checkboxes (supporting check all/none) and allowing MVC to handle the elegance on it’s own.
• Give users the ability to build a list of items on a complex object, then submit that object to an MVC controller for processing.

The entire working solution is available for download at the end of the file.

Preface

In the first two examples here I have lists of data that are statically programmed into the page.  From my earlier posts in the series you can see how easy it is to generate partial views that would drive the UI elements from a database or other backend.  For brevity, I’m leaving those elements out of this example.

Sortable Lists

The jQuery UI library provides the sortable() function which transforms the children of a selected element in the DOM to draggable, orderable items for the user to manipulate.

The sortable() extension also provides a mechanism for us to capture the order of the list via the toArray method.

Using the jQuery.ajax() method, we submit the results of the users’ efforts via post to a controller action.  For the purpose of this post, I’m not going to do any processing in the controller, but you can set breakpoints to see the data getting hydrated into the models.

Let’s start by setting up the controller action, which accepts a list of ints as a parameter to capture the order of the IDs.

Yes. It’s that simple.  Now, you’d likely want to do some processing, perhaps even save the order to a database, but this is all we need to catch the data jQuery.ajax() will throw at us.

The juicy bits in jQuery are as follows:

Note: In order to make the results of the array compatible with the binding mechanism in ASP.NET MVC (as at MVC 2.0) we need to use the ‘traditional’ setting in $.ajax().

There are a couple of interesting things to note here:

• jQuery.ajax() by default makes requests to the current URL via get.  My controller action that accepts the List<int> is the same name as the basic view.  I change the type here to POST and the proper controller action is called.
• The ‘toArray’ returns an array of the selected element IDs.
• My unordered list contains list items with IDs that represent the unique items.  In this case, they are integers stored as strings (by nature of HTML).
• The name of the list of IDs is passed in as the same name as the parameter in the controller action.
• When submitted to the controller, the MVC framework finds the appropriate method, looks at the expected parameter type and sees the array sent by the client.  It then uses reflection and parsing (and maybe some voodoo) to coerce the values into the expected parameter type.

We can then use the list of IDs as required in the comfort of c#.

One of the interesting things that you can do, as the List<int> parameter is an IEnumerable, is that you can use LINQ to Objects on these guys without any effort.  Thanks MVC Framework!

Submitting Checkboxes

How do you submit a list of the selected checkboxes back to an ASP.NET MVC controller action?  It’s all too simple.  In fact, the only reason I mention it here is to highlight some of the simplicity we inherit when we use the MVC Framework.

I actually laughed out loud when I figured this one out.  It’s that good (or, I’m that easily impressed).

For jQuery on this example, I’m only really going to use it to augment the user experience by providing a couple of buttons to check all or check none of the options.

We’ll use a standard HTML form and allow the user to select the items in a list they feel are appropriate.  The form will be submitted via POST to our controller action (named the same as the ActionResult for the original View) and our parameter will be automatically populated for us.

Some things to point out at this junction:

• The values on the checkboxes here are the same strings that are displayed in the labels.
• I have given all the checkboxes the same name. When submitted, MVC sees these as some kind of enumerable thing and will then try to bind based on that.
• Optimus Prime is not a Jedi.
• This the name used for the checkboxes is the same name as the parameter in the controller action.

Packing a Complex Model

What about if you have a complex type with properties that can’t be expressed with simple HTML form fields? What if there are enumerable types as properties on the object? 

Man, am I glad you asked! The ASP.NET MVC Framework is pretty smart about taking items off the client Request and building up your objects for you in the hydration process.

Here is my Suitcase class, with a List<string> that will contain all of the things that someone wants to take along on their vacation.

So how do we get those items into the object?  The first step is to allow users to create them.  We do this with a simple textbox and a button, rigged up to some jQuery script as follows:

When the user enters an item and clicks ‘Add to suitcase’ (or hits enter) we grab a reference to the textbox.  Next, we use jQuery.append() to create a new LI element with the contents of the textbox.  Finally, we clear out the value and return focus to the input field.

When the user is finished loaded up their bags, we need to create a data map that will be submitted.  To simplify the process a little, we’ll first get that list of clothes together.

We first create an empty array.  Next we use jQuery.each() to loop through all the returned elements – the list of LI elements that the user has created – and add the text of those LIs to the array.

Next, we POST the data back to the server:

Here are some observations:

• We’re POSTing and using the traditional setting so that the enumerated items are compatible with the current versions of jQuery and MVC.
• The names of the properties in the Suitcase class are the names of the values we use in the data map submitted by jQuery.ajax().
• As in the first example, jQuery.ajax() is posting to the default URL, which is the same URL as the view in this case.  In the controller we differentiate the action with the HttpPost attribute and, of course, the Suitcase parameter.

When the data is submitted we see this in the controller action breakpoint:

And the contents of the Suitcase.Clothes property:

Wrapping Up

There you have it: the basics of advanced…stuff. 

From here you should be able to work out most scenarios when building up objects in jQuery, submitting them to the controller and making a jazzier UI come together with jQuery UI while still using MVC in the backend.

Some things I’ve learned along the way:

• Remember to watch the names of your variables in data maps! They have to match the parameters (or member properties) of the controller action.
• If you’re having trouble getting things to submit and you’re not seeing any errors, try attaching FireBug in FireFox to the browsing session and see what’s happening to your requests/responses.
• Make sure that you’re sending the values of the jQuery selections, and not the objects themselves if you’re having trouble binding.
• Don’t send: $(“#my-textbox”)
• Send: $(“#my-textbox”).val()

Resources

• The complete solution for all three scenarios (download VS2010 solution)
• The rest of this series
• jQuery’s Website
• jQuery UI’s Website

ASP.NET MVC and jQuery Part 3 – Model Binding

This is the third post in a series about jQuery and ASP.NET MVC 2 in Visual Studio 2010.

100% of the developers I have talked to this morning are enjoying jQuery and how it makes ASP.NET MVC sites a treat to work on. Of course, the sample size was one (1) developer, and he’s writing this post. Just sayin’.

In this article I’m going to cover some of the model binding scenarios that work seamlessly with these two technologies, starting off with some background and a sample, then progressing to more complex concepts.

Model Binding Basics

Model binding occurs in the processing of a request in the MVC framework, after routing and the creation of the controller. After the controller comes out of the factory, reflection kicks in to match up the request from the routing engine (as a result of some client action) with any parameters in the HTTP request.

Said another way: form values and querystring parameters get automatically turned into .NET objects in the MVC framework. Cool.

To provide a simple overview of how model binding works, we’re going to set up a quick demonstration. Start up the IDE and create an ASP.NET MVC 2 Web Application. Delete the Index file (we’re going to create our own later). Here’s the steps we’re going to follow:

• Create a new model called Person (and build our project)
• Update our Controller to setup an “empty” person for our view
• Create a strongly-typed view to create a person
• Create an action method on our Home Controller to capture the ‘create’
• Let the MVC framework do the rest

We’re not actually going to persist anything here, this is just a show-and-tell.

The simple parts

Navigate to your Models folder and right-click to Add –> Class called Person. Complete the class out as follows:

We need to build our project here (SHIFT + CTRL + b) for the IDE to be able to see our class in later steps. The type-awareness from reflection requires that our type exist in an assembly.

Pop over to Controllers –> HomeController and delete the ViewData assignment. We’re going to create a new Person here and return it with the view. Our action looks very simply like so:

Right-click anywhere in the method and select Add View… from the context menu. We are adding a view named Index, setting it to be a strongly-typed view and setting the view content to Create. This will allow code generation to output the basics of the form we’re going to use.

Note that here, or anytime you try to add a view, that if your model hasn’t been updated by building your project your types won’t appear in the View Data Class drop-down. You can cancel, build, and re-open the dialog if that is the case.

The page that is generated is super handy as a starting point. Even if it doesn’t save me much time (after all the changes and deleting I do) for some reason it just makes me feel better that the computer had to do some work too.

Let’s clean it up a bit. Remove the validation controls, delete the DIV with the ‘back to list’ link in it and change the H2 to something more interesting.

Because I’m not going to be posting back to my Index action method, I need to also update the using statement to have to correct calls created for submitting the form:

Html.BeginForm("CreatePerson", "Home")

Finally, let’s add a bit of code with the corresponding method, CreatePerson, and a breakpoint in our Home controller:

The above doesn’t actually do anything (and won’t go anywhere past the breakpoint), but if you pause where I suggest and evaluate the Person object or the name that was assigned the string, you’ll see the values populated.

How did the Model Binding Work?

There are actually a ton of in-depth explanations out there, but here is the summary of what we’ve done and what the MVC framework does to support model binding:

• We have a class with public properties
• The template engine created a page for us with the HTML helper TextBoxFor
• TextBoxFor uses the name of the public properties to generate a form input with the same name
• The template creates a form to host those controls, which we directed to our controller and action
• When written to the browser, the form action is set to “/Home/CreatePerson” using the POST verb
• The MVC framework routes the form submission to the Home controller, then uses reflection to find the CreatePerson method
• Because the method accepts a Person object as a parameter, the MVC framework evaluates the HTTP request (querystring parameters, form values) and then hydrates an object for us

Now, Let’s Make it Interesting

So far, this has just been a demonstration of simple model binding in the MVC framework. Let’s get jQuery involved.

• Change the controller action to a partial view result
• Create a partial view that reveals the created person
• Add jQuery and jQuery UI to the Site.Master file
• Remove the using statement from the Index page
• Modify the input so it’s easier to select in jQuery
• Add a DIV to store the results of the create
• Add a calendar selector for the birthdate
• Submit the form via jQuery when the user clicks the button
• Clear the form when the partial view result comes back, and display the result

Let’s start by changing the method to only accept POSTs and simply returning the Person object we were passed in to the PartialView.

Right-click anywhere on the method and select Add View… from the context menu.

This time we’ll create the view as a partial, it will be strongly-typed to Person again, but we’ll set the View Content to Details.

The tooling support for the MVC Framework in Visual Studio 2010 will then create the ASCX (server control) for us with all the fields displayed.

Delete the P tag at the end of the generated control with the ActionLinks in it, leaving only the control tag at the top and the FIELDSET control.

Next, pop into Views –> Shared –> Site.Master and add jQuery to the HEAD of the master page. Let’s also add jQuery UI at this time to open the doors to some other augmentations. For full functionality you’ll need the CSS and the images folder in your project as well, and the CSS linked in the HEAD of the master page.

In Index.aspx, remove the using statement so that the form is no longer generated. This is easy if you use Visual Studio 2010’s collapsible regions (you can collapse the FIELDSET tag to see the whole using construct).

Add an ID with a value of “create-person-button” to the submit button at the bottom of Index.aspx. Lastly, before we get scripting, add a DIV to display the partial view when the person is ‘created’. These last two bits should look like the following:

On to the script

jQuery gives us a way to easily make AJAX requests via POSTing to the server. We pass in a map of data that the server is expecting. The result can be passed to a function that evaluates the results.

With the inputs setup the way they are and our placeholder…uh…holding a place, we’re all set to execute our POST.

We’ll write a helper function that will process the results of the POST operation and, of course, a jQuery ‘document ready’ event handler to setup the calendar and trap the submit button click.

Most of the code should be easy enough to follow along. The one interesting bit is that the data map need not be constructed with proper case. That is, if your fieldname is FirstName you can use FiRsTnAmE as the name in the data map and that is okay.

Run the app and enjoy!

The jQuery UI datepicker in action:

The form cleared after submit and the results of the POST displayed:

Some Caveats

At this point we don’t have any validation in place, we’re not saving to a database of any kind and we’re hooped if there’s a server-side error.

Unfortunately the jQuery POST doesn’t play nicely with unhandled exceptions that are thrown on the server. $.post is shorthand for a sub-set of the functionality (with some presets) of $.ajax, and only maps a handler for the success event (not error events).

To see this in, well, inaction change your CreatePerson action to the following:

This will instruct the MVC framework to pass the person object through to a view named “foo”, which doesn’t exist. If you run the form at this point, and submit, you’ll see no errors (unless you attach a debugger, like FireBug, to the script).

More to Come

In my next article I’m going to look at more complex data scenarios, like selections from a list and posting arrays back to the controller. I’ll also integrate some other goodies, like jQuery UI’s autocomplete, to help users pick a color.

Resources

• Download the project created in this post
• View the rest of the series
• jQuery’s web site
• Information on $.post
• Download jQuery UI

ASP.NET MVC and jQuery Part 2 – Suggesting Content

This is the second post in a series about jQuery and ASP.NET MVC 2 in Visual Studio 2010.

Two perpetually frustrating tasks I have dealt with are scratching out a UI to collect data and having to work with that data client-side. Thankfully, a marriage of jQuery and ASP.NET MVC make this much more appealing and helps us to achieve, very quickly, a usable interface.

Suggesting Content from User Text

If you’ve used forums or user communities such as MSDN or StackOverflow where you can pose questions to peers, you’ve likely noticed that as you type your question related content begins to appear.

Here, we’ll replicate that behaviour and show how easy it is to make it work using jQuery and ASP.NET MVC. Because I will use some contrived data to make this work I will also include a solution download at the end of the article.

The Basic Steps

If you have a good grasp on things and just want to give it a try, here’s what you need to do:

• Create an ASP.NET MVC 2 Web Application
• Add jQuery to your Site.Master page
• Establish your model for the results of the search
• Create a repository to return a set of results
• Create a controller action to return the list of results in a partial view
• Create the required partial view
• Create the entry form that lets users ask questions
• Write script to take the form input and send it to the appropriate controller action, updating a DOM element with the results of the call

The Walkthrough

Setting up a project and getting jQuery was highlighted in the first article in this series. Create the project and get it set up for jQuery before you get going.

Creating a Model

Under normal circumstances you’d be working from a database that stores the related content you wish to display. Your model

Right-click on the Models folder in the Solution Explorer and click Add –> Class. Name the class Question and click Add. We’re going to add some properties to the class. This is really easy with auto-implemented properties in c# and the prop snippet. Type prop inside the class and you’ll see the following:

Hit tab and Visual Studio will generate the code you need and give you some assistance in filling in the key bits. You’ll notice the hightlighted text. You can use tab to cycle through the highlighted sections, which will select the text for you, and you can just over-type your values. Press enter to exit the snippet.

Add the following properties to the class:

• int UpVotes
• string Title
• string Tags

Building the Repository

Right-click on the Models folder and add another class called QuestionRepository. We are going to fake a database here and create a property called Questions. Make the property private and of type IEnumerable<Question>.

When the class is created we want Questions to be filled with some data to emulate something like a DataContext you would see if you were using LINQ to SQL. Create a constructor and populate a List<Question> with several questions. This is easy if you use the parameterless constructors of c#. I even just write a blank one, then copy-and-paste it out:

Fill in the blanks! For my sample (and in the download) I have added about 10 questions and assigned the list of questions to the class’ private Questions property. I also assigned the UpVotes to a random number between 0-20 so that I could sort off of it and get different results.

Next, add an internal function called FindMatchedQuestions with the following signature:

The algorithm for deducing the related questions is not the subject of this article. Though I’ve included some basic logic to make it work in the download, here’s all you need to get going for now:

With that inside our ‘find’ function, we’ll always get some random results. Use the downloadable project for search-relevant results.

At this point, let’s build our project (Shift + CTRL + b) to get our models compiled and help out our tooling. If you do not compile, some steps will not be as smooth as I suggest; MVC tooling uses reflection to find types in namespaces, types that don’t exist without an initial compilation

To the Controller

Navigate to Controllers –> HomeController.cs and open it up. Add a new public PartialViewResult to the class called FindRelated that accepts a string parameter. Add the following code to the method, which calls the repository to get some data (the model) and returns a PartialViewResult with said model.

Visual Studio 2010 contains some great helpers for the MVCers of the world. While the library is heavily tested, (mostly) strongly-typed, robust and extensive, it also allows us to rely on convention to afford us great convenience in code and in tool support.

The first convenience I used here is part of the framework; by passing my model into the PartialView() that I’m returning, the framework looks for a View that matches the name of my action (FindRelated) and passes the model to it. The executed result is what is returned to the browser (after the framework is done with it).

The second convenience I’m demonstrating comes from the tooling support and the IDE’s awareness of the MVC conventions. On to our View…

Building the Partial View

I’m not going for style points, here, so I’m going to use what we get for free. Let’s use that convention-aware tooling and create our partial view by right-clicking on the Home folder in Views, then selecting Add view…

You’ll see the following:

This is okay, but there’s an even better way to do this. Cancel the wizard and go back to your HomeController source file. Right-click anywhere inside the the FindRelated function and click Add View…

Now, you’ll see the already-named, convention-following parameters for creating your view. We’re going to set the wizard to create a partial view that is strongly-typed with the Question class. We’ll also set the View content to List.

The template outputs a table for us, which is acceptable, but it won’t look great for our purposes. For now, let’s just clean up a little bit by:

• Removing the first row which contains the headers
• Removing the first column in the foreach with the ActionLinks
• Removing the column that contains the output for item.Tags
• Removing the P tag at the end of the View with the Create link

If you kill the whitespace in the document you are left with a very short Partial View:

To finish off the view, add an H3 tag for a title and set the contents to Related Questions.

A Quick Test

At this point, we’re basically ready to rig up our functionality. If you want to see the results of your work so far, we can just make a request to the controller’s PartialViewResult action and see the list of related content. Press F5 to run the project, then enter the following in your browser (remember to replace your port number!):

http://localhost:PORT/Home/FindRelated?searchText=foo

Looking at the URL we can observe the following interesting things:

• Home is the name of our controller
• FindRelated in the name of our action
• searchText is the name of the parameter in our action
• The view that is rendered sits in a folder called Home which is the first place the framework looks when resolving views for a controller called HomeController

Through convention and the routing support in MVC 2 and ASP.NET we are able to see our results. If you examine the HTML source you’ll notice there are no HTML, HEAD or BODY tags; they aren’t rendered from partial views.

Here’s the results of my test view:

Again, not pretty, but it will do!

Involving the User and Adding Script

The default template for an MVC 2 project includes Index.aspx. Open it to edit from the Views –> Home folder in Solution Explorer.

Delete the H2 tag and the P tag that were so kindly added to the home page for you.

Add two DIVs. One will host the user input control and the other will be the container for our results, so we’ll ID them appropriately. Specifying an ID allows us to work directly with the controls with a simple jQuery selector.

Expand the user search container to include brief instructions and a text input.

Finally, add your SCRIPT tag so we can insert some JavaScript. First, lets add our function that can update the contents of our results placeholder:

Next, let’s add a jQuery handler that is executed when the document is fully loaded. In here, we’ll bind the ‘blur’ event of the text input to a the SubmitQuery function we just wrote:

That should be it! Now, just like when you tab out of the question asking box on StackOverflow, your query will be submitted and a list of related questions can come back! Run the app with F5 to see the results. Enter some text and tab out of the text box to see the list load.

Wrapping Up

Obviously this is not a complete feature-for-feature exhibit of a related-question section on a site, but it’s a good start. In the download I have improved the search results (somewhat) and styled the results to look a little more like SO’s.

You can also extend your model to include an ID, or use a model from a database. With an ID, you could then create a controller action that loads a question, given an ID, and outputs a view that is strongly-typed to render a complete question.

Good luck!

Resources

• Download the project created in this post
• View the rest of the series
• jQuery’s web site

ASP.NET MVC and jQuery Part 1 – Getting Started

This is the first post in a series about jQuery and ASP.NET MVC 2 in Visual Studio 2010.

If you’ve had web development experience with ASP.NET and JavaScript it is highly likely that you’ve heard of or are maybe even interested in the new partnership of these two technologies.

Getting started isn’t terribly difficult, so I’m not going to over-complicate this post. A couple of things to clear up, then we’ll jump to the meat.

What is the ASP.NET MVC Framework?

Model-View-Controller, abbreviated as MVC, is a design pattern (a concept) that helps us organize our code in such a way that we can keep clear separation between our data, our behaviours & business rules and our user interface. Those parts, respectively are referred to as the model, the controller and the view.

The MVC Framework for ASP.NET MVC gives us tools support, conventions and a base set of classes to enable use of this pattern, rather than the default Page-Controller pattern that is used in ASP.NET.

What is jQuery?

There is a reference to every element in an HTML document and JavaScript has access to them. With JavaScript, you can manipulate the DOM and write scripts to animate parts of your web page, make AJAX requests or perform validation.

Once you’ve written that code, you then need to keep a repository for it (you don’t want to write it again). When you want a new feature you might need to make breaking changes. You will have performance issues and browser compatibility problems, perhaps even platform-related issues.

jQuery is a library of JavaScript code where the kinds of things you want to do are already done. It is cross-browser compatible, has many pre-built components and has better performance with every release.

Think of jQuery as a way of “doing something” to “a group of things,” even if it is a group of one. You almost always begin by finding “the things” and then performing an action on them. “The things” are elements of the DOM like links, DIV tags, images, form elements, forms or the document root itself.

The Basic Steps

For you impatient types out there (like me):

• Create an ASP.NET MVC 2 Web Application
• Add the jQuery reference to the Site.Master to enable jQuery on all pages
• Use the if(false) technique to enable IntelliSense on partial views
• Use script references to enable IntelliSense on stand-alone JavaScript files

The Meaty Version

Start Visual Studio 2010 and create a new project. Navigate to the Web category and select ASP.NET MVC 2 Web Application. Name your project (I used Spike.jQueryMvc) and press OK.

Visual Studio will ask you to create a Unit Test Project. Just say no for now (I’ll cover tests in a later post). Finish the wizard and you’ll have your MVC project created.

Open up the Site.Master file which you will find in Views –> Shared in the Solution Explorer. Expand the Scripts folder as well so that you can see the default scripts.

In the HEAD tag of your Site.Master, drag the jQuery ‘min’ file and, below it, the jQuery ‘vsdoc’ file. Wrap your vsdoc file with an if(false) statement. The vsdoc will never be written to the browser (because false is never true) but Visual Studio will pick up the file and enable IntelliSense with this trick.

We’re all set to use jQuery and Visual Studio 2010’s awesome IntelliSense.

Now, navigate to the Index.aspx page in Views –> Home and open it up. After the closing P tag, add the following code:

<script language="javascript" type="text/javascript">
$(function () {
   $("p").click(function () {
       $(this).slideUp();
   });
})
</script>

You’ll notice as you’re typing that Visual Studio is popping up help text for your jQuery functions.

Press F5 to run the app. You will be prompted to modify the Web.Config file; accept this.

The browser will open and you’ll be staring at a slightly-modified default MVC page. Click on the text “To learn more about ASP.NET MVC” and see your jQuery in action.

FTW? How did that work?

Here’s the basics:

• A SCRIPT tag was added to the document
  
  
  
  
  



• We used a jQuery shortcut to wait for the document and run a function when it was completely loaded
  
  
  
  
  



• When loaded, we found all the P elements in the DOM and created an event handler to respond to user clicks. This is done with an anonymous function
  
  
  
  
  



• Inside our click event handler, we used another jQuery shortcut $(this) to select the P element that the user clicked on, and we told it to use the slideUp animation
  
  
  

The first shortcut is basically an event handler – in this case an anonymous function – that gets executed when the document is loaded. You should use this on every page because jQuery can’t find elements that haven’t yet been added to the DOM.

$(function () {

})

Inside this function – again, that gets executed after the DOM is loaded – we use a jQuery selector to find all the P elements in the document and attach a click handler to them.

$("p").click(...);

The selector can work with any element, ID or class. For IDs and classes you use the CSS-style sytax (# and . respectively), so for a input of type text with an ID of “first-name” you could find it with jQuery like so:

$("#first-name")

All that’s left is the anonymous function we used as an event handler.

function () {
$(this).slideUp();
}

We call the slideUp animation for the clicked element and let jQuery do it’s business.

Feedback

I have started this series to help a friend who is learning about web development. I found that by writing these tips out that I was gaining a better understanding of the underlaying technologies myself. I hope it can serve as a reference to others out there as well.

That said, if there’s something you’d like to point out, a question you have or a topic you’d like me to cover, please let me know and I will do my best to respond.