Today, the topic gets its own post.

If you’ve worked with ASMX ScriptServices or Page Methods without ASP.NET AJAX’s client-side proxy (e.g. using jQuery or pure XMLHttpRequest code), you’ve may have seen this cryptic error yourself. Or, perhaps you’ve just arrived here due to seeing it for the first time.

Either way, you may be surprised to learn that the most common reason for this error is that you’ve lied to ASP.NET during your AJAX request.

It all begins with the Content-Type

HTTP’s Content-Type header is a fundamental aspect of communication between browsers and servers, yet often remains hidden from us in day-to-day development. The Content-Type header allows an HTTP connection to describe the format of its contents, using Internet media types (also known as MIME types). A few common ones that you’ve probably seen before are text/html, image/png, and the more topical application/json.

Without the flexible negotiation process content types provide, your users’ browsers and your version of IIS would have to both be “ASMX Compatible” and “JSON Compatible” in order for ScriptServices to function. What a nightmare that would be! The IE6 difficulties we face today would pale in comparison.

Further, Content-Type negotiation is part of what allows a single URL, such as WebService.asmx, to represent data in more than one format (e.g. XML and JSON in ASMX’s case).

The benefits of Content-Type negotiation are well worth a bit of occasional hassle.

Okay, but why does that matter?

When your browser sends a POST request, the W3C’s recommendation is that it should default to using a Content-Type of application/x-www-form-urlencoded. The HTML 4.01 spec describes that serialization scheme:

This is the default content type. Forms submitted with this content type must be encoded as follows:

1. [Omitted for brevity; not relevant to this post.]
2. The control names/values are listed in the order they appear in the document. The name is separated from the value by ‘=’ and name/value pairs are separated from each other by ‘&’.

For an example of what that means, consider this simple form:

<form method="post">
  <label>First Name</label>
  <input id="FirstName" value="Dave" name="FirstName" />
 
  <label>Last Name</label>
  <input id="LastName" value="Ward" name="LastName" />
</form>

When the preceding form is submitted with URL encoded serialization, the request’s POST data will look like this:

That standardized serialization format allows a server-side backend like ASP.NET to decipher a form submission’s contents and give you access to each key/value pair. Regardless of what sort of browser submits a form to the server, the Content-Type facilitates a predictable conversion from POST data to server-side collection.

In other words, the Content-Type corresponds to a serialization scheme.

What does that have to do with JSON Primitives?

Understanding Content-Type negotiation and how it relates to serialization is important due to its role in coaxing JSON out of ASMX ScriptServices. Specifically, the fact that you must set a Content-Type of application/json on the request means you’re instructing ASP.NET to interpret your input parameters as JSON serialized data.

However, the W3C’s mandate of URL encoding by default means that most AJAX libraries default to that serialization scheme. Similarly, AJAX tutorials targeting endpoints other than ASMX ScriptServices (including even ASP.NET MVC examples) will describe sending URL encoded data to the server.

In other words, when you’re working with a client-side object like this:

var Person = { FirstName: 'Dave', 
               LastName:  'Ward' }

The default serialization scheme makes it easy to inadvertently transmit that data to the server as a URL encoded string:

FirstName=Dave&LastName=Ward

Again, remember that a Content-Type of application/json is a requirement when working with ASMX ScriptServices. By setting that Content-Type on the request, you’ve committed to sending JSON serialized parameters, and a URL encoded string is far from valid JSON.

In fact, it’s invalid JSON (primitive?), hence the cryptic error message.

Instead of the URL encoded string above, you must be sure to send a JSON string:

{'FirstName':'Dave','LastName':'Ward'}

Whether you’re using XMLHttpRequest directly or a JavaScript library that abstracts the details, getting your request’s serialization wrong is the root of the invalid JSON primitive error. However, a more specific issue tends to be the leading cause of this happening.

When good JavaScript libraries go bad

The most common source of this error stems from a subtlety of using jQuery’s $.ajax() method to call ASMX ScriptServices. Cobbling together snippets of code from the documentation, platform agnostic tutorials, and even posts here on my site, it’s easy to end up with something like this:

// WRONG!
$.ajax({
  type: 'POST',
  contentType: 'application/json',
  dataType: 'json',
  url: 'WebService.asmx/Hello',
  data: { FirstName: "Dave", LastName: "Ward" }
});

Notice the JavaScript object literal being supplied to $.ajax()’s data parameter. That appears vaguely correct, but will result in the invalid JSON primitive error.

Why? jQuery serializes $.ajax()’s data parameter using the URL encoded scheme, regardless of what Content-Type is specified. Even though the contentType parameter clearly specifies JSON serialization, this URL encoded string is what jQuery will send to the server:

FirstName=Dave&LastName=Ward

That obviously isn’t valid JSON!

The solution is as simple as two single-quotes:

// RIGHT
$.ajax({
  type: 'POST',
  contentType: 'application/json',
  dataType: 'json',
  url: 'WebService.asmx/Hello',
  data: '{ FirstName: "Dave", LastName: "Ward" }'
});

Did you spot the difference?

Instead of a JavaScript object literal, the data parameter is a JSON string now. The difference is subtle, but helpful to understand. Since it’s a string, jQuery won’t attempt to perform any further transformation, and the JSON string will be unimpeded as it is passed to the ASMX ScriptService.

It doesn’t have to be this way

The problem is trivial once you’re aware of the underlying issue, but there’s not a great reason I can see why things need to be this way in the first place. Either half of this equation could easily provide a remedy.

jQuery – I believe the most correct solution would be $.ajax() attempting to honor the serialization scheme indicated by its contentType parameter. In the case of application/json, fixing this could be easy as testing for JSON.stringify and using it if available. That would work great, but also avoid adding any complexity/size to jQuery core.

That would leave it our responsibility to reference a copy of json2.js in older browsers, but that convention wouldn’t be much of a burden. We generally do that anyway when the client-side objects get complex.

Microsoft – It’s absolutely correct that the framework throws an error when you lie to it about what you’re sending. However, a bit of leniency could potentially save thousands of hours spent troubleshooting this problem (if my search traffic is any indication of its prevalence).

Is there any reason that the ScriptHandlerFactory can’t intelligently differentiate between between JSON and URL encoded inputs? If the first non-whitespace character of the request isn’t an opening curly brace, why not attempt to deserialize it as URL encoded before throwing an invalid JSON primitive error?

You've been reading ASMX ScriptService mistake – Invalid JSON primitive, originally posted at Encosia. I hope you enjoyed it, and thanks for reading.

Related posts:

1. ASMX and JSON – Common mistakes and misconceptions
2. ASMX ScriptService mistakes: Installation and configuration
3. 3 mistakes to avoid when using jQuery with ASP.NET AJAX

System.Web.Extensions (aka ASP.NET AJAX)

The ability for ASMX services to return raw JSON is made possible by two key features originally added by the ASP.NET AJAX Extensions v1.0:

• JavaScriptSerializer – The JavaScriptSerializer class is the actual workhorse that translates back and forth between JSON strings and .NET CLR objects. Though less powerful than WCF’s DataContractJsonSerializer and third-party libraries like Json.NET, JavaScriptSerializer is likely all you’ll ever need for simple AJAX callbacks.
• ScriptHandlerFactory – There are several more classes behind the scenes*, but the ScriptHandlerFactory is the tip of the iceberg that you’ll need to remember during configuration. Redirecting ASMX requests through this HttpHandler is what coordinates the pairing of ScriptService with JavaScriptSerializer to provide automatic JSON handling.

Though both of these classes appear in the System.Web.Script namespace, they actually reside in ASP.NET AJAX’s System.Web.Extensions assembly. That has different implications depending on which version of ASP.NET your site targets:

• 1.x – No support for ScriptServices. A custom HttpHandler coupled with a third party library like Json.NET is your best bet (if anyone has a good tutorial on doing this under 1.x, let me know so that I can link to it).
• 2.0 – ScriptServices are available in ASP.NET 2.0 with the installation of the ASP.NET AJAX Extensions v1.0.
  • That means that the ASP.NET AJAX installer needs to be run on the server that hosts your site, not just on your local development machine.
  • For some of a ScriptService’s features to work in medium trust (i.e. shared hosting), the System.Web.Extensions assembly needs to be in your server’s global assembly cache (GAC). Don’t waste your time trying to make it work in your site’s /bin directory; insist that the extensions be properly installed on the server.
• 3.5+ – As of .NET 3.5, System.Web.Extensions ships with the framework. No additional assemblies need be installed.

* If you’re interested in the internals, I highly recommend downloading the ASP.NET AJAX Extensions v1.0 source and taking a look at ScriptHandlerFactory, RestHandlerFactory, and RestHandler. Though the classes have changed slightly since v1.0, they are still very similar.

