Hey Dave, is there a way to create an event handler so when .tmpl() is done it will fire a function? I’m trying to make it global, so I was hoping I could say, when ANY template gets done, do this…

The question of how to retroactively add hooks before and/or after a pre-existing JavaScript function executes is one that comes up from time to time. Whether it’s a simple method like tmpl(), a server-generated script artifact, or a function in a third-party script, sometimes it’s desirable to alter a JavaScript function without access to change the original declaration of the function.

One of the handy things about JavaScript is that you can combine its functional and dynamic aspects to make surprisingly quick work of tasks like this one. Doing so is fairly straightforward, but it involves an approach you might not consider if you’re more familiar with languages that lack JavaScript’s unique features.

In this post, I’ll briefly cover a few examples of how to “patch” existing JavaScript functions with callbacks. We’ll begin with simple examples, then address an issue that stems from applying this approach to jQuery plugins, and finish with a more elegant way to handle the problem of patching functions that accept parameters.

A simple() example

Let’s start with the simplest possible example, a function that accepts no arguments and returns nothing:

function simple() {
  // I am a black box.
}

Maybe that function is pre-defined and emitted by server-side code. Maybe it’s part of a script you’re referencing from a public CDN. For whatever reason, assume that this function is part of your page, but that you don’t have the ability to directly change its code.

If you need to run some of your own code before and/or after any time the simple() function is called, you can use a technique called monkey patching to achieve that without access to the original function declaration.

// Get a reference to the previously defined simple() function.
var oldSimple = simple;
 
function simple() {
  // Code that runs before any call to simple() here.
 
  // Make a call to the old/previous simple() function.
  oldSimple();
 
  // Code that runs after any call to simple() here.
}

Since functions are just like any other variable in JavaScript, it’s that simple.

Without touching the original simple() function declaration, this snippet has effectively redefined it anyway. Calls to the original function will also execute our before and after code now, unaware that anything has changed.

Parameters and external “event” handlers

If you want to apply this technique to a function that accepts parameters, you’ll also need to capture and relay those parameters.

Take this more complex function, for example:

function complex(foo, bar, baz) {
  // An assortment of black boxes.
}

You could patch in a “before” event, parameters unimpeded, like this:

var oldComplex = complex;
 
// Capture the parameters that the original complex()
//  function expects.
function complex(foo, bar, baz) {
  // Call onBeforeComplex() if it's defined when this runs, and
  //  pass a copy of the parameters that complex() was called with.
  if (typeof onBeforeComplex === 'function')
    onBeforeComplex(foo, bar, baz);
 
  // Call the original function, parameters included.
  oldComplex(foo, bar, baz);
}

Using a separate onBeforeComplex() function instead of inline code isn’t necessary, but I prefer that approach. Now, you can drop this code into a script include anywhere after complex() is defined and then declare the “handler” function anywhere on the page (or not at all).

Passing foo, bar, and baz to onBeforeComplex() is optional, of course, but it’s usually helpful to know something about what sort of call triggered the event.

Applying this to jQuery plugins

Now let’s apply this technique to the real-world problem of updating tmpl(). Doing that isn’t much more difficult than the previous example, but we do need to identify the method’s signature first so that we can apply the patch.

Digging into the last version of jQuery.tmpl.js on GitHub, the function we’ll need to override can be found beginning on line 80:

So, the function we’ll need to patch is jQuery.fn.tmpl. Given the previous examples, you might thing it would be as easy as this:

var oldTmpl = jQuery.fn.tmpl;
 
jQuery.fn.tmpl = function(data, options, parentItem) {
  if (typeof onBeforeTmpl === 'function')
    onBeforeTmpl(data, options, parentItem);
 
  oldTmpl(data, options, parentItem);
}

Unfortunately, that will break tmpl() (in two separate ways, no less).

jQuery plugins make “this” more complicated

Applying the monkey patching approach to functions that operate on and return jQuery collection objects, such as the tmpl() plugin that led to this post, requires extra consideration. The crux of jQuery’s fluent API is that chainable jQuery methods both operate upon and return an instance of the jQuery object.

Now that we’re interjecting an additional level of abstraction, we need to be sure to maintain the scope of this down into the original jQuery plugin method and preserve the original function’s return value. Otherwise, our intermediary function will break jQuery’s chaining.

Using apply() to call the original function allows us to control its this value:

var oldTmpl = jQuery.fn.tmpl;
 
// Note: the parameters don't need to be named the same as in the
//  original. This could just as well be function(a, b, c).
jQuery.fn.tmpl = function(data, options, parentItem) {
  if (typeof onBeforeTmpl === 'function')
    onBeforeTmpl.apply(this, [data, options, parentItem]);
 
  // Make a call to the old tmpl() function, maintaining the value 
  //  of "this" and its expected function arguments.
  var tmplResult = oldTmpl.apply(this, [data, options, parentItem]);
 
  if (typeof onAfterTmpl === 'function')
    onAfterTmpl.apply(this, [data, options, parentItem]);
 
  // Returning the result of tmpl() back so that it's actually 
  //  useful, but also to preserve jQuery's chaining.
  return tmplResult;
};

By capturing the return value of the original tmpl() function and returning that back to the original caller, chaining is preserved at that previous level. That’s particularly important in this specific example because that return value is the rendered template.

Better argument handling

If you’re like me, explicitly capturing and passing each individual function parameter doesn’t feel great. Not only is it extra work to determine how many parameters a method accepts, but our patched version of tmpl() would stop working correctly if the original were updated to begin accepting additional parameters.

We can improve this situation easily enough by taking advantage of JavaScript’s built-in way to capture all of the parameters that were passed to a function. Aptly named arguments, this so-called array-like object is perfect for eliminating the explicit plumbing code to pass parameters between the patched function and the original.

Even better, arguments will capture all the parameters passed into a function even if that function’s declaration doesn’t accept parameters at all. So, now there’s no need to worry about matching the original’s function signature:

var oldTmpl = jQuery.fn.tmpl;
 
jQuery.fn.tmpl = function() {
  if (typeof onBeforeTmpl === 'function')
    onBeforeTmpl.apply(this, arguments);
 
  var tmplResult = oldTmpl.apply(this, arguments);
 
  if (typeof onAfterTmpl === 'function')
    onAfterTmpl.apply(this, arguments);
 
  return tmplResult;
};

Throw that code on a page, anywhere after the reference to jquery.tmpl.js, and then all existing usages of tmpl() will begin triggering the before and after “events”.

Conclusion

We took a circuitous route to get here, but I hope you agree that it was worthwhile to build the solution up step by step. Even if you don’t need to patch an event into tmpl(), you might be surprised how often this technique comes in handy once you’re keeping the possibility in mind.

Related posts:

1. How to easily enhance your existing tables with simple CSS
2. Using external templates with jQuery Templates
3. Composition with jQuery Templates: Why and How

You've been reading Adding your own callbacks to existing JavaScript functions, originally posted at Encosia. I hope you enjoyed it, and thanks for reading.

If you've got any feedback, please click through and leave a comment; I'd love to hear from you. You can click here to jump directly to the comment section of this post.

Work on client-side applications long enough and it’s just about inevitable that you’ll eventually want to make an AJAX request that breaches the browser’s XMLHttpRequest security restrictions. Limitations on cross-domain requests are great when they’re preventing malicious sites from malfeasing, but are a thorn in the side when they complicate your legitimate applications.

Traditionally, direct communication across the same-origin boundary required using a rickety (though clever) workaround called JSONP. JSONP is a reasonable compromise if all you need to do is make blind requests to a third-party API like Twitter, but comes up short if you need to use any HTTP verb other than GET. Of course, that’s a deal-breaking issue when you’re working with ASMX ScriptServices or ASPX page methods.

Luckily, a relatively new feature has been making its way into browsers which provides a robust solution to the cross-domain AJAX problem: CORS.

In this post, I’m going to show you how to recognize exactly which requests are cross-origin, how to enable CORS for your ASP.NET site, and the extra configuration necessary when you’re working with ASP.NET’s JSON-enabled services.

Before we get started, I want to emphasize that this approach won’t work with any version of IE prior to IE10. If supporting older versions of IE is a requirement in your target environment, you’re stuck with something like JSONP or a server-side proxy. This will work in any version of IE if Chrome Frame is installed and enabled by your site/server though.

Understanding what constitutes a different “origin”

When it comes to making cross-origin AJAX requests, it’s helpful to understand which requests actually are cross-origin. Of course, a request from a page served under one domain to a resource on an entirely different one definitely falls under the umbrella of cross-origin:

However, the common moniker for these requests, cross-domain, tends to be misleading. While a request from one domain to another is obviously cross-origin, browsers are much more picky than that.

For example, a request from foo.domain.com to bar.domain.com is just as much cross-origin request as one to abc.com. That’s not quite as intuitive as the traditional cross-domain scenario, but requires the same consideration.

A less obvious troublemaker is making a request from localhost:8080 to localhost:8081, which XMLHttpRequest’s security restrictions will also deny you from making. That’s a particularly troublesome scenario for ASP.NET developers since Visual Studio is all too happy to help you spin up a separate services/API project almost transparently hosted at its own separate port.

The easiest way to determine whether a particular request will fall under the umbrella of cross origin resource sharing is to compare the portion of both addresses appearing before the first forward slash. Any difference before the first forward slash, including the port, protocol (HTTP vs. HTTPS), and sub-domain, will thwart a traditional XHR-based AJAX request.

Enabling CORS for an ASP.NET site

Though the conventional wisdom about cross-domain or cross-origin requests has long been JSONP or nothing, a solution called Cross-Origin Resource Sharing has gained broad support in modern browsers over the past couple years. This standard defines a set of HTTP headers that a server can use to instruct browsers that it’s okay for certain XMLHttpRequest requests to that server to cross the same-origin boundary.

In the broadest case, enabling CORS for an ASP.NET site is simple. The enable-cors.org site has handy list of concise examples of how to configure a variety of servers for CORS, including IIS. For sites hosted on IIS7.0+ and Integrated Pipeline, enabling CORS is as simple as adding this to the site’s web.config:

<system.webserver>
 <httpprotocol>
  <customheaders>
   <add name="Access-Control-Allow-Origin" value="*" />
  </customheaders>
 </httpprotocol>
</system.webserver>

That simple change gets you half way there. A regular GET request for an ASPX page’s HTML would work now, for example. Unfortunately, the Content-Type necessary for working with ASMX ScriptServices throws a new wrench in the works:

As it turns out, requests to ASP.NET’s JSON-enabled endpoints require one last configuration step to allow the request to go through unimpeded.

Access-Control-Allow-Headers

