Learning jQuery » Announcement http://www.learningjquery.com Tips, techniques, and tutorials for the jQuery JavaScript library Tue, 17 Jan 2012 14:14:01 +0000 en hourly 1 http://wordpress.org/?v=3.3.1 Introducing jQuery API Search http://www.learningjquery.com/2010/09/introducing-jquery-api-search http://www.learningjquery.com/2010/09/introducing-jquery-api-search#comments Fri, 10 Sep 2010 11:28:26 +0000 Karl Swedberg http://www.learningjquery.com/?p=1240 Half-baked tutorials and plugins have been stacking up for months in my virtual kitchen, waiting for me to fire up the oven, finish the cooking, and spread them out on the table. For some reason, though, I've become less and less sure about whether I've put all the right ingredients into the mix. It's irritating, to be sure, but I'm tired of fretting about it. I'm going to consider this the first of what I hope to be many "taste tests" — experiments in various degrees of completion thrown against the wall to see what, if anything, sticks.

As some of you may know, the online jQuery documentation went through a major overhaul in January of this year, coinciding with the release of jQuery 1.4. Packt Publishing "open sourced" the jQuery 1.4 Reference Guide that Jonathan Chaffer and I had been writing, allowing us to put its entire contents (and more) on api.jquery.com. Some of you may also know that the raw XML content of the site is available as a single file, which has allowed other sites such as jqapi.com and idocs.brandonaaron.net to provide alternative views of that content. But what most of you probably do not know is that the jQuery API has been available for quite some time as a searchable API that returns the results in JSON format.

Note: The reason you probably don't know about it is that it's half-baked. So, please go easy on it until some smart people have a chance to look under the hood at what I'm doing. Crazy abuse will surely bring it to its knees.

Motivation

I wanted to let people access the jQuery documentation via JavaScript from any other site and pull out exactly what is needed. I also wanted to play around with JSONP. This fits both of those desires.

URL

To access the searchable API, use the following URL:

http://api.jquery.com/jsonp/

Examples

You can tap into the API with one of jQuery's Ajax methods. If you use $.get() or $.getJSON(), you'll need to append "?callback=?" to the URL. With $.get(), you'll also need to set the dataType argument to "jsonp".

Find entries in the API that have "class" in their name and then do something with them:

PLAIN TEXT
JavaScript:
  1. $.get('http://api.jquery.com/jsonp/?callback=?',
  2.   {name: 'class'},
  3.   function(data) {
  4.     // do something with data
  5.   },
  6.   'jsonp');

Find all effects-category entries and then do something with them:

PLAIN TEXT
JavaScript:
  1. $.getJSON('http://api.jquery.com/jsonp/?callback=?',
  2.   {category: 'effects'},
  3.   function(json) {
  4.     // do something with json
  5. });

You can, of course, also use the low-level $.ajax() method.

Find entries with a title that ends in "ajax"; append a link for each to the document body:

PLAIN TEXT
JavaScript:
  2.   url: 'http://api.jquery.com/jsonp/',
  3.   dataType: 'jsonp',
  4.   data: {title: 'ajax', match: 'end'},
  5.   success: function(json) {
  6.     for (var i=0, len=json.length; i<len ; i++) {
  7.       var entry = json[i];
  8.       $('<a />', {
  9.         href: entry.url,
  10.         html: entry.title
  11.       }).appendTo('body');
  12.     }
  13.   }
  14. });

Search Types

The JSONP API is searchable by name, category, and version. Searching by more than one criterion returns results that match all of the criteria. All searches are case-insensitive.

  • Search by name:
    • Key: title
    • Value: the name of any jQuery method, property, or selector
    • Searches in: post title and post slug
    • Substitutions: Before querying the database, all "$" are converted to "jQuery" and each instance of one or more spaces is converted to a hyphen ("-") for both the search values and the the post title and slug.
    • Default: all titles
  • Search by category name
    • Key: category
    • Value: category name
    • Substitutions: Before querying the database, each instance of one or more spaces is converted to a hyphen ("-")
    • Searches in: category slug
    • Default: all categories
  • Search by version number
    • Key: version
    • Value: a jQuery version number
    • Searches in: category slug for all categories that are a child of the main "version" category
    • Default: all versions