Rerouting the ASMX handler via web.config

With the System.Web.Extensions assembly installed in the GAC, the remaining configuration step is an element in your site’s web.config. To take advantage of the ScriptService functionality, ASP.NET must be instructed to reroute ASMX requests through the ScriptHandlerFactory instead of ASP.NET’s standard ASMX handler.

This step is often unnecessary. The project templates in ASP.NET 3.5+ include all the necessary configuration elements, and ASP.NET 2.0 sites created with the “AJAX Enabled” templates are also pre-configured correctly.

However, if you find yourself unable to coax JSON out of an ASMX ScriptService, verifying your web.config is one of the best first steps in troubleshooting the issue. Whether due to a web.config generated by an older project template, accidental modification, or other issues, missing the httpHandlers web.config setting is a very common pitfall.

What should appear varies slightly depending on which version of ASP.NET your project targets. Regardless of your framework version, the config elements should be added to the <httpHandlers> section and are the only elements necessary. The variety of other config items required for the UpdatePanel and ScriptManager aren’t crucial to the ScriptService functionality.

ASP.NET 2.0 (with the ASP.NET AJAX Extensions installed)

<configuration>
  <system.web>
    <httphandlers>
      <remove path="*.asmx" verb="*" />
      <add path="*.asmx" verb="*" Culture=neutral, validate="false"
           type="System.Web.Script.Services.ScriptHandlerFactory, 
                 System.Web.Extensions, Version=1.0.61025.0,
                 PublicKeyToken=31bf3856ad364e35" />
    </httphandlers>
  </system.web>
</configuration>

ASP.NET 3.5

<configuration>
  <system.web>
    <httphandlers>
      <remove path="*.asmx" verb="*" />
      <add path="*.asmx" verb="*" Culture=neutral, validate="false"
           type="System.Web.Script.Services.ScriptHandlerFactory, 
                 System.Web.Extensions, Version=3.5.0.0,
                 PublicKeyToken=31bf3856ad364e35" />
    </httphandlers>
  </system.web>
</configuration>

ASP.NET 4

Thankfully, ASP.NET 4 has taken steps to reverse the trend of ever-enlarging baseline web.config files. By moving common configuration items such as the ScriptService’s HttpHandler to the default machine.config, each individual site need not include those configuration elements in their specific web.config files.

Unless you go out of your way to manually remove their HttpHandler, ASMX ScriptServices will work automatically in any ASP.NET 4 site.

You've been reading ASMX ScriptService mistakes: Installation and configuration, originally posted at Encosia. I hope you enjoyed it, and thanks for reading.

Related posts:

1. ASMX and JSON – Common mistakes and misconceptions
2. 3 mistakes to avoid when using jQuery with ASP.NET AJAX
3. A breaking change between versions of ASP.NET AJAX

To preemptively surface some of that commonly requested information, I’m going to publish a series of relatively short posts, each describing one mistake or misconception that I’ve seen come up frequently.

To get started, I want to cover one of the most fundamental of these misconceptions: That ASMX services can’t return JSON.

Misconception: ASMX services are limited to XML

One of the most stubbornly persistent misconceptions about ASMX services is the rumor that they are limited to returning XML. With that notion mind, many developers understandably avoid them for client-side AJAX callbacks. When every byte counts, raw JSON is always preferable to the bloat of XML.

However, the introduction of ASP.NET AJAX removed that XML limitation.

In any ASP.NET 2.0+ AJAX enabled site, one of ASP.NET AJAX’s additions is something called the ScriptService. When a ScriptService is called in the correct manner, it automatically returns its result serialized as JSON instead of XML.

In fact, these ASMX ScriptServices even accept their parameters as JSON.

The ASP.NET AJAX “ScriptService”

If you’ve created an ASMX service in the past few years, you’ve probably seen this blurb at the beginning of the default template:

// To allow this Web Service to be called from script, 
//   using ASP.NET AJAX, uncomment the following line. 
// [System.Web.Script.Services.ScriptService] 
public class WebService : System.Web.Services.WebService {

Since it never explicitly mentions JSON and implies a tight coupling with ASP.NET AJAX, it’s easy to understand why the ScriptService’s true power sometimes goes unnoticed. Thankfully, that attribute does much more than simply expose ASP.NET AJAX specific functionality.

In fact, the ScriptService attribute enables all of an ASMX service’s methods to respond with raw JSON if they are requested correctly. For example, these ScriptServices can easily send and receive JSON in conjunction with a third party library, without a ScriptManager or MicrosoftAjax.js anywhere to be seen.

Two simple requirements

As I alluded to earlier, the one stipulation is that these ScriptServices only return JSON serialized results if they are requested properly. Otherwise, even a service marked with the attribute will return XML instead of JSON. I can only assume that’s part of the reason for the misconception that ASMX services cannot respond with JSON.

Scott Guthrie has a great post on the specific requirements for coercing JSON out of ScriptServices. To summarize that, requests to the service methods must meet two requirements:

• Content-Type – The HTTP request must declare a content-type of application/json. This informs the ScriptService that it will receive its parameters as JSON and that it should respond in kind.
• HTTP Method – By default, the HTTP request must be a POST request. It is possible to circumvent this requirement, but it is advisable to stick with HTTP POST requests when dealing with JSON.

That’s it.

As long as those two requirements are satisfied, anything from low-level XMLHttpRequest code, to third-party libraries like jQuery, to ASP.NET AJAX itself can easily retrieve JSON serialized data from ASMX services.

You've been reading ASMX and JSON – Common mistakes and misconceptions, originally posted at Encosia. I hope you enjoyed it, and thanks for reading.

Related posts:

1. 3 mistakes to avoid when using jQuery with ASP.NET AJAX
2. Using jQuery to Consume ASP.NET JSON Web Services
3. A breaking change between versions of ASP.NET AJAX

No doubt, an upcoming ASP.NET Ajax Library iteration will update Start.js’ jQuery definition to reference jQuery 1.4.x. Regardless, knowing how to patch the script loader on your own terms is something that will be of recurring usefulness.

Luckily, the script loader is open and extensible enough that it’s possible to change which script versions are used. So, I want to briefly show you how the script loader defines JavaScript includes and how you can patch those definitions without modifying Start.js itself.

Using the script loader to inject jQuery

If you aren’t familiar with the script loader itself or with using it to asynchronously request jQuery, I recommend checking out its documentation and examples on the new ASP.NET Ajax Wiki.

To use it most basically, simply include a reference to Start.js either locally or on the Microsoft CDN, and then use this JavaScript to instruct the script loader to inject jQuery into the page:

// Instruct the script loader to request
//  jQuery in the background.
Sys.require(Sys.scripts.jQuery);
 
// This callback runs later, after jQuery
//  has been asynchronously loaded.
Sys.onReady(function () {
  console.log("Loaded jQuery " + jQuery.fn.jquery);
});

Monitoring the request in Firebug illuminates what that Sys.require statement triggered in the background:

As you can see, the end result is pretty straightforward. The primary benefit of this asynchronous loading technique is that scripts loaded through the script loader are non-blocking and may be loaded in parallel. By contrast, JavaScript includes referenced through HTML script elements block all rendering and further requests until they are parsed and executed. The difference is often significant.

Now, if only it were injecting jQuery 1.4 instead of 1.3.2.

Understanding how Sys.scripts.jQuery is defined

The Sys.scripts.jQuery parameter to the script loader is actually just a JavaScript object that defines a few parameters about the include. Here is how that is defined in Start.js (edited slightly for readability here):

var path = (window.location.protocol === "https" ? "https" : "http") 
           + "://ajax.microsoft.com/ajax/";
 
loader.defineScripts(null, [
 { name: "jQuery",
   releaseUrl: path + "jquery/jquery-1.3.2.min.js",
   debugUrl: path + "jquery/jquery-1.3.2.js",
   isLoaded: !!window.jQuery
 }
]);

If you’re using a local copy of Start.js, one option is to modify this jQuery script definition inside Start.js itself. However, I discourage that alternative. Not only would it require constant, manual maintenance after every new release, but it isn’t an option when using the Microsoft Ajax CDN’s copy of Start.js.

Defining a new target for it

Another option is to simply modify the Sys.scripts.jQuery object itself. Letting Start.js initialize the definition with jQuery 1.3.2’s path doesn’t hurt anything as long as we redefine it before calling Sys.require.

Inspecting the Sys.scripts collection in Firebug reveals how straightforward that modification will be:

Thanks to to the power of interactively interrogating the object in Firebug, it becomes clear that updating the releaseUrl and debugUrl properties of that object should be all that is necessary.

Updating the example to use jQuery 1.4

Because jQuery 1.4 isn’t available on the Microsoft CDN yet, I’m going to target Google’s AJAX Libraries CDN for jQuery instead. Once Microsoft’s CDN is updated with jQuery 1.4.x, this approach will work for either CDN.

// These re-definitions must be executed after 
//  Start.js, but before Sys.require.
var CDN = "http://ajax.googleapis.com/ajax/libs";
 
Sys.scripts.jQuery.releaseUrl = CDN + "/jquery/1.4.1/jquery.min.js";
Sys.scripts.jQuery.debugUrl   = CDN + "/jquery/1.4.1/jquery.js";
 
// Instruct the script loader to request
//  jQuery in the background.
Sys.require(Sys.scripts.jQuery);
 
// This callback runs later, after jQuery
//  has been asynchronously loaded.
Sys.onReady(function () {
  console.log"Loaded jQuery " + jQuery.fn.jquery);
});

