Tales from the Evil Empire : Microsoft AJAX Library

JavaScript class browser: once again with jQuery

Bertrand Le Roy — Fri, 30 Oct 2009 17:43:00 GMT

I’ve already posted twice about that little class browser application. The first iteration was mostly declarative and can be found here:
http://weblogs.asp.net/bleroy/archive/2009/09/14/building-a-class-browser-with-microsoft-ajax-4-0-preview-5.aspx

The second one was entirely imperative and can be found here:
http://weblogs.asp.net/bleroy/archive/2009/10/15/entirely-unobtrusive-and-imperative-templates-with-microsoft-ajax-4-preview-6.aspx

This new version builds on top of the code for the imperative version and adds the jQuery dependency in an attempt to make the code leaner and simpler. I invite you to refer to the imperative code (included in the archive for this post) and compare it with the jQuery version, which shows a couple of ways the Microsoft Ajax Library lights up when jQuery is present.

The first thing I want to do here is convert the plain function I was using to build the browser’s namespace and class tree into a jQuery plug-in:

$.fn.classBrowserTreeView = function (options) {
  var opts = $.extend({},
    $.fn.classBrowserTreeView.defaults,
    options);
  return this;
};

That plug-in will have two options: the data to render (which will default to the root namespaces in the Microsoft Ajax Library), and the node template selector (which will default to “#nodeTemplate”):

$.fn.classBrowserTreeView.defaults = {
  data: Type.getRootNamespaces(),
  nodeTemplate: "#nodeTemplate"
};

For the moment, as you can see, this plug-in does nothing. We want it to create a DataView control on each of the elements of the current wrapped set. We will do this by calling into the dataView plug-in.

You may be wondering where this plug-in might come from. Well, that’s the first kind of lighting up that the Microsoft Ajax Library’s script loader (start.js) will do in the presence of jQuery: every control and behavior will get surfaced as a jQuery plug-in, and components will get added as methods on the jQuery object. This is similar to what I had shown a while ago in this post, only much easier:
http://weblogs.asp.net/bleroy/archive/2009/05/04/creating-jquery-plug-ins-from-microsoftajax-components.aspx

For example, we can write this in our own plug-in to create DataView components over the current jQuery wrapped set:

return this.dataView({
  data: opts.data,
  itemTemplate: opts.nodeTemplate,
});

Now we can wire up the itemRendered event of the data view and start enriching the markup that the DataView control rendered for each data item. First, let’s get hold of the nodes in the rendered template and wrap them:

var elt = $(args.nodes);

Then, if the current node is representing a namespace, we want to hook up the expansion button’s click event so that it toggles visibility of the list of children, and we want to “unhide” the button itself (it has a “hidden” class in the default markup):

if (Type.isNamespace(args.dataItem)) {
  elt.find(".toggleButton").click(function (e) {
    e.preventDefault();
    return toggleVisibility(this);
  }).removeClass("hidden");
}

You can see here that we’re taking advantage of chaining.

Next thing is to set-up the node link itself. We start by inhibiting the link’s default action. Then we set the text for the link, and finally we set the command that will bubble up to the DataView when the link gets clicked:

elt.find(".treeNode").click(
  function (e) {
    e.preventDefault();
    return false;
  })
  .text(getSimpleName(args.dataItem.getName()))
  .setCommand("select");

Here, I’m using a small plug-in to set the command:

$.fn.setCommand = function (options) {
  var opts = $.extend({},
    $.fn.setCommand.defaults, options);
  return $(this).each(function () {
    $.setCommand(this,
      opts.commandName,
      opts.commandArgument,
      opts.commandTarget);
  });
}
$.fn.setCommand.defaults = {
    commandName: "select",
    commandArgument: null,
    commandTarget: null
};

I’m using $.setCommand here, which does get created by the framework for me, but I still need to create that small plug-in to make it work on a wrapped set instead of a static method off jQuery. I’ve sent feedback to the team that setCommand and bind should get created as plug-ins by the framework and hopefully it will happen in a future version.

The last thing we need to do here is to recursively create the child branches of our tree:

elt.find("ul").classBrowserTreeView({
    data: getChildren(args.dataItem)
});

This just finds the child UL element of the current branch and calls our plug-in on the results with the children namespaces and classes as the data.

And this is it for the tree, we can now create it with this simple call:

$("#tree").classBrowserTreeView();

The details view rendering will only differ in minor ways from the code we had in our previous imperative version. The only differences is the use of jQuery to traverse and manipulate the DOM instead of the mix of native DOM APIs and Sys.get that we were using before. For example,

args.get("li").innerHTML =
  args.dataItem.getName ?
    args.dataItem.getName() :
    args.dataItem.name;

becomes:

$(args.nodes).filter("li").text(
  args.dataItem.getName ?
    args.dataItem.getName() :
    args.dataItem.name);

Notice how jQuery’s text method makes things a little more secure than the innerHTML we had used before.

Updating the details view with the data for the item selected in the tree is done by handling the select command of the tree from the following function:

function onCommand(sender, args) {
  if (args.get_commandName() === "select") {
    var dataItem = sender.findContext(
      args.get_commandSource()).dataItem;
    var isClass = Type.isClass(dataItem) &&
                 !Type.isNamespace(dataItem);
    var childData =
      (isClass ? getMembers : getChildren)(dataItem);
    var detailsChild =
      Sys.Application.findComponent("detailsChild");
    detailsChild.onItemRendering =
      isClass ?
        onClassMemberRendering :
        onNamespaceChildRendering;
    detailsChild.onItemRendered =
      onDetailsChildRendered;
    detailsChild.set_data(childData);
    $("#detailsTitle").text(dataItem.getName());
    $(".namespace").css(
      "display",
      isClass ? "none" : "block");
    $(".class").css(
      "display",
      isClass ? "block" : "none");
    $("#details").css("display", "block");
  }
}

Not much change here from the previous version, again, except for the use of jQuery and some chaining.

And that is pretty much it. I’ve made other changes in the script to make use of the new script loader in the Microsoft Ajax Library but that will be the subject of a future post.

Hopefully, this has shown you how the Microsoft Ajax Library can light up with jQuery. The automatic creation of plug-ins feels very much like native jQuery plug-ins and brings all the power of client templates to jQuery. Once we have bind and setCommand plug-ins as well, the Microsoft Ajax Library may become a very useful tool to jQuery programmers just as much as jQuery itself is a very useful tool to Microsoft Ajax programmers.

The code can be found here:
http://weblogs.asp.net/blogs/bleroy/Samples/ClassBrowserWithjQueryUpdated.zip

Update: fixed a problem in Firefox & Chrome.

How to render the same template on the server and client with minimal redundancy

Bertrand Le Roy — Mon, 19 Oct 2009 08:50:00 GMT

Last week, I wrote a post about how the new Microsoft Ajax Library Preview 6 made it a lot easier to write unobtrusive and imperative data-driven applications. Because for the previous preview, I had written a cool little class browser using a declarative style, I thought it would be nice to rewrite this in a completely imperative way. The mistake I made though was to call it unobtrusive. Never mind that ‘unobtrusive’ is a perfectly well-defined word that actually existed way before JavaScript. ‘Unobtrusive JavaScript’ has a very specific meaning that people feel strongly about. To be worthy of that label, an application must basically conform to (at least) those two requirements:

Markup and behavior are strictly separated. That means no DOM-0 event handlers, no custom attributes or tags, and even no microformats imo.
Graceful degradation / progressive enhancement. This means that the application’s script is only used to improve what would work without script, in other words that the application is entirely usable without script.

While my little sample strictly conformed to (1), it didn’t conform to (2). Not because I’m too dumb or ignorant, mind you, but because for this application, it didn’t make any sense at all: the application’s whole point is to display client-side script objects. The server does not have the first clue about the data that needs to be rendered. Which makes it impossible for anything to render without script. Which in turn triggered some unpleasant comments on the post: this was not really unobtrusive JavaScript in the full sense of the term. Not the library’s fault though, just my own for using the wrong example.

The right example

So I thought the best thing to fix this is to provide a more relevant example, one where the server could actually be a fallback scenario.

The new sample code is a fairly simple master-details view on a silly data set: jedi data. We have a WCF web service that is returning a list of jedis and their associated data, which the application can render on the server-side or on the client-side. Once you have data that is available from both the server and client sides, your best and simplest tool to achieve progressive enhancement is the plain <a> tag. You can build the links in your application so that without script, they do something meaningful:

<a href="?jedi=all" id="expandButton">+</a>

What you see above is the + link on the top-left of the screen that will expand the list of jedis. To make it work client-side instead of the server-side, you use script to add a click handler that suppresses the default behavior of the link and replaces it with the equivalent client-side action:

Sys.UI.DomEvent.addHandler(
  Sys.get("#expandButton"), "click", function(e) {
    e.preventDefault();
    jediList.fetchData();
    return false;
  });

That’s fairly easy and has been possible since, well, I’m not sure but it’s been a looong time.

Now there’s the templated rendering. Rendering the same thing from the server and the client without repeating oneself too much is not as simple. The key to it is to render the server template with an empty data item and then to use the result of that as the client template.

<ul id="jediList"
<%if (!isDetails) { %> class="sys-template"<% } %>>
<%var jedis = !isDetails ?
    new List<Jedi>() {new Jedi()} :
    new JediService().GetJedis();
  foreach (var jedi in jedis) { %>
    <li>
      <a href="?jedi=<%= jedi.Name %>">
        <%= jedi.Name%>
      </a>
    </li>
<%} %>
</ul>

This way, there is only one template, only one version of the markup, that we are using on both the server and client sides. When rendered from the server with the actual data set, we get the list right away, and the browser just displays it (and search engines can see the list as well, something you can’t achieve with pure script). When rendered with the dummy dataset, we get the following:

<ul id="jediList" class="sys-template">
  <li><a href="?jedi=all">all</a></li>
</ul>

This markup can be used as a template on the client-side by this code:

var jediList = Sys.create.dataView("#jediList", {
  dataProvider: "JediService.svc",
  fetchOperation: "GetJedis",
  autoFetch: false,
  itemRendered: function(sender, args) {
    var link = args.get("a");
    var dataItem = args.dataItem;
    link.innerHTML = dataItem.Name;
    Sys.UI.DomEvent.addHandler(
      link, "click", function(e) {
        e.preventDefault();
        details.set_data(dataItem);
        return false;
      });
  }
});

The details view is built on pretty much the same principle. The main difference is that it does have additional markup to delimit the fields that we’ll want to set dynamically. Here’s how it renders with the dummy data:

<div id="details" class="sys-template">
    <span id="jediName"></span>
    owns a
    <span id="jediLightSaber"></span>
    lightsaber and is on the
    <span id="jediSide"></span>
    side.
</div>

All the itemRendered handler has to do then is fill in the blanks:

var details = Sys.create.dataView("#details", {
  itemRendered: function(sender, args) {
    args.get("#jediName").innerHTML =
      args.dataItem.Name;
    args.get("#jediLightSaber").innerHTML =
      args.dataItem.LightsaberColor;
    args.get("#jediSide").innerHTML =
      args.dataItem.DarkSide ? "dark" : "light";
  }
});

So what do you think?

Here’s the code (by the way, I’m using the Microsoft CDN in there):
http://weblogs.asp.net/blogs/bleroy/Samples/ServerClientTemplate.zip

Entirely unobtrusive and imperative templates with Microsoft Ajax Library Preview 6

Bertrand Le Roy — Thu, 15 Oct 2009 09:12:00 GMT

Today is the release of the sixth preview of Microsoft Ajax Library. Don’t get fooled by the somewhat silly and long name: this is a major release in many ways. The scripts have been majorly refactored since preview 5. Check out the other posts out there (links at the bottom of this post) to see just some of the many new features that are in there. Some of my favorite are all the small improvements that have been made to make imperative instantiation of components and templated contents easier than ever. Many of you have told us that you preferred to do things imperatively and this release makes it a lot better.

When Preview 5 came out, I built a simple class browser using the declarative syntax. The class browser shows the hierarchy of namespaces and classes in a tree view on the left side of the page, and the details of whatever’s selected in the tree on the right side of the page:http://weblogs.asp.net/bleroy/archive/2009/09/14/building-a-class-browser-with-microsoft-ajax-4-0-preview-5.aspx

It still works (and an updated version is attached to this post), but I thought I would demonstrate how you can take that same sample and re-implement it in a completely imperative way. Of course, you never have to go all the way one way or another, and it’s always possible for example to use the nice declarative syntax for bindings but instantiate your components imperatively if you choose to do so. In this post, I’m deliberately going imperative all the way. Just keep in mind this is rather extreme.

The first thing to notice in the new version is that the markup is perfectly clean and contains no weird extension, namespace or custom binding syntax whatsoever. It’s 100% pure HTML 5. Here is for example the complete markup for the tree view on that page:

<ul id="tree" class="tree"></ul>

<ul id="nodeTemplate" class="sys-template">
    <li>
        <a class="toggleButton" href="#">+</a>
        <a class="treeNode" href="#"></a>
        <ul></ul>
    </li>
</ul>

The script that builds the dynamic contents is bootstrapped by the following code:

<script type="text/javascript"
        src="Scripts/start.js"></script>
<script type="text/javascript">
Sys.loadScripts(["Scripts/Tree.js"], function() {
  Sys.require([Sys.components.dataView], function() {
    createTreeView("#tree",
                   Type.getRootNamespaces(),
                   "#nodeTemplate");
    Sys.create.dataView("#detailsChild", {
      itemRendered: onDetailsChildRendered
    });
  });
});
</script>

We’re making use of the new script loader here: we first include the bootstrapper file, start.js, and then we declare that we need one custom script, “tree.js” and everything necessary to instantiate a DataView. The script loader will figure out on its own the set of scripts it needs to download for that. Once those scripts have been downloaded, we call createTreeView, which is custom code that we’ll look at in a moment that creates nested DataView controls over the markup. We also create a second DataView to display the details of what’s selected in the tree.

Notice that we set some properties to a selector string here (for example “#nodeTemplate”). This is actually a breaking change from the previous preview, which only understood id strings. Microsoft Ajax does not include a full selector engine but it does understand the most basic of selectors (.class, tagName and #id). But where it gets really interesting is that if you had included jQuery on the page, the framework would detect it and enable you to use full selectors everywhere. Isn’t that sweet?

So how does the imperative approach compare with the declarative one? Well, for instantiating components, you already have an example above, where we use Sys.create.dataView. But what about wiring up events, setting text contents and attribute values, instantiating components over the markup inside the template?

All those are done by post-processing the template instances after they’ve been instantiated, by handling the itemRendered event:

itemRendered: function(sender, args) {
  // do magic
}

Wiring up events is as simple as getting a reference to an element and calling addHandler:

var toggleButton = args.get(".toggleButton");
Sys.UI.DomEvent.addHandler(toggleButton, "click",
  function(e) {
    toggleVisibility(this);
  }, true);

The args.get function, which you will use a lot, takes a selector and returns the first element that matches it inside the template. Here, we are looking for an element with class “toggleButton”, but a local id would work just as well.

To set text contents and attribute values is trivial once you know how to get references to elements from local selectors (remember, jQuery also works here transparently or even explicitly when and if you need it).

Finally, instantiating components is also quite easy. For example, here is the code that creates an inner DataView for the child nodes of a node in the tree, recursively:

var childView = args.get("ul");
createTreeView(childView,
               getChildren(args.dataItem),
               nodeTemplate);

The args.get funtion is used once more to get a reference to the first UL element within the template, and it is then easy to do a recursive call into our tree creation function and build the new branch of the tree.

The command bubbling feature that makes it so easy to wire up custom commands into a template is still usable in imperative code:

var treeNode = args.get(".treeNode");
Sys.setCommand(treeNode, "select");

Finally, there is one feature that I’m not using in that sample, but that’s immensely useful, and I’m talking of course of live bindings. Those work too, all you have to do is call the Sys.bind function and give it the target object, the name of the target property to bind, the source object and the source property name.

To render the details view, I decided to not use a single item DataView like I did with the declarative version: since I’m going to use imperative code instead of declarative bindings, it is just as easy to directly manipulate the DOM that already exists, and do some hiding and showing of elements:

function onCommand(sender, args) {
  if (args.get_commandName() === "select") {
    var dataItem = sender.findContext(
      args.get_commandSource()).dataItem;
    var isClass = Type.isClass(dataItem) &&
                 !Type.isNamespace(dataItem);
    var childData =
      (isClass ? getMembers : getChildren)(dataItem),
      namespaceElementsDisplay = 
        isClass ? "none" : "block",
      classElementsDisplay =
        isClass ? "block" : "none",
      detailsChild =
        Sys.Application.findComponent("detailsChild");
    detailsChild.onItemRendering =
      isClass ?
        onClassMemberRendering :
        onNamespaceChildRendering;
    detailsChild.set_data(childData);
    Sys.get("#detailsTitle").innerHTML =
      dataItem.getName();
    Sys.get("#namespacesColumn").style.display =
    Sys.get("#classesColumn").style.display =
      namespaceElementsDisplay;
    Sys.get("#propertiesColumn").style.display =
    Sys.get("#eventsColumn").style.display =
    Sys.get("#methodsColumn").style.display =
    Sys.get("#staticMethodsColumn").style.display =
      classElementsDisplay;
    Sys.get("#details").style.display = "block";
  }
}

We do have a DataView to render the contents of the currently selected object though. The nice trick we used with the declarative version to dynamically switch the target place holder where the template gets rendered is still there, which enables a single DataView control to dispatch the data into two to four separate lists (or however much you want for that matter):

function onNamespaceChildRendering(args) {
    args.set_itemPlaceholder(
        Type.isClass(args.get_dataItem()) ?
            "#classPlaceHolder" :
            "#namespacePlaceHolder"
    );
}

I think all this is pretty cool and I hope the comparison between the declarative version and the imperative version of this little application gives you a sense of the flexibility that the Microsoft Ajax library now offers, and of how much you can choose your own development style and do pretty much anything with the same ease.

Download the code for this post here:
http://weblogs.asp.net/blogs/bleroy/Samples/Preview6ClassBrowser.zip

Microsoft Ajax Library Preview 6 can be downloaded from here:
http://aspnet.codeplex.com/Release/ProjectReleases.aspx?ReleaseId=34488

Here are a few links about this release:
http://weblogs.asp.net/scottgu/archive/2009/10/15/announcing-microsoft-ajax-library-preview-6-and-the-microsoft-ajax-minifier.aspx
http://channel9.msdn.com/posts/jsenior/Announcing-Microsoft-Ajax-Library-Preview-6/
http://www.jamessenior.com/post/How-the-Script-Loader-in-the-Microsoft-Ajax-Library-will-make-your-life-wonderful.aspx

Ajax Control Toolkit: new controls, bug fixes

Bertrand Le Roy — Thu, 01 Oct 2009 00:28:00 GMT

And we have a new release of Ajax Control Toolkit. I didn’t work on this one but there are some nice things in there nonetheless :)

First, new controls!

SeaDragon: I’ve blogged before about Seadragon, the JavaScript-only way to do Deep Zoom. It became a lot easier to use a few month ago when the need for tools disappeared and you can just point to any image on the web and immediately get the URL and script tag to put on your page:

Now with this release of Ajax Control Toolkit, including and controlling Deep Zoom from an ASP.NET page is also very easy:

<ajaxToolkit:Seadragon ID="Seadragon"
    CssClass="seadragon" runat="server"
    SourceUrl="sample.xml"/>

James Senior just released a screencast on how to create Deep Zoom contents for the new Seadragon control:
http://channel9.msdn.com/posts/jsenior/Seadragon-Ajax-Control-Quick-Start-Guide/

AsyncFileUpload: This is by far one of the most requested controls for ACT. File upload fields, while a part of HTML, do not work with Ajax/XHR requests (for security reasons, JavaScript can’t access the contents of the field). The only way to use them is to get the browser to do a real form post.

This new control makes it a lot easier to handle file uploads from your Ajax applications by providing an abstraction on top of the form posting:

<ajaxToolkit:AsyncFileUpload
    OnClientUploadError="uploadError"
    OnClientUploadComplete="uploadComplete" 
    runat="server" ID="AsyncFileUpload1"
    Width="400px" UploaderStyle="Modern" 
    UploadingBackColor="#CCFFFF"
    ThrobberID="myThrobber"/>

It works pretty much as advertised: just drop the control on the page, and you can upload files without a full postback. It looks just like Ajax and requires no plug-in of any kind.

The control has client and server-side events that get triggered when the file has been uploaded. On the server-side, you have access to the uploaded file’s byte stream, which you can save to disk (or database, or whatever).

Bug fixes: This release also has some new bug fixes (courtesy of Obout) for some of the top-voted issues.

Download the new release here:
http://ajaxcontroltoolkit.codeplex.com/Release/ProjectReleases.aspx?ReleaseId=33804

Try the live demos here:
http://www.asp.net/ajax/ajaxcontroltoolkit/samples/

Stephen's in-depth post about this release:
http://stephenwalther.com/blog/archive/2009/10/01/new-ajax-control-toolkit-release.aspx

Building a class browser with Microsoft Ajax 4.0 Preview 5

Bertrand Le Roy — Mon, 14 Sep 2009 07:29:37 GMT

The Microsoft Ajax Library 4.0 Preview 5 is the first release of Microsoft Ajax that I didn’t participate in: I left the team a few months ago. But that doesn’t mean I don’t love what’s in there, and I really do. And by the way I’ve also seen what’s in Preview 6 too and man that will seriously rock.

So I thought I’d write a little something to celebrate the new preview. The new features include recursive templates, which is pretty much begging us to implement a treeview with it, and we’ll do just that in this post.

There is also an intriguing capability, which enables you to dynamically set what template to render for each data item, and where to render it. At first, this doesn’t look like the most useful thing in the world, but it actually opens up some very interesting possibilities, which we’ll also show in this post.

The sample code that I’m going to write for this post is a rudimentary class browser. It will render a treeview representing the hierarchical structure of namespaces and classes in Microsoft Ajax, and clicking one of the tree nodes will render a details view for it: a list of classes and subnamespaces for namespaces, and a grouped list of members for classes.

Let’s start with the tree. It will be rendered as nested unordered lists by a simple recursive DataView:

<ul id="tree" class="tree"
    sys:attach="dataview"
    dataview:data="{{ Type.getRootNamespaces() }}"
    dataview:itemtemplate="nodeTemplate"
    dataview:oncommand="{{ onCommand }}">
</ul>

<ul id="nodeTemplate" class="sys-template">
  <li>
    <a href="#" onclick="return false;"
       sys:command="select">
      {{ getSimpleName($dataItem.getName()) }}
    </a>
    <ul sys:attach="dataview"
        dataview:data="{{ getChildren($dataItem) }}"
        dataview:itemtemplate="nodeTemplate"
        dataview:oncommand="{{ onCommand }}"></ul>
    </li>
</ul>

On the first UL, which is the outer DataView for the tree, you can see that we set the data property to Type.getRootNamespaces(), which returns the set of root namespaces currently defined.

We also set the template to point to the “nodeTemplate” element, which has to be outside the DataView itself when doing recursive templates. Note that the outer node of the template, the UL, won’t actually get rendered into the target ul (tree). It is only a container.

The command event of the DataView is hooked to the onCommand function, and we’ll get back to that when we couple the tree with the detail view.

In the template itself, you can see we have a link with the select command so that clicking it will trigger the nearest onCommand event up the DOM.

The text of that link is the results of a call to getSimpleName, which will extract the last part of the fully-qualified name of the namespace or class.

After that link, we find another DataView control. The data property of that control points to an array of namespaces and classes under the current object. But the nice part here is that the template property points to “nodeTemplate”, its own parent, enabling the recursive nature of the tree.

In other words, we’ve morphed a simple DataView control into a tree, with minimal effort and code.

There is just one thing missing to the tree, and that is the +/- buttons that will collapse and expand the tree nodes. This is actually very easy to set-up using CSS and some simple script. First, let’s collapse the tree by default. This is done by defining the style of the tree as follows in our stylesheet:

.tree ul 
{
    padding: 0;
    display:none;
}

This has the effect of collapsing all unordered list nodes under the tree.

The +/- button is created by adding the following to the template, right before the existing link:

<a class="toggleButton" href="#"
   sys:if="Type.isNamespace($dataItem)" 
   onclick="return toggleVisibility(this);">+</a>

The button is a simple link whose rendering is conditioned by whether the current data item is a namespace: only namespaces can be expanded, classes are leaf nodes.

The toggling function itself is fairly simple:

function toggleVisibility(element) {
    var childList = element.parentNode
                     .getElementsByTagName("ul")[0],
        isClosed = element.innerHTML === "+";
    childList.style.display =
        isClosed ? "block" : "none";
    element.innerHTML = isClosed ? "-" : "+";
    return false;
}

This just toggles the display style of the first child UL between none and block, and the text of the link between + and –.

So there it is, we have built a simple tree by simply making use of the recursive capabilities of DataView and some very simple script.

Before we look at the details view, let’s look at the code that gets called when the user selects a node in the tree:

function onCommand(sender, args) {
    var dataItem = sender.findContext(
        args.get_commandSource()).dataItem;
    $find("details").set_data(dataItem);
}

That code gets a reference to the data item for the selected node from the template context that we can get from the sender of the event (the inner DataView that contains the selected node) using the command source as provided by the event arguments (that source is the element that triggered the command). We can then set the data of the details DataView to that data item, which will trigger that view to re-render.

Now let’s build the details view. The details view will display the child namespaces and classes if a namespace is selected in the tree, and the properties, events and methods (instance and static) in the case of a class.

For each case, we’ll use a different template: “namespaceTemplate” for namespaces, and “classTemplate” for classes, but we’ll do so from the same DataView. This dynamic template switching is done by handling the onItemRendering event of the DataView:

function onDetailsRendering(sender, args) {
    var dataItem = args.get_dataItem();
    args.set_itemTemplate(Type.isNamespace(dataItem) ?
        "namespaceTemplate" : "classTemplate");
}

This code gets the data item from the event arguments and sets the itemTemplate property depending on its type.

Each of these two templates will have to display the contents of the selected object. But, and that will be the tricky part, we want all those to be neatly grouped into separated lists.

One way to do that would be to have one DataView per list but where would the fun be in that? Here, we are going to enumerate only once through the data items to display and dispatch them dynamically to this or that placeholder depending on their nature.

Once more, the key to doing that will be handling the onItemRendering event:

function onNamespaceChildRendering(sender, args) {
    if (Type.isClass(args.get_dataItem())) {
        args.set_itemPlaceholder("classPlaceHolder");
    }
}

This code is simply changing the rendering place holder for the curent item from the default (the DataView’s element) to “classPlaceHolder” if the current data item is a class (instead of a namespace). The template itself looks like this:

<div id="namespaceTemplate" class="sys-template">
   <h1>{{ $dataItem.getName() }}</h1>
   <div class="column">
     <h2>Namespaces:</h2>
     <ul sys:id="namespacePlaceHolder"
         sys:attach="dataview"
         dataview:data="{{ getChildren($dataItem) }}"
         dataview:itemtemplate="namespaceChildTemplate"
         dataview:onitemrendering=
           "{{ onNamespaceChildRendering }}">
     </ul>
   </div>
   <div class="column">
   <h2>Classes:</h2>
     <ul><li sys:id="classPlaceHolder"></li></ul>
   </div>
</div>

<ul id="namespaceChildTemplate" class="sys-template">
  <li>{{ $dataItem.getName() }}</li>
</ul>

As you can see, there really is only one DataView in there, and thanks to the code above, it can dispatch its rendering to different places if necessary. The template for the items of that DataView happens to be the same in all cases (namespaceChildTemplate) but it could be easily different, as it was for the parent details view.

The template for displaying classes is essentially the same thing, but with four placeholders instead of two.

So here’s what it looks like in the end:

Key takeaways of this post are that it’s now super-easy to render hierarchical data structures with DataView, and that you can do some interesting grouping of data on the fly by handling the item rendering event.

You can play with the class browser live here:
http://boudin.vndv.com/AjaxPreview5Tree/default.htm

And you can download the code here:
http://weblogs.asp.net/blogs/bleroy/Samples/AjaxPreview5Tree.zip

Microsoft Ajax 4.0 Preview 5:
http://aspnet.codeplex.com/Release/ProjectReleases.aspx?ReleaseId=32770

Jim and Dave’s posts on Preview 5:
http://weblogs.asp.net/jimwang/archive/2009/09/11/asp-net-ajax-preview-5-and-updatepanel.aspx
http://weblogs.asp.net/infinitiesloop/archive/2009/09/10/microsoft-ajax-4-preview-5-the-dataview-control.aspx

querySelectorAll on old IE versions: something that doesn’t work

Bertrand Le Roy — Tue, 01 Sep 2009 01:03:13 GMT

In today’s post, I’m going to show an interesting technique to solve a problem and then I will tear it to pieces and explain why it is actually useless. I believe that negative results should also be published so that we can save other people from wasting time trying the same thing. So here goes…

A few days ago, a post on Ajaxian proposed a new version of a somewhat old technique to implement querySelectorAll on old versions of IE, using the browser’s native CSS engine. That sounds like a great idea at first, and the hack is quite clever. The idea is to dynamically add a CSS rule to the document that has the selector that you want to evaluate, and an expression that adds the matched elements to a global array.

When I read this, it reminded me of a similar approach that I had tried a few years ago. At the time, we were considering implementing our own selector engine (we had not yet decided to integrate jQuery to our Ajax offerings, which in the end made the whole effort moot) so we explored a number of approaches.

My idea was different in that it doesn’t use expressions at all. It does dynamically create a style rule, but instead of an expression, it just sets a non-existing “foo” style property to the equally arbitrary value of “bar”. It then scans the whole document (using the much decried and IE-specific but very fast document.all) and gets the computed style for each of the elements. We then look for the foo property on the resulting object and check whether it evaluates as “bar”. For each element that matches, we add to an array.

Here’s the code:

(function() {
    var style = document.styleSheets[0] ||
                document.createStyleSheet();
    window.select = function(selector) {
        style.addRule(selector, "foo:bar");
        var all = document.all, resultSet = [];
        for (var i = 0, l = all.length; i < l; i++) {
            if (all[i].currentStyle.foo === "bar") {
                resultSet[resultSet.length] = all[i];
            }
        }
        style.removeRule(0);
        return resultSet;
    }
})();

or, in minimized form:

(function(){var d=document;var a=d.styleSheets[0]||
d.createStyleSheet();window.select=function(e){
a.addRule(e,"f:b");var l=d.all,c=[];
for(var b=0,f=l.length;b<f;b++)if(l[b].currentStyle.f)
c[c.length]=l[b];a.removeRule(0);return c}})()

That’s 235 characters, which is not too bad (although not quite #twitcode small).

The first problem with that approach though is that because it’s using the native CSS selection engine in IE, it has the same limitations and quirks. That means no fancy CSS 3 (or even 2) selectors. It also means any IE bug will surface into the result set.

In other words, if you want more selectors than that, you will need to parse the selector string and branch off the code to another, more complete engine whenever something not supported is used. It also means that you need to know what is supported and what isn’t. That could be done through some dynamic discovery but doing so, we are getting into much complexity.

So limited as it is, how does it perform?

I ran the code in a SlickSpeed test (where I removed the selectors that it couldn’t handle) on IE6 and the good news is that despite the document.all scan and the current style computation, it’s more than three times faster than Paul Young’s implementation that got featured on Ajaxian.

But the bad news is that it’s also six times slower than jQuery:

I’m afraid a hack to use the native CSS selection engine of the browser is always going to be slower than an optimized pure JavaScript implementation (to be clear, I’m not talking about native implementations of querySelectorAll, but about hacks such as this which try to surface the feature on older IE versions that don’t have querySelectorAll). Somewhat counter-intuitive, but true.

End of story. Just use jQuery. :)

Why is ASP.NET encoding &’s in script URLs? A tale of looking at entirely the wrong place for a cause to a non-existing bug.

Bertrand Le Roy — Sat, 06 Jun 2009 00:27:15 GMT

Several people have reported seeing errors in their logs that seem to be due to requests such as this:

/ScriptResource.axd?d=
[lots of junk]&
t=ffffffffee24147c

The important part here is the HTML-encoded “&” sequence, which stands for “&” of course. If this exact URL is sent to the server, the server won’t know what to do with the escape sequence (URLs are not supposed to be HTML-encoded on the wire) so the parameters won’t get separated as expected, potentially resulting in a server error. This bug in the toolkit is an example of that: http://ajaxcontroltoolkit.codeplex.com/WorkItem/View.aspx?WorkItemId=13134

Of course, when people see 500 errors popping up in their server logs, they immediately assume the application is failing for some users. Or that some idiot at Microsoft did something incredibly stupid (that’s what we idiots at Microsoft do after all).

Case in point, a quick peek into the source code of the application’s pages immediately reveals that the script tags generated by ScriptManager do indeed generate these URLs:

So that’s where it came from! See? When I copy this URL into the browser’s URL bar, I do get the same error!

Then ensue various more or less rational reactions such as:

Correlate the user agent to the faulty requests (which correlates more or less with normal browser usage, i.e. lots of IE and then lots of Firefox, when there is a large enough sample).
Blame IE6 (lots of these requests come from IE6, hence it must be responsible: IE6 sucks).
“Fix” ScriptManager and remove the HTML encoding.

Well, by copying the URL from the source view into the URL bar, you did indeed reproduce the problem. A little too well. Better than you realize.

This is why. All of the errors in your server logs come from people doing precisely what you just did: copy the URL from the source view into the browser’s URL bar. They do it for various reasons: look at the source code for the scripts, understand what these weird URLs are, who knows?

But the point is, you will never be able to reproduce these errors during normal use of the application. There is nothing to fix here. The value that gets sent to the server never has the “&” sequence. You can verify it in IE6, you can verify it in any browser on any OS, it will just work.

When putting a URL in an HTML attribute, you should *always* HTML-encode it. It’s the standard, and for good reason (it enables the browser to tell between “&”, “&” and “&amp;”, it enables quotes to be embedded into attributes, etc.).

A consequence of that is that if you’re going to copy the value of one of these attributes from the source view, you should do what the browser does when parsing the HTML: decode the value first (in other words, replace “&” with “&”).

So yes, people do fail to do that and copy the URL without decoding. Well, they are not supposed to do that, nor do they need to do it. The error is normal, it results from a bad URL having been entered manually. Nobody would be surprised to get an error when querying foo.aspx?somenumber=thisisnotanumber for example. Same thing here. Pretty much.

Of course, this is not entirely trivial to figure out and I did pull my remaining hair a bit trying to understand what was going on, and you tend to trust people when they tell you there is a problem, especially when the description seems to make sense. There is some sort of confirmation bias going on there. But the more I looked at the different pieces of evidence, the more this explanation looked like the most likely, by far.

But of course, I may be missing something…

Survey: Ajax usage among .NET developers

Bertrand Le Roy — Fri, 22 May 2009 19:13:20 GMT

If you haven’t already and you are a .NET developer, please take a couple minutes and answer this survey, whether you use Ajax or not. There are a number of Ajax surveys around, but Simone’s is the only one that focuses on .NET developers.

The survey:
http://www.zoomerang.com/Survey/?p=WEB22973CYKW2H

Simone’s post:
http://codeclimber.net.nz/archive/2009/05/21/ajax-usage-among-.net-developers-in-2009.aspx

setInterval is (moderately) evil

Bertrand Le Roy — Fri, 15 May 2009 05:04:36 GMT

JavaScript has two ways of delaying execution of code: setInterval and setTimeout. Both take a function or a string as the first parameter, and a number of milliseconds as the second parameter. The only difference is that the code provided to setInterval will run every n milliseconds whereas the code in setTimeout will run only once.

Before I explain why I think setInterval is evil, allow me to rant on a related subject for a paragraph: you should never pass a string into any of those functions and instead always pass a function reference (unless you really, really know what you’re doing). If you pass a string, it will have to be evaluated on the fly, and eval is quite evil itself (unless you really, really know what you’re doing). It might seem tempting to generate code this way to inject dynamic parameters, but there are better ways of doing that, using currying. In Microsoft Ajax, for example, we provide the handy Function.createCallback and Function.createDelegate for exactly that usage.

Anyways now let’s get back to the issue at hand: setInterval is evil. To better compare, let’s assume you have a reason to use setInterval (why else would you be reading this?). Here’s the code you might write:

<!DOCTYPE html>
<html>
<head>
    <title>setInterval</title>
    <script type="text/javascript">
        var interval = setInterval(appendDateToBody, 5000);
 
        function appendDateToBody() {
            document.body.appendChild(
                document.createTextNode(new Date() + " "));
        }

        function stopInterval() {
            clearInterval(interval);
        }
    </script>
</head>
<body>
    <input type="button" value="Stop" onclick="stopInterval();" />
</body>
</html>

Both APIs have a corresponding clear API that enables the developer to cancel the interval or timeout. To identify what interval or timeout you’re cancelling, you pass into the API a token that is whatever value the call to setInterval or setTimeout returned. And that’s a first reason why setInterval is (mildly) evil: if you lose that token, there is no way you can ever stop that code from running every five seconds until you navigate away from the page. But that is a minor inconvenience, it just means you need to carefully manage your own stuff, right? Well, actually if code that you don’t know or don’t control created that interval, you’re probably in trouble even if you kept your own house real nice and tidy…

But the real reason why I dislike setInterval is that it is quite hard to debug, in particular if you have more than one running simultaneously. For example, if you have two intervals, one running every 100 milliseconds, the other every five seconds, and if you want to debug the second one, the first one will constantly get triggered and will get in the way.

So what, you might say, is the alternative? Well, here is code that is quasi-equivalent to the code above, but that uses the much less evil setTimeout:

var interval = setTimeout(appendDateToBody, 5000);

function appendDateToBody() {
    document.body.appendChild(
        document.createTextNode(new Date() + " "));
    interval = setTimeout(appendDateToBody, 5000);
}

function stopInterval() {
    clearTimeout(interval);
}

Here, instead of taking a subscription for life, we’re just renewing the lease as we go. The big advantage of this code is that to stop the interval, you don’t need the token. Actually, I rarely even bother to keep hold of it. All you have to do is skip the line of code that renews the timeout for the next iteration. So no housekeeping to do, and if during a debugging session you need to get one of the interval functions out of the way, just drag your debugger’s current execution pointer to the end of the function, hit F5 and you’ll never see that function run ever again, boom, it’s out of the way and you can focus on your own debugging.

So to summarize, replacing setInterval with setTimeout is easy, pain-free and removes the inconveniences of setInterval. So while the setInterval evil is about at the level of not replacing the cap of the toothpaste, the non-evil alternative is so easy that I can’t see a reason not to forget about setInterval for good.

New release of the Ajax Control Toolkit

Bertrand Le Roy — Thu, 14 May 2009 05:19:00 GMT

A new version of the AJAX Control Toolkit is now available for download from the CodePlex website. It contains three new controls:

HTMLEditor - allows you to easily create and edit HTML content. You can edit in WYSIWYG mode or in HTML source mode. The control exists as a server-side extender but can also be instantiated purely on the client-side with a single line of code. Many thanks to Obout for building this.

ComboBox - provides a DropDownList of items, combined with TextBox. Different modes determine the interplay between the text entry and the list of items. this control behaves very much like a Windows combo. Many thanks to Dan Ludwig for building this.

ColorPicker - can be attached to any ASP.NET TextBox control to provide client-side color-picking functionality from a popup. Many thanks to Alexander Turlov for building this.

The ASP.NET website has been updated with new videos and tutorials for these controls.

This new release also includes fixes for over 20 of the most voted bugs in existing AJAX Control Toolkit controls and now features minimized release versions of the script files.

The release can be downloaded as a server dll or as a set of files for use with pure client-side applications.

http://ajaxcontroltoolkit.codeplex.com/Release/ProjectReleases.aspx?ReleaseId=27326

Creating jQuery plug-ins from MicrosoftAjax components

Bertrand Le Roy — Tue, 05 May 2009 05:23:00 GMT

We had an interesting discussion recently on the ASP Insiders mailing list and ended up talking about what cool stuff we could build on top of jQuery. Many interesting things were mentioned and it was a very useful discussion but one suggestion in particular struck my curiosity as it was something I had investigated before and that could be improved on with very little code.

I had already written a little plugin to enable instantiation of Microsoft Ajax components on the results of a jQuery selector:

jQuery.fn.create = function(type, properties) {
    return this.each(function() {
        Sys.Component.create(type, properties, {}, {}, this);
    });
};

I have another version that is a little more elaborate and takes a bag of properties and events instead of just properties (get it from the attached sample) but you get the idea. This makes it fairly easy to instantiate components based on a selector:

$(":text.nomorethanfive")
    .create(Bleroy.Sample.CharCount, { maxLength: 5 });

But if this were a native jQuery plugin instead of a Microsoft Ajax component, as Rick Strahl suggested, chances are you’d do something like this instead:

$(":text.nomorethanfive").charCount({ maxLength: 5 });

We can actually get that exact result fairly easily by writing a plugin that is specific to this component, but we can’t expect every Microsoft Ajax component author to also write a jQuery plugin, can we? We can do better than that. Here is a second small piece of code that is still generic but is in the business of creating jQuery plugins:

Sys.Component.exposeTojQuery = function(type, pluginName) {
    return jQuery.fn[pluginName] = function(properties) {
        return this.each(function() {
            Sys.Component.create(type, properties, {}, {}, this);
        });
    }
}

Like above, the version in the sample is better than that in that it supports events in addition to properties but again you get the idea. Thanks to this function, we can create a jQuery plugin for any existing Microsoft Ajax component with a single line of code:

Sys.Component.exposeTojQuery(Bleroy.Sample.CharCount, "charCount");

After this call, we can write exactly the code we wrote before, but without having had to write a specific plugin. We can then use charCount like a native jQuery plugin:

$(":text.nomorethanfive").charCount({ maxLength: 5 });

This is really easy to use, and I quite like it. We could for example add the following line of code to the new MicrosoftAjaxTemplates.js:

if (jQuery)
    Sys.Component.exposeTojQuery(Sys.UI.DataView, "dataView");

This would enable us to instantiate DataView controls as simply as this:

<ul class="dv">
    <li>{{ $dataItem }}</li>
</ul>
<script type="text/javascript">
    $(".dv").dataView({ data: ["foo", "bar", "baz"] });
</script>

Get the code from here (you need to include jquery-1.3.2.js to the script folder):
http://weblogs.asp.net/blogs/bleroy/Samples/jQueryCreate.zip

A blog on Microsoft Ajax client templates and data

Bertrand Le Roy — Tue, 21 Apr 2009 21:45:01 GMT

Politian has a great blog series where he goes into the details of building a data-driven Ajax application using the new 4.0 client templates and data.

Check it out!
http://politian.wordpress.com/

Some MIX talks

Bertrand Le Roy — Mon, 23 Mar 2009 04:14:22 GMT

Stephen Walther just published links to the video, slides and sample code for his Ajax talk at MIX09:

http://stephenwalther.com/blog/archive/2009/03/22/mix-slides-code-and-session-recording.aspx

It’s pretty cool to see all the work we put into Ajax this past year or so presented at MIX. This is a really nice presentation, like Stephen’s always are.

Another presentation I had lots of fun watching (not just because the speaker is making an incredible impression of me but also because I’ve been spending a good part of my time lately contributing to the application he’s showing) is Rob Conery’s. Rob is showing an interesting way to develop ASP.NET applications, aimed at ease of use and customization rather than architectural purity. Check it out, let me know what you think…

http://videos.visitmix.com/MIX09/T62F

Microsoft Ajax 4.0 Preview 4 now available

Bertrand Le Roy — Wed, 18 Mar 2009 07:49:00 GMT

The Microsoft Ajax team made the fourth preview of the 4.0 version available on CodePlex. This is an important release because it enables the full client data story, complete with the ability to get changes back to the server automatically.

Here’s a quick recap of some of the available features:

Getting a client representation of data from an ADO.NET and REST data service.
Rendering data on the client using templates.
Declarative instantiation of client components.
Live bindings, enabling changes in the UI and in the data to be automatically propagated.
Command bubbling for codeless wiring of events in template-driven controls.
Data identity and association management for efficient and consistent client-server data exchanges.
Sending changes back to ADO.NET and REST data services.

In a nutshell, it is probably the easiest way to build a data-driven client application. Check this out:

<div id="peopleView" sys:attach="dataview" class="sys-template"
     dataview:dataprovider="{{ $create(Sys.Data.AdoNetDataContext,
                               {serviceUri: 'PeopleIKnow.svc'})}}"
     dataview:fetchoperation="PeopleIKnow"
     dataview:autofetch="true">
    <fieldset>
        <legend>
            <span>{binding FirstName}</span>
            <span>{binding LastName}</span>
        </legend>
        <img code:if="{{ Photo }}"
             sys:src="{{ 'Images/' + Photo }}"
             alt="{{ FirstName + ' ' + LastName }}" />
        <br />
        <input type="text" id="{{ $id('firstName') }}"
               class="editInPlace name"
               value="{binding FirstName}"
               sys:attach="inplace" inplace:cssclass="editing"/>
        <input type="text" id="{{ $id('lastName') }}"
               class="editInPlace name"
               value="{binding LastName}"
               sys:attach="inplace" inplace:cssclass="editing"/>
    </fieldset>
