Over the past month I have been reading jQuery Enlightenment by Cody Lindley. Let me say now, that if you use jQuery or are thinking about using jQuery then you should most certainly buy this book. It’s a quick read (122 pages) that includes colorized code samples, easy to follow examples and solid explanations.

Author Cody Lindley is a member of the jQuery team and explains why he wrote the book.

jQuery Enlightenment was written to express, in short-order, the concepts essential to intermediate and advanced jQuery development. Its purpose is to instill in you, the reader, practices that jQuery developers take as common knowledge. Each chapter contains concepts essential to becoming a seasoned jQuery developer.

This book is intended for three types of readers. The first is someone who has read introductory books on jQuery and is looking for the next logical step. The second type of reader is a JavaScript developer, already versed in another library, now trying to quickly learn jQuery. The third reader is myself, the author. I crafted this book to be used as my own personal reference point for jQuery concepts. This is exactly the type of book I wish every JavaScript library had available.

I would argue that this book is perfectly suitable for beginners too. It’s simply a must have jQuery book. It’s the only one you need; it will take you from beginner to competent user.

I do ASP.NET / C# web development where I build web-based software for school districts. My preferred architecture is one in which I use NO server-controls. That means no GridViews, no Repeaters, no ListViews. If fact, nothing that uses runat server will be found on the page. The page will only consist of XHTML. So there is no need for a viewstate either. We end up using jQuery a lot in this architecture. We use jQuery / Ajax to call Web services that then query the database using LINQ to SQL and pass our data back to the client where we can then populate our XHTML controls. It works great and is extremely fast and efficient. The code couldn’t be cleaner. In addition, this methodology would allow you to easily change to a PHP or Java backend and you wouldn’t have to change a single thing on the frontend. I will give a full example on this methodology another time, but the point is – you need to learn jQuery.

For more information on the jQuery Enlightenment book, including a breakdown of each chapter go here. I would recommend buying the full color book from lulu.com as it’s well designed and very handy to have on your desk.

jQuery is not all that difficult to learn. The biggest thing you have to understand is all the different "selectors" that are available to you. Using selectors developers can query, in a CSS like way, for HTML elements, and then apply "commands" to them.

For example, the below JavaScript uses jQuery to find a <div> element within a page that has a CSS id of "rightSide", and shows it and "leftSide" and hides it.

As another example, the JavaScript below uses jQuery to find a specific <table> on the page with an id of "datagrid1", then retrieves every other <tr> row within the datagrid, and sets those <tr> elements to have a CSS class of "even" - which could be used to alternate the background color of each row:

This next example gets all links <a> in a specific <div> and attaches an onclick event to them:

Being able to traverse the DOM and locate HTML elements to attach events, behaviors, animations and CSS is priceless. But what about ASP.NET controls like the RadioButtonList, GridView, ListView, Repeater, and many others that we as developers like to bind to? How do we traverse them when they all get their ids auto-generated? That's what we will look at now! And with jQuery it's not that hard!

When you add an ASP.NET RadioButtonList control to a page, like below:

The browser renders the control to the code below:

As you can see, we don't have control over the generated items id tag. It would not be an easy task to guess what the auto-generated id tags are going to be. There's simply too many ways it can very depending on if you are using master-pages and or web-controls. The one thing that we do know is that somewhere in the id will be the id we gave to the control; in this case "rblCaseControl". Lucky for us this is all jQuery needs to go to town. Look at the code below:

This code uses jQuery to get all radio buttons that have "rblCaseControl" somewhere in their id tag. We could get the selected value of the radio button list using this code:

With this code we have now found the selected value from our ASP.NET RadioButtonList control using jQuery. Perhaps now we want to send that value to a web method in our codebind page using Ajax? Well we could use jQuery for that too! But, that's another article.

Further Reading:

• http://weblogs.asp.net/scottgu/archive/2008/09/28/jquery-and-microsoft.aspx
• http://weblogs.asp.net/mikebosch/archive/2008/02/15/asp-net-mvc-submitting-ajax-form-with-jquery.aspx
• http://www.chadmyers.com/Blog/archive/2007/12/13/using-jquery-with-asp.net-mvc.aspx

Code Breakdown

This gets the class .down-list and sets its width equal to the width of the .dropdown-menu's width minus two. As you may already know or were able to deduce the dollar sign ($) is used to select HTML elements in the page. The $ method accepts a CSS selector(s) as argument(s), so if you want to select a specific element by it's id or it's class as in the case here you can use the $("#myElementId") code which returns a reference to the DOM element. Learning all the jQuery selectors is very important in mastering jQuery, but is not the scope of this article.