String Matching

The "match" parameter lets you be confine the results to those that match the entire search term, or just the start or end of it.

  • Key: match
  • Value: one of "start", "end", or "exact" (for search by version number, one of "end" or "exact")
  • Default: "anywhere", except for version number, which has a default of "start"

Returned Data

Data is returned as an array of objects. Each item in the array is an object representing a single method, property, or selector. For example, a result with one item would have the following structure:

PLAIN TEXT
JavaScript:
  1. [
  2.   {
  3.     "url": "...",
  4.     "title": "...",
  5.     "type": "...", // "method", "property", or "selector"
  6.     "signatures": [
  7.     {
  8.       "added":"...",
  9.       "params": [
  10.       {
  11.         "name": "...",
  12.         "type": "...",
  13.         "optional": "...", // either "true" or an empty string
  14.         "desc": "..." // description of the parameter
  15.       }
  16.       ]
  17.     }
  18.     ],
  19.     "desc": "...", // short description
  20.     "longdesc": "...", // long description
  21.     "return": "..." // type of return value
  22.   }
  23. ]

Note that currently the examples/demos from each entry are not returned.

A (Fairly) Basic Demo

I put together a quick demo to give an idea of the API's flexibility. Type something into the "Name" field in the form below—say, "ajax"—and watch as the results come back. Inside the "Advanced" area, choose the "Matching... End" radio button and search again to see how the results differ.

✚ Search Again

jQuery API Search A demonstration

✒ Advanced

Matching
Include in Results

Clear Results

A Little Less Basic Demo

I replicated this search form on a test server and added back-button support with Ben Alman's crazy delicious BBQ Plugin. Try out the demo.

But wait! There's more!

I put the whole shebang (well, except for the server-side stuff) in a GitHub repo. Clone it, fork it, have your way with it.

But Wait! There's Less!

As I mentioned above, this little project is incomplete. If you peek at the scripts, you'll quickly spot some major chunks of code in need of refactoring. Also, had I but world enough and time, I'd use a nice templating system such as mustache.js or the jQuery Templates plugin to output the search results. But I'll leave all that for another day (or another developer).

]]> http://www.learningjquery.com/2010/09/introducing-jquery-api-search/feed 9 Spring 2010 jQuery Conference: San Francisco Bay Area http://www.learningjquery.com/2010/03/spring-2010-jquery-conference-san-francisco-bay-area http://www.learningjquery.com/2010/03/spring-2010-jquery-conference-san-francisco-bay-area#comments Mon, 29 Mar 2010 13:26:17 +0000 Karl Swedberg http://www.learningjquery.com/?p=1057 Since the fall of 2007, jQuery developers around the world have been making an annual pilgrimage to Boston, Massachusetts, to meet jQuery team members, JavaScript luminaries, and other jQuery developers at the official jQuery Conference. This spring, in response to growing demand, the jQuery Project is offering its first-ever official jQuery conference on the U.S west coast. The conference will take place April 24–25 in Mountain View, California, and will include top-notch presentations from the jQuery team, as well as other web development and performance experts. Additionally, the conference will be preceded by a one-day intensive jQuery training course in downtown San Francisco, led by appendTo a leading jQuery training and consulting company.

Priced at $199, the two-day conference is one of the best bargains you'll find anywhere for a full-on tech conference. The jQuery team is committed to keeping the price as low as possible, relying on the support of sponsors to help defray the cost of registration. jQuery developers from beginner to advanced will learn a ton, have a great time, and meet many others who are using jQuery in innovative ways to make the web a better place.