Sending the Access-Control-Allow-Origin header allows basic cross-origin access, but calling ASP.NET services like ASMX ScriptServices, ASPX page methods, and WCF services with AspNetCompatibilityRequirements enabled requires jumping through a few more hoops. Namely, sending a specific Content-Type header of application/json.

One of the security precautions that the CORS specification includes is that browsers must tightly control what’s sent along with these cross-origin requests. Among the items that must be explicitly allowed: any but the most basic HTTP headers, including Content-Type.

In order for CORS requests to specify their Content-Type, your site needs to respond with one additional CORS header: Access-Control-Allow-Headers

That brings the web.config modifications necessary to this:

<system.webserver>
 <httpprotocol>
  <customheaders>
   <add name="Access-Control-Allow-Origin" value="*" />
   <add name="Access-Control-Allow-Headers" value="Content-Type" />
  </customheaders>
 </httpprotocol>
</system.webserver>

And finally, it’s possible to use the same, familiar jQuery $.ajax() syntax to request our service from same- and cross-domain origins alike:

Conclusion

Even as we’re teetering at the precipice of 2012, CORS is still a fairly new feature and lacks ubiquitous support. IE10 should support CORS as fully as Chrome and Firefox already do, but the XDomainRequest implementation in earlier versions of IE does not (to my knowledge) support Access-Control-Allow-Headers, which makes it all but useless in this scenario.

If you’re comfortable leaving the comfy confines of XMLHttpRequest and jQuery’s $.ajax, a more cross-browser friendly solution does exist: easyXDM. I haven’t personally used easyXDM beyond a bit of experimentation, but the approach it takes in older browsers is one that has been proven to be solid by similar libraries like Socket.IO.

However, if you’re working in an environment where you can mandate Chrome (or Chrome Frame in IE9-) and/or Firefox as the browser of choice, CORS is an invaluable addition to your bag of tricks (I feel like I’ve typed that phrase in another post recently…). I hope this post will help you get your feet wet with this new technology which seems to get more lip service than actual usage.

Get the source

If you’d like to browse through a complete working example of what’s been covered in this post, take a look at the companion project at GitHub. Or, if you’d like to download the entire project and run it in Visual Studio to see it in action yourself, grab the ZIP archive.

Browse on GitHubDownload the ZIP

Related posts:

1. Save yourself some typing when you call ASP.NET services
2. ASMX and JSON – Common mistakes and misconceptions
3. Using jQuery to Consume ASP.NET JSON Web Services

You've been reading Using CORS to access ASP.NET services across domains, originally posted at Encosia. I hope you enjoyed it, and thanks for reading.

If you've got any feedback, please click through and leave a comment; I'd love to hear from you. You can click here to jump directly to the comment section of this post.

One of the longest running themes here has been the compelling intersection between ASP.NET and jQuery. Beginning with my post about using jQuery to circumvent ASP.NET AJAX’s client-side apparatus for calling ASMX services, I’ve been writing about using ASP.NET and jQuery since the Spring of 2008.

As these related posts have accumulated over the years, I’ve made an effort to weave a thread of cross-links between them posts where appropriate. However, it’s nearly impossible to anticipate every possible entry point and subsequent path that someone might find themselves following here.

So, I’ve decided to finally do what I should have done a year or two ago: Create a top-level index to organize and improve the accessibility of my content for ASP.NET developers interested in integrating jQuery into their sites.

You can see my first draft of that here: jQuery for the ASP.NET Developer

Unlike the other content here, I’m publishing this one long before it’s “finished”. My hope is that I can solicit early feedback to help better construct a useful narrative while the document is still in its formative stages. So, if you have any feedback on the current page or what you think should ultimately be there, please leave me a comment on either this post or that page, contact me directly, or even @mention it my way on Twitter.

Related posts:

1. Best of 2008: 5 most popular posts
2. Best of 2007: 5 most popular posts (and contest winners)
3. 3 mistakes to avoid when using jQuery with ASP.NET AJAX

You've been reading Help me organize my posts about using jQuery with ASP.NET, originally posted at Encosia. I hope you enjoyed it, and thanks for reading.

If you've got any feedback, please click through and leave a comment; I'd love to hear from you. You can click here to jump directly to the comment section of this post.

Being able to use a web-based framework like jQuery Mobile to create a “native” mobile app is one of PhoneGap’s most appealing propositions. So, you can imagine my dismay when wrapping this latest project in PhoneGap broke its navigation. Worse yet, even closing jQuery Mobile’s dialog windows stopped working under PhoneGap 1.1.0.

Luckily, the problem ended up being a minor one with a simple fix. In this post, I’ll briefly show you why PhoneGap 1.1.0 caused jQuery Mobile’s back buttons to stop working and how you can fix that problem in your own app.

Getting back() to basics

If you’ve ever navigated through a jQuery Mobile app with the document’s address visible, you’ve probably noticed that jQuery Mobile makes heavy use of the browser’s history API to maintain state and facilitate navigation. Whether using its recently added pushState support or the more traditional hash-based history management, even something as simple as opening a dialog window creates a new history entry.

Conversely, moving back to previous states is then as simple as executing a quick history.back() in the browser. And, that’s exactly how jQuery Mobile’s built-in back buttons and dialog close buttons work. Surprisingly, that’s even what initially happens when you make a call to $.dialog('close').

Finding the problem

Knowing that the problem I faced was related to the browser’s history.back() API helped narrow it down quite a bit. The first thing I did was use Remy Sharp‘s invaluable JsConsole to establish a console session linked to the embedded browser window in my PhoneGap app. Using that interface to poke around at the browser’s history object made the problem clear:

PhoneGap’s client-side library had replaced the history.back() function with one of its own (app-native Java code, no less). Digging into the Android version of phonegap-1.1.0.js, the culprit can be found beginning at line 1,277:

PhoneGap.addConstructor(function() {
    navigator.app = new App();
    navigator.app.origHistoryBack = window.history.back;
    window.history.back = navigator.app.backHistory;
});

JavaScript’s incredible flexibility is usually a strength, but it is a bit like running with scissors at times. The latter couple lines of that function stores a reference to the browser’s native history.back function and then monkey patches it with PhoneGap’s implementation instead.

The fix

Fixing the issue could have been accomplished (at least) two different ways. Either jQuery Mobile needed to use navigator.app.origHistoryBack if it existed, or PhoneGap’s interloping needed to be curtailed. Since reverting PhoneGap’s history.back monkey patch was much simpler, I was already leaning that direction.

Then, when I saw this recent commit on GitHub, the choice was an easy one.

Presumably, this change will be included in the next PhoneGap release since it was committed to the master branch. In the meantime, you can easily apply the change to your own copy of phonegap-1.1.0.js by finding this code (beginning at line 1,277):

PhoneGap.addConstructor(function() {
    navigator.app = new App();
    navigator.app.origHistoryBack = window.history.back;
    window.history.back = navigator.app.backHistory;
});

And changing it to this:

PhoneGap.addConstructor(function() {
    navigator.app = new App();
});

As I mentioned earlier, this only impacts the Android version of PhoneGap (to my knowledge). So, don’t go digging through versions of phonegap-1.1.0.js for other platforms looking to remove this monkey patch – it isn’t there.

Related posts:

1. Disable a button control during postback.
2. A few thoughts on jQuery templating with jQuery.tmpl
3. jQuery 1.6.2 syntax error? You may be the victim of SEO.

You've been reading Why PhoneGap 1.1.0 broke jQuery Mobile’s back button, originally posted at Encosia. I hope you enjoyed it, and thanks for reading.

If you've got any feedback, please click through and leave a comment; I'd love to hear from you. You can click here to jump directly to the comment section of this post.

Unfortunately, that is not the case.

Exploiting your page’s insecurities

In case it’s hard to believe these code-behind methods truly are so easily accessible, let’s take a look at a quick example. Let’s say you have a page method that returns sensitive business information, like so:

[WebMethod]
public static int SecretFormula() {
  return 42;
}

Assuming that method is defined in a Default.aspx file’s code-behind, located in a folder named TopSecret, here’s a bit of jQuery you could use to request the secret formula from any page on the site:

$.ajax({
  url: '/TopSecret/Default.aspx/SecretFormula',
  type: 'POST',
  contentType: 'application/json',
  data: '{}',
  success: function(result) {
    alert(result.d);
  }
});

In fact, you can even make that request from a plain HTML file. In this example, I’m making the request right from a simple HTML file named index.htm:

Not only is the request not originating from the ASPX file that contains the page method, that request wasn’t originating from an ASPX file at all!

Is this really a problem?

You might be asking yourself if this is really a problem to begin with. After all, you aren’t very likely to write client-side code that requests sensitive data unless you actually need that data, regardless of whether you write that code on an ASPX page, HTML page, or anywhere else.

The trouble is, a villain could land on any of your site’s pages, open up Firebug, and start probing for weaknesses like this one. In this case, the obscurity of the exact location of the page method might lead you to a false sense of security, but if an attacker has any knowledge of your system’s architecture then the door is wide open.

Even more troubling, as long as an attacker uses POST requests with an application/json Content-Type, they could use a tool as simple as Fiddler to interrogate your site’s services remotely. A few lines of server-side code, and your competition could set up a site driven by the page method APIs on your site that you thought were private!

A fixable problem

Page methods aren’t indefensible against the shenanigans of external interlopers though. You can secure them with ASP.NET’s built-in authorization mechanism, just as you would any other ASPX page (or ASMX service). In fact, if you secure an ASPX page with ASP.NET authorization, page methods defined in its code-behind are automatically equally secure.

To deny unauthenticated access to methods in our TopSecret folder, adding an authorization entry to the web.config in that folder is all that’s necessary:

<?xml version="1.0"?>
<configuration>
  <system.web>
    <authorization>
      <deny users="?" />
    </authorization>
  </system.web>
</configuration>

Now, an unauthenticated user trying to access the SecretFormula method from index.htm (or anywhere else, without authenticating first) is denied access:

Of course, there are a variety of ways to control access to these methods. You might test to see which role a user’s in and respond accordingly, or you might only need to verify some token stored in the Session.

Regardless of the particular mechanism, the key is to remember that none of this is automatic and that you must be mindful of regulating access to your page methods.

Related posts:

1. Using jQuery to directly call ASP.NET AJAX page methods
2. Why do ASP.NET AJAX page methods have to be static?
3. Using complex types to make calling services less… complex

You've been reading ASP.NET page methods are only as secure as you make them, originally posted at Encosia. I hope you enjoyed it, and thanks for reading.

If you've got any feedback, please click through and leave a comment; I'd love to hear from you. You can click here to jump directly to the comment section of this post.

