Learning jQuery » DOM Modification http://www.learningjquery.com Tips, techniques, and tutorials for the jQuery JavaScript library Sat, 06 Mar 2010 18:10:17 +0000 http://wordpress.org/?v=2.9.1 en hourly 1 Simple Tooltip for Huge Number of Elements http://www.learningjquery.com/2009/12/simple-tooltip-for-huge-number-of-elements http://www.learningjquery.com/2009/12/simple-tooltip-for-huge-number-of-elements#comments Tue, 01 Dec 2009 17:57:29 +0000 Karl Swedberg http://www.learningjquery.com/?p=191 There are many, many jQuery tooltip plugins out there, and some of them are very good. But when someone on the jQuery Google Group asked (a year ago) which plugin could handle displaying tooltips for 2,000 links on a page, I wasn't able to find one. So, I decided to throw together a quick little plugin myself and was surprised by how easy it was.

Event Delegation, Again

The key to having JavaScript handle hundreds, or even thousands, of elements on a page is to use event delegation. As Louis-Rémi Babé described in Working with Events, Part 3: More Event Delegation with jQuery, jQuery's .live() method makes event delegation dead easy. A simple tooltip script using .live() might look something like this:

PLAIN TEXT
JavaScript:
  1. $('<div id="livetip"></div>').hide().appendTo('body');
  2. var tipTitle = '';
  3.  
  4. $('a').live('mouseover', function(event) {
  5.   var $link = $(this);
  6.  
  7.   tipTitle = this.title;
  8.   this.title = '';
  9.   $('#livetip')
  10.   .css({
  11.     top: event.pageY + 12,
  12.     left: event.pageX + 12
  13.   })
  14.   .html('<div>' + tipTitle + '</div><div>' + this.href + '</div>')
  15.   .show();
  16. }).live('mouseout', function(event) {
  17.   this.title = tipTitle;
  18.   $('#livetip').hide();
  19. });

This script does the following:

  • Creates a single tooltip element that will be shown and hidden as the user mouses over links (line 1)
  • Hides the tooltip and appends it to the body (line 1)
  • Changes the tooltip's contents according to the moused-over link's title and href attributes (lines 7 and 14)
  • Places the tooltip on the page 12px below and to the right of the cursor position at the time that it entered the link (lines 9–13)
  • Shows the tooltip (line 15)
  • Sets the link's title attribute to an empty string when the user mouses over the link; this prevents the browser's default tooltip from appearing (line 8)
  • Sets the link's title back to what it was originally and hides the tooltip when the user mouses out of the link (lines 16–19)

A Little Style

At minimum, the tooltip needs to have the position: absolute style declaration for it to be positioned correctly on the page, but I threw in a little extra CSS to make it look more appealing:

PLAIN TEXT
CSS:
  1. #livetip {
  2.   position: absolute;
  3.   background-color: #cfc;
  4.   border: 2px solid #c9c;
  5.   border-radius: 4px;
  6.   -webkit-border-radius: 4px;
  7.   -moz-border-radius: 4px;
  8. }

Typically I like to include live demos directly in the blog entry, but since this one involves 2,000 links, I've set up separate demo pages. Check out the tooltip demo using .live(), or download the zip.

A Little Less Simple, A Little More Speedy

Using .live() in this way avoids binding event handlers directly to the thousands of links on the page. However, it doesn't prevent jQuery from searching the entire document for all of those links. After all, I'm still using the $('a') jQuery function. Also, at least for now, .live() binds events to document, forcing event bubbling all the way up the DOM each time. If there is a noticeable performance lag when the script is initially executed, it may help to use custom event delegation. For example, here I bind the events to a containing table element:

PLAIN TEXT
JavaScript:
  1. $('<div id="livetip"></div>').hide().appendTo('body');
  2. var tipTitle = '';
  3.  
  4. $('#mytable').bind('mouseover', function(event) {
  5.   var $link = $(event.target).closest('a');
  6.   if ($link.length) {
  7.     var link = $link[0];
  8.  
  9.     tipTitle = link.title;
  10.     link.title = '';
  11.     $('#livetip')
  12.     .css({
  13.       top: event.pageY + 12,
  14.       left: event.pageX + 12
  15.     })
  16.     .html('<div>' + tipTitle + '</div><div>' + link.href + '</div>')
  17.     .show();
  18.   }
  19. }).bind('mouseout', function(event) {
  20.   var $link = $(event.target).closest('a');
  21.   if ($link.length) {
  22.     $link.attr('title', tipTitle);
  23.     $('#livetip').hide();
  24.   }
  25. });

With this approach, I needed to first make sure I was dealing with a link before I tried to do anything with it. Line 5 uses the .closest() method to select the <a> that is either the event.target or one of its ancestors. Line 6 checks the length property to see if any elements are included in the variable declared in line 5.

Note the use of .bind() instead of .live() and event.target instead of this. I could have used the .mouseover() and .mouseout() shortcut methods, but since I used .live() in the first example, it was easier to simply replace "live" with "bind." Also, you may be wondering why I used mouseover / mouseout when I could have used mouseenter / mouseleave or even the .hover() method (which uses mouseenter and mouseleave internally). The reason is that mouseenter and mouseleave prevent the event bubbling that this script relies on for its event delegation. Those two events would be triggered only when the mouse enters or leaves the full table, while mouseover and mouseout are triggered whenever the mouse enters or leaves any of the table's descendant elements, as well.

View the demo using custom event delegation, or download the zip.

One more Enhancement

Some people like having the tooltip move along with the cursor, as long as the mouse is over the element. Sometimes it's nice to be able move the tooltip a little if it initially overlaps something important. Adding the basic functionality is pretty straightforward. Just bind the mousemove event to the same table element:

PLAIN TEXT
JavaScript:
  1. $('<div id="livetip"></div>').hide().appendTo('body');
  2. var tipTitle = '';
  3.  
  4. $('#mytable').bind('mouseover', function(event) {
  5.   var $link = $(event.target).closest('a');
  6.   if ($link.length) {
  7.     var link = $link[0];
  8.  
  9.     tipTitle = link.title;
  10.     link.title = '';
  11.     $('#livetip')
  12.     .css({
  13.       top: event.pageY + 12,
  14.       left: event.pageX + 12
  15.     })
  16.     .html('<div>' + tipTitle + '</div><div>' + link.href + '</div>')
  17.     .show();
  18.   }
  19. }).bind('mouseout', function(event) {
  20.   var $link = $(event.target).closest('a');
  21.   if ($link.length) {
  22.     $link.attr('title', tipTitle);
  23.     $('#livetip').hide();
  24.   }
  25. }).bind('mousemove', function(event) {
  26.   if ($(event.target).closest('a').length) {
  27.     $('#livetip').css({
  28.       top: event.pageY + 12,
  29.       left: event.pageX + 12
  30.     });
  31.   }
  32. });

With the addition of lines 25 through 32, as the mouse moves over the links, the tooltip's top and left style properties are continually updated based on the mouse's position.

Try the demo and watch the tooltip move along with the mouse position, or download the zip.

The Plugin

The plugin doesn't offer much more than the scripts in this post, but feel free to try it out. One difference is that it doesn't rely on the .closest() method, so it can be used with jQuery 1.2.6 if you're stuck with that version for some reason. The syntax is a little funky:

PLAIN TEXT
JavaScript:
  1. $(document).ready(function() {
  2.   $(containerElement).eztip(invokingElement, [optionsMap]);
  3. });

The containerElement selector provides context so you can specify where exactly the event handlers are bound (unlike .live(), which binds to the document). The first argument of .eztip() is required. It should be a selector that matches the elements for which you wish to show a tooltip. The second argument is the typical options object, allowing for a handful of objects that you might expect to find in a stripped down tooltip plugin.

Let's Make Better Mistakes Tomorrow

The tooltip scripts in this post work fine, but they repeat code where they really shouldn't. Stay tuned tomorrow for a brief tutorial on one way to avoid such code repetition.

]]> http://www.learningjquery.com/2009/12/simple-tooltip-for-huge-number-of-elements/feed 34 43,439 reasons to use append() correctly http://www.learningjquery.com/2009/03/43439-reasons-to-use-append-correctly http://www.learningjquery.com/2009/03/43439-reasons-to-use-append-correctly#comments Mon, 02 Mar 2009 23:12:48 +0000 Josh Powell http://www.learningjquery.com/?p=542 The .append() method is perhaps the most misused of all jQuery methods. While an extremely useful and easy method to work with, it dramatically affects the performance of your page. When misused, the .append() method can cripple your JavaScript code's performance. When used well, it'll keep your script humming along.

[inline] [/inline]

Here is a typical example of append misuse:

PLAIN TEXT
JavaScript:
  1. var arr = reallyLongArray;
  2. $.each(arr, function(count, item) {
  3.     var newTd = $('<td></td>').html(item).attr('name','pieTD');
  4.     var newTr = $('<tr></tr>');
  5.     newTr.append(newTd);
  6.     $('table').append(newTr);
  7. });

Ran Once: Profile (308.697ms, 17861 calls, Firefox 3.06)
Ran in a for loop 100 times: Profile (51782.295ms, 1805100 calls)

If you're coming from Prototype to jQuery, chances are this looks quite natural to you. It's the way that Prototype does node creation/insertion, but with a little bit of jQuery chaining thrown in. Let's see how we can improve this.

PLAIN TEXT
JavaScript:
  1. var arr = reallyLongArray;
  2. $.each(arr, function(count, item) {
  3.     var newTr = '<tr><td name="pieTD">' + item + '</td></tr>';
  4.     $('table').append(newTr);
  5. });

Ran Once: Profile (107.458ms, 3991 calls, Firefox 3.06)
Loop of 100: Profile (21641.336ms, 399100 calls)

Whoa! Nearly a 3x difference, and much simpler to look at. jQuery can take more then one node at a time and create them all at once. You also don't need to wrap it in $() before appending it. jQuery knows what to do. But wait, there's more!

PLAIN TEXT
JavaScript:
  1. var arr = reallyLongArray;
  2. var textToInsert = '';
  3. $.each(arr, function(count, item) {
  4.     textToInsert  += '<tr><td name="pieTD">' + item + '</td></tr>';
  5. });
  6. $('table').append(textToInsert);

Ran Once: Profile (30.792ms, 778 calls, Firefox 3.06)
Loop of 100: Profile (8505.37ms, 77800 calls)

Taking full advantage of the ability of jQuery to insert a chunk of html in a string means only having to call insert once. It's much quicker, with an approximately 9-10x speed increase from the initial algorithm! This will be fast enough for 95% of cases, but for strings with lots of string concatenation… Wait, there's more!

PLAIN TEXT
JavaScript:
  1. var arr = reallyLongArray;
  2. var textToInsert = [];
  3. var i = 0;
  4. $.each(arr, function(count, item) {
  5.     textToInsert[i++]  = '<tr><td name="pieTD">';
  6.     textToInsert[i++] = item;
  7.     textToInsert[i++] = '</td></tr>';
  8. });
  9. $('table').append(textToInsert.join(''));

Credit for this one goes to Michael Geary
Ran Once: Profile (29.724ms, 778 calls, Firefox 3.06)
Loop of 100: Profile (8298.699ms, 77800 calls)

This version is a bit harder to understand, as the html is not in an easy to read format, and the results vary by browser* (see below for further analysis), but in most current and next generation browsers, adding to an array and joining it into a string at the end is quicker then doing string concatenations. So, if you are looping through a large number of string concatenation and need some more speed, you should consider this method. So, now we're done, right? This is as blazingly fast as we can get it? Not quite.

PLAIN TEXT
JavaScript:
  1. var arr = reallyLongArray;
  2. var textToInsert = [];
  3. var i = 0;
  4. var length = arr.length;
  5. for (var a = 0; a <length; a += 1) {
  6.     textToInsert[i++]  = '<tr><td name="pieTD">';
  7.     textToInsert[i++] = arr[a];
  8.     textToInsert[i++] = '</td> </tr>' ;
  9.  
  10. }
  11. $('table').append(textToInsert.join(''));

Ran Once: Profile (29.72ms, 587 calls, Firefox 3.06)
Loop of 100: Profile (8274.359ms, 58700 calls)

As handy as .each() is for small loops, calling a function that executes a callback inside of a loop will always be slower than just creating the loop in pure JavaScript. The difference here isn't so noticeable because the array I used only has a length of 190, but for really large loops it makes a measurable difference. In addition, while the difference is very slight (.000062 vs .000037 ms over 1,000,000 empty loops), it is quicker to save the array length in a variable and use it instead of looking up an object property every loop (thanks Karl Swedberg!).

For most of your uses, the method of creating one really long string and appending it at the end will be the best choice, as it makes the best use of the trade offs of code legibility, ease of programming, and speed.

Please tell me your methods for speeding up array loops or appending using jQuery in the comments below.

For completeness, I used jQuery 1.3.2, Firebug 1.3.3 and Fireunit 1.0a1 on Firefox 3.06 on a Mac to do the profiling. And the reallyLongArray I used was:

var arr = [1, 2, 3, 4, 5, 'adsf', 'as', 6, 2, 3, 6, 'ffadscdasc', 'cada', 
'2wd', 3, 7, 3, 2, 'sdf', 1, 2, 3, 4, 5, 'adsf', 'as', 6, 2, 3, 6, 'ffadscdasc', 
'cada', '2wd', 3, 7, 3, 2, 'sdf', 1, 2, 3, 4, 5, 'adsf', 'as', 6, 2, 3, 6, 
'ffadscdasc', 'cada', '2wd', 3, 7, 3, 2, 'sdf', 1, 2, 3, 4, 5, 'adsf', 'as', 
6, 2, 3, 6, 'ffadscdasc', 'cada', '2wd', 3, 7, 3, 2, 'sdf', 1, 2, 3, 4, 5, 
'adsf', 'as', 6, 2, 3, 6, 'ffadscdasc', 'cada', '2wd', 3, 7, 3, 2, 'sdf', 1, 
2, 3, 4, 5, 'adsf', 'as', 6, 2, 3, 6, 'ffadscdasc', 'cada', '2wd', 3, 7, 3, 
2, 'sdf', 1, 2, 3, 4, 5, 'adsf', 'as', 6, 2, 3, 6, 'ffadscdasc', 'cada', '2wd', 
3, 7, 3, 2, 'sdf', 1, 2, 3, 4, 5, 'adsf', 'as', 6, 2, 3, 6, 'ffadscdasc', 
'cada', '2wd', 3, 7, 3, 2, 'sdf', 1, 2, 3, 4, 5, 'adsf', 'as', 6, 2, 3, 6, 
'ffadscdasc', 'cada', '2wd', 3, 7, 3, 2, 'sdf', 1, 2, 3, 4, 5, 'adsf', 'as', 
6, 2, 3, 6, 'ffadscdasc', 'cada', '2wd', 3, 7, 3, 2, 'sdf'];

Further analysis of += vs array.join, broken down by browser

---------------
Current gen Browsers
FF3 		array.join is ~2x faster
Safari 3 	array.join ~1.5x faster
Opera 9		+= ~3x faster
ie6		array.join ~6x faster
ie7		array.join ~4x faster
Next gen browsers
FF3.1		+= array.join equal in speed
Chrome		+=  ~1.25x faster
IE8		array.join ~1.6x faster
Webkit		array.join ~2x faster

Raw results

(2709 characters) 9 character string, added 300 times. Looped 100,000 times and averaged. +=
FF3.06 		.2046  -  .25835 .1849  .17045
Opera9 		.1256  -  .12795 .12678 .12197
Safari3 	.1368  -  .14875 .13128 .13032
IE6 		3.359 - took forever, crashed/froze browser sometimes
IE7 		1.68985 - took forever

FF3.1		.0735  -  .0813 .0710 .0683
Chrome 		.0256  -  .025 .021 .031
Webkit 		.0655  -  .06602 .06527 .06533
IE8		.2921  -  .3104 .2905 .2755
array.join - called 300 times, looped 100,000 times and averaged.
FF3.06 		.1056  -  .10701 .10439 .10541
Opera9 		.3355  -  .33091 .31484 .36066
Safari3 	.0813  -  .08128 .08089 .08172
IE6  		.5086  -  .50609 .50829 .51156
IE7 		.4101  -  .42265 .38875 .41891

FF3.1		.0743  -  .0766 .0721 .0741
Chrome 		.0315  -  .03 .048 .027 .021
Webkit 		.0300  -  .02962 .03123 .02937
IE8		.1832  -  .1841.1872 .1872 .1741
(35109 character string) 351 character string added to a nine character string 100 times, looped 1000 times and averaged += 
FF3.06 		1.81	-   1.897 2.015 1.518
Opera9 		.6306	-   .631 .634 .627
Safari3 	.9156	-   .931 .884 .932
IE6 		65.657	-   58.078 56.641 89.313 58.594  // I can see where += was a huge problem then.
IE7 		.9316	-   .937 .934 .924