That’s all there is to it. Reviewing the requests in Firebug again, you can see that the same Sys.require statement is indeed now loading jQuery 1.4 from Google’s CDN:

Bonus: jQuery Validate 1.6

As I write this, Start.js’ definition for Sys.scripts.jQueryValidate is still targeting version 1.5.5 of the plugin, but 1.6 is the current version.

Using what’s been covered in this post, pointing the script loader at the newest version of jQuery Validate is no problem:

var MSCDN = "http://ajax.microsoft.com/ajax";
var GoogCDN = "http://ajax.googleapis.com/ajax/libs";
 
// Please forgive my ugly formatting to make this fit. Do not try 
//  this at home (unless your editor is only 492px too).
Sys.scripts.jQuery.releaseUrl = 
  GoogCDN + "/jquery/1.4.1/jquery.min.js";
Sys.scripts.jQuery.debugUrl = 
  GoogCDN + "/jquery/1.4.1/jquery.js";
 
Sys.scripts.jQueryValidate.releaseUrl = 
  MSCDN + "/jQuery.Validate/1.6/jQuery.Validate.min.js";
Sys.scripts.jQueryValidate.debugUrl = 
  MSCDN + "/jQuery.Validate/1.6/jQuery.Validate.js";
 
// Instruct the script loader to request
//  jQuery and jQuery Validate in the background.
Sys.require([Sys.scripts.jQuery, Sys.scripts.jQueryValidate]);
 
// This callback runs later, after both jQuery
//  and jQuery Validate have been loaded.
Sys.onReady(function () {
  console.log("Loaded jQuery " + jQuery.fn.jquery);
});

The jQuery Validate situation is a good example of why knowing how to update these script definitions yourself is worthwhile. Because the script loader was designed to be so flexible, there’s no need to wait on a new release of Start.js or give up its benefits.

You've been reading How you can force the Ajax Script Loader to use jQuery 1.4, originally posted at Encosia. I hope you enjoyed it, and thanks for reading.

Related posts:

1. 3 mistakes to avoid when using jQuery with ASP.NET AJAX
2. Using jQuery to directly call ASP.NET AJAX page methods
3. Updated your web.config, but Sys is still undefined?

If you haven’t been following the progress of Rob Conery and James Avery’s new venture, TekPub, you’ve been missing out on some great instructional videos. I especially like that they trend slightly Alt.NET, giving you more balanced information than is sometimes available from “official” .NET screencasts.

For the past few weeks, I’ve been working with James to record a series of episodes for TekPub myself: Mastering jQuery.

Mastering jQuery walks through the basics of using jQuery, the revolutionary JavaScript framework that makes writing client-side code fun and easy, and then dives into the details of writing AJAX enabled ASP.NET MVC and ASP.NET Web Forms applications. We will also cover popular plugins and extending jQuery in future episodes.

Today, the first video in that series is available: Getting Started with jQuery.

In this episode we cover the basics of getting started with jQuery. We start with a basic HTML page and show how to include jQuery, how to write your first code, and explain all of the moving pieces and how they work.

If you’ve been following my site and working with jQuery already, the first episode may sound elementary, but there’s going to be something for everyone before the series is finished. By the third episode, we’re already into topics like making AJAX calls to MVC controller actions and progressively enhancing an entry form with the jQuery form plugin.

I hope you’ll head over to TekPub, and have a look for yourself.

You've been reading Mastering jQuery now available at TekPub, originally posted at Encosia. I hope you enjoyed it, and thanks for reading.

Related posts:

1. Alt.NET Podcast – jQuery in ASP.NET
2. Emulate ASP.NET validation groups with jQuery validation
3. Using jQuery to directly call ASP.NET AJAX page methods

This approach worked fine for a single logical form, but wasn’t robust enough when handling validation for multiple logical forms on a single page. Additionally, it did not properly handle the enter key, allowing users to (perhaps accidentally) slip past validation if they simply hit the enter key within a TextBox.

In this post, we will continue by refining the solution from last time. So, if you haven’t read the previous post, familiarize yourself with it first. Specifically, this post will cover how to implement an analogue of WebForms’ ValidationGroup, use that to independently validate multiple form regions, handle the enter key, and refactor the final solution to minimize duplicated code.

ValidationGroups

In WebForms, we have the concept of a ValidationGroup to mitigate the issues that come with wrapping the entire page in a single form element. Whether right or wrong in principle, this scheme does a pretty good job of keeping the ASP.NET Validation controls from getting their wires crossed on complex forms.

However, using ASP.NET’s ValidationGroups requires that you use the WebForms validation controls, which generates quite a bit of cruft in your markup and injects two additional script references on your page.

If you’re like me, trying to trend away from client-heavy WebForms pages these side-effects are prohibitive.

Emulating Validation Groups

Though its implementation renders a bit messy on the client-side, the WebForms paradigm of a ValidationGroup is exactly what we need for segregating our physical form element into logical forms. In fact, I’m going to use the same nomenclature in this example (ValidationGroup and CausesValidation).

Using CSS classes as flags is a great way to emulate that concept in plain (X)HTML markup. Especially when using jQuery, CSS “flags” are a great way to tag elements with arbitrary attributes, that are easy to find with simple DOM selectors later. Taking the form shown in my previous post and tagging its fieldsets with a validationGroup class, we end up with this markup:

<fieldset class="validationGroup">
  <legend>Returning customer?  Login here</legend>
 
  <!-- Username and Password labels and inputs here -->
</fieldset>

Not a very large change, but it allows us to keep these logical forms separate, both when performing validation and when initially setting up their validation triggers.

Creating a CausesValidation counterpart

ValidationGroups may control the organization of logical forms, but it’s the controls marked with the CausesValidation property that drive validation of those forms. In similar fashion, we need a way to indicate which elements should trigger our own emulation of WebForms’ grouped validation.

Sticking with the same naming scheme and CSS flagging technique, it makes sense to tag our Button controls with a .causesValidation class:

<fieldset class="validationGroup">
  <legend>Returning customer?  Login here</legend>
 
  <!-- Username and Password labels and inputs here -->
 
  <asp:Button runat="server" ID="Login" Text="Login" 
              CssClass="causesValidation" />
</fieldset>

Now we just need to wire up functionality to make those causesValidation flags actually do something.

Acting on the validationGroup flag

With the markup modified to allow selective targeting of the validation groups, the next step is implementing validation functionality that leverages that targeting. Using jQuery’s powerful CSS-based selectors, that isn’t difficult:

$(document).ready(function () {
  $("#form1").validate({ onsubmit: false });
 
  // Search for controls marked with the causesValidation flag 
  //  that are contained anywhere within elements marked as 
  //  validationGroups, and wire their click event up.
  $('.validationGroup .causesValidation').click(function (evt) {
    // Ascend from the button that triggered this click event 
    //  until we find a container element flagged with 
    //  .validationGroup and store a reference to that element.
    var $group = $(this).parents('.validationGroup');
 
    var isValid = true;
 
    // Descending from that .validationGroup element, find any input
    //  elements within it, iterate over them, and run validation on 
    //  each of them.
    $group.find(':input').each(function (i, item) {
      if (!$(item).valid())
        isValid = false;
    });
 
    if (!isValid)
      evt.preventDefault();
  });
});

Note: For more explanation of any uncommented code above, be sure to see the previous post in this series. Those parts are explained in detail there.

This sets up a click event handler on any element flagged with the causesValidation class; the two Button controls in our case. When those raise click events, we start at the triggering element and use the parents() traversal method to search upward for the nearest parent flagged as a validationGroup.

In this example, that will find a reference to the fieldset which contains the Button control that triggers the click event (e.g. if the user clicks the Login Button, then $group will store a reference to the first fieldset element).

With that reference to the the logical form requiring validation, jQuery’s find() traversal method allows us to select a set of all the input elements within just that region of the page. Note that this will also include the Button control that triggered the event, but since the valid() method returns true for elements that don’t have validation rules configured, this doesn’t cause a problem.