Worse, if you encounter an API with no JSONP support, the cross-domain barrier can quickly become a formidable one. CORS is slowly becoming a viable alternative, but it requires that the remote service support it via special HTTP headers and browser support for CORS is still not ubiquitous.

Until CORS is more broadly supported, an alternative solution is to bounce cross-domain requests through the web server that hosts your website. In ASP.NET, the best tool for implementing that sort of middleman endpoint is the HttpHandler.

In this post, I’ll show you how to create an HttpHandler to service cross-domain requests, how to use jQuery to communicate with the handler, and an example of one improvement that this approach makes possible.

An example remote API

To focus on an example that’s already familiar to many, I’m going to use Twitter. Twitter’s API does support JSONP, which is a viable alternative for consuming it across domains. In fact, the Twitter status that you see in my sidebar to the right was retrieved from Twitter’s API via JSONP.

However, not every service supports JSONP, its third-party script injection mechanism is sometimes problematic, and using JSONP robs us of niceties like local caching. So, for the sake of a good example, let’s find a way to use the Twitter API on the client-side without resorting to JSONP.

Specifically, I’m interested in querying the service for my last few status updates. The Twitter API request to accomplish that looks like this:

http://api.twitter.com/1/statuses/user_timeline.json?id=Encosia

Twitter will respond to that with a JSON array of objects representing my (or your) last 20 tweets, which is exactly what we’re after.

The best tool for the job: HttpHandler

If you’re accustomed to using ASP.NET’s page methods and ScriptServices to facilitate communication between client and server, those tools begin to look like a hammer that matches every JSON-shaped nail in sight. However, when simply relaying an external API’s JSON through to the client, they often add unnecessary overhead and complexity.

Rather, a lower-level tool is more appropriate in this case.

HttpHandlers are one of ASP.NET’s most under-utilized tools. They’re simple to implement and allow you to handle requests closer to the metal than WebForms pages or MVC controller actions.

One place in particular where HttpHandlers shine is where you would otherwise consider writing Response.Write statements in a WebForms page’s code-behind. This anti-pattern of using ASPX’s code-behind to get closer to the metal looks similar to approaches that you’ll see on some other platforms, such as PHP, but is not equivalent.

Unfortunately, even if you don’t use WebForms controls or ASPX markup at all, executing that low-level code from an ASPX page’s code-behind requires that every request filter through the full page life cycle. That means even the simplest request still has to percolate all the way from PreInit to Unload, adding needless overhead.

Instead, the HttpHandler is where you should write that sort of code that ultimately boils down to Response.Write calls.

Choosing the right handler type

A tricky issue when you’re writing your first HttpHandler is that Visual Studio presents you with two templates, “ASP.NET Handler” and “Generic Handler”:

Both are similar, but the “ASP.NET Handler” template’s approach requires modifying your web.config to configure which URL your handler accepts requests at. Mucking around in the web.config isn’t terribly difficult, but it’s extra friction which makes the process less approachable.

In the spirit of keeping things simple, let’s stick with the more traditionally file-based “Generic Handler”.

Getting started with your first HttpHandler

After choosing that template, specifying a name, and adding the new file to your site, you’ll end up with a bit of boilerplate code that includes this method:

public void ProcessRequest(HttpContext context) {
  context.Response.ContentType = "text/plain";
  context.Response.Write("Hello World");
}

If you start the site up in Visual Studio and then request your newly-created HttpHandler in a browser, Handler1.ashx if you accept the default name, you will see “Hello World” as you might expect.

That’s not very impressive yet, but the response you saw made its way to your browser without touching WebForms’ page life cycle or filtering through ASP.NET MVC’s routing engine and action filters. While those things are worthwhile niceties for the majority of your application, they’re unwanted overhead when all you need is to efficiently relay some content through the server.

Bouncing a request to Twitter through the HttpHandler

To adapt an HttpHandler for relaying requests to the Twitter API, we can use .NET’s handy WebClient class to make the request to Twitter’s API, and then return the result back through as the handler’s response:

public void ProcessRequest(HttpContext context) {
  WebClient twitter = new WebClient();
 
  // The base URL for Twitter API requests.
  string baseUrl = "http://api.twitter.com/1/";
 
  // The specific API call that we're interested in.
  string request = "statuses/user_timeline.json?id=Encosia";
 
  // Make a request to the API and capture its result.
  string response = twitter.DownloadString(baseUrl + request);
 
  // Set the content-type so that libraries like jQuery can 
  //  automatically parse the result.
  context.Response.ContentType = "application/json";
 
  // Relay the API response back down to the client.
  context.Response.Write(response);
}

That code simply makes an HTTP request to the Twitter API and blindly bounces the result back through as the HttpHandler’s response. For the time being, everything is hard-coded, but we’ll improve on that soon enough.

Using the handler proxy on the client-side

With our web server doing the heavy lifting, using this server-side proxy to make a remote request is trivial:

$.getJSON('TwitterProxy.ashx', function(tweets) {
  // Call a magical function that does all the presentational work.
  displayTweets(tweets);
});

The jQuery code here is actually identical what you’d use when requesting the API via JSONP. Whether that response is truly being fulfilled by the specified URL or it’s being relayed through our HttpHandler, it’s all the same to the jQuery code on the client-side.

As you’ll see when we add caching, this can easily be exploited for good.

Mixing things up with QueryString parameters

The hard-coded approach works well enough, but what if we wanted to be able to query any Twitter account’s recent updates instead of being limited to just that boring Encosia character?

Since HttpHandlers receive an instance of the current HttpContext as the parameter to their ProcessRequest method, it’s easy to access QueryString parameters and react accordingly. For example, this would allow us to request any Twitter account’s timeline by via an id parameter on the QueryString:

public void ProcessRequest(HttpContext context) {
  WebClient twitter = new WebClient();
 
  string baseUrl = "http://api.twitter.com/1/";
 
  // Extract the desired account ID from the QueryString.
  string id = context.Request.QueryString["id"];
 
  // Make a request to the API for the specified id.
  string request = "statuses/user_timeline.json?id=" + id;
 
  // Same as before, from here on out:
  string response = twitter.DownloadString(baseUrl + request);
 
  context.Response.ContentType = "application/json";
  context.Response.Write(response);
}

Now it works exactly the same way as before, but we can choose which Twitter account’s timeline is requested. For example, this URL would request Scott Guthrie‘s latest tweets:

TwitterProxy.ashx?id=ScottGu

Supplying parameters with $.getJSON

To pass this new parameter in from the client-side, you could handcraft the entire URL including the appropriate QueryString. Even better though, $.getJSON has an optional “data” argument that accepts a JavaScript object and converts it to QueryString parameters:

$.getJSON('TwitterProxy.ashx', { id: 'ScottGu' }, function(tweets) {
  displayTweets(tweets);
});

jQuery will automatically URLEncode the parameters you specify in the “data” argument and properly assemble them into the final URL to be requested:

Which is exactly what we need it to do.

Using a configuration object like this is cleaner than manually concatenating a string together and makes it easier to vary the parameter at runtime.

Improving performance with server-side caching

An advantage the HttpHandler proxy has over CORS and JSONP is that you can perform any arbitrary server-side processing that you wish, both before and after the remote service repsonds. A great way to take advantage of that is adding a server-side caching layer.

Server-side caching will reduce how often requests actually trigger API calls and can significantly improve performance for requests that are already cached. A caching middleman like this is especially valuable when dealing with rate-limited APIs like Twitter’s.

Let’s say that we wanted to cache Twitter responses for up to five minutes, for example:

public void ProcessRequest(HttpContext context) {
  // This will be the case whether there's a cache hit or not.
  context.Response.ContentType = "application/json";
 
  // Check to see if the twitter status is already cached,
  //   then retrieve and return the cached value if so.
  // 8/3/11: Updated with more robust test, thanks to ctolkien.
  object tweetsCache = context.Cache["tweets-" + id];
 
  if (tweetsCache != null) {
    string cachedTweets = tweetsCache.ToString();
 
    context.Response.Write(cachedTweets);
 
    // We're done here.
    return;
  }
 
  WebClient twitter = new WebClient();
 
  // Move along; nothing to see here. The concatenation is just
  //  to avoid horizontal scrolling within the meager 492
  //  pixels I have to work with here.
  string url = "http://api.twitter.com/1/statuses/" +
               "user_timeline.json?id=Encosia";
 
  string tweets = twitter.DownloadString(url);
 
  // This monstrosity essentially just caches the WebClient result
  //  with a maximum lifetime of 5 minutes from now.
  // If you don't care about the expiration, this can be a simple
  //  context.Cache["tweets"] = tweets; instead.
  context.Cache.Add("tweets", tweets,
    null, DateTime.Now.AddMinutes(5), 
    System.Web.Caching.Cache.NoSlidingExpiration,
    System.Web.Caching.CacheItemPriority.Normal, 
    null);
 
  context.Response.Write(tweets);
}

Adding the intermediate cache results in a tremendous performance improvement after the first request:

With the server able to immediately serve requests within the five minute caching window, subsequent $.getJSON requests are an order of magnitude faster!

Perhaps even more importantly in the case of Twitter, these four refreshes only counted as one API call against my hourly rate-limit.

Conclusion

Using HttpHandlers as server-side proxies turns out to be a simple way to solve the pesky cross-domain restrictions that we’ve all run into from time to time. All said and done, using an HttpHandler to proxy third-party requests takes few lines of code, but offers nearly unlimited flexibility.

In addition to the obvious benefit of getting around the cross-domain restriction, bouncing requests through your own server potentially has a range of other benefits, including:

• Error handling – This approach not only passes unhandled exceptions on the WebClient request back through to the client-side, but it also gives you the ability to enhance the error handling with your own sanity checks and constraints.
• Caching – As shown in this post’s final example, you can very easily interject your own caching layer for requests passing through the HttpHandler proxy. That’s especially useful when working against rate limited or potentially slow/flaky APIs (like Twitter’s).
• Security – When you’re accustomed to server-side programming, the revealing nature of client-side JavaScript can be unnerving. Learning to appropriately partition sensitive algorithms and data between client and server is key to mitigating that issue. Along those lines, moving the remote request to code running on your server is one way to keep sensitive information like API keys and passwords safely hidden from view-source and client-side developer tools.
• Reliability – One of JSONP’s less obvious drawbacks is the fact that it relies on injecting a third-party script. However, your users may be using something like NoScript to purposely block third-party scripts, effectively shutting down your ability to use JSONP. Even if you prefer JSONP in most cases, a local server-side proxy can be helpful as a fallback in case of unexpected JSONP failures.