On a personal note, this will be the first jQuery conference ever that I won't be able to attend (regrettably, a scheduling conflict is keeping me home this time). But having heard many of the speakers in the past and having been involved a bit in the planning of this conference, I can assure you that you won't want to miss it. While we hope to continue offering a west-coast event on an annual basis, as we have done with the east-coast event a lot will depend on the level of interest and attendance this time around. So, what are you waiting for? Sign up now!

One brief personal plug: I will be teaching a 3-day jQuery class June 2–4 in beautiful Holland, Michigan. If for some reason you can't make it to the conference in April—or even if you can—you might want to consider taking the class. This will be the fourth class I've taught with Idea Foundry, and if it's anything like the others, we'll have a blast, with lots and lots of great learning.

]]> http://www.learningjquery.com/2010/03/spring-2010-jquery-conference-san-francisco-bay-area/feed 3 Better, Stronger, Safer jQuerify Bookmarklet http://www.learningjquery.com/2009/04/better-stronger-safer-jquerify-bookmarklet http://www.learningjquery.com/2009/04/better-stronger-safer-jquerify-bookmarklet#comments Wed, 29 Apr 2009 14:12:43 +0000 Karl Swedberg http://www.learningjquery.com/?p=687 A long time ago I built myself a little bookmarklet to load jQuery on pages that don't already have it. The idea was to allow me to play around with any page on the web, using jQuery in the Firebug (and now Safari or IE8) console. I blogged about it, got lots of great feedback, and then blogged about an improved version. Now that a lot more great feedback has come through the comments of the updated bookmarklet post, I've decided to update it one more time.

The Bookmarklet

To use the bookmarklet, drag the following link to your bookmark/favorites list:

» jQuerify «

Then, when you're on a page in which you want to play around with jQuery in the console, just click the bookmarklet.

Problems with the Other One

The biggest problem with the former version was that it didn't work when other libraries that use the $ function, such as Prototype and Mootools, were already loaded on the page. A number of people in the comments suggested that I simply add a jQuery.noConflict(); line to the script. But I wasn't crazy about the idea of having to use jQuery() instead of $() even if no other libraries had been loaded.

Another problem, one that I noticed while testing my new version, was that sometimes the jQuery file that I was inserting from the Google CDN wouldn't fully load by the time I attempted to use it later in the bookmarklet. At least, I think that's what was going on. In any case, it was throwing a "jQuery is not defined" error.

A Few Improvements in This One

To handle the problems, I'm having the script do a few things differently:

  • Set up a counter to check 10 times if jQuery is loaded before giving up.
  • Use a setTimeout to put a one-quarter-second (250ms) delay interval in between attempts.
  • Check if the $() function is already being used by another library. If it is:
    • use jQuery's $.noConflict function to release the $() to the other library.
    • set $jq as an alias to jQuery for convenience.
    • mention in the flash notice that jQuery is in noConflict mode and that $jq() should be used instead of $().
  • If after multiple attempts jQuery still won't load for some reason, set the flash notice's message accordingly and then remove it through plain old JavaScript rather than jQuery.

Update

Based on a few comments, I've updated the script one more time to "basically watch the onload and readyState, and fire the callback, thus removing the necessity to poll," as Paul Irish describes below.

The script also removes references to script after success now, as suggested below, to avoid a memory leak.

Here is the updated link (I also updated it above):

» jQuerify «

And here is the updated script:

PLAIN TEXT
JavaScript:
  1. (function() {
  2.   var el=document.createElement('div'),
  3.       b=document.getElementsByTagName('body')[0],
  4.       otherlib=false,
  5.       msg='';
  6.   el.style.position='fixed';
  7.   el.style.height='32px';
  8.   el.style.width='220px';
  9.   el.style.marginLeft='-110px';
  10.   el.style.top='0';
  11.   el.style.left='50%';
  12.   el.style.padding='5px 10px';
  13.   el.style.zIndex = 1001;
  14.   el.style.fontSize='12px';
  15.   el.style.color='#222';
  16.   el.style.backgroundColor='#f99';
  17.  
  18.   if(typeof jQuery!='undefined') {
  19.     msg='This page already using jQuery v'+jQuery.fn.jquery;
  20.     return showMsg();
  21.   } else if (typeof $=='function') {
  22.     otherlib=true;
  23.   }
  24.  
  25.   // more or less stolen form jquery core and adapted by paul irish
  26.   function getScript(url,success){
  27.     var script=document.createElement('script');
  28.     script.src=url;
  29.     var head=document.getElementsByTagName('head')[0],
  30.         done=false;
  31.     // Attach handlers for all browsers
  32.     script.onload=script.onreadystatechange = function(){
  33.       if ( !done && (!this.readyState
  34.            || this.readyState == 'loaded'
  35.            || this.readyState == 'complete') ) {
  36.         done=true;
  37.         success();
  38.         script.onload = script.onreadystatechange = null;
  39.         head.removeChild(script);
  40.       }
  41.     };
  42.     head.appendChild(script);
  43.   }
  44.   getScript('http://code.jquery.com/jquery-latest.min.js',function() {
  45.     if (typeof jQuery=='undefined') {
  46.       msg='Sorry, but jQuery wasn\'t able to load';
  47.     } else {
  48.       msg='This page is now jQuerified with v' + jQuery.fn.jquery;
  49.       if (otherlib) {msg+=' and noConflict(). Use $jq(), not $().';}
  50.     }
  51.     return showMsg();
  52.   });
  53.   function showMsg() {
  54.     el.innerHTML=msg;
  55.     b.appendChild(el);
  56.     window.setTimeout(function() {
  57.       if (typeof jQuery=='undefined') {
  58.         b.removeChild(el);
  59.       } else {
  60.         jQuery(el).fadeOut('slow',function() {
  61.           jQuery(this).remove();
  62.         });
  63.         if (otherlib) {
  64.           $jq=jQuery.noConflict();
  65.         }
  66.       }
  67.     } ,2500);    
  68.   }
  69. })();

Let me know if this one causes any problems.

]]> http://www.learningjquery.com/2009/04/better-stronger-safer-jquerify-bookmarklet/feed 86 The Year of jQuery UI http://www.learningjquery.com/2009/01/the-year-of-jquery-ui http://www.learningjquery.com/2009/01/the-year-of-jquery-ui#comments Sat, 03 Jan 2009 18:44:56 +0000 Karl Swedberg http://www.learningjquery.com/?p=223 Year of jQuery." Since then, jQuery's popularity has grown in ways that none of the core contributors could have imagined. Now I'm ready to make another bold pronouncement: 2009 will be the year of jQuery UI. Here's why:
  • jQuery UI 1.6 is shaping up to be a rock-solid re-factoring of the entire library. With RC4 released just two days ago, the UI team have further cleaned up the API while providing a set of tools that are even more extensible and configurable than they were before.
  • Better project management and greater transparency. Over the last year or so, Paul Bakaus has done much more than lead the development of jQuery UI. He has shaped and nurtured a team of top-notch JavaScript developers and has opened up a lot of the decision-making process to outside scrutiny. This bodes well for the direction of the project.
  • Improved jQuery UI ThemeRoller. ThemeRoller, developed and designed by the folks at Filament Group, was already an amazingly useful and elegant complement to jQuery UI. But now it's even better, with a much-improved CSS framework and lighter CSS footprint, a slick default theme, a cool icon sprite set, and more configuration options. Also, it'll soon be easier than ever to create your own UI widgets that take advantage of the ThemeRoller — with upcoming tools, documentation, and tutorials for making your site "ThemeRoller-ready."
  • Improved documentation and demos. The documentation wiki has undergone some significant updates in recent months, and the demos went through a complete overhaul in coordination with the 1.6rc4 release.
  • More widespread adoption. As the API changes settle down and the core UI developers have more time to spend on providing more widgets and components, such as a spinner, menu, and colorpicker, more sites are sure to join the likes of WordPress in adopting jQuery UI.
  • A new blog. While most of the details are still under wraps, a brand new weblog dedicated to learning jQuery UI, similar in quality and scope to Learning jQuery, will be online soon.