FF3.1		.9141	-   .47 .663 1.123 .705 1.165 1.361 .698 1.128
Chrome 		.031	-   .039 .024 .02 .041
Webkit 		.996	-   .991 1.014 .983
IE8		.09	-   .094 .094 .078 .094
array.join the above
FF3.06		.9143	-  .923  .83 .99
Opera9		1.773	-  1.832 1.747 1.741
Safari3		.2106	-  .249 .19 .193
IE6		.8368	-  2 .375 .469 2.078 .343 .36 .735 .625 .547
IE7		.4428	-  .531 .516 .391 .375 .438 .406 .609


FF3.1		1.070	-  1.221 .678 1.366 1.508 .665 1.423 .631
Chrome		.0318	-  .02 .022 .059 .026
Webkit		.1773	-  .175 .176 .181
IE8		.4820	-  .14 1.141 .156 .609 .625 .328 .375
]]> http://www.learningjquery.com/2009/03/43439-reasons-to-use-append-correctly/feed 58 Quick Tip: Dynamically add an icon for external links http://www.learningjquery.com/2008/08/quick-tip-dynamically-add-an-icon-for-external-links http://www.learningjquery.com/2008/08/quick-tip-dynamically-add-an-icon-for-external-links#comments Wed, 20 Aug 2008 03:42:36 +0000 Karl Swedberg http://www.learningjquery.com/2008/08/quick-tip-dynamically-add-an-icon-for-external-links A common feature I've seen on “web 2.0” sites and wikis is the "external link" icon: external link. While I'm not crazy about the idea of sticking these little images all over the HTML, they're a great candidate for using progressive enhancement. In our case, we can use jQuery to add the images pretty easily.

Test the hostname

To identify the external links, we test for the location.hostname against the link's hostname, which will be represented by this.hostname once we have the selector in place, and make sure the two don't match. We should also test for the mere existence of this.hostname to avoid problems or false positives with "mailto" links. our tests will look like this: this.hostname && location.hostname !== this.hostname.

Use the filter function

Now let's wrap that test in a filter function. For our example, we'll test all links inside an "extlinks" element that match the above test. Here is what it looks like:

PLAIN TEXT
JavaScript:
  1. $(document).ready(function() {
  2.   $('#extlinks a').filter(function() {
  3.     return this.hostname && this.hostname !== location.hostname;
  4.   }).after(' <img src="/images/external.png" alt="external link"/>');
  5. });

A $(document).ready() is wrapped around the script so that it will execute when the DOM has loaded. Line 4 shows the insertion of the image after each of the external links.

Demo

Here is a little demo using the above code. Of the three links, only the second points to a different site. We should see the external-link icon next to it.

So, that's it. Short and sweet.

]]> http://www.learningjquery.com/2008/08/quick-tip-dynamically-add-an-icon-for-external-links/feed 67 Three Quick Ways to Avoid Widows http://www.learningjquery.com/2008/07/three-quick-ways-to-avoid-widows http://www.learningjquery.com/2008/07/three-quick-ways-to-avoid-widows#comments Tue, 08 Jul 2008 17:44:01 +0000 Karl Swedberg http://www.learningjquery.com/2008/07/three-quick-ways-to-avoid-widows A few months ago I threw together a quick redesign of the Learning jQuery site. It's nothing fancy, mind you, but I was itching to retire the thin veil covering the tired old WordPress Kubrick theme, so something had to be done.

Almost immediately upon changing the font-family and font-size of the blog post titles, I noticed a few unsightly widows (just to clarify, we're talking about typographical widows. My mother already suspects me of avoiding her; I don't want to add to her anxiety. ;) ).

Here is an example of one such widow:

widow

See how the last word, "plugin," appears on its own line? According to a couple designerly friends of mine, that's a no-no. So, I considered for half a minute how to get that title to look more like this:

no widow

The lowly yet lovely non-breaking space (&nbsp;) would do the trick, but how to replace it for the regular, breaking space? I certainly wasn't about to manually edit all of the entries' titles. Not only would it take too long, but it would also pollute the markup with something that really shouldn't be there. No, what I needed was a little JavaScript.

Selecting the Titles

On this site, entry titles are wrapped in <h2><a href="foo"></a></h2>, which can be selected in jQuery with $('h2 a'). Easy. Now, because I want to manipulate the text of each title independently, I'll need to use the .each() method, which is basically a chainable for loop. Inside the .each() is where I substitute the last breaking space with the non-breaking variety. Here are three ways I came up with to achieve this.

Array

The first approach was to convert the title string into an array of words and then stitch the array items back together, dealing with the last one specially.

PLAIN TEXT
JavaScript:
  1. $(document).ready(function() {
  2.   var h2Text = '';
  3.   $('h2 a').each(function() {
  4.     var h2Array = $(this).text().split(' '),
  5.       h2Last = h2Array.pop();
  6.     h2Text = h2Array.join(' ') + ' ' + h2Last;
  7.     $(this).html(h2Text);
  8.   });  
  9. });

A couple things to note about line 5 above: (a) the variable is actually being declared (with a "var") because it's separated from the previous variable declaration by a comma rather than a statement-ending semicolon. (b) The JavaScript .pop() array method "pops" the last item off the array and returns it; so it's no longer part of h2Array, but its value is stored in the h2Last variable. This is especially handy for us, because we don't want the last word to appear twice.

Line 6 joins the remaining array items with a space between them and then appends the non-breaking space and the popped last item. Line 7 dumps that concatenated string back into the title, inside <h2><a></a></h2>.

String

The next approach involved working solely with strings, using the slice and lastIndexOf methods to split the the string into two pieces — one leading up to the last space, and one immediately following the last space.

PLAIN TEXT
JavaScript:
  1. $(document).ready(function() {
  2.   var h2all, h2a, h2b;
  3.   $('h2 a').each(function() {
  4.     h2all = $(this).text();
  5.     h2a = h2all.slice(0, h2all.lastIndexOf(' '));
  6.     h2b = ' ' + h2all.slice(h2all.lastIndexOf(' ')+1);
  7.     $(this).html(h2a + h2b);
  8.   });
  9. });

As line 7 demonstrates, the two sliced strings are stitched back together to keep the last two words on the same line.

Regular Expression

The final technique is the one I ended up sticking with, partly because it's the tersest and partly because I have a fondness for regular expressions:

PLAIN TEXT
JavaScript:
  1. $(document).ready(function() {
  2.   var h2Text = '';
  3.   $('h2 a').each(function() {
  4.     h2Text  = $(this).text().replace(/ (\w+)$/,' $1');
  5.     $(this).html(h2Text);
  6.   });
  7. });

The distinguishing feature here is line 4, which uses the replace regular-expression method. This method takes two arguments, a pattern to match against and a replacement value. For the pattern, which appears between the two slashes, we first match a space and then match one or more "word characters" (letters, numerals, or underscores). The parentheses capture all but that initials space, and the "$" at the end ensures that the match appears at the end of the string. The replacement argument starts with the non-breaking space and follows with $1, which refers to the first (and in our case, only) parenthetical "capture group." (Please forgive me if I've provided too much detail about the regular expression. I'm never quite sure how much of this stuff is worth mentioning, but since this entry is targeting beginners, I suppose it's better to err on the side of too much.)

Update

A few people pointed out in the comments that my regular expression could be improved, and I agree. In particular, as noted by Art Lawry, the \w can be changed to \S (that's an uppercase S) to match any non-whitespace character. That way it'll match characters such as ö and ç as well.

By the way, all three of these code examples can be reduced in length quite a bit. For example, the regular expression example can be pared down from 7 to 5 lines if we don't bother with the h2Text variable and instead do something like this:

$(this).html($(this).text().replace(/ (\w+)$/,' $1'));

However, the code is usually easier to read and maintain (for me, at least) if the value is first stored in a variable.

Any suggestions for improvement here? Any other approaches that you would recommend instead? Leave a comment.

]]> http://www.learningjquery.com/2008/07/three-quick-ways-to-avoid-widows/feed 23 Using Low Pro for jQuery http://www.learningjquery.com/2008/05/using-low-pro-for-jquery http://www.learningjquery.com/2008/05/using-low-pro-for-jquery#comments Mon, 12 May 2008 12:39:50 +0000 Tane Piper http://www.learningjquery.com/2008/05/using-low-pro-for-jquery Recently I have been getting a real buzz out of developing with jQuery. I've been using the library since 2006, releasing sporadic bits of code. In April of this year, I released the third revision of my most complex plugin, jMaps, and updated several other plugins, which are available in my mercurial repository.

This was also the same month I discovered a new plugin which has dramatically changed how I develop applications with jQuery. The plugin in question is Dan Webb's Low Pro for jQuery, a port of the plugin of the same name for Prototype.

What is Low Pro?

So what is Low Pro? It's a plugin that provides a way of making more object-oriented JavaScript through event delegation. jQuery's plugin architecture provides a really simple way of extending the core functionality, but there is no easy way of making macros of code that do several types of events on one element. Until now!

