element inside the dragged item as the “handle” that a visitor must grab, you’d pass an object with those two options set like this: $('#controls').draggable({ cursor : 'pointer', handle : 'h2' }); Here are the most common options: • axis. You can limit the movement of a draggable element to just left and right or up and down using the axis property. For example, say you wanted to drag an item along a timeline. The dragged item needed to stay positioned along that line, so you wouldn’t want someone to drag the element to the bottom of the page off the line. Use either 'x' (to constrain the dragged item to just left and right movement) or 'y' (to make sure the dragged item can only be moved up and down the page): axis : 'x' • cancel. This option lets you prevent dragging when a specific element is clicked on. For example, say you created an announcement box that visitors could drag around the screen. The announcement has a headline, but also several paragraphs of text that includes important information like a street address and phone number. Normally, if a visitor tried to select the street address (to copy and paste into Google Maps, for instance), she’d end up dragging the announcement around the window instead. You could turn off the dragging action of those paragraphs, by setting the cancel option: cancel : 'p' Now, if someone clicked on a paragraph inside the announcement, she wouldn’t trigger the dragging action and could freely select and copy text. The handle option discussed on page 405, can also let visitors select content within a draggable item. • connectToSortable. Lets you specify a collection of sortable items that the dragged item can be added to. jQuery UI offers a sortable interaction which lets you group a collection of items that can be sorted, such as a To-do list (you’ll learn about sortable items on page 426). To use this option, just specify an ID for an element you’ve already turned into a sortable group (as described on page 426): connectToSortable : 402 '#toDoList' JAVASCRIPT & JQUERY: THE MISSING MANUAL • containment. You can prevent a visitor from dragging an element outside a container element. For example, say you create a “Refrigerator magnet” activity where a visitor can drag words around to form a sentence. You can add a bunch of small, draggable divs with words in them and include an area of the page where the visitor can construct the sentence. You want to make sure that he doesn’t drag words all over the place, like into the navigation bar, headline, or footer. The containment options let you limit the interaction to a smaller area of the page. It accepts several possible values: THE DRAGGABLE WIDGET • A selector. If you provide a selector name, then jQuery UI will keep the draggable item confined to the boundaries of that element. For example, if you had a

on the page with an ID of refrigerator, you could keep the draggable element inside that div by setting the containment option like this: containment : '#refrigerator' • parent, document, or window. To keep the draggable item contained inside its parent element, use parent as the value. For example, if the draggable item is a

inside another

and you want to limit the dragging to within that outer div, use parent like this: containment : 'parent' The document and window values are nearly the same, except document keeps the entire draggable area contained within the document area and window lets you drag the element partly outside the window. • An array of coordinates. Lastly, you can supply an array of coordinates that represent the top-left and bottom-right points of a containing box. You provide pixel values that are in relation to the top-left of the browser window. For example, say you wanted to limit dragging to an area that starts 50 pixels from the left and 100 pixels from the top and ends 500 pixels from the left and 600 pixels from the top. You’d assign those values like this: containment : [50, 100, 500, 600] Because using coordinates like this requires precise values, it’s not very good for a fluid design. You’re better off using a containing element and specifying a selector. • cursor. When an element is dragged, you can change the appearance of the cursor. Normally, the cursor will look like either an arrow (if you click on an empty space in an element) or a text selection bar (if you click on text in a headline, for example). However, you can tell jQuery UI to use a different cursor as the visitor drags an element by setting the cursor option with a valid CSS cursor value. You can find a list of values at https://developer.mozilla.org/en-US/docs/ Web/CSS/cursor, but common cursors used when dragging include pointer, crosshair, and default (which is an arrow): cursor : 'pointer' Chapter 12: jQuery UI Interactions and Effects 403 THE DRAGGABLE WIDGET • cursorAt. You can control where the cursor appears as the visitor drags the element. Usually the cursor remains wherever the visitor first grabs the element. For example, if you grab a draggable div at the bottom, the cursor will remain at the bottom of the div as you drag it around the screen. However, maybe you want the cursor to appear in a specific spot—maybe a visual handle that you’ve added to the draggable element. To do so, provide an object for the cursorAt option. The object can contain values using left, right, top, and bottom properties. For example, to position the cursor at the top-left of an element as the visitor drags it, set the left and top properties like this: cursorAt : { left : 5, top : 5 } You can’t set both left and right because they’re different locations on the same axis; and you can’t set both top and bottom for the same reason. However, you can use one value from each axis (left or right and top or bottom). Likewise, you can set just one value if you prefer. For example, if you only care that the cursor appears inside a bar at the top of a draggable element, you can set just the top value. The horizontal value will be set to the horizontal position from which the visitor grabbed the element in the first place: cursorAt : { top : 5 } • disabled. Determines whether the item is draggable. If this property is set to true, then you can’t drag the item. You’re probably thinking that if you wanted to not make an element draggable, you’d just avoid the draggable() function. True, you probably wouldn’t use the disabled option when you first apply the draggable widget to an element. However, it can come in handy after someone has dragged the item. For example, you might want to let a visitor drag an item into a shopping cart, but not let them drag it out. In this case, you can apply this option after the dragging operation is complete (you’ll see an example of this on page 418). • grid. Normally, when you drag an element it moves freely across the window. However, you might want to force an element to move a specific number of spaces horizontally and vertically when dragged. For example, imagine an online checkers game. You have a grid of 8 squares by 8 squares. The checker pieces can be dragged around the border, but it would look sloppy if you could just drag those pieces anywhere. You want the pieces to move the same distance as a square on the board. jQuery UI lets you force an element to move in specific horizontal and vertical increments. The grid option takes an array of two numbers. The first number is the horizontal increment, and the second is the vertical increment. For example, say you wanted an element to move in increments of 50 pixels when dragged 404 JAVASCRIPT & JQUERY: THE MISSING MANUAL left or right. You also wanted the element to move in 100 pixel increments when dragged up or down. You can set the grid option to do that like this: THE DRAGGABLE WIDGET grid : [50, 100] • handle. You can limit the area that a visitor clicks to drag an element. Normally, you can click anywhere inside a draggable element to drag it. However, you might want to limit that to just one area such as a headline or a visual drag bar in the element. Use the handle option to identify a selector within the draggable item that will act as the handle for dragging. For example, you can make it so you can only drag an element by clicking its headline—an