I have had the great pleasure to use jQuery UI on a couple recent projects, and I can honestly say that it has come a long way since its first release a year and a half ago. If you haven't used the UI library before, now is a great time to start. If my prediction comes true, you'll be at the forefront of a major trend.

Update:

I failed to mention that the new blog will be run by jQuery UI developer Richard D. Worth. In addition to being a great developer, Richard does an awesome job of promoting and explaining jQuery UI. I'm really looking forward to seeing the good stuff he'll be posting soon.]]> http://www.learningjquery.com/2009/01/the-year-of-jquery-ui/feed 14 jQuery Site Redesign – The Community Speaks http://www.learningjquery.com/2008/08/jquery-site-redesign-the-community-speaks http://www.learningjquery.com/2008/08/jquery-site-redesign-the-community-speaks#comments Fri, 29 Aug 2008 14:52:38 +0000 Karl Swedberg http://www.learningjquery.com/2008/08/jquery-site-redesign-the-community-speaks Re-posted from Rey Bango's blog.

As many of you have seen by now, the jQuery Project's site has been redesigned. It had been a long overdue task and it was important to put a fresh new spin on the main hub, and the face, of jQuery. One of the things about the jQuery Project is that we've never run with the crowd or accepted the norm. By pushing boundaries and sometimes being "in your face," we've not only grown tremendously in popularity but we've pushed most of the other JS library projects to rethink their own principles and make changes to improve their products. That's a good thing for everyone as competition is always good.

So, it should come as no surprise by the drastic change in the jQuery website. So far, the single biggest complaint has been associated with the new banner (ie: rockstar caricature & slogan). Again, we wanted to push the boundaries and come up with something that would generate a lot of buzz. Overall, we've succeeded in that goal with plenty of positive feedback, but unfortunately, with some very negative comments as well. We actually value both types of feedback and want more as it's the only way to determine if we're on the right track. As with any site redesign, you can't please everyone and we understand that. But we also want everyone to realize that this is a first cut and it doesn't mean that it can't be tweaked.

We're actively reviewing all of the feedback and will certainly be looking at how to best handle some of the concerns of the community. After all, the community is what makes the jQuery Project so special and so different from other projects. In addition, the jQuery team has always listened to the needs of the community and this time is no exception. Again, I think the team is unique in that we *DO LISTEN* to the community and we're going to work on making the site an invaluable tool for everyone. So just give us some time to go through the messages and keep an eye on this blog for updates.

Thanks for your patience and we truly appreciate your feedback.

— Rey Bango

]]> http://www.learningjquery.com/2008/08/jquery-site-redesign-the-community-speaks/feed 15 jQuery Documentation Alternatives http://www.learningjquery.com/2008/07/jquery-documentation-alternatives http://www.learningjquery.com/2008/07/jquery-documentation-alternatives#comments Tue, 29 Jul 2008 21:55:30 +0000 Karl Swedberg http://www.learningjquery.com/2008/07/jquery-documentation-alternatives jquery.com and its subdomains have been offline intermittently over the past several weeks. On behalf of the jQuery Project Team, I apologize for any inconvenience this has caused. John Resig is aware of the problem and is working with the hosting company to get things resolved as quickly as possible. In the meantime, Remy Sharp, who runs jQuery for Designers, has graciously provided a few alternatives for API documentation: He also has the raw XML file of the jQuery documentation in an SVN repository hosted at googlecode.com. Jörn Zaefferer also has a jQuery API Browser that lets you browse by category as well as alphabetically. Also, it can be downloaded as a zip file. Many thanks to Remy and Jörn for these great resources.]]> http://www.learningjquery.com/2008/07/jquery-documentation-alternatives/feed 16 Introduction to jQuery UI http://www.learningjquery.com/2008/07/introduction-to-jquery-ui http://www.learningjquery.com/2008/07/introduction-to-jquery-ui#comments Wed, 02 Jul 2008 17:35:38 +0000 Marc Grabanski http://www.learningjquery.com/2008/07/introduction-to-jquery-ui After many months of stellar work, the jQuery UI team has released version 1.5 of their flagship suite of user-interface widgets, components, and effects. This release was focused on bringing you a standardized development API across all of the components, allowing for a more seamless experience when working with the jQuery UI library.