Probably the simplest way to explain how Low Pro works is to build a quick demonstration. Sometimes I find that too many tutorials out there expect prior knowledge, so with that in mind, I will try to make the tutorial as simple as possible. However, this example does use another couple of plugins that are outside the scope of this tutorial:

  • Live Query - Low Pro uses this plugin to make binding to dynamic elements in the DOM easier.
  • jQuery Validation - We'll use this plugin to show how we can bind other plugin functions to events.

Both these plugins already have excellent documentation, so if you wish to extend this example, please check them out.

Example 1: Creating a re-usable registration form

For this example we'll build a simple user registration form. This is something that is common enough on the web, but a nice advantage of this example is that it can be used over and over again with little or no modification. Hopefully once you have learned this pattern, you will be able to see lots of other applications that can be reused over and over again in the same fashion.

Our first step is to create our basic form:

PLAIN TEXT
HTML:
  1. <!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01//EN"
  2.  "http://www.w3.org/TR/html4/strict.dtd">
  3. <html>
  4.   <head>
  5.     <meta http-equiv="Content-Type" content="text/html; charset=iso-8859-1" />
  6.     <title>Lowpro Example</title>
  7.     <script type="text/javascript" src="js/jquery.js" />
  8.     <script type="text/javascript" src="js/jquery.livequery.js" />
  9.     <script type="text/javascript" src="js/lowpro.jquery.js" />
  10.     <script type="text/javascript" src="js/jquery.validate.js" />
  11.     <script type="text/javascript" src="js/reg-form.js" />
  12.   </head>
  13.   <body>
  14.     <div id="form-container">
  15.       <form method="post" action="." id="lowpro-form">
  16.         <fieldset>
  17.           <legend>User Details</legend>
  18.           <ul>
  19.             <li>
  20.               <label for="username">Username</label>
  21.               <input type="text" id="username" name="username" />
  22.             </li>
  23.             <li>
  24.               <label for="email">Email</label>
  25.               <input type="text" id="email" name="email" />
  26.             </li>
  27.             <li>
  28.               <label for="password1">Password</label>
  29.               <input type="password" id="password1" name="password1" />
  30.             </li>
  31.             <li>
  32.               <label for="username">Password (Again)</label>
  33.               <input type="password" id="password2" name="password2" />
  34.             </li>
  35.           </ul>
  36.           <input type="submit" class="register" value="Register" />
  37.         </fieldset>
  38.       </form>
  39.     </div>
  40.   </body>
  41. </html>

Now, we create our JavaScript file called reg-form.js. In here, we will create our class that we'll attach to the form. Inside this class, we'll create some functions that trigger on specific events. Every class created with Low Pro takes the form of $.klass({...});. Inside the curly braces, we use JavaScript prototype nature to create a pseudo-class. We will call our example RegisterForm.

PLAIN TEXT
JavaScript:
  1. RegisterForm = $.klass({
  2.   initialize : function(options) {
  3.  
  4.   }
  5. });

If you have developed in languages like PHP, Python, or Java, you've probably seen something like this before. This first function, initialize, is a reserved function in Low Pro that accepts one parameter—an options parameter (we'll discuss that later). This function is always called whenever you bind a class to an element. Because it does not require any event to trigger, it is very useful for setting up initial data or events on dynamic DOM elements.

Validation

The first thing we'll do is create our JavaScript validation rules. This tutorial does not cover the creation of these rules; however, they should be reasonably understandable. If you would like more information, please check out the excellent documentation.

PLAIN TEXT
JavaScript:
  1. RegisterForm = $.klass({
  2.   initialize : function(options) {
  3.     this.element.validate({
  4.       rules: {
  5.         username: {
  6.           required: true,
  7.           minlength: 4
  8.         },
  9.         email : {
  10.           required: true,
  11.           email: true
  12.         },
  13.         password2 : {
  14.           equalTo: "#password1"
  15.         }
  16.       },
  17.       messages : {
  18.         username : {
  19.           required: 'Your username is required',
  20.           minlength: 'The minimum number of characters is 4'
  21.         },
  22.         email : {
  23.           required: 'You must enter your email',
  24.           email: 'You must enter a valid email'
  25.         },
  26.         password2 : {
  27.           equalTo: 'Your passwords must match'
  28.         }
  29.       }
  30.     });
  31.   }
  32. });

Notice that I am using this.element instead of $('#lowpro-form') inside the function. Low Pro provides this handy alias so you always work with the correct object. If you are going to be writing a complex function, it's always a good idea within the function to assign it to another variable.

But this code isn't actually doing anything yet. This is because we now need to bind the class to the form. Here is where we go back to the good old jQuery we know and love. Below the class, put this in the file:

PLAIN TEXT
JavaScript:
  1. $(document).ready(function(){
  2.   $('#lowpro-form').attach(RegisterForm);
  3. });

Now, open up the page in your browser and start to type into the fields. You should start to see the validation rules apply to the fields. Congratulations, you've written your first re-usable class with Low Pro!

Enhancements

Now that we have our validation rules, let's start to make the form a bit more sexy. First, something simple. Let's make sure that the first field (the username field) is always selected first, so the user can easily tab down the form. After the validation method inside the initalize function, add this:

PLAIN TEXT
JavaScript:
  1. $('#username').focus();

Refresh the page, and your username field should now get the focus.

Now let's introduce another event into the mix. When the user submits the form, we want to let the user know that it's being sent to the server. To do this, we could notify the user by changing the text on the button from "Register" to "Submitting".

PLAIN TEXT
JavaScript:
  1. RegisterForm = $.klass({
  2.   initialize : function(options) {
  3.     ...
  4.   },
  5.   onsubmit : function() {
  6.     $form = this.element;
  7.     $('.register').val('Submitting');
  8.         /* If your using Ajax it goes in here */
  9.         return false;
  10.   }
  11. });

So there we have it: A reusable, fully functional Ajax registration form with validation. You can check out a demo here and also grab the source code of this example from my repository.

One final thing I should touch on in this first tutorial is the initialize function's options parameter. When attaching any Low Pro class, the initialize function accepts an object containing any options you want to pass into the function:

PLAIN TEXT
JavaScript:
  1. $('#myform').attach(MyFunction, {foo:'moo', bar:2}

In our above example, we'll add a tag to display a message of the day. In the HTML, create a div with a class of motd. Next, add the following code into the initalize function:

PLAIN TEXT
JavaScript:
  1. if (options.motd) {
  2.   $('.motd').text(options.motd);
  3. }

Now, when we attach our class to the form, we use the following:

PLAIN TEXT
JavaScript:
  1. $(document).ready(function(){
  2.   $('#lowpro-form').attach(RegisterForm, {motd: 'jQuery Rocks!'});
  3. });

When you now refresh the form, you should see a message on the screen.

Well, that wraps it up for this tutorial. I hope I've given you a small idea of the power that Low Pro contains. In conjunction with LiveQuery, you can really create some dynamic and interesting applications.

If anyone would be interested in more tutorials like this, then please leave a comment and let me know what you think.

Tane Piper is a full time web developer, geek and Humanist from Edinburgh, Scotland.(55.957898, -3.159792) He has released or is working on several open source projects including jMaps and Mercurial manager. He is also available for hire as a freelance developer, working with PHP, Python and JavaScript.
]]> http://www.learningjquery.com/2008/05/using-low-pro-for-jquery/feed 16 Working with Events, part 1 http://www.learningjquery.com/2008/03/working-with-events-part-1 http://www.learningjquery.com/2008/03/working-with-events-part-1#comments Mon, 31 Mar 2008 16:34:12 +0000 Karl Swedberg http://www.learningjquery.com/2008/03/working-with-events-part-1 CSS and JavaScript are different in many ways, almost all of which are too obvious to mention. However, one difference between the two bears explanation, because it is often the cause of confusion and consternation, especially among those who are making the transition from CSS guru to jQuery novice. In fact, it was one of the first things I asked about on the jQuery mailing list back in 2006. Since then, I've seen at least one question on the subject every week, and sometimes as many as one per day—despite an FAQ page and these three plugins to help users deal with it.

How CSS and JavaScript Are Different

So, what's this important difference?

In CSS, style rules are automatically applied to any element that matches the selectors, no matter when those elements are added to the document (DOM).

In JavaScript, event handlers that are registered for elements in the document apply only to those elements that are part of the DOM at the time the event is attached. If we add similar elements to the DOM at a later time, whether through simple DOM manipulation or ajax, CSS will give those elements the same appearance, but JavaScript will not automatically make them act the same way.

For example, let's say we have "<button class="alert">Alert!</button>" in our document, and we want to attach a click handler to it that generates an alert message. In jQuery, we might do so with the following code:

PLAIN TEXT
JavaScript:
  1. $(document).ready(function() {
  2.   $('button.alert').click(function() {
  3.     alert('this is an alert message');
  4.   });
  5. });

Here we are registering the click handler for the button with a class of "alert" as soon as the DOM has loaded. So, the button is there, and we have a click function bound to it. If we add a second <button class="alert"> later on, however, it will know nothing about that click handler. The click event had been dealt with before this second button existed. So, the second button will not generate an alert.

[inline][/inline]

Let's test what we've just discussed. I've added a script with the above three lines of jQuery code so that the following button will produce an alert message when clicked. Try it:

Events Don't Work with Added Elements

Now, let's create a new button (if we don't already have a second one) using jQuery code like this:

PLAIN TEXT
JavaScript:
  1. $('#create-button').click(function() {
  2.   if ( $('button.alert').length <2) {
  3.     $('<button class="alert">Not another alert').insertAfter(this);
  4.   }
  5.   return false;
  6. });

create the button

Have you clicked the link to create the second button? Great. Now click that button. It does nothing. Just as expected.

CSS Continues to "Work" with Newly Created Elements

Now let's take a look at another example. In this one, we have three list items—two plain items and one with a class of special:

PLAIN TEXT
HTML:
  1. <ul id="list1" class="eventlist">
  2.   <li>plain</li>
  3.   <li class="special">special <button>I am special</button></li>
  4.   <li>plain</li>
  5. </ul>

Press the "I am special" button to create a new list item with a class of "special":

  • plain
  • special
  • plain

Notice that, like the first special li, the new one has the yellow background. The CSS has come through for us. But press the newly created "I am new" button and, just as with the second alert above, nothing happens. The jQuery code we're using to add the new item says that upon clicking a button inside a list item with a class of "special" (which itself is inside an element with id of "list1") a new list item with class="special" should be inserted after the list item in which the button was clicked:

PLAIN TEXT
JavaScript:
  1. $(document).ready(function() {
  2.   $('#list1 li.special button').click(function() {
  3.     var $newLi = $('<li class="special">special and new <button>I am new</button></li>');
  4.     $(this).parent().after($newLi);
  5.   });
  6. });

So, how can we get the events to carry over to the new elements? Two common approaches are event delegation and "re-binding" event handlers. In this entry, we'll examine event delegation; in part 2, we'll explore ways to re-bind.

Event Delegation: Getting Events to Embrace New Elements

The general idea of event delegation is to bind the event handler to a containing element and then have an action take place based on which specific element within that containing element is targeted. Let's say we have another unordered list: <ul id="list2"> ... </ul>. Instead of attaching the .click() method to a button — $('#list2 li.special button').click(...) — we can attach it to the entire surrounding <ul>. Through the magic of "bubbling," any click on the button is also a click on the button's surrounding list item, the list as a whole, the containing div, and all the way up to the window object. Since the <ul> that gets clicked is the same one each time (we're only creating items within the <ul>), the same thing will happen when clicking on all of the buttons, regardless of when they were created.

When we use event delegation, we need to pass in the "event" argument. So, in our case, instead of .click(), we'll have .click(event). We don't have to name this argument event. We can call it e or evt or gummy or whatever we want. I just like to use labels that are as obvious as possible because I have a hard time keeping track of things. Here is what we have so far:

PLAIN TEXT
JavaScript:
  1. $(document).ready(function() {
  2.   $('#list2').click(function(event) {
  3.     var $newLi = $('<li class="special">special and new <button>I am new</button></li>');
  4.   });
  5. });

So far, the code is very similar to our first attempt, except for the selector we're starting with (#list2) and the addition of the event argument. Now we need to determine whether what is being clicked inside the <ul> is a "special" button or not. If it is, we can add a new <li class="special">. We check the clicked element by using the "target" property of the event argument:

PLAIN TEXT
JavaScript:
  1. $(document).ready(function() {  
  2.   $('#list2').click(function(event) {
  3.     var $newLi = $('<li class="special">special and new <button>I am new</button></li>');
  4.     var $tgt = $(event.target);
  5.     if ($tgt.is('button')) {
  6.       $tgt.parent().after($newLi);
  7.     }
  8.  
  9.     // next 2 lines show that you've clicked on the ul
  10.     var bgc = $(this).css('backgroundColor');
  11.     $(this).css({backgroundColor: bgc == '#ffcccc' || bgc == 'rgb(255, 204, 204)' ? '#ccccff' : '#ffcccc'});
  12.   });
  13. });

Line 4 above puts the target element in a jQuery wrapper and stores it in the $tgt variable. Line 5 checks whether the click's target is a button. If it is, the new list item is inserted after the parent of the clicked button. Let's try it:

  • plain
  • special
  • plain

I put an additional two lines at the end to demonstrate that a click on one of the buttons is still considered a click on the <ul> You'll see that clicking anywhere within the <ul> toggles its background between pink and blue.

It's probably worth noting that jQuery makes working with the event argument cross-browser friendly. If you do this sort of thing with plain JavaScript and DOM nodes, you'd have to do something like this:

var list2 = document.getElementById('list2');
list2.onclick = function(e) {
  var e = e || window.event;
  var tgt = e.target || e.srcElement;
  if (tgt.nodeName.toLowerCase() == 'button') {
    // do something
  }
};

As you can see, it's a bit of a hassle.

Another Huge Benefit of Event Delegation

Event delegation is also a great way to avoid crippling the user's browser when you're working with a huge document. For example, if you have a table with thousands of cells, and you want something to happen when the user clicks on one, you won't want to attach a click handler to every single one of them (believe me, it can get ugly). Instead, you can attach the click handler to a single table element and use event.target to pinpoint the cell that is being clicked:

PLAIN TEXT
JavaScript:
  1. $(document).ready(function() {
  2.   $('table').click(function(event) {
  3.     var $thisCell, $tgt = $(event.target);
  4.     if ($tgt.is('td')) {
  5.       $thisCell = $tgt;
  6.     } else if ($tgt.parents('td').length) {
  7.       $thisCell = $tgt.parents('td:first');
  8.     }
  9.     // now do something with $thisCell
  10.   });
  11. });

Note that I had to account for the possibility of clicking in a child/descendant of a table cell, but this seems a small inconvenience for the great performance increase that event delegation affords.

Coming Up Next

In part 2 of this tutorial, we'll look at how to get events to carry over to newly created elements through careful placement of function calls. We'll also, necessarily, examine unbinding events and using namespaced events. In the meantime, I hope you find part 1 useful. If I've made any mistakes, especially in my terminology, please don't hesitate to point them.

]]> http://www.learningjquery.com/2008/03/working-with-events-part-1/feed 93 Revealing Details with jQuery http://www.learningjquery.com/2008/01/revealing-details-with-jquery http://www.learningjquery.com/2008/01/revealing-details-with-jquery#comments Fri, 04 Jan 2008 04:57:57 +0000 Karl Swedberg http://www.learningjquery.com/2008/01/revealing-details-with-jquery A week or so ago, someone posted a comment on one of my previous articles, asking if I could help her split up the textual content of an element, showing the first part and replacing the second with a link that, when clicked, would reveal the text. This behavior would appear in an FAQ using a definition list (<dl>), with each question contained in a <dt> and each answer contained in a <dd>. I soon realized that the solution would be rather involved, so I decided to create a new entry out of it rather than simply answer her question in another comment.

Here is the simple definition list structure that I'll be using for the example:

[inline][/inline]
PLAIN TEXT
HTML:
  1. <dl class="expander">
  2.   <dt><strong>Benedick's Question</strong>...</dt>
  3.   <dd><strong>Beatrice's Answer</strong>...</dd>
  4.   <dt><strong>Benedick's Question</strong>...</dt>
  5.   <dd><strong>Beatrice's Answer</strong>...</dd>
  6. </dl>

First Steps

As usual, we start the script with a "document.ready" line so that it can be fired when the DOM has finished loading. Next comes our primary selector expression. For this example, I've given the targeted <dl> element a class of "expander" so that we don't inadvertently attach the behavior to other <dl>s. And since we're manipulating the contents of each <dd> independently of one another, we can make things happen inside an .each() method:

PLAIN TEXT
JavaScript:
  1. $(document).ready(function() {
  2.   $('dl.expander dd').each(function(index) {
  3.    
  4.   });
  5. });