That’s not to say that there’s no downsides to this approach. When you’re using an HttpHandler proxy, it’s important to keep in mind that it can be slower since you’re making a series of two connections instead of a single, direct one. You also lose the ability to request content with the user’s third-party cookies attached to the request, which is helpful in some cases.

Overall, using server-side proxies is a very useful item to have in your toolbox. I hope this post has served to introduce you to the approach and/or given you better insight into how you can use HttpHandlers to your advantage.

Get the source

If you’d like to browse through a complete working example of what’s been covered in this post, take a look at the companion project at GitHub. Or, if you’d like to download the entire project and run it in Visual Studio to see it in action yourself, grab the ZIP archive.

HttpHandler-Proxy on GitHubHttpHandler-Proxy.zip

Related posts:

1. AJAX, file downloads, and IFRAMEs
2. The easiest way to break ASP.NET AJAX pages
3. Why ASP.NET AJAX UpdatePanels are dangerous

You've been reading Use ASP.NET’s HttpHandler to bridge the cross-domain gap, originally posted at Encosia. I hope you enjoyed it, and thanks for reading.

If you've got any feedback, please click through and leave a comment; I'd love to hear from you. You can click here to jump directly to the comment section of this post.

I didn’t really expect that updating from jQuery 1.6.1 to 1.6.2 would break anything, much less break everything.

As it turns out, the problem didn’t have anything to do with jQuery 1.6.2 or my own code. However, while investigating, I ended up falling prey to the same treachery that led to the original bug report.

This is why we can’t have nice things

Google has been raked across the coals this year, with serious questions being raised about their ability to handle the mounting problems of hyper-SEO’d spam sites and content farms. Unfortunately, this weekend’s problem with jQuery 1.6.2 was yet another failure in Google’s ongoing struggle with that dross.

Hopefully, the situation will have improved by the time you’re reading this post, but as I’m writing this, the first organic search result for jQuery 1.6.2 is this one:

If you’re in a hurry to download a copy of the latest jQuery revision, that result looks legitimate enough, but look closely at the domain name. Notice that it’s .it, not .com. This domain is not owned or controlled by the jQuery Project.

Regardless, following the link to this search result takes you to what appears to be an authentic jQuery blog post:

As legitimate as it looks, that site is an entirely unsanctioned ripoff of the official jQuery site. Yet, this impostor has somehow out-ranked the official jQuery blog in Google searches for its own content.

That’s lame, but what’s the harm?

In my hurry, I didn’t notice the .it domain, much less that this seemingly authentic jQuery blog post was an automated copy of the real thing. I right-clicked the link to unminified jQuery 1.6.2, saved it locally, and went about my testing.

After unwittingly downloading this fraud’s copy of jQuery 1.6.2 and testing it in some of my old samples, I did indeed begin seeing JavaScript errors as my reader had reported. Closer inspection revealed that the errors were related to the jQuery script include itself though, not my own code.

So, what was going on? Following the errors back to their source, I found this at the very end of the jQuery script I had downloaded:

// Expose jQuery to the global object
window.jQuery = window.$ = jQuery;
})(window);Time to generate: 1.35903

Things were looking good until that final Time to generate bit at the very end. That is obviously not valid JavaScript. Likely, it was appended to the file by whatever tool was used to clone the official site.

When browsers hit a hard syntax error like this while parsing a script include, the entire script is ignored and no part of it makes its way into the DOM. So, this tiny error at the very end of thousands of lines of code was all it took to effectively disable the entire library.

Finding a legitimate copy of jQuery

So, where should you be looking for the authentic copies of jQuery 1.6.2?

• You can find unfettered copies of jQuery 1.6.2 on the (real) jQuery blog.
• The latest version is also available on the jQuery site’s download page.
• Finally, I’m a long-time proponent of the performance advantages that Google’s AJAX APIs CDN can bring to your site via its public CDN for jQuery. That CDN is another authoritative source for jQuery 1.6.2 (uncompressed, minified).

Conclusion

Posting criticisms of Google on a site that depends on search for over 60% of its traffic may be asking for trouble, but this is a flagrant failure on Google’s part. Algorithms be damned; they simply cannot allow a random AdSense splog to hijack well-targeted searches for the most popular JavaScript library on the planet.

Imagine how much worse things could have been if this site were actively evil instead of harmlessly inept. Injecting even a tiny bit of malicious JavaScript into such a ubiquitous library could have resulted in a minor catastrophe, as thousands of developers downloaded that subverted version and tested it on their sites.

Update: Thanks to Pierre’s helpful comment below, the issue that allowed the scraper’s site to outrank the original is now apparent: requests to individual post permalinks on blog.jQuery.com return a 500 error when requested with a User-Agent of Googlebot.

As frustrating it is to see a splog outrank the original, there’s no way to fault Googlebot for not indexing something that it couldn’t see. My original conclusion about this being a failure on Google’s part was obviously unwarranted.

Sorry about that.

Epilogue: As of last night, this is what I’m seeing returned for jQuery 1.6.2 searches now.

All’s well that ends well.

Related posts:

1. What ASP.NET developers should know about jQuery
2. Hear me talk jQuery and ASP.NET on the jQuery Podcast
3. Mastering jQuery now available at TekPub

You've been reading jQuery 1.6.2 syntax error? You may be the victim of SEO., originally posted at Encosia. I hope you enjoyed it, and thanks for reading.

If you've got any feedback, please click through and leave a comment; I'd love to hear from you. You can click here to jump directly to the comment section of this post.

If you’ve been using my approach for directly calling ASP.NET’s JSON-based services with jQuery, you know that specifying the correct Content-Type on your requests to them is a crucial part of coaxing JSON out of them. However, when I suggested that a Content-Type of application/json; charset=utf-8 was necessary, that was overly specific.

Charset=who-cares

As it turns out, only the application/json portion is necessary.

More accurately, ASP.NET checks that your request’s Content-Type header begins with application/json. Beyond that, you can even specify a charset of acrobatic-unicorns and it still works (no, really; I tried).

That may only sound like a minor reduction in typing, but I find that it makes a non-trivial improvement in how memorable the parameter is. At least for me, the punctuation in ; charset=utf-8 made that Content-Type string tedious to remember and I would often resort to copy/paste to be sure that it was correct.

It’s nice to be able to quickly type out an $.ajax() call to your services without tedious memorization, online reference, or copy/paste.

Bonus: Ditch the dataType

When I originally wrote about using jQuery with ASP.NET’s web services, the current jQuery version was 1.2 and jQuery’s $.ajax() method looked nothing like what it does today. One of the changes that occurred over the years is that jQuery 1.4 added support for parsing responses based on their Content-Type.

Before that addition, it was imperative that you specify a dataType of json if you wanted jQuery to automatically handle converting JSON responses to JavaScript objects. Beginning with version 1.4, responses with the Content-Type application/json are automatically treated as JSON and parsed accordingly.

Since ASP.NET does set the correct Content-Type on its JSON-serialized responses, manually specifying a dataType is no longer necessary as long as you’re using jQuery 1.4 or later.

So, what’s left?

Eliminating all that dead weight, your AJAX calls to ASMX ScriptServices, Page Methods, and WCF services can now be simplified to this:

$.ajax({
  url: 'Service.asmx/Method',
  type: 'POST',
  contentType: 'application/json',
  data: '{"Parameters":"Must be JSON strings!"}',
  success: function(response) {
    // Don't forget that the response is wrapped in a
    //  ".d" object in ASP.NET 3.5 and later.
    console.log(response.d);
  }
});

Sometimes it’s the little things…

Related posts:

1. jQuery 1.5′s AJAX rewrite and ASP.NET services: All is well
2. Simplify calling ASP.NET AJAX services from jQuery
3. Using jQuery to Consume ASP.NET JSON Web Services

You've been reading Save yourself some typing when you call ASP.NET services, originally posted at Encosia. I hope you enjoyed it, and thanks for reading.

If you've got any feedback, please click through and leave a comment; I'd love to hear from you. You can click here to jump directly to the comment section of this post.

$.map() has always been a useful utility method, somewhat mimicking ECMAScript 5′s native Array.map() method. If you’ve been working with JavaScript long, you’re probably already comfortable with passing anonymous function callbacks around anyway, which makes higher order functions like map an intuitive way to write concise, expressive transformation code.

With jQuery 1.6, now you can use the same approach when working with regular JavaScript objects. There are a variety of uses for this, but I want to focus on one real-world usage in this post: extracting an array of the keys contained within a JavaScript object.

Keys to the kingdom (or at least to an object)

The question of how to extract a collection of an object’s keys comes up often. For example, given an object like this one:

var person = { name: "Dave",
               website: "http://DaveWard.com",
               twitter: "@Encosia" };

An array of its distinct keys would look like this:

var personKeys = ['name', 'website', 'twitter'];

That information is useful for a variety of applications, such as building a table header to represent an arbitrary object’s schema. It’s not something you’ll use on a daily basis, but quite helpful when you do find a need for it.

ECMAScript 5 actually exposes an Object.keys property to provide exactly that information. However, ECMAScript 5 is several years away from being cross-browser safe. For example, Object.keys wasn’t implemented in Internet Explorer until version 9. So, that new feature isn’t terribly useful for most real-world development (yet).

Using $.map() to emulate Object.keys

Until we reach the Utopian future of ubiquitous ECMAScript 5 support, jQuery 1.6′s enhanced map utility provides a syntactically sugary avenue for emulating Object.keys across all browsers.

As map applies its callback function to each property in an object, that function is provided different parameters than the item and index that $.map() has provided in the past. When map is used against an object, the callback function is passed each property’s key and value:

var obj = { key1: 'foo', key2: 'bar' };
 
// Output:
// key1 foo
// key2 bar
$.map(obj, function(value, key) {
  console.log(key, value);
});

Objects or not, $.map does still return an array consisting of each callback’s return value. Now that we know how to reference each object property’s key name during the callback, building an array of an object’s keys is simple:

var person = { name: "Dave",
               website: "http://DaveWard.com",
               twitter: "@Encosia" };
 
// personKeys will contain this JavaScript array after execution:
//  ['name', 'website', 'twitter']
var personKeys = $.map(person, function(value, key) {
  return key;
});

Nice and easy, isn’t it?

As always with higher order functions like map, there are iterative alternatives. However, those iterative approaches only result in more code to accomplish the same task. Use this functional approach and enjoy!

Related posts:

1. Use jQuery to extract data from HTML lists and tables
2. Use jQuery and ASP.NET AJAX to build a client side Repeater
3. Avoid this tricky conflict between ASP.NET AJAX and jQuery