A very exciting CSS theming application was also released with jQuery UI 1.5, called ThemeRoller. ThemeRoller is an amazing way to customize the style and colors across all of the jQuery UI components. It comes with a few preset styles, as well as allowing you to create your own. Once you are done, it packages your theme into a zip file that contains all of the images and CSS you need.

Brief Overview of the jQuery UI Project

The jQuery UI project was originally created to bring you a set of "official" jQuery plugins. Mature components from the plugins repository were pulled together to form the first release of jQuery UI. But since each of these plugins had its own style, having been written by different authors, the first release of the library felt a bit cumbersome when packaged together. With that in mind, the focus of UI 1.5 was on achieving a coherent, standardized API to eliminate much of the differences between the components. Through much time and effort, many bugs and feature requests were addressed along the way as well.

Inside Look at jQuery UI Version 1.5

Before starting, I want to make sure you know where the jQuery UI Documentation is located. You may also want to head to the download page to grab the library for yourself. Note that the development bundle is the easiest to get started with.

First, let's start by including the necessary files for jQuery UI: jQuery latest js file, the Flora theme complete stylesheet, and the core UI file. Each of the components is built on top of these files. Here is how to include them:

PLAIN TEXT
HTML:
  1. <link rel="stylesheet" href="themes/flora/flora.all.css" type="text/css" media="screen" title="Flora (Default)" />
  2. <script src="http://code.jquery.com/jquery-latest.js"></script>
  3. <script src="ui/ui.core.js"></script>

You may want to download these files and put them on your own server, but this is just fine for our demonstration.

At this point you may include the jquery.ui.all.js script for testing, or include each of the components individually. Here are the components that we are using for this demo:

PLAIN TEXT
HTML:
  1. <script src="ui/ui.draggable.js"></script>
  2. <script src="ui/ui.resizable.js"></script>
  3. <script src="ui/ui.accordion.js"></script>

Activating Components

Each component has a constructor method, which is the component name. For instance, we can make a div draggable by using the draggable() method:

PLAIN TEXT
JavaScript:
  1. $(document).ready(function() {
  2.   $("#dragme").draggable();
  3. });

The component defaults can be overridden by passing in options to the main function. For instance, if we want to make the div drag only horizontally, we can set the axis option to "x" with the following code:

PLAIN TEXT
JavaScript:
  1. $(document).ready(function() {
  2.   $("#dragme-x").draggable({ axis: "x" });
  3. });

Likewise, the Accordion can be accessed the same way. Here we set a custom option to specify the accordion to slide on the mouseover event:

PLAIN TEXT
JavaScript:
  1. $(document).ready(function() {
  2.   $("#accordionDemo").accordion({ event: "mouseover" });
  3.  
  4. });

  • Test 1
    Lorem ipsum dolor sit amet, consectetur adipisicing elit, sed do eiusmod tempor incididunt ut labore et dolore magna aliqua. Ut enim ad minim veniam, quis nostrud exercitation ullamco laboris nisi ut aliquip ex ea commodo consequat.
  • Test 2
    Lorem ipsum dolor sit amet, consectetur adipisicing elit, sed do eiusmod tempor incididunt ut labore et dolore magna aliqua. Ut enim ad minim veniam
  • Test 3
    Lorem ipsum dolor sit amet, consectetur adipisicing elit, sed do eiusmod tempor incididunt ut labore et dolore magna aliqua. Ut enim ad minim veniam, quis nostrud exercitation ullamco laboris nisi ut aliquip ex ea commodo consequat.