element, for instance—like this: handle : 'h2' • helper. You may not want the user to move the actual draggable element on the page. For example, say you create a shopping cart page. Pictures of products appear on the page and visitors can add items to the cart by dragging a picture of a product onto a shopping cart icon. In this case, you don’t want the shopper to actually move the product photo into the cart—that would move the picture on the page. You’d rather have the shopper just drag a copy of the picture while leaving the original photo unmoved. You can do this by setting the helper option to 'clone' like this: helper : 'clone' A more complex option is to pass the helper option a function that generates the HTML that jQuery UI should display as the user drags her mouse. For example, to display a generic helper div (instead of dragging the actual HTML element), you could set the helper like this: helper: function( event ) { return $( "

I'm a custom helper

" ); } Whatever you provide for the return statement is what jQuery UI will display under the user’s mouse cursor. Note that you must return a jQuery object, so use the $() function to create the helper. A plain string of HTML won’t work. • opacity. When an element is dragged, you can make its opacity change. For example, you can fade the element to 50% opacity to give it a ghost-like appearance. This technique is a popular way to indicate that you’re moving an item from one place to another. Use a value between 0 (completely invisible) to 1 (completely opaque). This works just like the CSS opacity property. For example, to make the dragged element appear 50% transparent, set the opacity value to 0.5: opacity : 0.5 • revert. This option dictates whether the dragged item returns to its original position after the user stops dragging it. Normally, this is set to false, which Chapter 12: jQuery UI Interactions and Effects 405 THE DRAGGABLE WIDGET means that when you drag the element and let go, it stays where you left it. For draggable windows or dialog boxes, that’s generally a good approach: you drag the window out of the way of something else on the page. However, there are times when you want to make the dragged element return to its starting position. For example, if you’re using the droppable widget (page 412), you might want a dragged item that’s not dropped in a specific spot to return to where it came from. For example, say you created an app for organizing images. You can drag thumbnails of the images into different folders on the page, or into a trashcan icon. However, a user might drag an image up into a headline on the page, or down into the footer, and not into one of the intended folders or the trashcan. In that case, you’d want the image to move back to where it was on the page and not sit there obscuring the headline or footer. The revert option accepts several different values: true makes the dragged item always return back to its starting point (great for your next prank website); 'invalid' makes the dragged item return only if it’s not dropped on a valid droppable item (page 412). In the case of the photo-organizing app mentioned above, you’d use the invalid option like this: revert : 'invalid' Lastly, you can pass a function to this option. If the function returns true, then the element reverts back to its original position. You could use a function in a JavaScript checkers game, for example: if a player moves his piece and drops it on another square on the board, a function could check if the move was invalid (if that square is already occupied by another piece, or if the piece moved farther than allowed, for instance). In that case, the function would return the value true, and jQuery UI would move the piece back to its original position. revert : function() { // do some kind of test in this function and return either // true to make the element revert to its original position // or false if the element can stay where the user dropped it } • revertDuration. When jQuery UI reverts a dropped element (moves it backs to its original position), it animates this movement. The default value is 500 milliseconds or half a second. It looks really cool, but you can make the animation happen faster (a number less than 500) or slower (a number greater than 500). To do that, set the revertDuration option, which accepts a number indicating the number of milliseconds the animation should take. For example, for a quarter of a second animation (250 milliseconds) you’d set the revertDuration option like this: revertDuration : 250 • scope. The scope option lets you group sets of draggable and droppable items. For example, say your page has a calendar. Users can drag an event from one 406 JAVASCRIPT & JQUERY: THE MISSING MANUAL day on the calendar to another. All the draggable events in the calendar belong to the calendar, so you can set the draggable item’s scope to calendar like this: scope : THE DRAGGABLE WIDGET 'calendar' The string 'calendar' here doesn’t refer to a selector or element on the page. It’s just a name used to group draggable and droppable items together. You could use any term you want; just make sure you use the same name for the scope option on the droppable item (page 412). You need to set the scope option only if there’s a chance that a page has different types of draggable and droppable items. For example, if you have a jigsaw puzzle on the same page as the calendar, you wouldn’t want people dragging events from the calendar onto the puzzle and puzzle pieces onto the calendar. By specifying different scopes for each group, you can control which draggable items can be dropped on what other elements (see page 412 for more on the droppable widget). NOTE You can try out these options on the tutorial file—draggable.html—you programmed on page 401. If you didn’t complete that tutorial, open the complete_draggable.html file and add some of these options to the draggable() function in that file. • snap. You can make a draggable item snap to another page element or another draggable item. For example, say you create a jigsaw puzzle game. A dozen square fragments of a photo need to be re-assembled to create the original photo. You can make one puzzle piece snap to another piece by setting this option. Use one of two possible values for this option: • true tells jQuery UI to make the dragged item snap to any other draggable item on the page. This is good in the case of a jigsaw puzzle because you’ll have lots of individual tiles. • A selector name. The name of any selector on the page. For example, if you want the dragged item to snap to a div with the ID of photoholder, you could do this: snap : '#photoholder' How the item snaps to another element is controlled by the snapMode and snapTolerance options, discussed next. • snapMode. This option only works if you’ve also set the snap option. This option takes one of three keywords: inner, outer, or both. If you want the dragged element to snap only when its inside the element, use inner, which makes the dragged element snap to any of the inner edges of the element specified by the snap option. Use outer when you want the element to snap to the outside edge of an item. This option is ideal for things like the jigsaw puzzle because you want the pieces to snap next to each other. Chapter 12: jQuery UI Interactions and Effects 407 THE DRAGGABLE WIDGET Finally, you can make the dragged item snap to either the outer or inner edges using the both option: snapMode : 'both' • snapTolerance determines how close the dragged item should be before it snaps to an element. The larger the number, the farther away the dragged item can be before it tries to snap to an element. Specify a pixel value for this option: snapTolerance : 30 • zIndex. This option lets you set a z-index for the dragged element. The CSS z-index property determines the stacking order of elements on the page. An element with a higher z-index will appear on top of any page elements it overlaps. This property comes in handy when you want to make sure that, as the visitor drags an item around the page, that item appears on top of surrounding content. (You’ll see an example of this option in the tutorial on page 423.) zIndex : 100 NOTE You’ll find even more options for the draggable widget at http://api.jqueryui.com/draggable/. See Figure 12-2. Draggable Widget Events The droppable widget supports several different events, each of which is triggered at a different moment of the dragging process. You add a function to an event to make your program do something in response to the item being dragged. Say you’ve created a game that requires a player to quickly drag an item to a target. The faster he can drag the item, the higher the score. You could check the time when the player first starts to drag the item, then check the time when the player stops. Three events deal with the various points in the dragging process. THE CREATE EVENT This event fires whenever you use the draggable() function to create a new draggable item. You could use this event to pop up a dialog box with the instructions “Drag this product to your shopping cart.” It only runs once, when the draggable widget is created. You use this event by passing a create property with a function to the draggable method like this: $('.product').draggable({ create : function (event){ // programming here } }); 408 JAVASCRIPT & JQUERY: THE MISSING MANUAL THE DRAGGABLE WIDGET FIGURE 12-2 jQuery UI’s documentation is extensive. The page dedicated to the draggable widget lists multiple options, methods, and events that you can tap into to customize how this widget works. THE START EVENT This event triggers as soon as a user begins dragging an element. You assign this event as a property of the draggable widget’s options object. The name of the event—start—is the property name, and the value should be a function that runs when the visitor starts dragging the item. For example, say you have a

tag with an ID of raceCar. You turn that div into a draggable item, and assign it a start event like this: $('#raceCar).draggable({ start : function (event, ui) { // programming goes here } }); Chapter 12: jQuery UI Interactions and Effects 409 THE DRAGGABLE WIDGET The function assigned to the start event has two parameters—event and ui. The event parameter is a jQuery event object and provides details about which element is receiving the event, the screen coordinates of the mouse, and other information. (You can read about the event object and how to use it on page 164.) The ui parameter is an object with three properties: • The ui.helper property is a jQuery object containing a reference to the item that’s visibly dragged across the screen. This is usually the same as the element to which you applied the draggable() method. However, that’s not always the case. If you set the draggable widget’s helper option to 'clone' or passed it a function to generate the helper HTML (page 405), ui.helper refers to an element other than the original draggable element: either a copy of that element or a jQuery object created as a helper (as described on page 405). This arrangement is helpful in a shopping cart, for example, when dragging a product from one place on the page to the shopping cart will disturb the page’s layout. Instead, the shopper should drag a copy of the product into the cart. Use the ui.helper property whenever you want to perform an action on the item that’s visibly dragged across the page. For example, say you wanted to make an item double in size when the user starts to drag it. You could set a CSS property on the ui.helper object like this: $('#photo').draggable({ start : function (event, ui) { ui.helper.css('transform', 'scale(2)'); } }); This uses jQuery’s css() method (page 134) and sets the CSS transform property to scale the element by 2 (doubling it size). You could also use jQuery’s addClass() method to add a class to the item as the user starts dragging it—a style that highlights the item, for example. Then remove the class using removeClass() when the visitor stops dragging the item (see the stop event on page 411). NOTE To learn more about CSS transforms, visit https://developer.mozilla.org/en-US/docs/Web/Guide/CSS/ Using_CSS_transforms. • ui.position provides the x and y position of the top-left corner of the helper item (the item that is visibly dragged across the screen). This is the element’s CSS position value, and it can be affected by the position of its parent element (or any other positioned ancestor). For example, if you have a draggable item inside a

, and that

is absolutely positioned on the page, the draggable element’s left and top position values will be in relation to the left and top corner of the positioned ancestor. The ui.position property is a JavaScript object composed of two properties top and left. The top property is the element’s top position as measured in 410 JAVASCRIPT & JQUERY: THE MISSING MANUAL a number of pixels from the top of its nearest positioned ancestor (that is, a tag with either absolute or relative positioning that wraps around the dragged element). The left property is the helper’s position relative to the left edge of the nearest positioned ancestor. Accessing this property can be useful for determining where the helper is when the visitor stops dragging (or while he’s dragging the element) (see the drag and stop events next). THE DRAGGABLE WIDGET You can access those values like this: ui.position.top and ui.position.left. • ui.offset also provides an object with two properties top and left. The position is calculated relative to the top left of the browser window. ui.position and ui.offset will be the same if the dragged element is not inside any other elements that have CSS position property of absolute or relative. The ui.offset.top property identifies how far the top of the helper element is from the top of the window. The ui.offset.left property identifies how many pixels the draggable item is placed from the left side of the browser window. • ui.originalPosition contains the same two properties—top and left—as ui.position and ui.offset. However, ui.originalPosition indicates the draggable element’s starting position—the spot the element was in just before the user started dragging it. Like the ui.position property, ui.originalPosition is based on any positioned ancestors. THE DRAG EVENT Draggable items also fire off a drag event as they are dragged around the screen. You can create a function that runs repeatedly while the object is being dragged. You could use this event to leave a trail of sparkles as the dragged object is moved across the window, for example. Because this event fires off numerous times while dragging an element, try to limit the amount of work the function does. If you perform lots of complicated operations in response to the drag event, the browser may slow to a crawl. The drag event function accepts the same two parameters as the start event described on page 409—event and ui. Say you wanted to display the current position of a dragged item as it’s dragged across the screen. Assume the page has a couple of tags with the ID of left and top to display these values. You could continuously update the values as the element is being dragged like this: $('#raceCar').draggable({ drag : function (event, ui) { $('#left').text(ui.position.left); $('#top').text(ui.position.top); } }); THE STOP EVENT The Draggable widget’s stop event works just like the start event, except it’s triggered when the user stops dragging the item and releases the mouse button. This Chapter 12: jQuery UI Interactions and Effects 411 THE DROPPABLE WIDGET doesn’t necessarily mean that the user dropped the item on a droppable target (like the ones discussed in the next section). It doesn’t even mean that the user has completely finished dragging the element. For example, a user could click a draggable element and begin moving it (the start event fires); keep moving it around the page (the drag event fires continuously); then stop dragging (the stop event fires); then click and drag the same element again repeating all of the same events. You use the stop event following the same structure as the start event. For example, say you used the code above to make the draggable element scale up to twice its size while being dragged. You could return the element to normal size when the user stops dragging it using this code: $('#photo').draggable({ stop : function (event, ui) { ui.helper.css('transform', 'scale(1)'); } }); The Droppable Widget The Draggable widget, by itself, is useful for dialog boxes or other page elements that you’d move around the screen (like tool palettes, for example). However, when you add the droppable widget to the mix, you can build highly interactive applications, where dragging one item onto another item can make something else happen. For example, a photo sharing application might let a user drag a thumbnail image to a trashcan to delete that photo from the site. A language-learning website could test students by having them drag a word onto a corresponding picture to show their mastery of vocabulary. Using the Droppable Widget Droppable widgets aren’t useful without draggable widgets. A droppable widget acts like a “drop zone” for draggable items. When an item is dropped on it, a droppable widget can also trigger additional programming. You can turn anything on a page into a droppable element. Of course, it should make sense that a visitor would drag something on to it: for example, icons of shopping carts and trashcans are visual metaphors that clearly indicate that items can be dropped into them. But you can also turn divs into droppable widgets as long as you clearly indicate to the visitor what they can drag and where they can drag it to. Using the droppable widget is very easy: 1. Follow the steps on page 304 to attach the CSS and JavaScript files. Remember that jQuery UI has its own CSS and JavaScript files, and that the jQuery UI JavaScript file should be linked to after the jQuery JavaScript file. 412 JAVASCRIPT & JQUERY: THE MISSING MANUAL 2. Add jQuery’s $(document).ready() function to your page or to another external JavaScript file: THE DROPPABLE WIDGET $(document).ready(function() { }); // end ready As discussed on page 160, this step is only necessary if you’re putting your JavaScript code in the page’s , before the majority of your HTML. Some programmers put their JavaScript code at the bottom of the page, before the closing tag; in that case, you can skip the $(document).ready() function. Droppable widgets don’t make sense without something you can drag into them, so always add at least one draggable item to the page. 3. Use jQuery to select one or more page elements and apply the Draggable widget to it: $(document).ready(function() { $('.product').draggable(); }); // end ready In this example, you have a catalog page with a bunch of products on it. Each product photo has the class product applied to it, so this code will make each of those photos draggable. 4. Use jQuery to select a drop zone and make it droppable: $(document).ready(function() { $('.product').draggable(); $('#cart').droppable(); }); // end ready The item on the page with an ID of cart is now a drop zone. But this is just the start. You have to set various options of the droppable element in order to make something happen: such as calculate a sales total each time a product is added to the cart. You do this by passing an object containing options and functions to the droppable() function. 5. Add options to the droppable() function: $(document).ready(function() { $('.product').draggable(); $('#cart').droppable({ activeClass : 'highlight', drop : function (event,ui) { alert('Product added'); } }); }); // end ready Chapter 12: jQuery UI Interactions and Effects 413 THE DROPPABLE WIDGET You’ll learn about the various options for this widget next, but as a sneak preview, you’ll take a look at what the code above does. First, the activeClass option tells jQuery UI to add a class named highlight to the drop zone element, which you use to apply a CSS rule to the droppable element. The CSS can visually identify the drop zone by adding a bold background color to the drop zone, or outlining it with a bright red border. The second option, drop, is an event handler. It lets you run a function when an item is dropped onto the drop zone. In this case, an alert box pops open with a message. Droppable Widget Options The droppable widget doesn’t provide as many options as the draggable widget (the droppable widget’s main role is to receive items, and, most importantly, run functions when that happens): • accept. Dictates which draggable items can be added to the droppable widget. You can assign either a selector or a function. The selector indicates the selector for the draggable item. For example, if you had a bunch of images all with the class photo on them, and wanted to be able to drop them on a droppable item, you’d set the option like this: accept : '.photo' • activeClass. You can highlight a droppable element when any acceptable draggable element is being dragged. For example, say you created a filesystem app that let users view files on the server, move them to different folders, rename the files, and so on. You could also drag a file to the trash to delete it. The trashcan would be a droppable widget, and a file a draggable widget. When a visitor started to drag a file, you could apply a class that highlights the trashcan in some way (for example, changes the background image to display a trashcan with an open lid, ready for the file). Just assign a class name (without a period) to this property, and jQuery UI will add the class to the droppable item, when an acceptable draggable item is dragged: activeClass : 'highlight' • disabled. Determines whether the item is an active drop zone. If this property is set to true, then you can’t drop anything on the element. You can use this property after creating the drop zone as a way to turn off the ability. For example, say you had a drop zone but you only wanted users to be able to drop 5 items into it. Once the five items were in place, you would then turn off the drop zone, so users could no longer drop anything into it (you can use the drop event described on page 416 to trigger a function that disables the drop zone): $('#dropZone').droppable({ disabled : true }); 414 JAVASCRIPT & JQUERY: THE MISSING MANUAL You’re probably thinking that if you wanted to turn an element into a drop zone, then just avoid the droppable() function altogether. True, you probably wouldn’t use the disabled option when you first apply the droppable widget to an element. THE DROPPABLE WIDGET However, it can come in handy after someone has dropped an item into the droppable widget. For example, you might want to let a visitor add only five items to a shopping cart. Once the shopper drops in the fifth item, you can disable the drop zone so he can no longer add items to the cart. • hoverClass. You can also apply a class when an acceptable draggable item is dragged over a droppable item (Figure 12-3). For example, you could add a class to the trashcan element mentioned earlier only when the file is dragged on top of the trashcan: hoverClass : 'openTrashcan' FIGURE 12-3 Using a Droppable widget’s hoverClass option, you can apply a class to a droppable element when another element is dragged over it. Here, the large box lights up in bright yellow when the smaller box is dragged over it (the color change is provided by a CSS class style). The style adds both a background color and background image, but you could create a class style that added a bold outline to the drop zone, or even added a CSS animation to make the drop zone’s color pulsate between white and another color. • scope. Works like the draggable property of the same name (page 406). Lets you group related draggable and droppable widgets. scope : 'calendar' The name you use—'calendar' in this example—doesn’t matter. Use any name that makes sense—just make sure to use the same scope name for the related Draggable widgets and Droppable widgets. Chapter 12: jQuery UI Interactions and Effects 415 THE DROPPABLE WIDGET • tolerance. This option determines when a draggable item is considered to be hovering over a droppable item. There are four possible values for this option: • 'fit'—the draggable item must fit entirely within the droppable item. • 'intersect'—the draggable item must overlap the droppable item by at least 50% in both directions. In other words, the draggable item needs to be mostly inside the droppable item, but not entirely. This is the normal setting for droppables. • 'pointer'—only the mouse cursor needs to be inside the droppable item. • 'touch'—the draggable needs only to touch the droppable item on one side. The 'fit' option is good for confirming that the user really wants to place the draggable item onto the droppable item, but requires that the draggable item be smaller than the droppable item. The most common choice is 'intersect' because it doesn’t require extreme precision on a user’s part: tolerance : 'intersect' NOTE For a complete list of droppable widget options, methods, and events, visit http://api.jqueryui.com/ droppable/. Droppable Widget Events The real fun with droppable widgets comes when you make something happen when an item is dropped onto it…or dragged over it…or dragged off it. For example, you could calculate and display a sales total each time a shopper drops a product into a shopping cart, then recalculate that total if the shopper drags the product out of the cart. The droppable widget supports several different events, each of which is triggered by a different interaction with the droppable widget. You add a function to an event to make your program do something in response to dragging an item, moving an item over or out of the drop zone, or dropping an item onto the drop zone. For example, say you created a to-do list application: when a visitor drags an item from the list and drops it onto a trashcan icon, the item is removed from the to-do list and from the page. The event in this example is the drop event. Next, we’ll look at each event, starting with the most commonly used one. THE DROP EVENT This event triggers a function when an item is dropped onto the droppable item. The dropped item must be an acceptable item—that is, one that’s specified by the accept option (page 414) or within the same scope (page 406) as the droppable widget. The event is assigned as a property sent to the droppable widget as part of the options object. For example, say you have a

tag with an ID of trashcan. You turn that div into a droppable item, and assign it a drop event like this: 416 JAVASCRIPT & JQUERY: THE MISSING MANUAL $('#trashcan').droppable({ drop : function (event, ui) { // programming goes here } }); THE DROPPABLE WIDGET The function assigned to the drop event has two parameters—event and ui. The event parameter is a jQuery event object (page 164) that provides details such as which element is receiving the event, the screen coordinates of the mouse, and other information. The ui parameter is like the parameter used in draggable widget events (page 408). • The ui.helper property is a jQuery object containing a reference to the item that’s visibly dragged across the screen and is the same as the ui.helper property described for draggable items on page 410. Use the ui.helper property whenever you want to perform an action to the item that’s visibly dragged across the page. For example, if you wanted to make an element “explode” when it was dropped onto a trashcan, you could use this code: $('#trashcan').droppable({ drop : function (event, ui) { ui.helper.hide('explode'); } }); The 'explode' value here is actually a cool jQuery UI effect, that you’ll learn about on page 440. • The ui.draggable property is a jQuery object containing a reference to the element the draggable() method is run on. In many cases, this is the same as ui.helper. However, if you’ve set the draggable item’s helper property (page 405) to 'clone', the cloned item is dragged across the screen, while the original item is left in place. This property could also come in handy in the case of a shopping cart page. Say you’ve built a shopping cart system that tracks inventory as well as products. A catalog page might show a photo of a product plus a label indicating how many of those products are in stock—10, for example. When a shopper clicked on the product, she’d drag a clone of that product to the cart. When she dropped the clone on the cart, the drop function could update the ui.draggable item to lower the stock number by one (and at the same time, use Ajax—Chapter 13—to send the shopping data to the server). • ui.position provides the x and y positions of the top-left corner of the helper item when it’s dropped onto the target. It’s the same as the ui.position property described for draggable items on page 410. Chapter 12: jQuery UI Interactions and Effects 417 THE DROPPABLE WIDGET • ui.offset provides the top and left position of the draggable item in relation to the browser window. It’s the same as the draggable item’s ui.offset property described on page 411. • ui.originalPosition provides the top and left position of the draggable item just before a user starts dragging it. It’s the same as the draggable item’s ui.originalPosition property described on page 411. When using drop zone, you’ll probably end up using the drop event frequently. One task you might wish to perform is to prevent an item from being dragged out of the drop zone. Going back to the checkers example, you could make it so once a player moves a piece, she can’t take the move back. In other words, you want to “lock” the piece in place when it’s dropped onto a square. You could do that by disabling the dragged item, when it’s dropped on the drop zone: $('.square').drop({ drop : function (event, ui) { ui.helper.draggable({ disabled : true }); } }); You’re using the ui parameter’s helper object (the thing that was dragged onto the drop zone) and then calling the draggable() method to turn off dragging by setting that item’s disabled property to true. Keep in mind this is the disabled property of the draggable item (page 404) not of the drop zone. You'll need to set the disable property of the draggable item back to false to make the element draggable again (see page 404). THE ACTIVATE EVENT When a user starts dragging an element that’s acceptable to the drop target (see the droppable widget’s accept and scope options above), an activate event is triggered. You can add programming to respond to this event. Say, for example, you’re creating a web application that lets a user drag one or more photos into a div and then click a Send button to email those photos to a friend. You could add a label like “Drop photo here” to the drop zone, but only when the user starts dragging a photo. You could add a function to the activate event to write “Drop photo here” to the drop zone. Assuming the droppable item is a div with an ID of photoZone, here’s how you could add a message to the drop zone when the user started dragging a photo: $('#photoZone').droppable({ activate : function (event, ui) { $(this).append('

Drop photo here

'); } }); 418 JAVASCRIPT & JQUERY: THE MISSING MANUAL The $(this) refers to the drop zone element (see page 139 if you need a refresher on what $(this) is and how it works). The append() method just adds HTML inside a tag as the last child of the element (page 127). THE DROPPABLE WIDGET The activate function accepts the same two parameters—event and ui—as the drop event (page 416). THE DEACTIVATE EVENT The deactivate event is the flip side of the activate event. It triggers a function when a user stops dragging an acceptable item—meaning the user has released the mouse button. You could use this to undo an action performed by the activate event. For example, to add a message to the drop zone while the user drags an item and then remove that message when he stops dragging the item, you could use this: $('#photoZone').droppable({ activate : function (event, ui) { $(this).append('

Drop photo here

'); }, deactivate : function (event, ui) { $('#dropMessage').remove(); } }); THE OVER EVENT You can even run a function when a visitor drags an item over a droppable element. The over event is triggered as soon as a draggable item is over the drop zone, but before it’s dropped. You could use this event, for example, to add an encouraging message as a hesitant shopper pauses before dropping a product into a shopping cart: “You know you’ll look fabulous in those shoes. Just buy them!” Or, say you’ve created a trashcan drop zone for users to delete photos from their page. The trashcan is normally closed, but when the droppable item is over the can, the can’s lid comes off; when the item is dropped in the can, you could then use the drop event to replace the empty can with an image of a can full of trash. You program the over event just like any other Droppable widget event—just assign a function to the over property: $('#trashcan').droppable({ over : function (event, ui) { $('#trashCanImage').attr('src','images/open-lid-can.png'); } }); In this example, you’re just swapping out an image for another file, but you could make a much more elaborate function for this (or any) event. NOTE The tolerance property (page 416) determines when jQuery UI thinks a draggable item is over, dropped on, or out of the droppable zone. Chapter 12: jQuery UI Interactions and Effects 419 DRAGAND-DROP TUTORIAL THE OUT EVENT Finally, you can trigger a function when a visitor drags an item out of a drop zone. For example, say a shopper dragged a product into a shopping cart and you calculate the sales total when the product was dropped into the cart. Then, when the shopper decides he’s no longer interested in the product, he drags it out of the cart. The out event gives you a chance to deduct the cost of the removed product from the sales total: $('#shoppingCart').droppable({ drop : function (event, ui) { // perform math to update sales total }, out : function (event, ui) { // perform math to remove product cost from sales total } }); These few examples demonstrate that you’ll often use events in pairs to trigger opposite actions. For example, the out event with the drop event, and the deactivate event with the activate event. Drag-and-Drop Tutorial This example combines the draggable and droppable widgets into one program. You’ll build a simple drag-and-drop application that demonstrates the basic components of each widget. The final project will let you drag a photo to a trashcan, removing the photo in a dramatic fashion, as shown in Figure 12-4. NOTE See the note on page 12 for information on how to download the tutorial files. 1. In a text editor, open the file to-the-trash.html in the chapter12 folder. This file already contains a link to the proper CSS and JavaScript files as well as the $(document).ready() function (page 160). If you preview this page, you’ll see that there’s an image of a trashcan on the left and a row of photos on the right (Figure 12-4). The HTML for the trashcan and photos looks like this:

420 JAVASCRIPT & JQUERY: THE MISSING MANUAL The trashcan image has an ID of trashcan, and the photos are all inside a div with an ID of photos. You’ll start by making the photos draggable. DRAGAND-DROP TUTORIAL 2. In the empty line inside the $(document).ready() function, add the bolded line below: $(document).ready(function() { $('#photos img').draggable(); }); // end ready This selects all the img elements inside the photos div and turns them into draggable items. Because the goal of this project is to add an image to the trashcan, you want to make sure that if the visitor drops the photo anywhere but in the trashcan, the photo snaps back to its original location. FIGURE 12-4 Adding drag-and-drop elements to a page can create a fun, immersive and interactive experience for your site’s visitors. In this tutorial, you’ll learn how to create draggable items and make them disappear when dropped onto the proper target. 3. Add an object literal to the draggable() function, with the revert property set to 'invalid': $('#photos img').draggable({ revert : 'invalid' }); The revert option (page 405) can return a dragged item to its original starting place. By setting this option to 'invalid', you’re basically saying “Return this item to its original spot (revert), if its dropped in an 'invalid' spot.” What’s Chapter 12: jQuery UI Interactions and Effects 421 DRAGAND-DROP TUTORIAL invalid? Any element that isn’t specified as a droppable widget. Because you haven’t added a Droppable widget yet, the photos will always snap back to their original spot when dropped. 4. Save the page and preview it in a browser. Drag a photo around the page and drop it. The photo should snap back to where it started. If it doesn’t, double check your code and look in the JavaScript console for any errors (page 18). Next, you’ll use draggable events to make something happen when you start dragging a photo on the page. Specifically, you’ll apply a CSS transformation to the dragged photo. 5. Type a comma after invalid in the code you just added, hit Return and add a start event handler like this: $('#photos img').draggable({ revert : 'invalid', start : function (event, ui) { } }); The start option requires a function as its value. The function is an event handler just like the ones you used for jQuery’s click() and mouseover() functions (page 152). “Start” isn’t a real browser event, though. It’s a custom event programmed by the jQuery UI team, and it fires the moment someone starts to drag an item. The function here is empty, so you’ll need to add some programming to it next. In this case, you’ll just apply some simple CSS using jQuery’s css() function (page 134.) 6. Inside the function you just added, type the following code (in bold): $('#photos img').draggable({ revert : 'invalid', start : function (event, ui) { ui.helper.css('transform', 'rotate(5deg) scale(1.5)'); } }); As you read on page 409, the function assigned to draggable events accepts two parameters: an event object, and an object representing the draggable item— that’s the ui parameter. You can use the ui parameter to select the dragged item and do something to it. The ui.helper (page 410) is the actual element the user drags across the screen, and because it’s a jQuery object, you can apply any of jQuery’s many functions to it. In this case, the css() function applies the CSS transform property to the element, rotating it slightly and enlarging it 1.5 times. In other words, the image will rotate and grow bigger when it’s dragged. 422 JAVASCRIPT & JQUERY: THE MISSING MANUAL Next, you’ll make the photo return the photo back to normal when the visitor stops dragging it. NOTE DRAGAND-DROP TUTORIAL To learn more about the CSS transform property, visit www.sitepoint.com/css3-transformations-2d- functions/. 7. Add the stop event option to the option’s object: $('#photos img').draggable({ revert : 'invalid', start : function (event, ui) { ui.helper.css('transform', 'rotate(5deg) scale(1.5)'); }, stop : function (event, ui) { ui.helper.css('transform', 'rotate(0deg) scale(1)'); } }); Don’t forget the comma after the start function. This function simply undoes the CSS that was applied at the start of the drag, returning the photo to its regular size and removing the rotation. If you save the file and preview it in a browser, you’ll notice something a little strange: if you click and start to drag a photo, you’ll notice that it appears underneath the photo to the right of it (Figure 12-5). The reason for this phenomenon is explained in Figure 12-5. The solution is simple; just increase the z-index value of the dragged element. 8. Add one last option, zIndex, to the options object. $('#photos img').draggable({ revert : 'invalid', start : function (event, ui) { ui.helper.css('transform', 'rotate(5deg) scale(1.5)'); }, stop : function (event, ui) { ui.helper.css('transform', 'rotate(0deg) scale(1)'); }, zIndex : 100 }); Don’t forget the comma after the stop function. The zIndex option (page 408) simply adjusts the dragged element’s CSS z-index property. The higher the z-index value, the higher up the element is in the stacking order. A value of 100 is high enough to assure that the dragged element won’t appear behind any other items on the page. Chapter 12: jQuery UI Interactions and Effects 423 DRAGAND-DROP TUTORIAL FIGURE 12-5 An element’s z-index is affected by several factors. For example, the order of HTML can affect the stacking order of elements. In this case, the tag for the selected hotel photo (circled) appears in the HTML of the page before the tag of the golf tees (see the HTML snippet in step 1 on page 420). Accordingly, the hotel image is displayed underneath the photo of the tees. 9. Save the file and preview it in a web browser. Drag a photo around the page. The photo should rotate and grow slightly when you drag it, then snap back into place and revert to its normal size and rotation when released. In addition, when you first start to drag the photo, it should appear above any other photos around it. That’s enough work on the photos. Next, you’ll turn the trashcan image into a drop zone. 10. After the draggable() function, create a new line and add the following code: $('#trashcan').droppable(); This turns the trashcan image into a droppable widget. If you save the page and preview it now, you’ll see you can drop photos on the trashcan. The photos don’t move back to their original spot on the screen, however, because the trashcan is a valid drop zone. To make things more exciting, you’ll highlight the trashcan when a visitor starts to drag one of the photos. You’ll also make the trashcan appear brighter, alerting visitors that they can drag the photo to the trash. 11. Add an options object to the droppable() function: $('#trashcan').droppable({ activeClass : 'highlight' }); 424 JAVASCRIPT & JQUERY: THE MISSING MANUAL The activeClass option (page 414) simply adds a class name to the droppable widget as soon as someone drags a valid draggable on the screen. In this case, the highlight class, defined in the interactions.css file, changes the opacity of the trashcan image to 1 (100% opaque). Another rule in that CSS file sets the opacity of the trashcan to .6 (60% transparency) when the page loads. By changing the opacity from .6 to 1 with CSS, the trashcan appears brighter when a photo is dragged. DRAGAND-DROP TUTORIAL While this slight change looks cool and adds guidance for people viewing the page, you haven’t yet done anything when the photo is dropped in the trash. To do that, you need to use the droppable widget’s drop event. 12. Type a comma after 'highlight' in the code you just added, hit Return, and add a drop event handler like this: $('#trashcan').droppable({ activeClass : 'highlight', drop : function (event, ui) { } }); The drop option requires a function as its value, just like the start and stop events on draggable items. This function is empty and doesn’t do anything yet, but you can make it do something—like make the dropped photo explode! 13. In the drop function, add the code in bold below: $('#trashcan').droppable({ activeClass : 'highlight', drop : function (event, ui) { ui.helper.hide('explode'); } }); ui.helper refers to the dragged item (page 410). The hide() method is a jQuery function you’ve used earlier in this book (page 184); however, jQuery UI gives additional effects for hiding and showing elements. The explode option creates a fun, animated effect—a playful way to make the photo disappear from the page. (You’ll read more about these effects on page 438.) One last thing: swap in a new image for the trashcan after a photo has been dropped on it, showing a trashcan full of trash. 14. Add one last line of code inside the drop function: $('#trashcan').droppable({ activeClass : 'highlight', drop : function (event, ui) { ui.helper.hide('explode'); $(this).attr('src','../_images/trashcan-full-icon.png'); } }); Chapter 12: jQuery UI Interactions and Effects 425 SORTING PAGE ITEMS $(this) refers to the trashcan—the element on the page with the ID of trashcan. You’re simply changing that element’s src attribute to point to a new graphic. (You learned how to do that back in Chapter 7.) The finished code should look like this: $(document).ready(function() { $('#photos img').draggable({ revert : "invalid", start : function (event, ui) { ui.helper.css('transform', 'rotate(5deg) scale(1.5)'); }, stop : function (event, ui) { ui.helper.css('transform', 'rotate(0deg) scale(1)'); }, zIndex : 100 }); $('#trashcan').droppable({ activeClass : 'highlight', drop : function (event, ui) { ui.helper.hide('explode'); $(this).attr('src','../_images/trashcan-full-icon.png'); } }); }); // end ready 15. Save the file and preview it in a web browser. You can drag photos onto the trashcan, and they explode and disappear from the page (Figure 12-4). There’s a lot more programming you could add to the drop event in this example. For example, you could send an Ajax request to a server and instruct the server to remove the photo from the user’s account (you’ll learn about Ajax in Chapter 13). But this quick tour hopefully has you thinking of many possible uses for the draggable and droppable widgets. NOTE You’ll find the finished version of this tutorial in the complete-to-the-trash.html file. Sorting Page Items jQuery UI also provides a widget for working with lists such as to-do lists, music playlists, and even lists within lists like folders inside of folders. The sortable widget makes it easy to re-order items within a group simply by dragging an item to a new position. This widget is useful for managing a list of songs, for example—users can create their own playlist by dragging songs into a playlist and even re-ordering those songs by dragging them to new spots in the list (Figure 12-6). 426 JAVASCRIPT & JQUERY: THE MISSING MANUAL The sortable widget works with any grouped collection of items. While it’s a natural option for an unordered or ordered list, you can also turn a group of divs, paragraphs, or images into a sortable group. SORTING PAGE ITEMS Using the Sortable Widget Sortable widgets are a collection of elements that can be dragged into a different position within a group: for example, in a to-do list, each to-do item can be dragged to a different position in the list. The list, then, is the sortable widget, and the list items inside it are the elements you can sort. In other words, the sortable widget must be a container element such as an unordered list (

), ordered list (
), or a
element containing other items such as additional divs, paragraphs, or images. FIGURE 12-6 jQuery UI’s sortable widget makes re-ordering list items a breeze. Drag items from one list—like My Favorite Songs—to another list—My Playlist. This kind of interaction is common in many desktop programs like iTunes, or even in a directory listing of files. Using the sortable widget is easy: 1. Follow the steps on page 304 to attach the CSS and JavaScript files. Remember that jQuery UI has its own CSS and JavaScript files, and that the jQuery UI JavaScript file should be linked to after the jQuery JavaScript file. 2. Add containing element to your web page. This might be an unordered list or a

tag:

Chapter 12: jQuery UI Interactions and Effects 427 SORTING PAGE ITEMS It’s a good idea to add an ID or class to the tag, so you have a way to select that item with jQuery. 3. Add items inside the containing element. In the case of an unordered or ordered list, that would be a series of

tags. The items in the containing element represent the things that you can drag around and place in a new order within the list. In the case of a

, you could place images, paragraphs, or other divs inside (those items will be the sortable elements of the widget):

• My Way -- Frank Sinatra
• Like a Rolling Stone -- Bob Dylan
• Respect -- Aretha Franklin

4. Add jQuery’s $(document).ready() function to your page or to another external JavaScript file: $(document).ready(function() { }); // end ready As discussed on page 160, this step is only necessary if you’re putting your JavaScript code in the of the page, before the majority of your HTML. Some programmers put their JavaScript code at the bottom of the page, before the closing tag. In that case, you can skip the $(document). ready() function. 5. Use jQuery to select the containing element you added in step 2: $(document).ready(function() { $('#playlist').sortable(); }); // end ready This code selects the containing element (the

element represented by the code in step 3) and makes all the items inside sortable. You can customize the sortable widget with many different options, described later. 6. Add options to the sortable() function: $(document).ready(function() { $('#playlist').sortable({ opacity : 0.5, placeholder : 'ui-state-highlight' }); }); // end ready You’ll learn about the various options for this widget next, but you can get a sneak preview by taking a look at what this code does. First, the opacity option tells jQuery UI to reduce the opacity of an element while it’s being dragged. The 428 JAVASCRIPT & JQUERY: THE MISSING MANUAL second option, placeholder, tells jQuery to apply a style to the empty space where a dragged item can be dropped onto. NOTE SORTING PAGE ITEMS You’ll get to try out the Sortable widget in the web app you’re going to build in Chapter 14. Sortable Widget Options jQuery UI’s sortable widget includes many options. You can control a sortable item’s direction and distance, how it behaves when you drag it, and even what portion of the element you can grab. Like other jQuery UI widgets, you can set options by passing an object to the sortable() function. For example, to change the cursor to a pointing finger and to set the

element inside the item as the handle that a visitor must grab, you’d pass an object with those two options set: $('#playlist).sortable({ cursor : 'pointer', handle : 'h2' }); Here are some commonly used options: • axis. You can limit the movement of a sortable element to just left and right or up and down using the axis property. For example, say you created a horizontal group of divs that a visitor could re-order as part of a game (Figure 12-8). You could limit motion of those items to just left and right. Use either 'x' (to constrain the dragged item to just left and right movement) or 'y' (to make sure the dragged item can only be moved up and down the page): axis : 'x' • cancel. This option lets you prevent dragging an item if a specific element is clicked on. For example, say you had a playlist of songs (an unordered list). Next to the name of each song is a trashcan icon; users could click this icon to remove the song from the list. However, if a user grabbed that icon, he could drag the song to new spot on the list instead of delete the song. To prevent an element inside a sortable item from acting as handle, provide a selector to the cancel option: cancel : '.trashcan' Now, if someone clicked on the trashcan icon (assuming that icon had a class name of trashcan applied to it), she wouldn’t trigger the dragging action. You can even specify multiple elements—just separate them by commas: cancel : '.trashcan, .addToFavorites' The handle option, discussed on page 431, lets you specify a particular element to act as the “grabbable” part of the item. • connectWith. Lets you specify a selector of other sortable items—another list—that you can drag a list item to. For example, say you had two lists on a page: a wish list of products that you’d like to buy, and a shopping cart list that Chapter 12: jQuery UI Interactions and Effects 429 SORTING PAGE ITEMS includes all the products you’re going to buy. You might want to re-order your wish list—put your most desired products at the top of the list, for example— but also be able to drag an item from the wish list to the shopping cart list. In this case, you’d have two different lists, and apply the sortable() function separately to each. However, using the connectWith option, you can let users drag an item from one list to another: $('#wishList').sortable({ connectWith : '#shoppingCart' }); The connectWith option is a one-way connection. In other words, in the above code, you could only drag items from the group of items within the wish list to the shopping cart, but not from the shopping cart to the wish list. To connect both lists, you need to use the connectWith option on both lists: $('#shoppingCart').sortable({ connectWith : '#wishList' }); The value you supply the connectWith option should be a selector that matches an element to which you’ve applied the sortable() function. • containment. You can prevent a visitor from dragging a list item outside a container element. This works just like the containment option for the draggable widget (page 403). In fact, a sortable item is really just a draggable item that you can insert within a list of items. The containment option accepts several possible values: • A selector. If you provide a selector name, then jQuery UI will keep the list item confined to the boundaries of that element. For example, if you had a

on the page with an ID of mainContent, you could keep the draggable element inside that div by setting the containment option like this: containment : '#mainContent' • parent, document, or window. To keep the list item contained inside its parent element, use parent as the value. For example, if the list item is an unordered list and you want to limit the dragging to within that list: containment : 'parent' The document and window values are nearly the same, except document keeps the entire draggable area contained within the document area and window lets you drag the element partly outside the window (this doesn’t look very good, so think twice before using window). • cursor. Same as the cursor setting for draggable items (page 403) • cursorAt. Same as the cursorAt setting for draggable items (page 404) 430 JAVASCRIPT & JQUERY: THE MISSING MANUAL • delay. An amount in milliseconds to delay dragging the sortable item. This delay is handy if you find it easy to accidentally drag a list item as you’re mousing around the page. The delay indicates how long someone needs to hold down the mouse button before the dragging is allowed: SORTING PAGE ITEMS delay : 100 • distance. A pixel distance that a list item must be dragged before sorting begins. This is useful if visitors need to click on a sortable item other than to drag it. For example, if the sortable item includes a button to delete that item, you could set the distance option to prevent the item from being dragged when a visitor accidentally moves the mouse when clicking on the Delete button. Use a small number for this setting (otherwise, visitors will have to drag the item a fair distance before seeing the sortable behavior): distance : 10 • grid. Snaps the list item to a grid. This option could work well if you have a group of equally sized photos or divs: you can snap the list item to move exactly the width of the other list items when you drag it. It works just like the grid option for the draggable widget (page 404). • handle. Indicates the part of the item the user must click to drag the item to another place in the list. Normally, users can drag by clicking on any spot of a sortable item. However, you might want to force users to click on a specific part of the item—like a tab. This option works like the handle option for draggable options described on page 405. • items. You can limit which items within the sortable group can be sorted. For example, say you applied the sortable function to a nested list—a list containing indented lists or sublists (Figure 12-7). You don’t want to make the top-level list items sortable (in Figure 12-7, the top-level list items are Folder A and Folder B). You do want nested list items to be sortable, so they can be dragged into other nested lists or rearranged in their current nested list. In this case, you can use the items option and set it to 'li li', which means only a list item inside another list item (a nested list item) can be sorted. The top-level lists aren’t nested, so they can’t be sorted: items : 'li li' • opacity. When dragging an element you can make its opacity change. For example, you can fade the element to 50% opacity to give it a “ghost-like” appearance. Opacity is a common way to indicate that an item is moving from one place to another. Use a value between 0 (completely invisible) to 1 (completely opaque). This works just like the CSS opacity property. For example, to make the dragged element appear 50% transparent, set the value to 0.5: opacity : 0.5 Chapter 12: jQuery UI Interactions and Effects 431 SORTING PAGE ITEMS • placeholder. A class name jQuery UI applies to the empty spot where a list item can be dragged to. You can use one of jQuery UI’s own classes (page 395) to highlight this spot: placeholder : 'ui-state-highlight' FIGURE 12-7 You can create nested lists (lists within lists) in HTML by adding an unordered (

) or ordered (
) list tag inside a list item:
1. Folder A
   • Sublist
. jQuery UI lets you control which elements inside the sortable widget can be dragged and sorted, so you can limit sorting to just items inside nested lists. NOTE You’ll find even more options for the sortable widget at http://api.jqueryui.com/sortable/. Sortable Events As a visitor interacts with a sortable list, jQuery UI fires off all sorts of events—like when a visitor starts dragging an item in the list and when he stops dragging that item. jQuery UI provides over a dozen different sortable widget events, each of which you can respond to with your own programming. Some of these events fire off very close to each other and, in practice, are indistinguishable. As with the draggable and droppable widgets, you assign functions to a sortable event as part of the options object passed to the sortable() function. For example, to open an alert box after a user has moved an item in the list, you could write the following: $('#playList').sortable({ stop : function (event, ui) { alert('Well sorted, my friend!'); } }); Some events apply to all lists, and two only apply when you have two (or more) sortable lists on the same page and are dragging items between the lists. Suppose 432 JAVASCRIPT & JQUERY: THE MISSING MANUAL you start with a list of events that apply to all sortable widgets. These events are triggered in a specific order, so you’ll list them that way: SORTING PAGE ITEMS • create. This event fires whenever you use the sortable() function to create a new sortable list. You could use this event to pop up a dialog box with instructions “Drag the songs around to re-order your playlist.” It only runs once—when the sortable widget is created. NOTE Unlike all other Sortable widget events, the create event doesn’t receive the ui object (described on page 409). • start. Fired as soon as a user starts dragging a list item. The function you assign to this event accepts two arguments: an event object (page 164); and a ui object, which contains information about the widget. The ui object contains seven other objects, each with important information about the widget: • ui.helper. The helper object is a jQuery object that represents the item the user drags. jQuery UI makes a clone of the original item, so as you drag a sortable item, there are two different HTML elements in play: the helper clone and the actual element that’s part of the list. When the visitor stops dragging the item, the helper element is removed from the document. Because helper is a regular jQuery object, you can use jQuery methods such as css() , animate(), or find() on it. • ui.item. Represents the actual sortable item that the visitor clicked to drag, like an
2. element. It’s the real HTML element, and will be inserted into the proper spot in the list once the user has finished dragging the helper element. It’s also a jQuery object, so all the regular jQuery methods apply to it. • ui.position provides the x and y position of the top-left corner of the helper item (the item that is visibly dragged across the screen) in relation its nearest positioned ancestor. If the sortable widget is inside a relative or absolutely positioned element, then the ui.position property will provide the top and left position values for the help in relation to the top-left of the positioned element. You can access those values like this: ui.position.top and ui.position. left. • ui.originalPosition. The original position of the sortable item; where it was before the user started to drag it. This is an object like ui.position with two properties—top and left. • ui.offset is an object with two properties top and left. But, in this case, the position is calculated relative to the top left of the browser window. The ui.offset.top property identifies how far the top of the helper element is from the top of the window. The ui.offset.left property identifies how many pixels the draggable item is placed from the left side of the browser window. Chapter 12: jQuery UI Interactions and Effects 433 SORTING PAGE ITEMS • ui.sender. This property only applies when dragging from one sortable widget to another. The ui.sender property contains a jQuery object for the sortable widget the dragged item is coming from. • placeholder. A jQuery object representing the empty placeholder spot created when dragging a sortable item. The ui object is available to all other sortable event handlers—activate, over, sort, and so on—except the create event. • activate. Fires just after start, but at basically the same moment. You can use this to add a second function you want to run just after a function you’ve assigned to start. • sort. The sort event fires each time the mouse is moved while a sortable item is being dragged. In other words, this event fires off continuously, so don’t assign any time- or processor-intensive tasks to this event. If you do, the repeated calling of the function will slow the page’s responsiveness and probably make dragging the Sortable widget difficult for your visitors. • change. This event is fired as soon as sortable items change place. For example, when you drag an item from the top of a list down, and the second item jumps up to replace the first, the change event is triggered. You could use this event to highlight the two items that swapped position, for example. • beforestop. The beforestop event fires just after the user lets go of a sortable item. It’s the last event that still has access to the ui.helper object. After this event, the ui.helper (the clone of the dragged) item is deleted. • update. When all of the sortable items are in place, and the DOM has been updated, the update event fires. • deactivate. When sorting is done, the deactivate event always fires immediately after update. • stop. After the sortable item is dropped into place, the stop event fires. This event is last of all, and always follows stop and deactivate. Assign a function to this event, when you want it to be the last thing to happen after a list item has been dropped. For example, you could use the stop event to check the status of the list to see if it matches some pre-defined order (Figure 12-7). The events just listed fire in the order listed above. However, there are a few other events that are triggered at different times and for different types of Sortable widgets. • out. The out event is trigged when a sortable item is moved out of a Sortable widget; for example, if you drag an item out of its Sortable widget to an empty spot on the page. It also fires when you move an item out of one Sortable widget into another. • over. When you move a sortable item over a connected list. For example, if you have two connected lists and drag an item from the first list to the second, then 434 JAVASCRIPT & JQUERY: THE MISSING MANUAL the over event fires on that second list. This event also fires when you move an item off a group of sortable items and then back onto it. SORTING PAGE ITEMS • receive. Use the receive event when using multiple connected Sortable widgets (see the connectWith option on page 429). When a sortable widget receives an item from another sortable widget, the receive event fires. You can use this event in conjunction with the ui.sender object (page 434) to determine where the new sortable item came from. • remove. This event fires when an item is removed from the current sortable widget. For example, say you had two sortable widgets: a wish list and a shopping cart. If a shopper dragged an item from the wish list to the shopping cart, the remove event would fire on the wish list (as well as the out event). (In this scenario, the over and receive events would fire on the shopping cart as well.) Sortable Methods The sortable widget includes several different methods, or functions that you can run on the widget. You don’t call these methods as you would a normal jQuery method, like selecting a page element then applying the method to it like this: $('body'). hide(). Instead, you give the method name, as a string, to the sortable() method. Say you’re using the destroy method, which completely removes the sortable widget—it returns a sortable set of list items, to regular list items that can’t be dragged. The code to invoke the destroy method looks like this: $('#sortableItems').sortable('destroy'); The selector—#sortableItems, in this example—should match the selector for a sortable widget on the page. You’ll commonly use these methods in response to one of the sortable events discussed in the previous section. For example, if you created a game that required a player to place a set of blocks into a particular order, you could destroy the sortable after the player completed the game, keeping him from moving the blocks again. You can find a complete list of sortable methods at http://api.jqueryui.com/sortable/, but here are a few of the most useful: • cancel. This cancels any change in the current order of a sortable. In other words, it stops the re-ordering of the list. You could use this with the receive method (page 435), to reject a list item that was dragged to another sortable widget. Or as part of the stop event (page 434), you could create a function that checks the placement of the newly dropped item, and rejects that change if the item doesn’t meet certain conditions. For example, in a to-do list application, you might make certain tasks dependent upon other tasks. For example, if a user tries to drag a task to the top of the to-do list, but another task must be completed first, you could cancel that user’s action and pop up a dialog box with an explanation of why the move was rejected. • destroy. To completely remove the sortable functionality of a sortable widget, use the destroy method. Chapter 12: jQuery UI Interactions and Effects 435 SORTING PAGE ITEMS • disable. To temporarily remove the sortable functionality of a widget, invoke the disable method. Use this when you want to prevent sorting temporarily, until some other condition is true. You can turn the sorting back on with the enable method (discussed next). • enable. Turn sorting back on for a disabled sortable widget—a widget that previously had the disable method applied to it. • serialize. This method is useful for sending the order of the list back to a web server via Ajax or a form post. You might want to do this if it’s important to store this information on the server for later use. For example, if a manager was organizing a list of tasks for her employees, the order could be sent to the server, stored in a database, and retrieved when an employee logged in to see what tasks needed to be done (and in what order). You need to format your sortable items in a specific way: • Each list item must have an ID • Each ID should begin with the same word, which acts like a group identifier for the list, followed by an underscore (_) character. • After the _ character in the ID name must follow a unique identifier for the list item. For example, say you had a playlist of songs. The HTML might look like this:
   • My Way -- Frank Sinatra
   • Like a Rolling Stone -- Bob Dylan
   • Respect -- Aretha Franklin
   Notice that the ID for each list item begins with "song_" and ends with a unique number. It doesn’t have to be a number—it could be a word, or a unique ID from a database. The idea is to provide a way to let the server know the new order of the list. You can use the serialize method to capture the current order of the list: var listOrder = $('#playlist").sortable('serialize'); The serialize method returns a string that looks something like this: song[]=2&song[]=3&song[]=1 The string indicates the order of the items in the list. In this case, the numbers are 2, 3, and 1, indicating that the first item in the list was dragged to the bottom of the list. You can tag the string value returned by serialize to a URL as part of an Ajax call (Chapter 13). NOTE The serialize method lets you provide options that control the format of the string returned by the method. You can read about those options at http://api.jqueryui.com/sortable/#method-serialize. 436 JAVASCRIPT & JQUERY: THE MISSING MANUAL • toArray. The toArray method, like serialize, is a way to retrieve an ordered list of items in a sortable widget. To use it, you must add an ID to each item in the sortable list. But, unlike the serialize method, it doesn’t require any special format. The method simply returns an array listing the ID of each item in the sortable widget in the order the items appear in the list. For example, say you had a sortable widget with an ID of colorList. Inside it are three list items, each with a different color: SORTING PAGE ITEMS
   • Red
   • Green
   • Blue
   Say a user dragged the colors into a different order so Blue was first, Red was second, and Green was last. You could use the toArray method at that point like this: var colors = $('#colorList').sortable('toArray'); The color variable would then contain this array: ['blue', 'red', 'green'] The result is a basic JavaScript array (page 44). You can use any of the array methods discussed on pages 46-51 to manipulate it. One use of the toArray method is to see the order of the list matches some predefined state. For example, say you created a game that showed a randomly assorted list of color blocks. The player is supposed to sort the blocks into the order they appear in the rainbow (remember, ROY G BIV?). You could add a function to the stop event (page 434) that gets the current order of the blocks using the toArray method and then compares it to another array containing the answer (Figure 12-8). NOTE jQuery UI includes two other interaction widgets. The resizable widget is used by the dialog widget (page 305) to let users resize them by dragging a resize handle in the corner of the box. You can use this widget to make resizable floating windows. Learn more about this widget at http://api.jqueryui.com/resizable/. Chapter 12: jQuery UI Interactions and Effects 437 JQUERY UI EFFECTS FIGURE 12-8 Use the sortable widget’s toArray method to retrieve an array of item IDs in the order those items currently appear in the list. You can use this information to compare the current order to some predefined result. In this game, each time a block is moved, the current order of the blocks is compared to a correct answer. If the order matches the answer, the player wins. You’ll find this file—pattern-game. html—in the chapter12 folder of the tutorial files. NOTE The selectable widget lets a visitor select elements (highlight them) by clicking them. You could use it for a photo download page: “Select the photos that you’d like to download.” Learn more at: http://api.jqueryui. com/selectable/. jQuery UI Effects jQuery UI includes a suite of visual, animated effects that you can use to enliven your web applications. For example, the explode effect, which you saw in action in the tutorial on page 425—makes an element break apart and fade out of view. You’ll learn more about these kinds of effects in a moment, but first you need to know how to apply them. Effects are intended to either bring an element into view, make the element disappear, or highlight the element in some way—for example, by making it light up or shake. To apply effects, you use either jQuery functions, as you’ve done so far in this book, or the jQuery UI-only effect() function. For example, to use the jQuery UI drop effect to make an element appear to drop onto the page, you could use the show() method with the name of the effect and a duration: $('#pageElement').show('drop', 1000); 438 JAVASCRIPT & JQUERY: THE MISSING MANUAL This would “drop” the element onto the page over the course of 1 second (1,000 milliseconds). The show() method should look familiar (page 184). It’s a jQuery function that reveals a hidden element on the page. However, jQuery UI adds some new features to jQuery’s show() function as well as to two other jQuery functions. jQuery UI offers four different functions for adding effects to elements: JQUERY UI EFFECTS • show(). jQuery UI extends jQuery’s show() function by letting you use one of 15 different effects to reveal an already hidden element. You should make sure the element is hidden (see the hide() method on page 184) before using show(); otherwise, you’ll end up with the element quickly disappearing then reappearing. • hide(). To apply one of jQuery UI’s effects while hiding an element, use the hide() method. It works like jQuery hide() function (page 184) in that it makes an element disappear from the page—but using a special effect. Make sure the element is visible on the page, before using this function. • toggle(). The toggle() method either shows or hides an element. If the element is hidden, the toggle() makes it appear using a specified effect. If the element is visible, then toggle() reveals the element. • effect(). Most of jQuery UI’s effects are designed to reveal or hide an element with flair. A few effects—bounce, highlight, pulsate, and shake—can be used to highlight an already visible item without making it disappear. The highlight effect, for example, momentarily highlights an item by flashing a bright color, providing a great way to draw a visitor’s attention to a specific spot on the page. The effect() function is unique to jQuery UI and isn’t a normal jQuery function. NOTE You’ll use the effect() function in the web app you’re going to build in Chapter 14. The Effects The jQuery UI effects add powerful animated tools to your web design toolkit. You can pass each of these effects as an argument to the functions listed above. Each effect provides a different visual result. The basic structure for using an effect with one of the above functions looks like this: $('#element').hide('effectName', { optionName : optionValue }, duration, callBackFunction); For example, if you wanted to hide an element with an ID of deleteThis on the page by making it explode into 16 pieces in half a second, and then pop up an alert box that says “Boom!” you’d write this code: $('#deleteThis').hide('explode', { pieces : 16 }, 500, function () { alert('Boom!'); }); Most effects let you pass one or more additional options to control how the effect works. Options are passed as an object consisting of option names and values. In Chapter 12: jQuery UI Interactions and Effects 439 JQUERY UI EFFECTS the previous example, the option is the number of pieces the explode effect should divide the element into: { pieces : 16 } Each effect has different options, and some effects have no options at all. jQuery UI provides many effects: • blind. The blind effect either shows or hides an element simulating a blind being lifted open or pulled closed. The effect accepts one option—direction—which indicates the direction the blind should move: up, down, left, or right. You pass the option as an object—option name and value—as second argument to the function. For example, to make a particular element disappear from the screen: $('#element').hide('blind', { direction : 'left'}, 1000); • bounce. The bounce effect can be applied when hiding or showing an element. You can also use bounce with the effect() function to simply bounce a visible item up and down—a great way to make a page element say “look at me!!!!” The effect has two options: • distance. The farthest distance (in pixels) that the element will travel as it bounces. The higher the number, the farther it bounces, and the more attention it grabs. • times. The number of times the element will bounce. For example, to make an item bounce 20 times, at a distance of 100 pixels every time it’s clicked, you could write this code: $('#theElement').click(function () { $(this).effect('bounce', { distance : 100, times : 20 }, 1000 ); }); • clip. The clip effect applies the CSS clip attribute to an item to make it appear either vertically or horizontally. The effect accepts only one option—direction with a value of either vertical or horizontal: { direction : 'horizontal' } • drop. The drop effect shows or hides an element by fading it into or out of view while sliding it up, down, left, or right. It has a single option, direction, which accepts one of the following four values: up, down, left, or right. • explode. The explode effect divides an element into a bunch of pieces, animates them outward and fades them out of view. When used with the show() function, the element looks like an explosion in reverse: separate pieces coming together 440 JAVASCRIPT & JQUERY: THE MISSING MANUAL to form a whole. It only has one option—pieces—which indicates the number of pieces the element should be divided into. The number has to be a squared value: 1, 4, 9, 16, 25, and so on (but don’t make the number any bigger than 25 or this effect slows down to a crawl): JQUERY UI EFFECTS { pieces : 16 } • fade. Works like jQuery’s fadeIn() and fadeOut() functions. In other words, it’s not a terribly exciting effect. • fold. The fold effect shows or hides an element by folding it. You can set two options for this intriguing visual effect. size is the size in pixels (or percentages) that the item should reduce to before folding in the opposite direction and horizFirst accepts a Boolean value that determines whether the element should fold up vertically first (the default) or horizontally first: { size : '50%', horizFirst : true } • highlight. The highlight effect momentarily changes the background color of an element to draw attention to it. It’s another effect you can use on a visible element without hiding it. You can change the color of the background color by setting the color option. For example, to highlight an element by flashing a red background color for 1 second, you could apply the effect() method like this: $('#element').effect('highlight', { color : '#ff0000' }, 1000); • puff. This effect makes an element change size and fade out (or into) view. It has a single option, percent, which dictates the percentage the element should fade from (if showing the element) or fade to (if hiding the element): { percent : 200 } • pulsate. Another effect that you can use to draw attention to an element without hiding it first. This effect hides and shows an element repeatedly. You can dictate the number of times the element pulsates by setting the times option like this: $('#element').effect('pulsate', {times : 20}, 2000); • scale. Use this effect to scale an element. You can use this effect with either the hide() or show() methods. Normally, if you use the show() method to reveal a hidden element, the element will scale up from a tiny spot on the page to its full size; if the element is visible and you use the hide() method, the element will shrink and disappear. • shake. This effect can be applied to an element that’s visible on the page using the effect() function (page 439). It simply shakes the element a specific direction, distance, and number of times. This is another one of those “Pay attention to me” type of effects, but it can serve a more important purpose, like indicating an error; for example, shaking a dialog box when a visitor hasn’t checked the “Terms of service” box on a signup form. This effect has three options. The direction option dictates the direction to begin shaking the element: up, down, left, or right. Set the distance option to specify the number Chapter 12: jQuery UI Interactions and Effects 441 JQUERY UI EFFECTS of pixels the element should move on each shake; the greater the number, the more obvious the shaking action. Finally, the times option indicates the number of times the element shakes. For example, to shake an element left (and keep shaking it horizontally) 10 times, 50 pixels each time, you’d pass this object containing these options to the effect() function: { direction : 'left' , distance : 50, times : 10 } • size. This effect resizes an element to a specified width and height. It accepts three options: to is an object with width and height properties dictating the width and height the element should be resized to (when hiding the element) or the width and height to start at (when showing the element). The origin property dictates the vanishing point when using the size effect to hide an element. It’s an array of two numbers: the first number indicates the top position, and the second the left position. The scale property is used to indicate what should be scaled. The possible values include both, box, and content. For example, to increase or decrease just the size of the outer box (the border, background, and width and height) use the box value. Doing so doesn’t scale the content (like text) inside the element. • slide. This effect slides an element out of the viewport (if hiding it) or slides the element into place (if it’s showing). Provide a direction option—left, right, up, or down—to dictate the direction the slide effect moves: $('#element').show('slide', { direction : 'right' }, 1000 ); NOTE To learn more about jQueryUI effects, visit http://api.jqueryui.com/category/effects/. Easing jQuery UI includes a set of easing functions that control the speed of changes during an animation. Easing doesn’t change the overall time an effect takes to animate, but does changes the speed at which individual parts of an animation occur. For example, if you use the bounce effect, you could apply an easing function that makes the bouncing start slowly then bounce really quickly before stopping. NOTE Visit the jQuery UI Easings page to see what each easing function looks like and to try them out: http://api.jqueryui.com/easings/. To use an easing function with an effect, you need to pass it as a property of the options object. Its property name is easing, and the value should be one of the possible easing functions—easeInOutQuart, easeInSine, and so on (for a complete list of easing function names, visit http://api.jqueryui.com/easings/). For example, say you want to use the bounce effect (page 440), to bounce an element each time it’s clicked. You want the element to bounce 20 times with a 442 JAVASCRIPT & JQUERY: THE MISSING MANUAL maximum distance of 100 pixels (those are both options of the bounce effect). You also want to apply an easing function to make it look more realistic—a bouncing element slows down as it runs out of energy. You could add an easing property to the options object like this: JQUERY UI EFFECTS $('#theElement').click(function () { $(this).effect('bounce', { distance : 100, times : 20, easing : 'easeOutBounce' }, 1000 ); }); You’re not limited to using these easing functions only with jQuery UI’s effects. As discussed on page 192, you can use these functions with jQuery UI animations as well. Animating Changes Between Classes jQuery UI includes several functions that animate changes to an element’s CSS properties when a class is added or removed from the element. These functions are actually extensions of existing jQuery functions: addClass(), toggleClass(), and removeClass() (page 131). jQuery UI simply adds animation to the changes, so when you add or remove a class, jQuery UI animates the visual changes that occur because of the addition or removal of CSS properties. NOTE jQuery UI’s class animations may sound a lot like CSS transitions. In fact, they’re very similar: while CSS transitions depend on the browser’s built-in CSS rendering engine, jQuery uses JavaScript to animate the changes. CSS transitions are actually a better way to go: they work more smoothly and don’t require any work from the JavaScript interpreter. However, CSS transitions aren’t supported by Internet Explorer 9 or earlier, therefore you may need to use jQuery UI’s class animation feature to get the same effect in those browsers. However, if you don’t need to support outdated versions of Internet Explorer, then use CSS transitions, and skip these jQuery UI functions. To learn more about CSS transitions, visit: https://developer.mozilla.org/en-US/docs/Web/Guide/CSS/ Using_CSS_transitions. Each of jQuery UI’s class animation features accept up to four arguments to modify how they work. The first argument is the class name you want to add or remove. The next three are composed of a duration, easing, and completion function—the same arguments you pass the effect() method (page 439). For example, to select an element with the ID of feature, add a class name highlight, and animate the visual changes caused by adding that class, you could write this: $('#feature').addClass('highlight', 1000, 'easeOutBack', function () { alert('done animating'); }); Chapter 12: jQuery UI Interactions and Effects 443 JQUERY UI EFFECTS This code adds the highlight class to the selected element and animates the visual changes to the element over the course of 1 second (1,000 milliseconds) using the easeOutBack easing method (page 442). After jQuery UI is finished animating the class change, a callback function is run opening an alert box with the words “done animating.” Only a class name and duration are necessary to get the animated effect. jQuery UI provides four functions for animating class changes: • The addClass() method lets you add a class to one or more elements and animate the visual changes over a specified amount of time. NOTE If you don’t pass a time argument to any of these methods, jQuery UI simply uses the standard jQuery form of the function, without animation. For example: $('#feature').addClass('highlight'); This code adds the class highlight to the element, but doesn’t animate the change. • The removeClass() method works just like the addClass() method. You pass it a class name, animation duration, optional easing value, and optional callback function. However, this function removes the specified class and animates any visual changes caused by removing that class. • The toggleClass() method removes a class from an element if that class is in place, or adds the specified class if it’s missing. You could use this function in conjunction with a click event (page 149) to add a class the first time an element is clicked, then remove that