From there, it’s straightforward to iterate over the appropriate input elements and validate each independently, using the valid() trick covered in the last post.

Handling the enter key

At this point, everything works pretty well, so long as the user clicks on the Button controls to submit the logical forms. Unfortunately, things fall apart if the user triggers form submission by pressing enter in one of the form fields.

One way to fix that would be to handle the form’s onsubmit event, determine if an element flagged with the causesValidation class triggered the submission, and then run through our validation first. That’s perfectly valid, but I avoid that because it tends to clash with other functionality that handles the event; the jQuery form plugin for example.

The alternative that I prefer is to handle a validated field’s onkeydown event. That way, if the element does need to trigger validation, it can do so early, and get out of the way quickly otherwise.

Using jQuery’s cross-browser normalized event object, testing for the enter key is not difficult at all. When handling keyboard related events, one property of that object is keyCode. This property will contain the ASCII character code of the key which triggered the event. In the case of the enter key, that keyCode is 13.

That in mind, this is a first iteration of adding enter key handling to our existing validation code:

// Select any input[type=text] elements within a validation group
//  and attach keydown handlers to all of them.
$('.validationGroup :text').keydown(function (evt) {
  // Only execute validation if the key pressed was enter.
  if (evt.keyCode == 13) {
    // Validation code goes here.
  }
});

Whether the form is submitted by clicking a button or hitting the enter key within one of our validation groups’ text fields, the appropriate inputs will be validated, error messages displayed if necessary, and submission will only continue if the form is valid.

Refactoring to eliminate duplication

After adding the keydown handler, everything works great, but it’s no good to have that validation code duplicated for both the click and keydown handlers. By passing around a reference to the jQuery event object, we can reuse the same validation code for both event types and make the code much more concise:

$(document).ready(function () {
  // Initialize validation on the entire ASP.NET form.
  $("#form1").validate({
    // This prevents validation from running on every
    //  form submission by default.
    onsubmit: false
  });
 
  // Search for controls marked with the causesValidation flag 
  //  that are contained anywhere within elements marked as 
  //  validationGroups, and wire their click event up.
  $('.validationGroup .causesValidation').click(ValidateAndSubmit);
 
  // Select any input[type=text] elements within a validation group
  //  and attach keydown handlers to all of them.
  $('.validationGroup :text').keydown(function (evt) {
    // Only execute validation if the key pressed was enter.
    if (evt.keyCode == 13) {
      ValidateAndSubmit(evt);
    }
  });
});
 
function ValidateAndSubmit(evt) {
  // Ascend from the button that triggered this click event 
  //  until we find a container element flagged with 
  //  .validationGroup and store a reference to that element.
  var $group = $(evt.currentTarget).parents('.validationGroup');
 
  var isValid = true;
 
  // Descending from that .validationGroup element, find any input
  //  elements within it, iterate over them, and run validation on 
  //  each of them.
  $group.find(':input').each(function (i, item) {
    if (!$(item).valid())
      isValid = false;
  });
 
  // If any fields failed validation, prevent the button's click 
  //  event from triggering form submission.
  if (!isValid)
    evt.preventDefault();
}

First, the validation code is refactored into a separate function: Validate.

Since it needs the ability to conditionally call preventDefault in order to stop form submission, the function accepts the event handlers’ jQuery event object as a parameter.

In fact, because $(this) is a reasonable place to begin the parents() traversal for either event that may call the method, very little refactoring is necessary.

The one thing that may seem strange is that the Validate function is being passed as a click handler without any parameters. The reason that this works is because the Validate function is defined with the same signature that jQuery expects. Because of that alignment, Validate will automatically be provided with the same event object that we’ve been using in anonymous callback functions thus far.

Calculated readability

Note that I attached keydown handlers to all of the text inputs within a validation group, regardless of whether or not they are actually validated fields. Similarly, you may have noticed that the click handler finds every input element within its validation group, even if those inputs aren’t marked for validation. This may seem like an oversight, but it’s an intended readability compromise.

You could modify the selector to be more precise, selecting only fields flagged with validation classes (e.g. required, email, number, etc). However, this gets messy when you consider the wide variety of classes that are valid for tagging elements with jQuery validation functionality.

Rather than be precisely specific, I rely on the fact that jQuery validation’s valid() method returns true for elements which are not configured for validation. So, even if we do end up checking the validation status of a few irrelevant input fields, it won’t adversely impact the outcome of the validation process.

There are performance penalties to performing validation on these unnecessary elements, but it is negligible for a reasonably sized form. The ancillary inputs would have to number in the thousands before the penalty were noticeable, at which no one will probably ever successfully complete it anyway!

Conclusion

There are even more enhancements to be had, but I think this brings the solution to a point that it’s useful. With multiple logical forms handled and the perennially pesky enter key tamed, the majority of use cases should be covered.

The most troublesome issue still remaining is that care should be taken to avoid nesting container elements with the validationGroup class on them. Otherwise, the Validate() function will search “too high” and possibly hinge validation on input fields that are not intended. It’s an edge case (fixable if necessary), but something to keep in mind.

Another edge case is that, unlike the ASP.NET Validators, these validation groups can’t overlap. For my own use, this has never been an issue. I’m curious if that’s a real-world problem for any of you.

Finally, an entirely different approach well worth considering is John Rummell’s xVal for Webforms. Using Data Annotations to specify validation rules is gaining a lot of popularity, so it’s worth investigating options like this one. At the minimum, it will help you be more familiar with how validation is handled in ASP.NET MVC.

Hope that helps. Be sure to take a look at the source download to see everything pulled together and one extra usability feature that I didn’t have time to cover.

Source

You've been reading Emulate ASP.NET validation groups with jQuery validation, originally posted at Encosia. I hope you enjoyed it, and thanks for reading.

Related posts:

1. Using jQuery validation with ASP.NET WebForms
2. Using jQuery to display a modal UpdatePanel confirmation
3. Exploring one of MS AJAX’s often overlooked features.

You’ve probably noticed that Jörn Zaefferer’s jQuery validation plugin has been gaining momentum in the ASP.NET community lately. Between Microsoft’s implied endorsement via ASP.NET MVC 2.0 integration and the plugin’s recent inclusion on the Microsoft AJAX CDN, adoption is only increasing. Unfortunately for those who don’t or can’t use ASP.NET MVC yet, using the validation plugin within WebForms applications can be tricky.

Because the WebForms Postback model requires that the entire page be contained within a single form element, form submissions that shouldn’t trigger validation are likely. ASP.NET’s built-in validation controls solve this with ValidationGroups and the CausesValidation property, but that doesn’t help if you’d prefer to use the jQuery validation plugin.

However, there are a couple relatively easy workarounds that make it possible to use the jQuery validation plugin on WebForms pages, without re-architecting the page or its forms. In this post, I’ll show you why the WebForms page structure is a problem, how to make jQuery validation work with it, and an example of implementing those workarounds.

Note: I want to preface this by saying that you should never rely entirely on client-side validation. The jQuery validation plugin can be a great replacement for the client-side part of the ASP.NET Validators, but it is not a complete replacement on its own. Use responsibly!

<form> over function

When it comes to using jQuery validation, the trouble with WebForms is that it requires all of the ASP.NET controls on a page to be contained within a single form element. That doesn’t lead to any problems in simple demos, but things are more complicated when it comes to real-world pages. They often require multiple logical forms on the same page, and that’s where the problems start.

For example, consider the common scenario of having both a login form and a customer information form on the same page. We’ve probably all seen something like this before:

<form id="form1" runat="server">
  <fieldset>
    <legend>Returning customer?  Login here</legend>
 
    <label for="Username">Email:</label>
    <asp:TextBox runat="server" ID="Username" />
 
    <label for="Password">Password:</label>
    <asp:TextBox runat="server" ID="Password" TextMode="Password" />
 
    <asp:Button runat="server" ID="Login" Text="Login" />
  </fieldset>
 
  <fieldset id="BillingInfo">
    <legend>New customer?  Provide the following</legend>
 
    <label for="FirstName">First Name:</label>
    <asp:TextBox runat="server" ID="FirstName" CssClass="required" />
 
    <label for="LastName">Last Name:</label>
    <asp:TextBox runat="server" ID="LastName" CssClass="required" />
 
    <label for="Address">Address:</label>
    <asp:TextBox runat="server" ID="Address" CssClass="required" />
 
    <label for="City">City:</label>
    <asp:TextBox runat="server" ID="City" CssClass="required" />
 
    <label for="State">State:</label>
    <asp:TextBox runat="server" ID="State" CssClass="required" />
 
    <label for="Zip">Zip:</label>
    <asp:TextBox runat="server" ID="Zip" CssClass="required" />
 
    <asp:Button runat="server" ID="Order" Text="Submit Order" />
  </fieldset>