You've been reading Using jQuery 1.6 to find an array of an object’s keys, originally posted at Encosia. I hope you enjoyed it, and thanks for reading.

If you've got any feedback, please click through and leave a comment; I'd love to hear from you. You can click here to jump directly to the comment section of this post.

Whether you’re enhancing legacy elements that have been generated on the server-side or want to parse the output of a third-party DHTML widget, there are a variety of situations where converting HTML to raw data is a legitimate need. You may have seen iterative solutions to this problem before. However, nested looping code gets messy fast, doesn’t feel much like idiomatic jQuery, and certainly isn’t as concise as you’d probably like.

Luckily, one of JavaScript’s lesser-known utility methods and jQuery’s implementation of it can improve the situation quite a bit. In this post, I’m going to show you how to use this method, jQuery’s cross-browser solution, and how to use it to extract data objects from arbitrary HTML lists and tables.

Array.map()

It turns out that there’s a tool perfectly suited to the task of coercing one data structure into another: map.

Map is a higher-order function that allows you to transform the contents of a collection by applying a function to each item, capturing the result, and building a new collection of those results.

Map is a perfect tool for translating a collection full of extraneous data into a tightly-focused collection of exactly the desired subset. Even better, JavaScript 1.6 even includes a native implementation of map, which is exposed as a method on the Array prototype.

For example, this is how you could use JavaScript 1.6′s Array.map() to analyze an array of strings and create a new array containing each string’s length:

var sites = ['Encosia', 'jQuery', 'ASP.NET', 'StackOverflow'];
 
// For each site in the array, apply this function 
//  and build an array of the results.
var lengths = sites.map(function(site, index) {
  // Use the length of each name as its value in the new array.
  return site.length;
});
 
// This outputs: [7, 6, 7, 13]
console.log(lengths);

This is a very simple example, but you can probably already imagine applying that same technique to an array of list elements or table rows. The concise expressiveness of the map approach is great for paring away extraneous markup and extracting just underlying data.

Mapping uncharted territory

Unfortunately, JavaScript 1.6 and its map implementation is not something that you can count on being available in older browsers. Notably, Internet Explorer doesn’t provide an Array.map() implementation until IE9.

Though that is disappointing, map isn’t difficult to manually implement. For example, this is a polyfill that the MDC recommends for patching Array.map() into older browsers:

if (!Array.prototype.map) {
  Array.prototype.map = function(fun /*, thisp */)  {
    "use strict";
 
    if (this === void 0 || this === null)
      throw new TypeError();
 
    var t = Object(this);
    var len = t.length >>> 0;
    if (typeof fun !== "function")
      throw new TypeError();
 
    var res = new Array(len);
    var thisp = arguments[1];
    for (var i = 0; i < len; i++)  {
      if (i in t)
        res[i] = fun.call(thisp, t[i], i, t);
    }
 
    return res;
  };
}

That’s a workable solution, but I doubt you’re very excited about the prospect of including all this code in your page. I know I wouldn’t be.

jQuery has you covered

If you’re already including jQuery in your pages, the good news is that jQuery has a built-in map implementation that works in every browser. In fact, jQuery provides two separate map methods: one that’s specially suited to working with jQuery selections and a general utility method that’s more similar to the polyfill shown above.

For working with HTML, I’m going to focus on using the former: .map().

To replicate the JavaScript 1.6 dependent example shown earlier, using jQuery’s implementation instead, the code would look like this:

var sites = ['Encosia', 'jQuery', 'ASP.NET', 'StackOverflow'];
 
// Same as before, using jQuery's map() implementation.
var lengths = $(sites).map(function(index, site) {
  // Use the length of each site name as its value in the new array.
  return site.length;
});
 
// This outputs: [7, 6, 7, 13]
console.log(lengths);

Making “this” approach more concise

To condense the code a bit, we can take advantage of the execution context within the callback function. During each callback, this holds the value of the array item currently being operated on. So, there’s no need to bother capturing the callback’s two input parameters:

var lengths = $(sites).map(function() {
  // "this" refers to the current array element as this callback is
  //  applied to each array element.
  return this.length;
});

That isn’t a huge improvement, but every little bit helps and I’ll be using this in the examples throughout the rest of this post. So, I wanted to make sure what’s happening there is clear.

Unwrapping the result of jQuery’s .map()

The one quirk when using jQuery’s .map() method is that it sometimes returns a jQuery wrapped set; specifically, when you apply it to the result of a jQuery DOM selection. Even if your mapping function returns scalar values like strings and numbers, the end result of .map() will include the jQuery object prototype on each element.

That isn’t really a problem if you only intend to use that result immediately in your JavaScript code. However, the jQuery object prototype hanging off each element throws a wrench in the works if you try to use JSON.stringify() on the result of .map(). Since JSON serialization is such a common task when storing or transmitting JavaScript data, this quirk turns out to be a real issue.

The solution is to call jQuery’s get() method on those wrapped-array results, which boils them down to plain arrays. When you see .get() tagged onto the end of the examples ahead, that’s why it’s there.

Now, let’s take a look at applying .map() to HTML and using it to extract data.

Mapping the data within HTML unordered lists

Using .map() against an unordered list is one of the most straightforward examples to start with. Imagine you had this simple HTML markup:

<ul>
  <li>Item 1</li>
  <li>Item 2</li>
  <li>Item 3</li>
</ul>

To extract each of those items’ displayed value, you could use .map() like this:

// Returns ['Item 1', 'Item 2', 'Item 3']
$('li').map(function() {
  // For each <li> in the list, return its inner text and let .map()
  //  build an array of those values.
  return $(this).text();
}).get();

Complicating things slightly, maybe the list items also have an HTML5 data- attribute that you need to collect in addition to their values:

<ul>
  <li data-id="123">Item 1</li>
  <li data-id="456">Item 2</li>
  <li data-id="789">Item 3</li>
</ul>

Using .map() to extract that more complex data is just as easy:

// Returns [{id: 123, text: 'Item 1'}, 
//          {id: 456, text: 'Item 2'},
//          {id: 789, text: 'Item 3'}]
$('li').map(function() {
  // $(this) is used more than once; cache it for performance.
  var $item = $(this);
 
  return { 
    // Note: using .data() to read HTML5 data- attributes 
    //  requires jQuery 1.4.3+. Use attr() in older versions.
    id: $item.data('id'), 
    text: $item.text()
  };
}).get();

As you can see, .map() is a powerful tool for concisely pulling arbitrary bits of data together into a useful structure. You could certainly do this with a temp variable and for-loop, but it’s hard to beat the clean expressiveness this approach lends your code.

Extracting data from HTML tables

Working with the lists is good for a simple example, but what if we need to apply this technique to an HTML structure that’s more complex than an unordered list?

HTML tables are one of the most common targets for this technique. It’s not unusual to end up with a pre-rendered table that was generated off-page and to desire a client-side data structure representing that table’s data.

For example, here’s a tabular representation of the same data contained in the second list example:

<table id="myTable">
  <thead>
    <tr>
      <th>id</th>
      <th>text</th>
    </tr>
  </thead>
  <tbody>
    <tr>
      <td>123</td>
      <td>Item 1</td>
    </tr>
    <tr>
      <td>456</td>
      <td>Item 2</td>
    </tr>
    <tr>
      <td>789</td>
      <td>Item 3</td>
    </tr>
  </tbody>
</table>

If you wanted to boil that table down to exactly the same JavaScript object shown in the second list example, this .map() usage would do the trick:

// Returns [{id: 123, text: 'Item 1'}, 
//          {id: 456, text: 'Item 2'},
//          {id: 789, text: 'Item 3'}]
$('#myTable tbody tr').map(function() {
  // $(this) is used more than once; cache it for performance.
  var $row = $(this);
 
  // For each row that's "mapped", return an object that
  //  describes the first and second <td> in the row.
  return {
    id: $row.find(':nth-child(1)').text(),
    text: $row.find(':nth-child(2)').text()
  };
}).get();

The key to making this approach work is using the :nth-child selector to index into each row and retrieve the contents of the cells we’re interested in. This is very similar to how we handled the unordered list earlier, but can be applied to arbitrarily large structures such as wide HTML tables.

If you use this approach, one thing to keep in mind is that :nth-child uses one-based indexing. So, you must use :nth-child(1) to select the first cell, not :nth-child(0) as you might expect.

A general solution for tables

Using hard coded :nth-child selectors works well enough in simple scenarios, but it’s brittle. If the table structure changes, relying on a certain table layout will break. Hard coding the selectors for each column also becomes tedious when dealing with wider tables that have many columns.

So, as you apply this technique to larger or less predictable tables, you may desire a more general solution for extracting the data. One way of doing that is using the table’s column heading cells to build a basic schema of the table’s data.

Assuming your table has a proper <thead>, this is how you could extract an array of its column headings to use as a schema for mapping the rest of the table’s data:

var columns = $('#myTable thead th').map(function() {
  // This assumes that your headings are suitable to be used as
  //  JavaScript object keys. If the headings contain characters 
  //  that would be invalid, such as spaces or dashes, you should
  //  use a regex here to strip those characters out.
  return $(this).text();
});

With that column list handy, we can determine which column name any cell in the table should be filed under, given nothing more than its index in the row. Now we can automate the process that previously required those :nth-child selectors:

var tableObject = $('#myTable tbody tr').map(function(i) {
  var row = {};
 
  // Find all of the table cells on this row.
  $(this).find('td').each(function(i) {
    // Determine the cell's column name by comparing its index
    //  within the row with the columns list we built previously.
    var rowName = columns[i];
 
    // Add a new property to the row object, using this cell's
    //  column name as the key and the cell's text as the value.
    row[rowName] = $(this).text();
  });
 
  // Finally, return the row's object representation, to be included
  //  in the array that $.map() ultimately returns.
  return row;
 
// Don't forget .get() to convert the jQuery set to a regular array.
}).get();

That’s it.

With all the comments, that looks like more work than it actually is. Eleven lines of code for the entire ordeal isn’t bad considering that it will automatically handle the majority of tables you throw at it.

Conclusion

I’m going to stop here, before this gets any longer. I hope that you found this helpful and/or interesting.

Even if you don’t often convert HTML markup to JavaScript objects, do keep .map() in mind when you’re working with collections of any type. When you need it, the notion of map is an extremely useful aspect of JavaScript’s functional nature, but often goes overlooked.

Related posts:

1. Use jQuery and quickSearch to interactively search any data
2. Using jQuery 1.6 to find an array of an object’s keys
3. A few thoughts on jQuery templating with jQuery.tmpl

You've been reading Use jQuery to extract data from HTML lists and tables, originally posted at Encosia. I hope you enjoyed it, and thanks for reading.

