A jQuery Primer for SharePoint: Events and Effects

In previous articles, I have covered how you find things in the DOM and manipulate them; now let’s think about reacting to user actions with events and effects.

• jQuery Core
• Selectors
• Attributes
• Traversing
• Manipulation
• CSS
• Events
• Effects
• Ajax
• Utilities
• jQuery UI

Events

As your users interact with pages in their browser, various events occur. The most familiar to you might be the click event or the hover event. However, the JavaScript event model provides you with a whole range of events into which you can hook your own script. This lets you set things up so that the page reacts to what the user is doing. You see this all the time on web pages, but may not give much thought to how it actually works. jQuery builds upon the JavaScript event model, providing a clean abstraction and making it far easier to react to events.

The JavaScript events that are available to you for any particular element in the DOM vary with the element’s type. You will want to learn what events are available for each type of element, because not all events are available for all elements. I frequently use the w3schools.com site to look up information about JavaScript events (and many other things), if you are looking for a good reference.

Let’s take a look at a simple example, as usual. Say that you would like to show the user an alert when they click the title of a web part (not terribly practical, but it shows the concept). The following code selects for the web part titles on the page—yes, all of them at once—and then binds to the click event for those H3 elements. When the user clicks any of the titles, they will see the alert.

$("h3.ms-WPTitle").click(function() {
 
alert("You'll now be taken directly to the list.");
 
});

The same script should work in SharePoint 2007 or 2010. In addition, if the title is a hyperlink to the default list view, they will still end up there after they close the alert.

That is a basic little example, but it should show you how you could start to think about what a user does in their browser and how you might want the page to react to those actions. We could choose to bind to different events for the same web part title, too. For instance, if we replace “click” with “mouseover,” then we will get the alert whenever we put the cursor over the text.

$("h3.ms-WPTitle").mouseover(function() {
 
alert("You just put your cursor on me.");
 
});

You can see all of the available events on the Events documentation page on the jQuery site.

Effects

With effects, you can make things happen, like you can by changing element attributes. jQuery’s effects may be what most people think of when they hear about jQuery. They include such nice stuff as fading in or out, sliding up or down, and animation. These effects are difficult to show you in a text article, so you’ll have to take my word for some things, but even better, you should try them yourself.

Showing an alert like I did previously is not likely to be a big goal; instead, you can execute any script you want in the function you have bound to the event. For instance, you might want to expand or collapse part of the visible page content based on the user’s click. This is where effects can come in.

Take a look at this example code:

$("h3.ms-WPTitle").find("nobr").unwrap("<a></a>");
 
$("h3.ms-WPTitle").click(function() {
 
$(this).closest("table").closest("tr").next().toggle();
 
});

Here I am first removing the hyperlinks on all of the web part titles using the .unwrap() function (just so that I stay on the page when I click them). Next, I am binding to the click event on those titles (as I did earlier). The new piece is that I am then traversing up and across the DOM to find the table row that contains the web part body, and then I’m using the .toggle() function to collapse or expand the contents. (I have tested this script in both WSS 3.0 and SharePoint 2010 with a few common List View web parts.)

The .toggle() function figures out whether the selected element is visible or not and switches the visibility. This nets out to each web part expanding or collapsing—based on its current state—when I click its title. This is a nice little trick to gain some screen real estate for the user. Of course, you would probably want to dress it up a little bit with some nice icons and such in a real situation.

This simple script should give you a glimmer what you can start to do with effects. This is the sort of enhancement I often talk about to make the page feel more “tactile” for the user. Rather than clicking a setting and waiting for a postback, we can make changes to the page in real time with jQuery; they end up interacting with the page rather than the server.

The following are other useful effect “families”:

.hide(), .show(), .toggle(): These three functions simply change the visibility.

.slideUp(), .slideDown(), and .slideToggle(): These functions slide elements up or down and work best with divs.

.fadeOut(), .fadeIn(), and .fadeToggle(): These functions fade elements in or out, basically animating their opacity from 0 to 100 percent, or the reverse.

.animate(): With animate, you can “move” CSS properties from one value to another over time. By combining changes to multiple CSS properties into a single animation, you can do things like moving elements around the page, increasing or decreasing them in size, or changing their color or shape.

Summary

By attaching your script to events and using effects, you can provide a high level of interactivity for your users. They are used to seeing these sorts of interactions on other commonly used websites, and by using them in SharePoint, you can improve the overall user experience. By carefully using selectors and traversing to locate the right elements in the DOM, you can react to user actions and alter the DOM in real time.

Next up will be the .ajax() function. The .ajax() function is at the core of my SPServices jQuery library. Using Ajax, you can request pieces of content from the server during the current page’s life span. Those pieces can be entire web pages, results from a web service call, or anything you can request over the HTTP protocol.