</div>
<br />
<input id="saveButton" type="button" value="Save" />

This creates a DataView that queries the PeopleIKnow.svc ADO.NET data service, and repeats the markup in the div over the data. The legend contains two spans that will respond to live changes to the data ({binding FirstName and {binding LastName}). The image will only be rendered if there is a photo to show (code:if). It builds the image path using a simple JavaScript expression: {{ ‘Images/’ + Photo }}.

The two input tags are augmented by a custom edit in place behavior (sys:attach=”inplace”) and are bound to the FirstName and LastName data columns so that any change to the value of the field will be propagated to everything that depends on the same data: the data itself of course but also the legend of the fieldset (see video below).

The save button is hooked to the following handler:

$addHandler($get("saveButton"), "click", function() {
    $find("peopleView").get_dataProvider().saveChanges();
}, true);

This handler is super-simple as it only has to call saveChanges on the data provider of the DataView. This is enough because any changes made in the input fields have been propagated to the client data model already, which tracked all changes and can build a simple JSON object to send back to the data service. Here is an example of the kind of JSON object that travels back to the server after I’ve changed Simon’s name through the UI:

{
  "__metadata":{
    "uri":"http://127.0.0.1:26402/Asp.Net_Ajax_Preview_4/
           PeopleIKnow.svc/PeopleIKnow(1)",
    "type":"PeopleIKnowModel.PeopleIKnow"
  },
  "ID":1,
  "FirstName":"Simon",
  "LastName":"Calvert",
  "Photo":"simoncal.jpg"
}

Here’s the application running:

<br/><a href="http://video.msn.com/video.aspx?vid=140e8d2a-8d01-49ab-b96f-77e219f93e40" target="_new" title="ASP.NET Ajax 4.0 Preview 4 ">Video: ASP.NET Ajax 4.0 Preview 4 </a>

The source code can be downloaded from here (contains code licensed under MS-PL):
http://weblogs.asp.net/blogs/bleroy/Samples/Asp.Net_Ajax_Preview_4.zip

But wait, there’s more in stock for the next preview… I’ll post more details about some of those features in the following weeks… Stay tuned…

http://aspnet.codeplex.com/Release/ProjectReleases.aspx?ReleaseId=24645

How to choose a client template engine

Bertrand Le Roy — Thu, 05 Feb 2009 08:03:00 GMT

Disclaimer: I worked on the Microsoft Ajax 4.0 template engine, so my criteria are of course heavily influenced by our own design.

Templates are a data rendering method that server-side developers have enjoyed since the old days of classic ASP and PHP. The idea was quite simple (add code blocks and dynamic expressions directly into HTML markup) but it revolutionized web development, which before that relied on the opposite method (spitting HTML from CGI code).

On the client-side, the browser provides two ways to generate HTML: innerHTML and the DOM API. Template rendering is of course possible, but only using a JavaScript library. To be honest, one should mention XSLT here, which is standard and widely supported but whose somewhat unusual syntax has had limited success convincing web developers.

There are literally dozens of template engines available today, using many different markup conventions and algorithms. Template engines are not equal, they have different levels of complexity, different feature sets, different security models. It can be quite hard to pick one, and it really depends on the requirements of your application and also on taste.

I’ll try to go over a few things that you might want to check on a template engine. You will want to cherry-pick what’s important to you and what’s not so that you can pick the tool that’s best adapted to your problem.

1. Expression delimiter

A template system is adding new semantics to an existing language. This is not completely harmless as you have to give a new meaning to sequences of characters that were understood before as plain literals. That means that an escaping mechanism must exist to express the literal contents that were given a new meaning. For example, if the expression delimiters are <%= and %>, how do you express the “<%=” and “%>” sequences of characters as literals?

<%= and %> are by far the most common and familiar delimiters (they have been used by ASP, PHP, JSP, ASP.NET and many others), but they have one flaw that couldn’t be seen back in 1996: XHTML compliance. Granted, you may not care at all about XHTML. If you don’t, just skip this. But if you do, any template engine that uses <%= %> simply can’t have template code that is XHTML-compliant. Now this may still not be a big deal if you don’t care that the template code is compliant, but only care about the generated markup.

But there is another reason why <%= %> is a bad choice: it’s conflicting with the server-side. A client-side engine must be able to coexist peacefully with whatever server-side technology you’re using. If your server technology of choice is using <%= %> like it very likely does, it will be conflicting with your client templates. The server-side engine will kick in when it sees these delimiters and will fail one way or another.

We chose {{ }} as the expression delimiter (and also {expr } for extensible markup expressions such as {binding }), which happens to be the same choice that Django made (and Dojo, as they implement Django on the client-side, and by the way I don’t know how they manage conflict with server-side Django; if you know, drop me a comment). It works fine with XHTML and it doesn’t conflict with ASP or PHP. If you want to express the “{{“ literal, we don’t provide an escape sequence per se, but you can still do it by writing {{ “{{“ }}.

On a final note, there are a few template engines that do not have expression delimiters but instead rely on microformats. While this absolutely preserves the HTML semantics, it’s often clumsier to use and quite limiting. It’s a matter of taste, but microformats also can look like markup within markup.

2. Expression language

In the simplest cases, you’ll want to inject a simple data field into the template, like {{ Price }}. But many times, you’ll want to go beyond those simple cases and embed a more complex expression into the markup. For example, you might want to display that price with two decimal places, like $42.00. In order to handle that case and more complex ones, it is necessary to have a full expression language.

In the same way, if the template engine allows for code blocks to introduce control structures such as conditional execution or loops, it needs a full programming language.

Some template engines, such as Django, introduce their own new language. Others, such as ours, just use what’s already available and familiar: JavaScript. In addition to being familiar, it eliminates the need to write a parser and interpreter, which reduces library code size and gives better performance.

3. Protection against injection attacks

If you don’t know what an injection attack is… wow. Just wow. Go read this, now. Seriously.
http://weblogs.asp.net/bleroy/archive/2004/08/18/please-please-please-learn-about-injection-attacks.aspx

The frightening thing about almost any single one of the client template engines out there is that they have no mechanism in place to protect against injection attacks, which puts the responsibility to encode and check contents in the hands of the application developer. That’s you.

Most of the engines out there are using a very simple algorithm to build HTML: array joining, and then injecting the result using innerHTML. This is very similar to building SQL by concatenating strings: in a nutshell, you shouldn’t do that. In the same way that SQL is better built using parameterized queries, HTML is more securely built using the DOM API which just eliminates the need for encoding.

Even when using encoding or the DOM API, there is a number of attributes that still present a fair amount of danger if user data gets injected in them. For example, if you bind the href attribute of a link to a piece of user data, no amount of encoding will protect the application against a user injecting “javascript:doSomeEvil();”.

To prevent that kind of attack, we white-list the protocols in all known URL attributes to relative URLs, http and https. It is possible for the application to extend this white list as needed (available in Microsoft Ajax 4.0 Preview 4 and later).

One thing to understand is that the dangerous contents here is the data, not the template itself, which is trusted as application code is.

4. Template location

Depending on the library, the template can be embedded in comments, in script tags or just be part of the DOM. It can also be included from a separate file.

Putting the template in comments or script tags easily hides its markup from initial rendering, but it makes it harder to design with existing tools and puts it out of the reach of markup validation tools.

Including from a separate file adds one more request to the server, which might be a problem or not: it might also improve performance by allowing partial caching. The best is to have a choice here, so I’d reject an engine where external files is the only possibility, knowing that all other engines allow external files with minimal effort by feeding a simple XHR’s result into the system.

Instead of using script tags or comments, we chose to embed the template as real HTML contents anywhere in the document and just hide it from initial rendering using CSS. This makes the code designable using any existing tool, and enables us to use the browser’s native HTML parser to understand the structure of the markup.

5. Hooking up events and instantiating components

In a modern Web application, you won’t just create plain HTML, you’ll want to hook up events and instantiate components. The template engine might let you do this inline, which is obtrusive but convenient, or it might require you to enrich the DOM after template instantiation through code, or it might give you a choice between the two.

One thing to look for is how much knowledge of the template markup’s shape must be injected into the code in order to enrich the DOM.

For a picture of the different possibilities using our engine, read this post:
http://weblogs.asp.net/bleroy/archive/2008/11/28/instantiating-components-on-template-markup.aspx

6. Live bindings

One big advantage of client rendering is that the data remains under raw data form until it reaches the template engine. That means that you have a representation of the data on the client. This in turn means there is an opportunity to monitor changes to the data and to bind UI directly to it, eliminating round-trips to the server along the way.

We call this ability live bindings and it makes for very responsive applications that are still easy to build.

7. Constraints on markup shape

One thing you should try with any template engine is to repeat a row in a table, using IE. This may sound trivial, but innerHTML doesn’t work on IE in a number of places, which puts a constraint on the markup that you need to write to render certain shapes of HTML. There is almost always a workaround but it can be more or less painful to implement. Try and compare, see what you find reasonable.

8. Ease of data field access

This one is quite simple. Some template engines force you to access the current data item’s field through some special syntax such as “$T.price”. In our engine and several others, you just write “price”.

9. Readability

This one is quite subjective, but when choosing a template engine, just look at a few samples. Does the code hurt your eyes? Can you understand it right away?

10. Performance

A template engine must be able to render a reasonable number of data items with a reasonably complex template under the perception threshold. What’s “reasonable” pretty much depends on your application design, but I’d say a hundred items in a typical grid layout should be hardly noticeable. So before you choose, do a mock-up of your design and data and try it. Increase the number of items and see where rendering starts to get noticeable. Usually rendering performance is not linear so this should give you a good idea of how far you can go with each engine. Better to determine that before you invest heavily in one engine.

11. XHTML compliance

As I said above, this is one you might not care about. Don’t leave yet, it actually goes both ways, as an engine, by enforcing XHTML compliance, might potentially get in the way of writing HTML the way you want.

The lowest level of compliance is that the rendered output is compliant. Being template engines, most if not all engines enable you to create compliant or horribly broken markup, depending on your own style. What it must absolutely not do is prevent you from generating compliant markup.

The second level of compliance is that the template code itself, before data is injected, is compliant. This is much less common. Even less common is that the compliance requirement does not impose too strong a constraint on the markup you have to write.

In other words, a good template engine lets you write XHTML but doesn’t force you to.

12. Nested templates

Rendering a template within a template might look like a whacky scenario at first if the engine understands control structures such as loops. In reality, if you include something like live bindings into the mix, you will want for example an inner template to be re-drawn when the outer data item changes. This will be much easier to achieve with nested templates.

So if this is a scenario that you care about, make sure that your engine handles that case gracefully.

In conclusion

There are many engines to choose from, and many criteria to check. I’m quite convinced that our own offering is pretty solid for all these criteria and offers a good compromise of features against simplicity and performance.

There is another engine that I quite like because it’s an impressively small bit of code that remains useful, and that is John Resig’s micro-template engine, which is only 20 lines of code. Like our own engine, it “compiles” the template into a reusable function that takes the data as a parameter. But unlike ours, it has no security mechanism and has issues with some markup, which may or may not be an issue for you. It’s a different kind of compromise that puts code size and simplicity before any other consideration.

I hope this helps in making a choice.

A good resource on client templates:
http://ajaxpatterns.org/Browser-Side_Templating

John Resig’s micro-templates:
http://ejohn.org/blog/javascript-micro-templating/

ASP.NET 4.0 Ajax Preview 3:
http://www.codeplex.com/aspnet/Wiki/View.aspx?title=AJAX

UPDATE: added performance and XHTML compliance to the list from Dave Reed’s feedback, and nested templates from Keith’s.