If you've got any feedback, please click through and leave a comment; I'd love to hear from you. You can click here to jump directly to the comment section of this post.

I’ve noticed several people looking for a jQuery 1.5 VSDoc this week. After looking around myself, I didn’t see one anywhere either. So, I updated Damian Edwards’ VsDocBuilder for jQuery 1.5 and generated a new VSDoc.

It doesn’t handle the new jqXHR and Deferred return types quite right, so you won’t get Intellisense for the new chained $.ajax() callbacks. However, it should be better than nothing until a fully functioning version is released.

You can download it here: jQuery-1.5.0-vsdoc.js

Update: Damian has just made a fully functional version of the 1.5 VSDoc available (that was quick): jquery-1.5-vsdoc.js. You should use his instead of mine.

Important: This new VSDoc makes use of <para> tags to display line breaks inside documentation tooltips. To view them properly, you’ll need to be sure that you have the JScript Editor Extensions installed so that Visual Studio understands those new VSDoc tags.

Related posts:

1. See how I used Firebug to learn jQuery
2. How you can force the Ajax Script Loader to use jQuery 1.4
3. Hear me talk jQuery and ASP.NET on the jQuery Podcast

You've been reading A VSDoc for jQuery 1.5, originally posted at Encosia. I hope you enjoyed it, and thanks for reading.

If you've got any feedback, please click through and leave a comment; I'd love to hear from you. You can click here to jump directly to the comment section of this post.

I’m happy to report that the short answer is: jQuery 1.5′s new AJAX module has almost no negative impact on any of the techniques you may have read about here. The rewrite maintains very good compatibility for the $.ajax(settings) calling syntax and for now-deprecated features such as dataFilters.

One advanced dataFilter usage appears to be broken, but it’s something that you probably already stopped using with jQuery 1.4. To be clear, I’ll briefly enumerate all of the techniques I’ve re-tested and jQuery 1.5′s impact (or lack thereof) on each.

ASMX ScriptServices and ASPX page methods

The most common way of using jQuery to communicate with an ASP.NET WebForms application today is to use an ASMX ScriptService or ASPX page method. If you’re requesting an ASMX ScriptService using the approach I originally described:

$.ajax({
  type: "POST",
  contentType: "application/json",
  url: "/YourService.asmx/YourMethod",
  data: "{}",
  dataType: "json",
  success: function(msg) {
    console.log(msg.d);
  }
});

That code will continue to work exactly as-is with jQuery 1.5. If you prefer page methods instead, you’re in the clear too.

Note: You can simplify the contentType parameter to “application/json” when using any version. The ScriptService handler only checks that the header contains “application/json”, not for an exact string match. It’s a small improvement, but noticeably easier to remember and type.

DTOs and JSON.stringify()

If you’re using jQuery and ASP.NET JSON endpoints to accomplish more complicated tasks, you may be using JSON.stringify() to simplify making requests that include data transfer objects. Paired with corresponding complex types or collections on the server-side, this approach seems almost too good to be true:

var NewPerson = { };
 
NewPerson.FirstName = $("#FirstName").val();
NewPerson.LastName = $("#LastName").val();
NewPerson.Address = $("#Address").val();
NewPerson.City = $("#City").val();
NewPerson.State = $("#State").val();
NewPerson.Zip = $("#Zip").val();
 
var DTO = { 'Person' : NewPerson };
 
$.ajax({
  type: "POST",
  contentType: "application/json; charset=utf-8",
  url: "PersonService.asmx/AddPerson",
  data: JSON.stringify(DTO),
  dataType: "json"
});

jQuery 1.5′s AJAX rewrite has not impacted that technique either. If you provide a string value for its data parameter, jQuery will pass that string on to the server unmodified.

dataFilters and “.d”

With jQuery 1.5 fundamentally revamping $.ajax()‘s extensibility model, the technique of using a dataFilter to normalize ASP.NET’s “.d” wrapper is what I worried most about surviving the 1.5 transition. That approach looked like this:

$.ajaxSetup({
  type: "POST",
  contentType: "application/json; charset=utf-8",
  data: "{}",
  dataFilter: function(data) {
    if (msg.hasOwnProperty('d'))
      return msg.d;
    else
      return msg;
  }
});
 
$.ajax({
  url: 'YourService.asmx/YourMethod',
  success: function(response) {
    // You'll never have to worry about the response being 
    //  buried in response.d here.
  }
});

Though jQuery 1.5′s new converters will probably enable a better solution, this dataFilter approach does continue to work in jQuery 1.5.

dataFilters and JSON parsing

While the simple dataFilter does work, if you’re using a dataFilter to implement custom JSON parsing, you may need to make a small change. What I mean by that is code like this:

$.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 + ')');
  }
});

The usefulness of that approach dates back to jQuery 1.3 and earlier, when jQuery exclusively used eval() for deserializing JSON responses. At that time, it was helpful to manually override the deserialization process to take advantage of browser-native implementations of JSON.parse() when available. Doing so yielded both performance and security gains.

In jQuery 1.4, this was no longer necessary because jQuery contained a similar bit of browser-native parser testing code itself. However, the dataFilter approach above did continue to work in jQuery 1.4 $.ajax() requests, so long as the dataType for the request was either omitted or set to a value that didn’t trigger jQuery’s automatic JSON deserialization (e.g. “text” or “foo”).

As of jQuery 1.5, using this dataFilter approach for manually controlling deserialization will no longer work if the request’s dataType is set to “json” or even omitted.

Except for the most obscure of edge cases, the best solution is simply to drop this code. It’s redundant if you’re using jQuery 1.4.0 or later. Again though, you can continue using a dataFilter to handle the “.d” issue.

Conclusion

For the most part, upgrading to jQuery 1.5 is a non-issue when it comes to using $.ajax() with ASP.NET JSON endpoints. Considering the fundamental nature of the module’s rewrite, it really is commendable how well backwards compatibility has been maintained.

Once you’ve vetted your existing code for compatibility with jQuery 1.5, do be sure to check out the powerful new features that have been added to $.ajax() in this rewrite. Its new extension points, prefilters, converters, and transports, will offer finer-grained control than ever before.

Even more exciting is the AJAX rewrite’s inclusion of “deferreds”. You can count on seeing more about that here soon, but right now I highly recommend taking a look at this post by Eric Hynds.

If you’ve tested jQuery 1.5 in your own sites/projects, I’m curious if you’ve run into any issues I didn’t address. Please do leave a comment if I’ve missed anything that caused you trouble in the upgrade.

Related posts:

1. Simplify calling ASP.NET AJAX services from jQuery
2. Using complex types to make calling services less… complex
3. Using jQuery to Consume ASP.NET JSON Web Services

You've been reading jQuery 1.5′s AJAX rewrite and ASP.NET services: All is well, originally posted at Encosia. I hope you enjoyed it, and thanks for reading.

If you've got any feedback, please click through and leave a comment; I'd love to hear from you. You can click here to jump directly to the comment section of this post.

With the impending policy change on hotlinking copies of jQuery hosted on jQuery.com, I expect that at least several sites will be migrating their hotlinked script references to one of the public CDNs soon. So, I think this is a good time to address one CDN-related usage mistake that I’ve seen an uptick in lately.

Firesheep and SSL

By now, you’ve probably heard about last year’s release of Firesheep, a Firefox addon that sniffs out HTTP session cookies transmitted in cleartext, and the turmoil that it caused. Seeing someone hijack a stranger’s Twitter or Facebook identity with a single click is enough to make anyone more conscious about the security of their browsing habits.

Traditionally, most sites have used encrypted connections for authentication and sensitive information, to avoid transmitting passwords or private data in cleartext, but they generally avoid forcing SSL connections on most other pages. This lack of site-wide support is usually attributed to the (perceived) server-side overhead of encrypting every connection and the tedious mixed content warnings that browsers display when HTTPS pages contain references to unencrypted content.

However, with SSL certificates available for cheaper than ever, Firesheep having raised so much awareness, and the prevalent use of unsecured WiFi networks in public settings, many sites have responded by offering SSL encryption for pages on their entire sites.

Unfortunately, this recent proliferation of SSL usage has at least one performance drawback that isn’t necessary obvious at first glance.

HTTPS and mixed content

To ensure airtight security, pages served via SSL should contain no references to content served through unencrypted connections. The reasoning behind this rule is sound. After all, the browser has no way of knowing whether an image contains a chart with sensitive financial data or if a JavaScript include contains a JSON collection detailing the user’s medical history.

Different browsers react to mixed HTTP and HTTPS content with varying degrees of severity, with Internet Explorer being the most hostile, but every browser displays some type of warning by default. If you’re curious about how your browser handles the situation, navigate to https://encosia.com.

Visiting my site via HTTPS retrieves the page’s content via a legitimately secured connection, encrypted with a valid SSL certificate. The catch is that its HTML contains insecure references to content such as CSS and images, which triggers the dreaded mixed content warning. The result is especially painful in Internet Explorer:

It’s obvious why avoiding the mixed content warning is an absolute necessity for any serious public-facing site.

An obvious solution

In cases where a given page may potentially be served via either HTTP or HTTPS, path-relative URLs can be used to automatically choose the right protocol for on-site content. For example, references such as /images/foo.png and /css/bar.css will automatically adapt to the correct protocol based on what was used to load the underlying document containing them.

Utilizing off-site resources like advertisements, third-party widgets, and CDN hosted libraries can be a bit more frustrating though. Because their fully qualified URLs specify a protocol, it’s easy to run afoul of the mixed content rule when pages are available through both HTTP and HTTPS protocols. Even a single, innocuous HTTP reference is enough to completely break a page served via HTTPS.

Since the inverse case – secure references on an unsecured page – isn’t subject to any obvious penalties, a common solution is to simply use HTTPS exclusively when linking to off-site resources that support it. On the secure pages, the HTTPS reference avoids a mixed content warning, and it still appears to work fine on HTTP pages as well. On sites where a given page might be viewed using either HTTP or HTTPS, assuming HTTPS can be the quickest, easiest remedy to the mixed content problem.

Unfortunately, that approach is burdened by a significant performance drawback on unsecured pages, which may not be readily apparent.

SSL == Super Slow Loading?

Using the secure reference everywhere seems like a workable solution, but there’s a major problem with over-using SSL for cacheable, static resources (such as jQuery). For the same reasons that browsers require those assets to be encrypted in the first place, most browsers default to not caching files to disk if they’ve been retrieved via SSL.

Worse, even if the user has a locally cached copy of jQuery sitting on disk that was requested from Google’s CDN via HTTP, their browser will not utilize that local copy when it encounters an HTTPS reference to the same resource on the same server.