</form>

In most web frameworks, you would divide both logical forms into separate form elements, but WebForms requires both to remain joined within its single form element. This means that clicking either of the Button controls will submit both logical forms together.

Once applied to a form through its default usage, the jQuery validation plugin will attempt to validate all of the elements on that form any time it is submitted. That automation is usually handy, but it means users trying to submit our login form will be denied due to validation failing on the unrelated fields below.

Since using separate form elements containing WebForms controls isn’t realistic, we need to tackle this on the client-side and find a way to make jQuery validation more WebForms-friendly.

Taming jQuery validation

To remedy this problem, we first need to prevent the jQuery validation plugin from automatically triggering on every form submission. The initializer’s onsubmit property allows us to do just that:

$(document).ready(function() {
  // Initialize validation on the entire ASP.NET form
  $("#form1").validate({
    // This prevents validation from running on every
    //  form submission by default.
    onsubmit: false
  });
});

That fixes our problem of the login form triggering unwanted validation in the form below, but it creates another issue. Now, neither of the forms will validate when submitted.

Taking control with on-demand validation

Instead of relying on the plugin to automatically validate form submissions, you may also use a less widely known method for triggering the validation on-demand. When added to a page, one of the new methods that jQuery validation exposes on the jQuery object is valid().

When valid() is called on the jQuery object returned from selecting a “validated” form element, it will trigger validation on every field within the form and return a Boolean value indicating whether or not the form is valid.

$(document).ready(function() {
  $("#form1").validate({
    onsubmit: false
  });
 
  $("#Order").click(function(evt) {
    // Validate the form and retain the result.
    var isValid = $("#form1").valid();
 
    // If the form didn't validate, prevent the
    //  form submission.
    if (!isValid)
      evt.preventDefault();
  });
});

At first glance, this code might look incomplete to you. We care about more than just preventing form submissions when the form fails validation; we must also indicate the validation errors to the user.

Fortunately, the valid() method has the very useful side effect of displaying the plugin’s configured validation errors for any fields it finds to fail validation.

From the user’s perspective, this implementation is the same as the original one using the default usage. This method just happens to also have the added benefit of actually allowing returning users to log in.

To be continued…

This solution is a good start, but has (at least) two flaws.

First, it doesn’t handle keyboard triggered form submissions. What happens if the user hits the enter key in one of the TextBoxes?

Second, what if we want to also validate the login form? If validation rules are added to that form’s fields, we’ll have exactly the opposite problem as what we started with. Valid submissions in the lower form will be prevented by validation failures on the upper form.

For solutions to both of those problems, be sure to read my followup post: Emulate ASP.NET WebForms validation groups with jQuery validation.

Download the Source

You've been reading Using jQuery validation with ASP.NET WebForms, originally posted at Encosia. I hope you enjoyed it, and thanks for reading.

Related posts:

1. Using jQuery to enhance ASP.NET AJAX progress indication
2. Use jQuery and quickSearch to interactively search any data
3. 7 of my favorite jQuery plugins for use with ASP.NET

However, you almost unanimously commented that it was too difficult to read the commands typed at the console, and you were right. So, Craig and I re-recorded the entire thing, paying extra attention to the legibility of the end result.

Craig also managed to edit the same content down to 9:59m this time, so you can watch it on YouTube if you prefer:

If the HQ version of the YouTube video still isn’t legible enough for you, Craig also made a full resolution WMV available as well.

You've been reading Updated: See how I used Firebug to learn jQuery, originally posted at Encosia. I hope you enjoyed it, and thanks for reading.

Related posts:

1. See how I used Firebug to learn jQuery
2. Highslide JS .NET Updated (v0.5)
3. Using jQuery to directly call ASP.NET AJAX page methods

Without understanding the underlying mechanisms well, developing successful solutions is as much a function of luck as it is skill; especially when it comes to debugging and maintenance. So, I think a comprehensive book like this is absolutely essential.

Now with more Encosia

Already being a fan of the book, you can probably imagine my response when I got an email from Alessandro asking if I’d like to participate in the Second Edition. It was certainly the easiest decision I made that day, to say the least. I’ll be helping add new examples, writing about ASP.NET AJAX 4.0’s new features, and discussion about automating things like script compression.

Though the book is still several months away from completion, three chapters are already available via the Manning Early Access Program (MEAP) for pre-orders. In fact, one chapter of the book is freely available, so be sure to check it out.

For a full ToC, the MEAP, and more information about the book, head over to the ASP.NET AJAX in Action, Second Edition page on Manning’s site.

You've been reading Get early access to ASP.NET AJAX in Action, Second Edition, originally posted at Encosia. I hope you enjoyed it, and thanks for reading.

Related posts:

1. Three copies of ASP.NET AJAX in Action up for grabs
2. Three copies of ASP.NET AJAX in Action still available
3. Review: Advanced ASP.NET AJAX Server Controls

Personally, the syntax never bothered me. The contentType parameter is ugly, but I have a Visual Studio code snippet for the $.ajax call and rarely think about it.

That came to an end earlier this year, when I started using dataFilter. I needed to isolate my code from the “.d” issue, and wanted to take advantage of browser-native JSON parsing in Firefox 3.5 and IE8, which required a bulky dataFilter.

Repeating that entire callback function in every $.ajax call was not acceptable. So, I was happy to learn that jQuery provides an excellent solution for consolidating settings to be used in multiple instances of $.ajax.

In this post, I’ll show you how to use that consolidation feature, and exactly how I am now using that to more simply call ASP.NET AJAX services with jQuery.

Configuring $.ajax’s default settings

Rather than wrapping the $.ajax call in a plugin or helper function, jQuery provides a built-in solution that I think is a better alternative:  $.ajaxSetup.

$.ajaxSetup accepts an array of settings that allows you to supply defaults for any of the parameters that you would set in an $.ajax call. Settings like contentType, type, and dataFilter are all fair game, for example.

Using this function, it’s easy to set jQuery’s $.ajax defaults to match the refined settings that we worked out together last year:

$.ajaxSetup({
  type: "POST",
  contentType: "application/json; charset=utf-8",
  data: "{}"
});

Because parameters to $.ajax override these defaults, presetting “data” to an empty JSON string is safe. Any $.ajax call that does specify a data parameter will function as expected, since the default will be ignored.

The particular issue caused by forgetting the empty data parameter can be difficult to track down, and only shows up after you’ve deployed your application to IIS. So, having the default as a safety net is recommended.

Adding JSON parsing improvements

Because $.ajaxSetup also supports setting a dataFilter, adding the “.d” isolation and browser-native JSON parsing from my last two posts is easy:

$.ajaxSetup({
  type: "POST",
  contentType: "application/json; charset=utf-8",
  data: "{}",
  dataFilter: function(data) {
    var msg;
 
    if (typeof (JSON) !== 'undefined' && 
        typeof (JSON.parse) === 'function')
      msg = JSON.parse(data);
    else
      msg = eval('(' + data + ')');
 
    if (msg.hasOwnProperty('d'))
      return msg.d;
    else
      return msg;
  }
});

This dataFilter processing is actually what pushed me to start using $.ajaxSetup in all of my own projects. It was one thing to accept multiple contentType and method declarations, but repeating the dataFilter for every $.ajax call was more than I could handle.

Putting it to work

With the ASP.NET AJAX defaults set in $.ajaxSetup, all that’s required to call a “ScriptService” or page method is the URL and a success callback:

$.ajax({
  url: "HelloWorld.asmx/Hello",
  success: function(msg) {
    console.log(msg);
  }
});

In fact, even the success callback is optional. For example, if you were periodically pinging a “heartbeat” service to keep the user’s session alive, $.ajax would only need the service’s URI.

This more concise syntax makes your service calls far more readable, especially for developers who aren’t familiar with the content-type required by ASP.NET AJAX.

Caution: Sometimes it works too well

While this is a handy way to simplify calls to ASP.NET AJAX services, do understand that $.ajaxSetup applies to all of jQuery’s AJAX derivatives. Setting the default HTTP method and content-type may also impact code and plugins that use jQuery’s built-in communication functionality (e.g. $.getJSON, $.post, etc).

For example, I often use jTemplates as a client-side templating solution. Because its processTemplateURL routine relies on $.ajax to retrieve remote template files, setting the ASP.NET AJAX content-type and POST method in $.ajaxSetup breaks that functionality of jTemplates.

Fixing that problem wasn’t difficult, but it also wasn’t immediately obvious what had caused the issue in the first place. In my experience using this technique, the undesirable side effects are rare enough that it’s not a serious concern, but do be aware of the potential.

Conclusion

