Intro to jQuery within Plone

jQuery is a JavaScript library that allows you to do many of the same things as regular JavaScript, but in an easier way that results in less code. It is not a separate language, so regular JavaScript (variable assignments, loops, etc) can still be used alongside jQuery code. The library contains dozens of functions that allow you to manipulate DOM elements, retrieve information, and show animation. It is extremely popular around the web, as it is used on over 60% of the top 100,000 websites.

This example shows how the code is easier and shorter.  The first line is JavaScript, the second jQuery, and both lines are hiding an element with the id element:

document.getElementById('element').style.display = "none";
$('#element').hide();

jQuery uses CSS-style selectors, which makes the language super easy for front end developers to pick up. This allows a lot of flexibility when narrowing down the specific element(s) you want to manipulate.

Tips

Generally the code written is for things that happen once the page has loaded (on document ready). To make sure your code doesn't run until the page is loaded, wrap it like this:

(function($) { $(function() {
    // code here
}); })(jQuery);

One tip to watch out for is that images don't count in determining whether the page is loaded yet.  So if you are doing any manipulation on images, make sure they are loaded first by wrapping the code in a window ready function (below). If you don't do this, the code may not apply each time the page is loaded, and you'll notice that checking for the height and width returns 0.

$(window).load(function(){
    // do something with images
});

Similarly, you cannot retrieve the height or width from elements set to display: none, but you can get this information if the element has visibility: hidden.

Use in Plone

jQuery has been included in Plone since Plone 3.1. More recently, the library was split out into a separate package (plone.app.jquery) in order to make updating jQuery itself easier. The jQuery community is very active in updating the code and pushing out new releases. Keep an eye out for functions being deprecated, which happened with .live() (one of my regulars) in 1.7.

Examples of Use

collective.easyslideshow, our slideshow product, uses a jQuery plugin called jquery.cycle. indianahistory.org displays easyslideshow in the upper right corner of the homepage. Just beneath that is a custom slider that was also created with jQuery.

Resources

1. The jQuery site contains great tutorials and documentation for each function: http://jquery.com
2. jsFiddle provides a handy testing resource for various JavaScript libraries, including jQuery: http://jsfiddle.net
3. For testing the quality of your code, there is JSLint: jslint.com.  JSLint is also available as an add-on for various code editors like TextMate and Sublime Text; mine is set to check for errors and warnings each time I save.