In other words, this URL:

http://ajax.googleapis.com/ajax/libs/jquery/1.4.4/jquery.min.js

Is entirely different than the following one, as far as a browser is concerned, thus the two are not subject to the sizable cross-caching benefit that comes with using Google’s CDN:

https://ajax.googleapis.com/ajax/libs/jquery/1.4.4/jquery.min.js

The result is that using HTTPS references to Google’s CDN will result in under-optimized caching when used on regular HTTP pages. Though you must use secure reference on pages that are secure themselves, you should avoid HTTPS references on pages that don’t require them.

Update: As several people have pointed out, the Google CDN does serve its assets with a Cache-Control header that allows most browsers to cache its copies of jQuery to disk. However, that doesn’t help mitigate the cross-site caching issue. A local copy that was originally requested via HTTP cannot be used as a cache hit when the browser later encounters an HTTPS reference to the same file (and vice versa). Two separate copies of the file will be stored and each treated as distinct resources.

A better solution

It’s not exactly light reading, but section 4.2 of RFC 3986 provides for fully qualified URLs that omit protocol (the HTTP or HTTPS) altogether. When a URL’s protocol is omitted, the browser uses the underlying document’s protocol instead.

Put simply, these “protocol-less” URLs allow a reference like this to work in every browser you’ll try it in:

//ajax.googleapis.com/ajax/libs/jquery/1.4.4/jquery.min.js

It looks strange at first, but this “protocol-less” URL is the best way to reference third party content that’s available via both HTTP and HTTPS.

On a page loaded through regular, unencrypted HTTP, script references using that URL will be loaded via HTTP and be cached as normal. Likewise, on a secure page that was loaded via HTTPS, script references targeting that protocol-less URL will automatically load the script from Google’s CDN via HTTPS and avoid the mixed content warning.

Thus, using the protocol-less URL allows a single script reference to adapt itself to what’s most optimal: HTTP and it’s full caching support on HTTP pages, and HTTPS on secured pages so that your users aren’t confronted with a mixed content warning.

Conclusion

I probably could have boiled this post down to a couple of sentences, but I hope you found the underlying “why” useful. Just saying that SSL resources aren’t cached isn’t nearly as interesting as understanding why, and how that relates to the mixed content issue.

Perhaps a big part of the problem is that the Google AJAX Libraries developer guide was recently updated to list only HTTPS URLs. Anyone who copy/pastes one of those URLs into their script reference without knowing better will be impacted by the loss of disk caching and cross-site caching, which is unfortunate. If anyone reading this has the right contacts, it would be great if that page could be updated to display the protocol-less URL for all of those libraries instead.

I hope if you see someone using a fixed HTTPS reference to a resource like jQuery on the Google CDN, you’ll point them here and hopefully help speed up the web just a tiny bit for everyone.

Related posts:

1. 3 reasons why you should let Google host jQuery for you
2. 6,953 reasons why I still let Google host jQuery for me
3. Do you know about this undocumented Google CDN feature?

You've been reading Cripple the Google CDN’s caching with a single character, originally posted at Encosia. I hope you enjoyed it, and thanks for reading.

If you've got any feedback, please click through and leave a comment; I'd love to hear from you. You can click here to jump directly to the comment section of this post.

I’ve described how to accomplish that with single templates in the past, using jQuery’s AJAX utilities and a particular usage of tmpl(). Unfortunately, remotely loading a group of composite templates from a single file is not quite as simple, and the technique I’ve described previously will not work.

Not to worry though, it’s still relatively easy.

In this post, I’ll show you how to move a group of composite templates to an external file, how to load and render them with jQuery Templates, and how to take advantage of an expected benefit to improve separation of concerns.

Caution: If you haven’t read my previous posts about remotely loading jQuery Templates definitions and using {{tmpl}} to achieve template composition, read them before continuing with this post. I’m not going to cover that material again here, and this may not make much sense without those prerequisites.

Moving the templates to an external file

Breaking the invoice template apart helped make it more approachable and maintainable, but I don’t like leaving the template embedded in the page’s markup. The larger a single file becomes, the more difficult it is to understand and work with – especially over time.

Disentangling chunks of the presentation tier and moving them to separate files is a great way to attack the problem of bloated pages and views. We’ve been doing that since the beginning of the web, from seemingly-ancient techniques like SSI includes, to file includes in scripting frameworks like ASP and PHP, to partial views in MVC frameworks. So, why stop now just because the templates are rendered in the browser?

Moving the previous example’s template definitions to a separate file is as simple as it sounds. Just take the invoice template and both its row templates, script wrappers included, and move them into a new file of your choosing. I’m going to move them to a file named _invoice.tmpl.htm:

<!-- Tip: It's safe to use HTML comments in the file -->
 
<!-- Invoice container template -->
<script id="invoiceTemplate" type="x-jquery-tmpl">
  <table class="invoice">
  {{each lineItems}}
    {{tmpl($value) get_invoiceRowTemplateName(type)}}
  {{/each}}
  </table>
</script>
 
<!-- Invoice row templates -->
<script id="serviceRowTemplate" type="x-jquery-tmpl">
  <tr class="service">
    <td colspan="2">${service}</td>
    <td colspan="2">${price}</td>
  </tr>
</script>
 
<script id="itemRowTemplate" type="x-jquery-tmpl">
  <tr class="item">
    <td>${item}</td>
    <td>${description}</td>
    <td>${price}</td>
    <td>${qty}</td>
  </tr>
</script>

Naming the template file

If you’re wondering why I chose that somewhat convoluted filename for the template, I’ll explain:

Ideally, I would like to call the template something like invoiceTemplate.tmpl, but most popular web servers refuse to serve files with non-standard extensions by default. You can circumvent that with a bit of manual configuration, but it’s not worth the unending hassle of extra configuration work on every server and/or site where you use this technique. So, .tmpl is out.

I really liked Nathan Smith’s suggestion for a naming compromise on my previous post about remote loading, which boils down to this:

• Prefix the filename with an underscore. This denotes a partial view in many modern view engines and is a useful convention for indicating that the file is not a valid/complete HTML document.
• Nathan suggested following _templateName with .tpl, to indicate that it’s a template. I’m going to tweak that slightly and use .tmpl, so it’s more clear that the template is intended for use with jQuery Templates.
• The file should end in .htm, to be sure the file will be readily served up under almost any web server’s default configuration. Using .htm or another text/html extension also improves the odds that the template definitions will be served with appropriate compression and caching.

The first two are just suggestions, of course. You can use any arbitrary naming scheme you prefer and the approach described in this post will still work fine.

I do recommend sticking with an .htm or .html extension though. I (stubbornly) went through the configuration hassle of using .tpl when I was originally working with jTemplates’ remote loading feature a couple years ago, and eventually had to give up on it. The ongoing configuration hassles ultimately outweighed the benefit of a uniquely descriptive extension.

Loading and rendering the template

With the templates moved to an external file, we need a way to load and render them. As I mentioned earlier, the approach I’ve previously described for remote template loading isn’t viable in this scenario. Treating the external file as a simple template string only works if the file contains a single template definition and no extraneous markup. Our file fails on both counts.

Another disadvantage my previous approach is caching. When you render a string-based template, jQuery Templates doesn’t cache the compiled template. If you end up rendering the same template more than once per pageview, the string-based approach was slower than it could have been.

To solve both those issues, we can use jQuery to load the contents of the template file, inject all of it into the document, and then work with the templates as if they had been embedded in the page all along.

// The invoice object to render (see previous post).
var invoice = {
  invoiceItems: [
    { type: 'item', 
      part: '99Designs', description: '99 Designs Logo', 
      price: 450.00, qty: 1 },
    { type: 'service',
      service: 'Web development and testing', 
      price: 25000.00 },
    { type: 'item',
      part: 'LinodeMonthly', description: 'Monthly site hosting', 
      price: 40.00, qty: 12 }
  ]
};
 
// Asynchronously load the template definition file.
$.get('_invoice.tmpl.htm', function(templates) {
  // Inject all those templates at the end of the document.
  $('body').append(templates);
 
  // Select the newly injected invoiceTemplate and use it
  //  render the invoice data.
  $('#invoiceTemplate').tmpl(invoice).appendTo('body');
});

Injecting the template definitions into the page’s markup allows you to render them with the same $('#templateId').tmpl(data) syntax that you’ve seen in most jQuery Templates examples.

Bringing the row template resolver along for the ride

One remaining annoyance is the now-orphaned row template name resolver, get_invoiceRowTemplateName() (covered in my composite template post). Keeping that function with the rest of the page’s JavaScript does work, but I’m not happy with it. To get the full benefit of encapsulating the template in an external file, we should keep any dependent JavaScript code with the template itself.

That’s especially true if the template is used from more than one page.

As it turns out, accomplishing that is much easier than it may seem at first. All we need to do is move the resolver function right into _invoice.tmpl.htm:

<!-- Invoice container template -->
<script id="invoiceTemplate" type="x-jquery-tmpl">
  <table class="invoice">
  {{each lineItems}}
    {{tmpl($value) get_invoiceRowTemplateName(type)}}
  {{/each}}
  </table>
</script>
 
<!-- Invoice row templates -->
<script id="serviceRowTemplate" type="x-jquery-tmpl">
  <tr class="service">
    <td colspan="2">${service}</td>
    <td colspan="2">${price}</td>
  </tr>
</script>
 
<script id="itemRowTemplate" type="x-jquery-tmpl">
  <tr class="item">
    <td>${item}</td>
    <td>${description}</td>
    <td>${price}</td>
    <td>${qty}</td>
  </tr>
</script>
 
<!-- This function is used by the invoice container to determine -->
<!--  which row template to render for a given line item -->
<script type="text/javascript">
  function get_invoiceRowTemplateName(type) {
    // Return a template selector that matches our 
    //  convention of <type>RowTemplate.
    return '#' + type + 'RowTemplate';
  }
</script>

When you inject markup into the DOM, browsers will immediately parse and evaluate that markup just as they do during the initial page load – including any JavaScript code in the markup. Since browsers do this in the same single-thread that they execute JavaScript, it’s safe to assume that embedded functions are available immediately after the markup has been injected.

It seems almost too good to be true, like one of those handy techniques that works in every browser except some version of IE. However, embedding the supporting function inside the template file works in every browser I’ve tested, even including the full complement of JavaScript-enabled options on BrowserShots.org.

Conclusion

I’ve been using this exact technique in production for about a month now. I initially came up with several approaches, but wanted to try them in real-world code before I recommended one. I’m happy to report that this has been working great for me so far. I hope you’ll find it helpful too.