I’ve been using this in production for several months now, with great results. Users have noticed the increased speed that came with browser-native JSON parsing, the “.d” isolation has reduced regression errors due to some code we run on both 2.0 and 3.5 servers, and it requires less effort on my part to do all that.

What do you think? Is this helpful?

Would a Visual Studio template with this rolled in be something you would use?

You've been reading Simplify calling ASP.NET AJAX services from jQuery, originally posted at Encosia. I hope you enjoyed it, and thanks for reading.

Related posts:

1. Using complex types to make calling services less… complex
2. Using jQuery to Consume ASP.NET JSON Web Services
3. 3 mistakes to avoid when using jQuery with ASP.NET AJAX

On one hand, eval() is the fastest widely available method, but it is not safe.

On the other hand, textual JSON parsers written in JavaScript may be much safer, but are dramatically slower. In client-side situations, where milliseconds count, such a large performance overhead is typically too prohibitive to accept.

Recently, an exciting new alternative has emerged: browser-native JSON parsing. Integrating JSON parsing as part of the browser’s implementation of JavaScript allows for using the more secure parsing method, and even provides performance faster than eval() offers.

To take advantage of that, this post will show you how to detect whether or not a browser supports native JSON parsing, and how to force jQuery to use browser-native parsing in its $.ajax calls when it is available.

Native JSON parsing in the browser

Previously known as ECMAScript 3.1, ECMAScript “Fifth Edition” (the specification that JavaScript implements) formally codifies a native JSON parsing feature. The spec’s API exactly mirrors that of Crockford’s implementations of JSON.parse and JSON.stringify in json2.js, easing the transition to browser-native functionality.

This native JSON parsing brings marked improvements in terms of both security and performance. Not only does the native routine use textual parsing to avoid the risk of executing malicious code embedded within JSON, but it is also fast.

At the time of this writing, three major browsers already include support for native JSON parsing: IE8, Firefox 3.5, and Chrome 3.

Safari 4 does not currently support the standard, but its underlying engine (WebKit) has recently implemented it. Hopefully the feature will make its way to Safari soon.

Detecting native JSON support

Determining whether or not native JSON parsing is available within a given browser is the first problem we need to solve. To do this, we ultimately need to know if the JSON.parse function is defined.

We can’t test for JSON.parse directly because attempting to reference it will throw a JavaScript error if the underlying JSON object doesn’t exist. So, first we need to inspect the type of that underlying object itself:

if (typeof(JSON) === 'object') { 
  // native JSON may be available.
}

If we find that the JSON object does exist, it’s likely that native JSON parsing is available. However, it’s a best to double check the JSON.parse function as well:

if (typeof(JSON.parse) === 'function') {
  // native JSON parsing is available.
}

Because JavaScript performs short-circuit evaluation, it’s safe to clean this up by combining both tests in a single conditional, as long as they’re in this order:

if (typeof(JSON) === 'object' && 
    typeof(JSON.parse) === 'function') {
  // Native JSON parsing is available.
}

Curious whether your browser supports native JSON parsing? Using the JavaScript above, I have determined that:

Extending jQuery to use native JSON parsing

In my previous post, I demonstrated how to use jQuery’s dataFilter to transform a JSON response before it is returned to the $.ajax() success handler. In the process, we also preempted jQuery’s default method for deserializing JSON data.

The focus at that time was implementing the same method for JSON parsing that jQuery uses by default, so eval() was still used. However, we can also use the same dataFilter mechanism to force browser-native JSON parsing instead.

Using our JSON parsing detection code and a dataFilter callback, upgrading jQuery to use browser-native parsing is simple:

$.ajax({
  // Your usual $.ajax() URL, data, dataType, etc.
  dataFilter: function(data) {
    if (typeof (JSON) !== 'undefined' && 
        typeof (JSON.parse) === 'function')
      return JSON.parse(data);
    else
      return eval('(' + data + ')');
  }
});

Because jQuery only attempts to deserialize JSON responses if their type is string, and because the dataFilter callback executes before jQuery would normally perform that deserialization, this technique preempts jQuery’s JSON evaluation completely. In the worst case, it will simply revert back to the same eval() method that jQuery internally uses by default anyway.

Note: It’s important to keep in mind that the dataFilter will run regardless of what type is actually returned from the server. You should only use this when you’re sure that you’re receiving a JSON string.

Conclusion

If you’ve been paying close attention to jQuery’s ongoing development, you may already know that jQuery 1.3.3 will provide functionality very similar to what I’ve shown you. I decided to go ahead and write this post anyway for a few reasons:

• You can use this today, without waiting for jQuery 1.3.3.
• You can use this in previous versions of jQuery, if upgrading isn’t feasible for you (as is often the case with plugins dependent on older versions).
• If you use my technique for isolating your code from ASP.NET AJAX’s “.d”, you will still need a method for deserializing JSON in the dataFilter.

Speaking of that last point, if you’re using jQuery with ASP.NET AJAX services, be sure to watch out for the next post in this (accidental) series. There is at least one more productive step left in improving this workflow that I have been using in my projects and want to share with you soon.

You've been reading Improving jQuery’s JSON performance and security, originally posted at Encosia. I hope you enjoyed it, and thanks for reading.

Related posts:

1. Never worry about ASP.NET AJAX’s .d again
2. Using jQuery to Consume ASP.NET JSON Web Services
3. 3 mistakes to avoid when using jQuery with ASP.NET AJAX

After hours and hours of slamming my head into the desk it turns out it was the darn "d" in the response. My home computer is on .NET 2.0 and my work computer is on 3.5. Jimminie Christmas!

I realized that the “.d” introduced in ASP.NET AJAX 3.5’s JSON responses is still all too common a stumbling block when calling ASP.NET AJAX services through a library such as jQuery. In fact, with jQuery’s popularity among ASP.NET developers on the rise, this appears to have become an even more frequent problem.

Since a lot of people are having trouble with it, I want to share one method you can use to completely isolate your code from the problem. If you bake this into an $.ajax() code snippet or otherwise use it as a template for calling ASP.NET AJAX services in jQuery, you should never have to think or worry about the “.d” again.

In this post, I will show you how to detect the “.d” and how you can completely isolate your $.ajax success handler from it.

“.d” what?

If you aren’t familiar with the “.d” I’m referring to, it is simply a security feature that Microsoft added in ASP.NET 3.5’s version of ASP.NET AJAX. By encapsulating the JSON response within a parent object, the framework helps protect against a particularly nasty XSS vulnerability.

Before ASP.NET 3.5, “ScriptServices” and page methods returned their data at the top level of the JSON response, like this:

In ASP.NET 3.5 and later, the same server-side code returns this:

For more information about the change and why the change is a good one, be sure to see my earlier post: A breaking change between versions of ASP.NET AJAX.

However, what my previous post lacks is a solution for mitigating the inconsistency entirely. Using different client-side code against 2.0 and 3.5 based services is workable, but far from ideal. Wouldn’t it be nicer to not have to worry about it?

Determining whether or not the “.d” is there

In order to isolate ourselves from the “.d”, we first need a reliable way to test for its presence. Though JavaScript provides several methods for determining this, I suggest hasOwnProperty, as recommended by Douglas Crockford.

By using hasOwnProperty, your code is protected against unexpected changes to an object’s prototype chain. Though it is an unlikely problem to encounter, it’s always best to code defensively in JavaScript. The browser is a hostile environment!

Using hasOwnProperty to test for “.d”, you might end up with something like this:

$.ajax({
  type: "POST",
  url: "WebService.asmx/MethodName",
  data: "{}",
  contentType: "application/json; charset=utf-8",
  dataType:"json",
  success: function(msg) {
    if (msg.hasOwnProperty("d"))
      // Leave the .d behind and pass the rest of 
      //  the JSON object forward.
      DoSomething(msg.d);
    else
      // No .d; no transformation necessary.
      DoSomething(msg);
  }
});
 
function DoSomething(msg) {
  // Do something with the response data here.
  //  Expect it to consistently have no .d.
}

This code will perform identically against any version of ASP.NET AJAX.

Unfortunately, this might still get in your way. You may not always want to use the response in a call to another function, and you’ll have to remember the conditional every time you write a success handler.

Don’t make me think

I prefer a solution that doesn’t touch the success handler at all. Then, you’re free to integrate the “.d” handling into a generic $.ajax code snippet in Visual Studio and/or easily copy-paste it between files without modification.

Luckily, jQuery provides a mechanism that allows us to do just that: dataFilter.

The dataFilter parameter to $.ajax allows you to arbitrarily transform a response just before the success handler fires. Specifically tailored to this sort of situation, it passes response data into a callback function, captures the return value of that callback, and then passes the modified data into your success handler.

Hence, you can forever stop worrying about that pesky “.d” like this:

$.ajax({
  type: "POST",
  url: "WebService.asmx/MethodName",
  data: "{}",
  contentType: "application/json; charset=utf-8",
  dataFilter: function(data) {
    // This boils the response string down 
    //  into a proper JavaScript Object().
    var msg = eval('(' + data + ')');
 
    // If the response has a ".d" top-level property,
    //  return what's below that instead.
    if (msg.hasOwnProperty('d'))
      return msg.d;
    else
      return msg;
  },
  success: function(msg) {
    // This will now output the same thing 
    //  across any current version of .NET.
    console.log(msg.foo);
  }
});

Now, regardless which of these JSON forms the server returns:

// ASP.NET 2.0 with the ASP.NET AJAX Extensions installed.
{'foo':'bar'}
 
// ASP.NET 3.5 and 4.0.
{'d':{'foo':'bar'}}

Your success handler will simply receive this consistent JSON object every time:

{'foo':'bar'}

dataType: none of your business

It’s important to note the removal of the dataType parameter in the $.ajax() code above. This is required in order to prevent a double-eval of service responses containing only a single string.

Internally, jQuery uses a combination of the dataType parameter and the implicit type the response. If the dataType is "json" and typeof(response) is “string”, then jQuery uses eval() to deserialize the response.

In the example above, manually deserializing the response in dataFilter results in it being of type Object, jQuery leaves it alone, and our dataFilter’d object makes its way back to the success callback either way.

However, if the dataType is set to “json” and the “.d” sanitized response happens to be of JavaScript type “string”, jQuery will assume that it is a JSON response from the server and still needs to be deserialized. That will throw an error at best.

The solution is to simply drop the dataType parameter from the $.ajax() call. It is only needed for purposes of instructing jQuery how to deserialize the response, and we’re handling that ourselves now.

Thanks to Brett for pointing this out.

Wait, isn’t eval() supposed to be evil?

If the eval() usage gives you pause, don’t worry. For now (as of jQuery 1.3.2), this is the same mechanism that jQuery uses to deserialize JSON too. Though eval() is potentially evil, it is still a necessary evil in many browsers.

In my next post, I’ll show you how to modify this to leverage a native browser implementation of JSON.parse instead of eval(), available in some newer browsers.

That post is available now: Improving jQuery’s JSON performance and security.

You've been reading Never worry about ASP.NET AJAX’s .d again, originally posted at Encosia. I hope you enjoyed it, and thanks for reading.

Related posts:

1. 3 mistakes to avoid when using jQuery with ASP.NET AJAX
2. Using jQuery to directly call ASP.NET AJAX page methods
3. A breaking change between versions of ASP.NET AJAX

To combat this, it’s important to combine and compress your JavaScript. While there are useful standalone tools and HttpHandler based solutions to the problem already, none of them work quite how I prefer. Instead, I’m going to show you my dead-simple method for automatically compressing and combining script includes.

To accomplish that in this post, we will select a compression utility, learn how to use it at the command line, explore a useful automation feature in Visual Studio, and apply that to keep scripts combined and compressed with no ongoing effort.

Selecting a JavaScript compression tool

The first thing we’ll need is a utility to compress our JavaScript. There are many utilities available, ranging from YUI Compressor to Dean Edwards’ Packer, each with its own strengths and weaknesses.

YUI Compressor is powerful, but requires a Java runtime be available during the build process. Packer is popular for its Base62 encoding mode, however that form of compression carries a non-trivial performance tax on the client-side.

In terms of simplicity, it’s hard to beat Douglas Crockford’s JSMin. It requires no command line options, no runtimes or frameworks, and accepts input directly from standard input (which will be useful for us later).

One common concern about JSMin is that it outputs less compact code than YUI Compressor and Packer on their most aggressive settings. However, this is a bit of a red herring. When gzipped, the result of all three boil down to almost exactly the same size across the wire. Since you should always serve your JavaScript with gzip compression at the HTTP level, this initial “disadvantage” is moot.

Using JSMin from the command line

Using JSMin is very straightforward. For example, say we have the following, well-commented JavaScript and want to minify it:

// how many times shall we loop? 
var foo = 10;
 
// what message should we use? 
var bar = 'Encosia';
 
// annoy our user with O(foo) alerts! 
for (var i = 0; i < foo; i++) { 
  alert(bar); 
}

Assuming that JavaScript is in a file called AlertLoop.js, this command line usage of JSMin will minify it and output it to the console:

jsmin < AlertLoop.js

What this does is run jsmin and feed the contents of AlertLoop.js into standard input. It’s the same as if you had run jsmin and then typed all that JavaScript on the command line.

Similarly, this usage does the trick if you want to redirect that output to a file:

jsmin < AlertLoop.js > AlertLoop.min.js

The minified output is less than half the size of the original. Not bad!

Note: If you’re wondering about the upper ASCII characters preceding the minified script, they’re nothing to be concerned about. Because I had created AlertLoop.js in Visual Studio, it was saved as UTF-8 by default and those characters are the UTF BOM (thanks to Oleg, Sugendran, and Bart for clarification).

Set up project directories

Before we get to the next steps, we need to define a structure for our project. The one shown to the right works for simple projects.

Within the website project, the important takeaway is that the JavaScript files to be compressed are all in the same directory and named with a *.debug.js pattern.

Outside of the website, notice the “tools” directory which contains a copy of JSMin. I think we can all agree that executables should not be included within a website project if possible. That would just be begging for trouble.

However, I do suggest including an external tools directory and JSMin executable in your project’s source control. You never want to create a scenario where someone can’t perform a checkout and then a successful build immediately afterward.

Automation: Visual Studio earns its keep

To automate script compression as part of the build process, I suggest using a build event. There are perfectly legitimate alternatives, but I prefer having a tangible file sitting on disk and having that compression process automated. So, “building” the minified JavaScript include(s) as part of the build process makes the most sense to me.

Build events may sound complicated, but they aren’t at all. Build events are simply a mechanism for executing command line code before and/or after your project is compiled.

For our purposes, a post-build event is perfect. Additionally, we can specify that it should only run the build event if the project builds successfully. That way we avoid wasting unnecessary time on minifying the JavaScript when there are build errors.

Setting up a build event in Visual Studio

To add build events, right-click on your project and choose properties. In the properties page that opens, click on the “Build Events” tab to the left. You’ll be presented with something similar to this:

Note: If you’re using Visual Basic, there will be no build events tab in the project properties. Instead, look for a build events button on the “Build” tab, which allows access the same functionality.

You can type commands directly in the post-build field if you want, but clicking the “Edit Post-build” button provides a better editing interface:

The interface’s macro list is especially useful. In particular, the ProjectDir macro will be handy for what we’re doing. $(ProjectDir) placed anywhere in a build event will be replaced with the actual project path, including a trailing backslash.

For example, we can use it to execute JSMin.exe in the hierarchy described above:

$(ProjectDir)..\tools\jsmin.exe

Or, reference that same project’s js directory:

$(ProjectDir)js\

Putting it all together: Minify a single file

Now that we’ve covered how to use JSMin at the command line and how to execute command line scripts as part of Visual Studio builds, putting it all together is easy.

For example, to minify default.debug.js, this post-build event will do the trick:

"$(ProjectDir)..\tools\jsmin" < 
"$(ProjectDir)js\default.debug.js" > 
"$(ProjectDir)js\default.min.js"

(The line breaks are for readability here. The command in your actual build event must not contain them, or it will be interpreted as separate commands and fail.)

The quotes are important, in case $(ProjectDir) happens to include directories with spaces in their names. Since you never know where this project may eventually be built at, it’s best to always use the quotes.

*Really* putting it together: Combine files

I did promise more than just compression in the post’s title. Combining scripts is just as important as compression, if not more so. Since JSMin takes its input from stdin, it’s easy to roll scripts together for minification into a single result:

type "$(ProjectDir)js\*.debug.js" | 
"$(ProjectDir)..\tools\jsmin" > 
"$(ProjectDir)js\script-bundle.min.js"

This build event would combine all of our *.debug.js scripts, minify the combined script bundle, and then output it in a new file named script-bundle.min.js.

This is great if you want to combine your most commonly used jQuery plugins into a single payload, for example. A reduction in HTTP requests usually provides a nice improvement in performance. This is especially true when you’re dealing with JavaScript, because the browser blocks while script references load.

Dealing with dependencies

Cross-dependencies between scripts is one issue that requires extra consideration when combining. Just the same as ordering script includes incorrectly, bundling scripts together in the wrong order may cause them to fail.

One relatively easy way to handle this is to give your scripts prefixes to force the correct order. For example, the source sample below includes this set of JavaScript files:

default.debug.js
jQuery-1.3.2.debug.js
jQuery-jtemplates.debug.js