We ought to declare some variables now. The first two will go right after the document.ready line, while the others will appear inside the .each() method because they change with each <dd> element.

  • slicePoint (integer): the number of characters at which the contents will be sliced into two parts. Note: any tag names in the HTML that appear inside the <dd> before the slicePoint will be counted along with the text characters.
  • widow (integer): this is a threshold of sorts for whether we want to initially hide part of the <dd>'s contents. If after slicing the contents in two there are fewer words in the second part than the value set by widow, we won't bother hiding anything.
  • allText (string): the full contents of the <dd>
  • startText (string): the first part of the <dd>'s contents — the part that is immediately visible. First, all characters up to the slicePoint are included, and then any "word" characters at the end of the string are removed to avoid ending with a partial word. Keep in mind that in almost every case this approach will leave us with fewer characters than we indicated in the slicePoint variable
  • endText (string): the second part of the <dd>'s contents. This part is initially hidden from view, replaced by a "read more..." link.

Here is what we have so far:

PLAIN TEXT
JavaScript:
  1. $(document).ready(function() {
  2.   var slicePoint = 100;
  3.   var widow = 4;
  4.   $('dl.expander dd').each(function() {
  5.     var allText = $(this).html();
  6.     var startText = allText.slice(0,slicePoint).replace(/\w+$/,'');
  7.     var endText = allText.slice(startText.length);
  8.   });
  9. });

Although jQuery has its own .slice() method, which operates on a jQuery object, we're using JavaScript's native method, which can operate on both strings (as is the case here) and arrays. Our first use of .slice(), declaring the startText variable, has two arguments — one for the beginning position of the string and one for the ending. Our second has only one argument, for the starting position; the (allText) string's length is the implied ending position. Also, note that for startText, we're chaining .slice() and the .replace() regular expression method.

Manipulating the Contents

Now that we have our two blocks of content, we're going to add a "read more..." link after the startText and wrap the endText in a span (with a class of "details"), but only if there are more words than the value defined by the widow variable. (tangent: am I the only one who can't type "widow" right the first time, always typing "window" instead?). There are many ways to create new elements and insert them into the DOM with jQuery. For this example, we're going to use the .html() method, create an array of strings inside it, and join those strings.

PLAIN TEXT
JavaScript:
  1. $(document).ready(function() {
  2.   var slicePoint = 100;
  3.   var widow = 4;
  4.   $('dl.expander dd').each(function() {
  5.     var allText = $(this).html();
  6.     var startText = allText.slice(0,slicePoint).replace(/\w+$/,'');
  7.     var endText = allText.slice(startText.length);
  8.    
  9.     // *** commence DOM manipulation ...
  10.     if ( endText.replace(/\s+$/,'').split(' ').length> widow ) {
  11.       $(this).html([
  12.         startText,
  13.         '<a href="#" class="read-more">read more...</a>',
  14.         '<span class="details">',
  15.           endText,
  16.         '</span>'
  17.         ].join('')
  18.       );
  19.     }
  20.   });
  21. });

I picked up that technique of creating an array and joining its elements from the jQuery Google Group. It seems cleaner than string concatenation somehow, and rumor has it that it's a bit faster, too.

Finishing Touches

We have everything in place now, so all we need to do is hide the content inside our newly created <span class="details"> and attach a click handler to the "read more" link. Here is the completed code:

PLAIN TEXT
JavaScript:
  1. $(document).ready(function() {
  2.   var slicePoint = 100;
  3.   var widow = 4;
  4.   $('dl.expander dd').each(function() {
  5.     var allText = $(this).html();
  6.     var startText = allText.slice(0,slicePoint).replace(/\w+$/,'');
  7.     var endText = allText.slice(startText.length);
  8.     if ( endText.replace(/\s+$/,'').split(' ').length> widow ) {
  9.       $(this).html([
  10.         startText,
  11.         '<a href="#" class="read-more">read more...</a>',
  12.         '<span class="details">',
  13.           endText,
  14.         '</span>'
  15.         ].join('')
  16.       );
  17.     }
  18.   });
  19.  
  20.   // *** hide details until read-more link is clicked;
  21.   // then hide link and show details.
  22.   $('span.details').hide();
  23.   $('a.read-more').click(function() {
  24.     $(this).hide()
  25.     .next('span.details').fadeIn();
  26.     return false;
  27.   });
  28. });

I used a .fadeIn() because I like the way it looks, but a simple .show() would do. The return false; line is important to prevent a jump to the top of the page on click.

the Demo

Here is a little demo:

Benedick's Question: I pray you, what is he?
Beatrice's Answer: Why, he is the prince's jester: a very dull fool; only his gift is in devising impossible slanders: none but libertines delight in him; and the commendation is not in his wit, but in his villany; for he both pleases men and angers them, and then they laugh at him and beat him. I am sure he is in the fleet: I would he had boarded me. (Much Ado About Nothing, II.1)
Benedick's Question: I do love nothing in the world so well as you: is not that strange?
Beatrice's Answer: As strange as the thing I know not. It were as possible for me to say I loved nothing so well as you: but believe me not; and yet I lie not; I confess nothing, nor I deny nothing. (Much Ado About Nothing, IV.1)
Karl's Question: Why aren't you using another question from Much Ado About Nothing here?
Karl's Answer: Because I'm lazy. And besides, this demo is getting a little too pretentious.
]]> http://www.learningjquery.com/2008/01/revealing-details-with-jquery/feed 28 Improved Animated Scrolling Script for Same-Page Links http://www.learningjquery.com/2007/10/improved-animated-scrolling-script-for-same-page-links http://www.learningjquery.com/2007/10/improved-animated-scrolling-script-for-same-page-links#comments Sat, 20 Oct 2007 19:20:30 +0000 Karl Swedberg http://www.learningjquery.com/2007/10/improved-animated-scrolling-script-for-same-page-links After posting the last entry on animated scrolling with jQuery 1.2, I realized that I had left out an important piece of code. Actually, I didn't discover it until someone notified me that another page on the site was broken. Can you spot the problem(s)? [Note: the problem is not in line 3. The syntax highlighter just can't handle the regular expression with two slashes in it ("//") and is incorrectly treating them as a comment mark.] See the answer below the code.