This code attaches the hover event to all .dropdown-menu classes. Short and sweet. The hover event uses two functions: over and out. Whenever the mouse cursor is moved over a matched element, the first specified function is fired. Whenever the mouse moves off of the element, the second specified function fires.

The first function is called when someone mouses over a dropdown menu. It adds the class slide-down to the menu and then animates it by sliding down. The 100 in the slideDown method is the speed of the animation measured in milliseconds.

The second function is called when they mouse out. The part to notice here is the additional function in the slideUp method. This is a callback function; it fires when the animation is complete. So in this case when the user mouses off our dropdown menu it will animate up and then remove the class slide-down. And that will wrap up our dropdown menu.

As you can see, very little code to achieve this common web effect thanks to jQuery.

This is a very large photo I took of a mountain near Choquequirao, Peru. Figure 1 shows it set as a normal background image without playing with CSS's background-position or anything else and only a rather boring corner of it (not that the whole image is that exciting either) is visible:

Figure 1

Figure 2 shows the same thing, except that the image has been centred using background-position:center:

Figure 2

It's even more boring! Now, with CSS we can still improve this a bit, by using the img element instead of a background image. Yes, this is not as beautifully semantic, but for the purposes of this example will do:

By setting the width and height of #bg and the image to 100%, we can fill the viewport up with the image, but of course the aspect ratio of the image will not be maintained and the stretchiness can look horrible, particularly if the browser window is resized.

Time for some JavaScript, then. The first thing to do is to make sure the image has actually loaded before we try to resize it. I've decided on the following approach:

The key thing here is that we first set an onload event listener on bgimg (the image we're resizing) which will fire when the image has finished loading. However, it will only fire if the src attribute is set, so we do that in the following line (it doesn't matter that it's the same src, fortunately).

The last three lines fire resizeBg when the browser window is resized and cater for decent browsers and IE. Here is resizeBg:

The first two lines obtain the width and height of the viewport. There is a small caveat here: For document.documentElement.clientWidth to work (since IE does not support self.innerX), IE must not be in quirks mode, i.e. the page must have a valid doctype. Not much of a caveat, really, since your pages should have valid doctypes anyway.

Following that, we just employ some simple mathematics. The first if block will set any image to the same width as the viewport. It also works out the new height for the image so that the aspect ratio is preserved.

The next if-else block is important. If the first block's calculations means that the new image's height is smaller than the viewport, we need to make it a bit bigger. This means setting the width to bigger than the viewport, so to preserve the aspect ratio, we centre it by shifting it left by half the difference.

If the height of the new image is bigger, then we need to centre it vertically, which is what the else if bit does.

Now, as shown in Figure 3, we can get a nicely-fitting centred image as the background!

Figure 3

See the finished example page (which Figure 3 links to too) and the accompanying JavaScript file. The JavaScript file includes code to run the resizing function when the DOM has loaded, using Dean Edwards' script, so the init function will look a little different to the one on this page.

Before anyone says anything, yes, the script could be made truly nice and unobtrusive by creating the HTML elements for the background image with JavaScript as well, but that is not the focus of this post, so it can be left as an exercise for the reader!

Update (29/01/09): I've updated the code to make the script work in IE6. Please note there are also changes to the CSS (in the finished example HTML file).

Yesterday I decided to add a little bit of functionality to Gmail. I wanted to be able to isolate messages from a mailing list I subscribe to that nobody had replied to. This would require marking as read "conversations" or messages containing "Re:" at the start of the subject line. The obvious place to put links to do this is along with the other "selectors" above the thread list (Figure 1).

Figure 1

I call them "selectors" simply because Gmail has given each "link" (actually a span) a custom selector attribute. The original markup before adding the links after "Unstarred" looks like this (it isn't nicely indented in Gmail's code though):

So, it looks pretty simple to add a couple of commas and two more spans. And it is, but how to access the containing div is what the Gmail API makes easier. This is the complete script, and we'll start off with the main loading business and the function that handles the adding of these two new links, addlinks:

The first three lines load the API, which is simply a bunch of methods belonging to the gmonkey object (a global variable). Since Greasemonkey operates in its own nice and safe environment, accessing the page's own JavaScript is done via unsafeWindow, which is in fact the window object in the actual page's DOM.

To check that we are only applying the script when a list of messages is shown (e.g. inbox, search results), gmail.getActiveViewType() lets us limit ourselves to "tl" (thread list) mode. gmail.getActiveViewElement() gives us the main box that contains the links and form controls shown in Figure 1, as well as the list of messages (Figure 2 below). It is rather enormous markup-wise and getting to our target div would require tedious and fragile DOM-walking. It is thus sensible to use XPath, which Mozilla supports quite well. One of the nice things about writing Greasemonkey scripts is that you only have to worry about supporting one browser!

Oddly enough, XPath sometimes works with Gmail when used with the normal document.evaluate but other times it doesn't, and this is one of those cases. I don't know why it is so erratic. To ensure it works, we have to get a reference to the right document, located in the frame containing the markup we're interested in. If you view-source Gmail, you will see a bare-bones HTML document with lots of embedded JavaScript and also four iframes. The one with all the content in it has the id "canvas_frame". contentWindow is a reference to the window object in this iframe and gets us "inside" the iframe.

We need to get a list of the div elements containing the links (green boxes in Figure 2 below). Initially there are 2, because there is one above and another below the thread list (in red, Figure 2). If you search for something, Gmail creates a separate "thread list", where there are 2 more of these divs.

Figure 2

The XPath expression, using tl (the thread list, in red above) as the reference node, puts the nodes it finds into a special collection, the contents of which have to be looped through and accessed using snapshotItem(). Within the loop, we check to see if the current div's last child (the span containing the "selectors") has more than 11 child nodes (the original six spans within, plus the five text nodes containing comma and space). If so, we move on to the next div, because the current one already has our new links appended to it. The rest of the addLinks function is fairly standard creation of elements and appending them to the DOM, which I won't go into.

Our new selector links are set to listen for click events, which will call the selectItems function, not shown in the code block above. Here it is:

This was the tricky bit. First of all we use the this keyword to establish whether the "Conversations" or the "Replies" link was clicked. Use of the ternary operator (? allows us to choose an XPath expression to target the checkboxes in rows that are conversations/replies. The XPath expressions look a little horrific, so I'll try to explain them. The markup below, which is for a single message in the thread list, is both a conversation (between Steve and me) and a reply (since the subject line, in a span, starts with "Re:").

XPath expression:

//tr/td[child::div/text()[last()][starts-with(., " (")]]/preceding-sibling::td//input[@type="checkbox"]

1. //tr/td finds all td elements in tr elements
2. The opening square bracket is a predicate, which means "the td elements that satisfy the condition within these square brackets".
3. The condition is that:
   • child::div - The td must have a child that is a div;
   • /text()[last()][starts-with(., " (")] - This div must contain text nodes: text() refers to all text nodes, and we want those that satisfy two conditions (as there are two predicates): it must be the last one, and it must start with the string " (". The dot within starts-with() refers to the current node.

   So far this has matched the text node containing "(3)" in the HTML.

4. /preceding-sibling::td - This matches any preceding td to our original td
5. //input[@type="checkbox"] - Finally, we match any ancestor (using // rather than /) that is an input element of type "checkbox".

Hopefully you will be able to work out what the other XPath expression means by yourself! Armed with these, we can now get a collection of the checkboxes we need to check/uncheck and cycle through them, accessing each using snapshotItem.

Checking the checkboxes by setting the checked attribute to "checked" does not work, as Gmail appears to have attached event listeners to them in order to control the contents of the "More Actions" dropdown menu (see Figure 1). Since it is impossible for us to attach these event listeners ourselves (due to the obfuscation of Gmail's code), we can turn to the click method, which emulates a user actually clicking an input element (it doesn't work for other elements).

The problem with this is if there are any checkboxes further down the page than we can see, the page will drunkenly scroll down with each one being checked (for some reason click() is very slow). To counter this, I tried many things and finally settled on using CSS's position:fixed on the body element. After the checkboxes are "clicked", the window is scrolled (using scroll()) to the position it was at before.

Finally, two lines need to be added after the declaration of selectItems:

The first one is part of the Gmail API and simple allows the script to call addLinks whenever one switches from viewing the thread list (e.g. inbox) to "compose", "search", etc. The second line simply runs addLinks when the gmonkey object is first loaded.

The drawbacks of this script (which you can download and install) are that it is slow (due to click()) and that because of the use of position:fixed, an area of whiteness can appear at the top of the page if it has been scrolled. Unfortunately, given the circumstances, there is not much that can be done about this, unless you can suggest something!

I hope this was a useful case study into writing a Greasemonkey script and the use of XPath for very specific targeting of DOM elements. The amount of time it took me to write this versus its usefulness is dubious but, like with all Greasemonkey scripts, they can pose an interesting challenge and at the end of the day can make websites you visit regularly a little bit easier to use.