Some of the components, such as draggable and resizable, can even be combined:

PLAIN TEXT
JavaScript:
  1. $(document).ready(function() {
  2.   $("#dragme-resize").draggable().resizable();
  3. });

This first makes the div draggable, then adds the resize handles to the div.

Now you should have what you need to start with each of the components! Head to the functional demos page to see in-depth examples of each of the components.

Looking at the Future of jQuery UI

With Paul Bakaus hired as (paid) full-time lead of jQuery UI, the project has been energized, charging forward by leaps and bounds. With an ever-growing set of UI components, jQuery UI's future is shaping up to be one of great promise.

]]> http://www.learningjquery.com/2008/07/introduction-to-jquery-ui/feed 28 Tutorials Elsewhere http://www.learningjquery.com/2007/11/tutorials-elsewhere http://www.learningjquery.com/2007/11/tutorials-elsewhere#comments Fri, 02 Nov 2007 20:27:24 +0000 Karl Swedberg http://www.learningjquery.com/2007/11/tutorials-elsewhere
  • jQuery Crash Course. Nathan Smith shows he scripted an airplane seat picker script with jQuery. Beautifully designed with nice, clean code.
  • Understanding the "Chain". Dan G. Switzer discusses how he went from an incorrect assumption to a solid understanding.
  • What is JSONP?. Remy Sharp describes the JSONP method of script-tag injection and shows how it can be done with jQuery.
  • Creating A Sliding Image Puzzle Plug-In. Ben Nadel demonstrates how he built a really cool sliding-image puzzle.
Any others out there that you have found particularly useful? Let us know in the comments.]]> http://www.learningjquery.com/2007/11/tutorials-elsewhere/feed 20 Thanks for jQuery http://www.learningjquery.com/2007/10/thanks-for-jquery http://www.learningjquery.com/2007/10/thanks-for-jquery#comments Thu, 01 Nov 2007 03:35:27 +0000 Karl Swedberg http://www.learningjquery.com/2007/10/thanks-for-jquery ajaxian.com The schedule was packed with outstanding presentations. But the highlight of my trip was jQueryCamp07, which was held at Harvard University on Saturday. Throughout the week I had quite a few opportunities to talk with John Resig, the creator and lead developer of jQuery. But, like the social clod that I am, I forgot to do the one thing that I had set out to do: Thank John Resig, in person, for the jQuery JavaScript Library. It was only after I returned home on Sunday that I realized my oversight. So, at the risk of sounding sappy, I figure I ought to write in a public forum what I had meant to say face to face. Thanks, John, for creating an elegant, powerful tool that has saved me and thousands of others countless hours of frustration. jQuery has not only saved businesses enormous amounts of time and money by enabling web developers to write less code more quickly than we ever could have imagined, but it has also sparked a nascent industry of its own. Thanks for jQueryCamp07, too. I really appreciate all the work you put into organizing the conference, securing a location, ordering the food, having the t-shirts printed — doing just about everything. It was great to meet people from the jQuery discussion list for the first time and hear about all the cool things they're doing with the library. I think it's safe to say that with 80+ people in attendance the conference was a huge success — especially considering how little (or no) advertising went into it. Sorry if this post seems a little over the top, but the sentiments are genuine. It's remarkable that people like John are pouring themselves into these amazing tools, and then giving them away. Free. So others can profit. Still, I bet he wouldn't turn down a donation. ]]> http://www.learningjquery.com/2007/10/thanks-for-jquery/feed 5 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); Here is a fix:

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 123