One caveat is that you should be careful about loading and injecting the external template more than once. Injecting multiple copies of the template definitions over and over actually doesn’t break the rendering process in browsers I’ve tested, but it will unecessarily impact performance as the DOM grows larger with every new injection.

I’m going to cover that and another templating concurrency issue soon, but if you want a head start: test $.template('#templateName') to determine whether a particular template is already loaded and cached.

Related posts:

1. Using external templates with jQuery Templates
2. Composition with jQuery Templates: Why and How
3. A few thoughts on jQuery templating with jQuery.tmpl

You've been reading jQuery Templates, composite rendering, and remote loading, originally posted at Encosia. I hope you enjoyed it, and thanks for reading.

If you've got any feedback, please click through and leave a comment; I'd love to hear from you. You can click here to jump directly to the comment section of this post.

Since then, a common question I’ve received amounts to: “Great, but why?”

I think that’s natural, because template composition is one of those things that can seem obscure until you put it to work for the first time. From that point onward, you’ll begin to see the structure of your client-side templates in a different light. Simplifying your templates into smaller logical parts and then combining those parts to create the desired end result is a powerful approach. It’s terrific for making large templates more approachable and maintainable over the lifetime of an application.

In this post, I want to show you an example of a scenario that template composition is well suited to, a couple ways that jQuery Templates’ {{tmpl}} feature can be used to simplify that scenario, and a bonus advantage that the composition approach provides even after the template has been rendered.

An example scenario: The invoice

Imagine that you need to display an invoice for a company that resells taxable items and also sells services. Ideally, the invoice line items for those separate “types” should be displayed with different markup. To explore a simple example of that, let’s create a template to render the invoice for a fictional web development company.

Whether retrieved from a server-side endpoint or embedded in the page during initial rendering, the underlying data for that invoice might be structured something like this:

var invoice = {
  invoiceItems: [
    { type: 'item', 
      part: '99Designs', description: '99 Designs Logo', 
      price: 450.00, qty: 1 },
    { type: 'service',
      service: 'Web development and testing', 
      price: 25000.00 },
    { type: 'item',
      part: 'LinodeMonthly', description: 'Monthly site hosting', 
      price: 40.00, qty: 12 }
  ]
};

Following from that data structure, our goal for the invoice’s markup might look something like this:

<table>
  <tr>
    <td>99Designs</td>
    <td>99 Designs Logo</td>
    <td>$450.00</td>
    <td>1</td>
  </tr>
  <tr>
    <td colspan="2">Web development and testing</td>
    <td colspan="2">$25,000.00</td>
  </tr>
  <tr>
    <td>LinodeMonthly</td>
    <td>Monthly hosting at Linode</td>
    <td>$40.00</td>
    <td>12</td>
  </tr>
</table>

Notice that the markup for service and item rows is structurally different, to better represent the underlying data. When that’s desirable, composing sub-templates is the way to go. As we’ll see next, the alternative is unappealing.

The old fashioned way

The key to our goal of rendering different markup for services and items is to render different template code depending on the line item’s type property.

Of course, it’s possible to achieve that without using template composition. The {{if}} template tag allows you to concoct just about any conditional rendering scheme that you can image. For example:

<script id="invoiceTemplate" type="x-jquery-tmpl">
  <table class="invoice">
    {{each invoiceItems}}
      {{if type == 'service'}}
      <tr class="service">
        <td colspan="2">${service}</td>
        <td colspan="2">${price}</td>
      </tr>          
      {{else type == 'item'}}
      <tr class="item">
        <td>${item}</td>
        <td>${description}</td>
        <td>${price}</td>
        <td>${qty}</td>
      </tr>          
      {{/if}}
    {{/each}}
  </table>
</script>

That works, but it’s a mess.

Even with only two types of items, the template is already fairly difficult to read and digest. Just imagine if there were a dozen item types instead of only two. Bundling all the templates together would quickly become a maintenance nightmare.

Wouldn’t it be nice if we could separate the row templates and define them individually? The {{tmpl}} template tag allows us to do just that.

Reorganizing the template for composition

First, we need to separate the template into a container and individual row templates for each line item type. The container will be rendered once for every invoice, and the row templates as dictated by the underlying data.

In this case, the container template will simply begin and end our <table>. In a real-world template, this is where you might also include a <thead> with column headings.

<script id="invoiceTemplate" type="x-jquery-tmpl">
  <table class="invoice">
    <!-- Composition magic goes here! -->
  </table>
</script>

The row templates are straightforward, extracted from the combined template we looked at in the last section:

<script id="serviceRowTemplate" type="x-jquery-tmpl">
  <tr class="service">
    <td colspan="2">${service}</td>
    <td colspan="2">${price}</td>
  </tr>
</script>
 
<script id="itemRowTemplate" type="x-jquery-tmpl">
  <tr class="item">
    <td>${item}</td>
    <td>${description}</td>
    <td>${price}</td>
    <td>${qty}</td>
  </tr>
</script>

Note that the templates have IDs that correspond to the type they’re designed to render. That will come in handy a bit later.

Template composition with jQuery Templates

Now, it’s finally time to add that composition magic to the container template. jQuery Templates has a special template tag which provides for rendering and composing nested templates: {{tmpl}}.

The {{tmpl}} tag has several usages (documentation), but the one I want to focus on is the one that accepts a selector as its template parameter. When a selector is specified, jQuery Templates locates the indicated template, renders it, and then replaces the {{tmpl}} token with that rendered markup.

The {{tmpl}} command also accepts a parameter specifying what data the sub-template should be rendered with. Including the template selector, the command will look like this: {{tmpl(dataItem) "#TemplateID"}}.

Putting that all together, this container template will use each item’s type to render the item with the appropriate row template:

<script id="invoiceTemplate" type="x-jquery-tmpl">
  <table class="invoice">
    {{each invoiceItems}}
      {{if type == 'service'}}
        {{tmpl($value) '#serviceRowTemplate'}}
      {{else type == 'item'}}
        {{tmpl($value) '#itemRowTemplate'}}
      {{/if}}
    {{/each}}
  </table>
</script>

If you aren’t familiar with {{each}} and its $value pseudo variable, all you need to know is that it contains the current iteration’s data item. It’s the same value that you would normally capture as the second parameter to an $.each() callback. In fact, {{each}} can also be used in that fashion instead:

<script id="invoiceTemplate" type="x-jquery-tmpl">
  <table class="invoice">
    {{each(i, item) invoiceItems}}
      {{if type == 'service'}}
        {{tmpl(item) '#serviceRowTemplate'}}
      {{else type == 'item'}}
        {{tmpl(item) '#itemRowTemplate'}}
      {{/if}}
    {{/each}}
  </table>
</script>

I prefer using the pseudo variable since it’s more concise, but both are equivalent.

For now, we’re still stuck with the {{if}} to determine which row template to render, but getting the row templates out of that conditional block has cleaned things up quite a bit. Don’t worry if the conditional strikes you as a distasteful remnant of the original approach. We’ll fix that soon.

Rendering the composite template

Having defined the container template and its sub-templates, using jQuery Templates to render the entire group is just as easy as rendering a single template. Assuming the same invoice variable as seen before:

$('#invoiceTemplate').tmpl(invoice).appendTo('body');

As far as we know at the time we render the container, nothing has changed (and that’s part of the point), yet the refactored template is going to be quite a bit easier to understand and maintain.

Unconditional rendering love

Now that the templates are separated, things are a lot cleaner than before. However, that remnant {{if}} block is still a bit irritating. If you end up with more than just a couple item types, the conditional will require ongoing maintenance and cruft up the template badly.

Instead of that explicit testing and branching to pick the right template, we can clean things up by automatically searching for a row template that matches our naming convention of typeRowTemplate. To do that, we just need to build a JavaScript function that takes a type parameter and returns the appropriate selector string:

function get_invoiceRowTemplateName(type) {
  // Return a template selector that matches our 
  //  convention of <type>RowTemplate.
  return '#' + type + 'RowTemplate';
}

Updating the container template to use our new function completely eliminates that {{if}} block:

<script id="invoiceTemplate" type="x-jquery-tmpl">
  <table class="invoice">
  {{each lineItems}}
    {{tmpl($value) get_invoiceRowTemplateName(type)}}
  {{/each}}
  </table>
</script>

Now, adapting to new item types is as simple as creating an appropriately named template. Convention over configuration, as they say.

Bonus: Rendering additional line items

Cleaning up the template is a good enough reason alone to use template composition, but the benefits extend beyond the initial rendering process. A nice side-effect of the compositional approach is that it’s easy to render additional rows even after the template has been rendered.

It’s easy to imagine that we might need to let users add new items to our invoice after it has been displayed. Assuming the invoice is already rendered, adding a matching row to it is as easy as this:

var newItem = {
  type: 'service',
  service: 'Service with a smile',
  price: 0.00
};
 
// Determine which template should be used to render the new item.
var tmpl = get_invoiceRowTemplateName(newItem.type);
 
// Render that template, using the new item as data,
//  and append that new row to the end of the existing invoice table.
$(tmpl).tmpl(newItem).appendTo('#table.invoice');

That’s cleaner, easier, and faster than the common alternatives of cloning an existing row, building the HTML manually, or completely re-rendering the entire table with updated data.

Perhaps more importantly, it centralizes your presentation code. When changes only need to be made once, in a single location, you are guaranteed to see less bugs over time.

Conclusion

I’ve been using this compositional approach with jTemplates for a couple years now, and I cannot overstate how helpful it is when you’re working on real-world apps with large, complex client-side templates. I do hope you’ll give it a try in your own projects, because I know you won’t be disappointed.

Kudos to everyone who worked on jQuery Templates and helped {{tmpl}} see its way into the first release. I think it’s an excellent implementation of the feature – certainly easier to use and understand than jTemplates’ #include.

An important piece of the puzzle that’s still missing at this point is a technique for storing these composite template groups in an external file and loading them asynchronously, as with single templates in my last post. Unfortunately, the simplistic approach in my previous post doesn’t work with composite templates. However it’s still very easily doable. I’ll cover that next, so stay tuned.

What do you think? Are you using template composition already? If not, have I managed to entice you to give it a try?

Related posts:

1. jQuery Templates, composite rendering, and remote loading
2. Using external templates with jQuery Templates
3. A few thoughts on jQuery templating with jQuery.tmpl

You've been reading Composition with jQuery Templates: Why and How, originally posted at Encosia. I hope you enjoyed it, and thanks for reading.

If you've got any feedback, please click through and leave a comment; I'd love to hear from you. You can click here to jump directly to the comment section of this post.