PLAIN TEXT
JavaScript:
  1. $(document).ready(function(){
  2.   $('a[href*=#]').click(function() {
  3.     if (location.pathname.replace(/^\//,'') == this.pathname.replace(/^\//,'')
  4.     && location.hostname == this.hostname) {
  5.       var $target = $(this.hash);
  6.       $target = $target.length && $target
  7.       || $('[name=' + this.hash.slice(1) +']');
  8.       if ($target.length) {
  9.         var targetOffset = $target.offset().top;
  10.         $('html,body')
  11.         .animate({scrollTop: targetOffset}, 1000);
  12.        return false;
  13.       }
  14.     }
  15.   });
  16. });

Answer: The animated scrolling script hijacks links that look like this: <a href="#">. A couple people confirmed in the comments that the script needed a bit more work, so I figured we could take one more pass at it.

By the way, even though we attached the click event handler to all links that have the "#" symbol anywhere in the href, the very next line ensures that the link is pointing to the same page — by checking for a match between location.pathname and this.pathname — and the line after that ensures that it's pointing to the same domain, by checking for a match between location.hostname and this.hostname. With this approach, we can accommodate same-page links whether they include a fully-qualified URL, a relative URL, or just the fragment identifier.

Check for the Hash

Let's fix the problem with the <a href="#"> links. The first thing we have to do is see if there is actually something following the "#" symbol in the href. Apparently, if there is a lone "#" symbol, without any following characters, Firefox and Internet Explorer don't consider it a hash. Safari does, however. So, to avoid a false positive on <a href="#">, we need to first strip the "#" and then check if there is anything left. We can do so by adding this condition to the first if statement: && this.hash.replace(/#/,'')

Check for the Named Anchor

Since we're already changing the script, maybe it's a good time to make some of it more readable, too. This part with the "short-circuit" logic, using && and ||, makes me a little dizzy:

PLAIN TEXT
JavaScript:
  1. var $target = $(this.hash);
  2. $target = $target.length && $target
  3. || $('[name=' + this.hash.slice(1) +']');
  4. if ($target.length) {

There is absolutely nothing wrong with this syntax. In fact, more advanced JavaScripters use it all the time. But I feel more comfortable using a simpler, more straightforward style. So, let's set two variables — one for a target ID and one for a target named anchor. We'll then use conditional (aka ternary) operators to set a third, $target, variable as the target ID if it's there, and if not, the target named anchor if it's there, and if not, false. Then we can just check if $target has some value (other than false):

PLAIN TEXT
JavaScript:
  1. var $targetId = $(this.hash),
  2.   $targetAnchor = $('[name=' + this.hash.slice(1) +']');
  3. var $target = $targetId.length ? $targetId
  4.   : $targetAnchor.length ? $targetAnchor
  5.     : false;
  6. if ($target) {

Now it appears that the animated scrolling behavior will be attached to all same-page links and not break other stuff on the page.

Loop First, Bind Last

But there is another problem. Since we're still binding the .click() method to every link with "#" in it, even if it's appropriately avoiding applying the animation for some of those links, jQuery is still hijacking links that have an inline onclick handler (but, oddly, only the first time those links are clicked). To fix this problem, we can replace the .click() with .each(). Then we'll iterate through all links that have "#" somewhere in them, but place the conditions inside the loop so that we bind the click handler only after we've filtered out all the links that don't apply. Here is what the script looks like with the change:

PLAIN TEXT
JavaScript:
  1. $(document).ready(function() {
  2.   $('a[href*=#]').each(function() {
  3.     if (location.pathname.replace(/^\//,'') == this.pathname.replace(/^\//,'')
  4.     && location.hostname == this.hostname
  5.     && this.hash.replace(/#/,'') ) {
  6.       var $targetId = $(this.hash), $targetAnchor = $('[name=' + this.hash.slice(1) +']');
  7.       var $target = $targetId.length ? $targetId : $targetAnchor.length ? $targetAnchor : false;
  8.        if ($target) {
  9.          var targetOffset = $target.offset().top;
  10.          $(this).click(function() {
  11.            $('html, body').animate({scrollTop: targetOffset}, 400);
  12.            return false;
  13.          });
  14.       }
  15.     }
  16.   });
  17. });

Notice especially lines 2 and line 10. This change not only takes care of our problem, but it feels cleaner somehow, too. Is it more efficient? I don't know. Maybe someone else can tell us in the comments.

Normalize Directory Indexes

To be complete, we should probably take care of one more thing: the possibility that, on an "index" page, a link could point to "/path/index.htm" when the current location says "/path/" or vice versa. One way to "normalize" these index pages and links is to add a couple more .replace() methods to both sides of the equation in line 3.

Update

Aman suggested in a comment below that I make this process DRYer, and kangax provided a great example. So we can write a filter function and apply it to both sides rather than repeating the three replaces on each side:

PLAIN TEXT
JavaScript:
  1. function filterPath(string) {
  2.   return string
  3.     .replace(/^\//,'')  
  4.     .replace(/(index|default).[a-zA-Z]{3,4}$/,'')  // first additional replace
  5.     .replace(/\/$/,'');  // second additional replace
  6. }

The first additional .replace() will find a string represented by "index" or "default," followed by a dot, followed by any three or four letters at the end the pathname, and replace it with an empty string (i.e. remove it). The second one will replace a trailing slash with an empty string. As with chained jQuery methods, these regular-expression methods can be placed on separate lines to improve readability. Finally, we have a bullet-proof (I hope) animated scrolling script for same-page links:

PLAIN TEXT
JavaScript:
  1. $(document).ready(function() {
  2.   function filterPath(string) {
  3.     return string
  4.       .replace(/^\//,'')  
  5.       .replace(/(index|default).[a-zA-Z]{3,4}$/,'')  
  6.       .replace(/\/$/,'');
  7.   }
  8.   $('a[href*=#]').each(function() {
  9.     if ( filterPath(location.pathname) == filterPath(this.pathname)
  10.     && location.hostname == this.hostname
  11.     && this.hash.replace(/#/,'') ) {
  12.       var $targetId = $(this.hash), $targetAnchor = $('[name=' + this.hash.slice(1) +']');
  13.       var $target = $targetId.length ? $targetId : $targetAnchor.length ? $targetAnchor : false;
  14.        if ($target) {
  15.          var targetOffset = $target.offset().top;
  16.          $(this).click(function() {
  17.            $('html, body').animate({scrollTop: targetOffset}, 400);
  18.            return false;
  19.          });
  20.       }
  21.     }
  22.   });
  23. });

If you try it out, let me know how it goes.

Update 2

Ariel Flesler has written an excellent ScrollTo plugin, which he says was inspired by this blog entry. Be sure to check out the demo.

Update 3

Someone called my attention to a problem that this script was having in IE and Opera. Not sure how I could have missed that, because I'm sure I tested it in both of those browsers. But never mind, I've come up with a little patch:

PLAIN TEXT
JavaScript:
  1. $(document).ready(function() {
  2.   function filterPath(string) {
  3.   return string
  4.     .replace(/^\//,'')
  5.     .replace(/(index|default).[a-zA-Z]{3,4}$/,'')
  6.     .replace(/\/$/,'');
  7.   }
  8.   var locationPath = filterPath(location.pathname);
  9.   $('a[href*=#]').each(function() {
  10.     var thisPath = filterPath(this.pathname) || locationPath;
  11.     if (  locationPath == thisPath
  12.     && (location.hostname == this.hostname || !this.hostname)
  13.     && this.hash.replace(/#/,'') ) {
  14.       var $target = $(this.hash), target = this.hash;
  15.       if (target) {
  16.         var targetOffset = $target.offset().top;
  17.         $(this).click(function(event) {
  18.           event.preventDefault();
  19.           $('html, body').animate({scrollTop: targetOffset}, 400, function() {
  20.             location.hash = target;
  21.           });
  22.         });
  23.       }
  24.     }
  25.   });
  26. });

Apparently, IE doesn't see a hostname or pathname if a link's href attribute is set with JavaScript and contains only a hash (such as "#example"). So, I'm checking now for either a match or an absence of hostname and pathname.

I hope this change fixes the problem that Mike was having. Seems to work in my tests now. Oh, and I took the opportunity to improve the code a bit. Now, it has mild back-button support: while clicking on the back button doesn't produce the animated scrolling, it at least gets you back to the previous location.

Update 4

Ariel Flesler suggested that the problem a few people have mentioned regarding this script with Opera has to do with this line: $('html, body').animate({scrollTop: targetOffset}, 400);. At the time I wrote the script, I was covering all my bases, since "html" worked for IE in standards mode and "body" worked in quirks mode. Apparently, though, the combination of the two messes things up in Opera. So, try removing "body" from the selector and see if that fixes things.

Update 5

Here is a fix for the problem people have with Opera (and possibly other browsers) when attaching the animate to both html and body:

PLAIN TEXT
JavaScript:
  1. $(document).ready(function() {
  2.   function filterPath(string) {
  3.   return string
  4.     .replace(/^\//,'')
  5.     .replace(/(index|default).[a-zA-Z]{3,4}$/,'')
  6.     .replace(/\/$/,'');
  7.   }
  8.   var locationPath = filterPath(location.pathname);
  9.   var scrollElem = scrollableElement('html', 'body');
  10.  
  11.   $('a[href*=#]').each(function() {
  12.     var thisPath = filterPath(this.pathname) || locationPath;
  13.     if (  locationPath == thisPath
  14.     && (location.hostname == this.hostname || !this.hostname)
  15.     && this.hash.replace(/#/,'') ) {
  16.       var $target = $(this.hash), target = this.hash;
  17.       if (target) {
  18.         var targetOffset = $target.offset().top;
  19.         $(this).click(function(event) {
  20.           event.preventDefault();
  21.           $(scrollElem).animate({scrollTop: targetOffset}, 400, function() {
  22.             location.hash = target;
  23.           });
  24.         });
  25.       }
  26.     }
  27.   });
  28.  
  29.   // use the first element that is "scrollable"
  30.   function scrollableElement(els) {
  31.     for (var i = 0, argLength = arguments.length; i <argLength; i++) {
  32.       var el = arguments[i],
  33.           $scrollElement = $(el);
  34.       if ($scrollElement.scrollTop()> 0) {
  35.         return el;
  36.       } else {
  37.         $scrollElement.scrollTop(1);
  38.         var isScrollable = $scrollElement.scrollTop()> 0;
  39.         $scrollElement.scrollTop(0);
  40.         if (isScrollable) {
  41.           return el;
  42.         }
  43.       }
  44.     }
  45.     return [];
  46.   }
  47.  
  48. });

I put together a little smooth-scroll jQuery plugin with a couple options, in case anyone is interested. For a more robust feature set, check out Ariel Flesler's scrollTo plugin.

]]> http://www.learningjquery.com/2007/10/improved-animated-scrolling-script-for-same-page-links/feed 80 Automatic Page Contents http://www.learningjquery.com/2007/06/automatic-page-contents http://www.learningjquery.com/2007/06/automatic-page-contents#comments Mon, 25 Jun 2007 11:44:05 +0000 Karl Swedberg http://www.learningjquery.com/2007/06/automatic-page-contents It's been so long since I last posted a tutorial here that I'm afraid everyone might have forgotten about the place. For the past few months, there has been a little "Page Contents" menu at the top-right corner of some of the pages on this site — actually, any page that has more than one <h2> elements in the main content area. In this entry, I'd like to demonstrate how to create an automatic page contents list using jQuery.

The Plugin Option

Before we begin, I should let you know that there are a number of plugins that do what I'm about to show you. If you want to go the plug-in route, take a look at one of these:

But if you want to see how to do this sort of thing on your own, read on...

Let's Begin

Here is what we need to do:

  1. Find out if there is more than one <h2> in the main content area of the page (on this site, the home page and most listing pages will have more than one). If so, we start building the table of contents...
  2. Create a new container <div> for the table of contents and insert a heading and an empty div inside.
  3. Copy the <h2> elements and the <a> elements inside them.
  4. Change the attributes of the copied links.
  5. Insert each copied <h2> along with its contained link into the page-contents <div>.
page contents example

When we're finished, we should have something that looks like the image to the right:

Create the container

Okay, so our first step is to create the container. We'll wrap our code in a $(document).ready(), as we do nearly every time, so that the script loads when the DOM (but not necessarily image, etc.) has loaded. Then we make sure that we're dealing with more than one <h2> and, if so, start building:

PLAIN TEXT
JavaScript:
  1. $(document).ready(function() {
  2.   if ( $('#content h2').length> 1) {
  3.     $('<div id="page-contents"></div>')
  4.       .prepend('<h3>Page Contents</h3>')
  5.       .append('<div></div>')
  6.       .prependTo('body');
  7.   }
  8. });

Okay, maybe a little explanation is warranted here. The first line inside our if condition (line 3) creates a new <div> element with an id of "page-contents." Line 4 inserts an <h3> at the beginning of that new <div> and line 5 inserts an empty <div> at the end of the page-contents <div>. Finally, line 5 inserts the whole group of newly created elements at the beginning of the <body>.

Copy the headings

The next part involves copying all of the <h2> elements, and while we're at it, changing the href of the copied <a> elements to point to the original <h2>s. How do we know where to point them? Each of the original <h2>s has an id associated with it. We just take the id, prepend a "#", and attach it to the href:

PLAIN TEXT
JavaScript:
  1. $(document).ready(function() {
  2.   if ( $('#content h2').length> 1) {
  3.     // ... etc. ...
  4.     $('#content h2').each(function(index) {
  5.       var $this = $(this);
  6.       var thisId = this.id;
  7.       $this
  8.         .clone()
  9.         .find('a')
  10.           .attr({
  11.             'title': 'jump to ' + $this.text(),
  12.             'href': '#' + thisId
  13.           })
  14.         .end()
  15.         .attr('id', 'pc-' + index)
  16.         .appendTo('#page-contents div');
  17.     });  
  18.   }
  19. });

We use a .each() method here so that we can apply a number of things to each <h2> in turn. Inside this method, we start by declaring a couple variables—one for $(this), because we use it twice, and one for each id, because we use it to set the hrefs.

So, for each <h2>, we make a copy using .clone() and find the <a> inside of it. Then we set each link's title and href attribute.

When we're finished with the links, we back up to the cloned <h2> elements by using .end(). We want to ensure that we don't duplicate the id along with the element, so we prepend "pc-" to it, keeping each one unique.

When all is ready, we append each <h2> to the <div>inside the page-contents container.

A Little Extra Flair

Now, for an optional addition to our script, we can hide the page-contents <div> in a style sheet (by setting it to display: none). Then we attach a click handler to the page-contents heading with a .toggleClass() to change the background image and a .slideToggle() to show and hide the same-page links.

Here is the complete script, with the additional click handler at the end:

PLAIN TEXT
JavaScript:
  1. $(document).ready(function() {
  2.   if ( $('#content h2').length> 1) {
  3.     $('<div id="page-contents"></div>')
  4.       .prepend('<h3>Page Contents</h3>')
  5.       .append('<div></div>')
  6.       .prependTo('body');  
  7.     $('#content h2').each(function(index) {
  8.       var $this = $(this);
  9.       var thisId = this.id;
  10.       $this
  11.         .clone()
  12.         .find('a')
  13.           .attr({
  14.             'title': 'jump to ' + $this.text(),
  15.             'href': '#' + thisId
  16.           })
  17.         .end()
  18.         .attr('id', 'pc-' + index)
  19.         .appendTo('#page-contents div');
  20.     });
  21.     $('#page-contents h3').click(function() {
  22.       $(this).toggleClass('arrow-down')
  23.         .next().slideToggle('fast');
  24.     });
  25.   }
  26. });

If you want to see it in action, just go to the Learning jQuery home page and look in the top-right corner of the page.

]]> http://www.learningjquery.com/2007/06/automatic-page-contents/feed 21 Copy Events from One Element to Another http://www.learningjquery.com/2007/01/copy-events-from-one-element-to-another http://www.learningjquery.com/2007/01/copy-events-from-one-element-to-another#comments Thu, 01 Feb 2007 01:00:06 +0000 Brandon Aaron http://www.learningjquery.com/2007/01/copy-events-from-one-element-to-another Need to clone an element and its events? Sure, you could rebind the events after doing the clone, but that wouldn't be very DRY now, would it? Introducing Copy Events, a new plugin for jQuery.

Clone an Element and its Events

The Copy Event plugin makes it easy to clone an element and its events. How? Amazingly simple. Let's say you have an unordered list and each list item has a click, mouseover, and mouseout event. Now you need to clone the last list item and append it to the unordered list.

Here is the HTML:

PLAIN TEXT
HTML:
  1. <ul id="myList">
  2.     <li>List Item 1</li>
  3.     <li>List Item 2</li>
  4.     <li>List Item 3</li>
  5. </ul>

Here is the JavaScript that applies the event handlers during the $(document).ready event:

PLAIN TEXT
JavaScript:
  1. $('#myList li')
  2.     .bind('click', function() {
  3.         alert( $(this).text() );
  4.     })
  5.     .bind('mouseover', function() {
  6.         $(this).addClass('over');
  7.     })
  8.     .bind('mouseout', function() {
  9.         $(this).removeClass('over');
  10.     });

Now, here is the code to clone the last list item with its events:

PLAIN TEXT
JavaScript:
  1. $('#myList li:last')
  2.     .cloneWithEvents()
  3.     .text('List Item ' + ($('#myList li').size()+1))
  4.     .appendTo('#myList');

DONE! Simple as calling cloneWithEvents(). This method takes an optional parameter called "deep" — just like the clone() method — which, if set to false, copies only the element itself, without any of its descendants. You can see the results here.

More Than Just Cloning

The Copy Events plugin offers two more methods to allow for easy copying of events from one element to another or to several other elements. The first is the copyEvents() method and copies events from an element to the elements in the jQuery object. The second is the copyEventsTo() method which copies events from the first matched element in the jQuery object to the matched elements passed in. Let's take a closer look at both of these methods using the unordered list as an example again.

The copyEvents() Method

The copyEvents() method will copy all event handlers from a given element to the set of elements in the current jQuery object. What does that mean? Using the unordered list example, let's add some list items to the unordered list using AJAX.

Here is the code for the AJAX call that gets the extra list items, copies the events and adds the items to the list:

PLAIN TEXT
JavaScript:
  1. $.get('list-items.html', function(lis) {
  2.     $(lis)
  3.         .copyEvents('#myList li')
  4.         .appendTo('#myList');
  5. });

Notice I passed a selector to the copyEvents() method. This method can take a jQuery object, a DOM Element and/or a selector string. When passing in a jQuery object or selector, it will use the first element to copy events from.

You can see the results for this copyEvents example here.

The copyEventsTo() Method

The copyEventsTo() method acts similar to the appendTo() method. It copies events from the first element in the current jQuery object to the passed in elements. Just like the copyEvents() method, the copyEventsTo() method can also take a jQuery object, a DOM Element and/or a selector string.

Let's say we have a new unordered list and would like to copy the events from the existing list to the new list when clicking on a special link:

PLAIN TEXT
HTML:
  1. <a href="#" id="copier" title="Copy Events">Copy Events</a>
  2. <ul id="newList">
  3.     <li>New List Item 1</li>
  4.     <li>New List Item 2</li>
  5.     <li>New List Item 3</li>
  6. </ul>

Now let's look at the JavaScript to copy these events over to the new list:

PLAIN TEXT
JavaScript:
  1. $('#copier')
  2.     .one('click', function() {
  3.         $('#myList li')
  4.             .copyEventsTo('#newList li');
  5.         $(this).remove();
  6.         return false;
  7.     });

I've used the one method to bind the click only once to the <a> tag. When clicked, the events will be copied from the first list item in the #myList unordered list.

Check out the example for yourself here.

Next Steps

The Copy Events plugin can be found in the jQuery Plugins SVN repository.

Update

The ability to copy events has been added to jQuery core as of jQuery 1.2.x. Simply use .clone(true).

]]> http://www.learningjquery.com/2007/01/copy-events-from-one-element-to-another/feed 5