Combining these and referencing the result will fail, because default.debug.js is sorted ahead both jQuery and the plugin by default. Since default.debug.js depends on both of those, this is a big problem. To fix this, rename the files with prefixes:

01-jQuery.debug.js
05-jQuery-jtemplates.debug.js
10-default.debug.js

Now it will work perfectly.

Any system of alphanumeric prefixes will work, but be sure to pad numbers with leading zeroes if you use a numeric system. Otherwise, the default sort ordering may catch you off guard (e.g. 2-file.js sorts ahead of 11-file.js through 19-file.js).

To debug, or not to debug

Now that we have the minification process under control, one final issue to address is how to keep this from complicating our development workflow.

While editing these scripts, we certainly don’t want to be forced to recompile every time we make a change to the JavaScript. After all, one of the nice things about JavaScript is that it doesn’t require precompilation. Even worse, using a JavaScript debugger against minified files is a nightmare I wouldn’t recommend to anyone.

The easiest way I know of to ensure that the correct scripts are emitted for both scenarios is to check the IsDebuggingEnabled property of the HttpContext:

<head>
<% if (HttpContext.Current.IsDebuggingEnabled) { %>
  <script type="text/javascript" src="js/01-jquery-1.3.2.debug.js"></script>
  <script type="text/javascript" src="js/05-jquery-jtemplates.debug.js"></script>
  <script type="text/javascript" src="js/10-default.debug.js"></script>
<% } else { %>
  <script type="text/javascript" src="js/js-bundle.min.js"></script>
<% } %>
</head>

When the web.config’s compilation mode is set to debug, the *.debug.js versions of the files are referenced, and the auto-minified bundle otherwise. Now we have the best of both worlds.

Conclusion

I hope you’ll find that this technique is a good compromise between the tedium of using manual minification tools and the overwrought complexity of setting up some of the more “enterprisey” automation solutions.

One not-so-obvious benefit that I’ve noticed stems from minification’s automatic comment stripping. Without worry about your comments burdening the size of the client-side payload or being distributed across the Internet, you’re more likely to comment your JavaScript well. Dealing with a dynamic language, sans-compiler, I find that comments are often crucial to maintainability.

This is one of those problems with quite a few perfectly legitimate solutions. What do you think of this solution? How do you normally handle this?

Get the source

For demonstration, I took my jQuery client-side repeater example and applied this technique. Having several JavaScript includes (one that’s full of comments), it’s a perfect candidate for combining and compression.

One particular thing to notice in this example is the use of numeric prefixes to order the JavaScript includes, as mentioned earlier. This naming scheme is crucial when dealing with interdependent scripts. If the scripts are combined in the wrong order, your functionality will break just the same as if you had used script reference tags in the wrong order.

You've been reading Automatically minify and combine JavaScript in Visual Studio, originally posted at Encosia. I hope you enjoyed it, and thanks for reading.

Related posts:

1. How to rotate JavaScript ads during ASP.NET AJAX requests
2. Updated your web.config, but Sys is still undefined?
3. Seamless inline text editing with ASP.NET AJAX

Reading this here, there’s a good chance the article is targeted below the amount of jQuery expertise you already have. However, it’s been brought to my attention that some readers have found it useful for sending to their more JavaScript-phobic coworkers.

So, I decided that it’s worth mentioning here after all:

It’s hard to believe that JavaScript is already well over a decade old. Often relegated to marginal tasks in its early years, JavaScript has grown to become a pillar of modern web development. With the current popularity of DHTML and AJAX, it can be difficult to find a site that doesn’t use JavaScript anymore. One of the driving forces behind JavaScript’s newfound popularity is a proliferation of JavaScript frameworks, such as jQuery.

 

Why?

Click here to continue reading this article on the MIX Online site »

You've been reading What ASP.NET developers should know about jQuery, originally posted at Encosia. I hope you enjoyed it, and thanks for reading.

Related posts:

1. Using jQuery to directly call ASP.NET AJAX page methods
2. Alt.NET Podcast – jQuery in ASP.NET
3. Using jQuery to Consume ASP.NET JSON Web Services

The problem of how to handle dates in JSON is one of the more troublesome issues that may arise when directly calling ASP.NET AJAX web services and page methods.

Unlike every other data type in the language, JavaScript offers no declarative method for expressing a Date. Consequently, embedding them within JSON requires a bit of fancy footwork. Since the question of how I handle this problem is something asked often in emails and in comments on other posts here, I want to address the topic with its own post.

To that end, I will attempt to explain what exactly the problem is with dates in JSON, how ASP.NET AJAX solves it, and my alternative solution that I believe is easier and works just as well in most cases.

What’s the problem?

The fundamental problem is that JavaScript does not provide a way to declaratively express Date objects. You may previously have seen this described as (the lack of) a Date literal.

What are literals? To illustrate, these are literals for several other data types:

// String
'foo';
 
// Number
3.14;
 
// Boolean
true;
 
// Array
[1, 2, 3, 5, 7];
 
// Object
{ pi: 3.14, phi: 1.62 };

Unfortunately, when it comes to dates, the lack of a literal means that the only way to create one is by explicitly initializing a Date object:

// Correct.
new Date('4/26/09');
 
// Correct (the month is 0 indexed, hence the 3).
new Date(2009, 3, 26);
 
// Incorrect. This is a string, not a Date.
'4/26/09';

While this limitation is fine when writing client-side JavaScript code, it leaves us without a good way to transmit dates within JSON objects.

How ASP.NET AJAX handles it

While the lack of a date literal is a problem, it’s certainly not without solution.

In fact, ASP.NET AJAX already handles this if you’re using MicrosoftAjax.js to call your services. You may not have even noticed as server-side DateTime values are transparently converted into JavaScript Date objects on the client-side.

For example, consider this web service:

[System.Web.Script.Services.ScriptService]
public class DateService : System.Web.Services.WebService
{
  [WebMethod]
  public DateTime GetDate()
  {
    return new DateTime(2009, 4, 26);
  }
}

If you consume that web service with jQuery (or any method that circumvents the ScriptManager), you’ll find that ASP.NET AJAX serializes the DateTime as an escaped JavaScript Date initializer:

{"d":"\/Date(1240718400000)\/"}

Note: If you’re unsure about why the “d” is there, be sure to see my recent post about this security feature which was added in ASP.NET 3.5.

On the client-side, MicrosoftAjax.js uses a regular expression to isolate any Date constructors and then eval() to initialize Date objects. The end result is that proper JavaScript Date objects are instantiated for every DateTime value returned.

However, if you’re not using MicrosoftAjax.js (i.e. the ScriptManager) to call your services, you’ve got a bit of a mess to decode. You can use regex machinations to work around the problem, but is that really necessary?

How I handle it

Consider why you want to send a DateTime to the client-side to begin with. Most often, you’re displaying a string representation of it and have no need for the proper JavaScript Date object.

What’s more, if you end up with a JavaScript Date object, you’ll probably use additional code or a JavaScript library to display it in a user-friendly format.

As much as I appreciate a clever workaround, I’d much rather avoid the problem completely. Rather than jump through all of these hoops to instantiate a JavaScript Date object on the client-side and then format it, I suggest simply returning a formatted string.

For example, we might modify the previous example like so:

[System.Web.Script.Services.ScriptService]
public class DateService : System.Web.Services.WebService
{
  [WebMethod]
  public string GetDate()
  {
    return new DateTime(2009, 4, 26).ToLongDateString();
  }
}

Now, calling the service will return this JSON:

{"d":"Sunday, April 26, 2009"}

No more regular expressions. No more JavaScript Date objects. No more worrying about formatting the data on the client-side.

Even better, no functionality is lost. If we need to instantiate Dates, we still can.

Still want Dates?

Even if you do end up needing JavaScript Date objects, DateTime strings are sufficient for instantiating them. JavaScript’s Date constructor is very flexible:

// ASP.NET AJAX form
var foo = new Date(1240718400000);
 
// DateTime.ToLongDateString() form
var bar = new Date('Sunday, April 26, 2009');
 
// DateTime.ToShortDateString() form
var baz = new Date('4/26/2009');
 
// true!
foo === bar === baz;

By delaying string-to-Date conversions until truly necessary, we save effort on the server- and client-side. Not only that, but we have the option of retaining both the formatted string and the JavaScript Date to use as desired.

The best of both worlds.

You've been reading How I handle JSON dates returned by ASP.NET AJAX, originally posted at Encosia. I hope you enjoyed it, and thanks for reading.

Related posts:

1. A breaking change between versions of ASP.NET AJAX
2. 3 mistakes to avoid when using jQuery with ASP.NET AJAX
3. Using jQuery to Consume ASP.NET JSON Web Services