Drag Layer

The Drag Layer action lets the user drag a layer. Use this action to create puzzles, slider controls, and other moveable user interface elements.

You can specify in which direction the user can drag the layer (horizontally, vertically, or in any direction), a target to which the user should drag the layer, whether to snap the layer to the target if the layer is within a certain number of pixels of the target, what to do when the layer hits the target, and more.

Because the Drag Layer action must be called before the layer can be dragged by the user, make sure that the event that triggers the action occurs before the user attempts to drag the layer. We recommend attaching Drag Layer to the BODY object (with the onLoad event), though you can also attach it to a link that fills the entire layer (such as a link around an image) using the onMouseOver event.

To use the Drag Layer action:

1	Choose Insert > Layer or click the Layer button on the Object palette and draw a layer in the Document window.
2	Follow steps 1 through 3 of the procedure in Attaching a behavior.
3	Select Drag Layer from the Actions pop-up menu.
	If Drag Layer is unavailable, you probably have a layer selected. Because layers do not accept events in both 4.0 browsers, you must select a different object—such as the BODY tag or a link (A tag)—or change the target browser to IE 4.0 in the Events For pop-up menu.
4	Select the layer that you want to make draggable from the Layer pop-up menu.
5	Select either Constrained or Unconstrained from the Movement pop-up menu.
	Unconstrained movement is appropriate for puzzles and other drag-and-drop games. For slider controls and moveable scenery such as file drawers, curtains, and mini-blinds, choose constrained movement.
6	For Constrained movement, enter values (expressed in pixels) in the Up, Down, Left, and Right fields.
	Values are relative to the starting position of the layer. To constrain movement within a rectangular region, enter positive values in all four fields. To allow only vertical movement, enter positive values for Up and Down and 0 for Left and Right. To allow only horizontal movement, enter positive values for Left and Right and 0 for Up and Down.
7	Enter values (expressed in pixels) for the drop target in the Left and Top fields.
	The drop target is the spot to which you want the user to drag the layer. A layer is considered to have reached the drop target when its left and top coordinates match the values you enter in the Left and Top fields. Values are relative to the top left corner of the browser window. Click Get Current Position to automatically populate the fields with the current position of the layer.
8	Enter a value (expressed in pixels) in the Snap if Within field to determine how close the user must get to the drop target before the layer snaps to the target.
	Larger values make it easier for the user to find the drop target.
9	For simple puzzles and scenery manipulation, you can stop here. To define the drag handle for the layer, track the movement of the layer while it is being dragged, and trigger an action when the layer is dropped, click More Options.
10	To specify that a particular area of the layer must be clicked to drag the layer, choose Area Within Layer from the Drag Handle pop-up menu and enter the Left and Top coordinates and the Width and Height of the drag handle.
	This option is useful when the image inside the layer has an element that suggests dragging, such as a title bar or drawer handle. Do not set this option if you want the user to be able to click anywhere in the layer to drag it.
11	Choose from the following While Dragging options, if desired:
	Select Bring Layer to Front if the layer should move to the top of the stacking order while it is being dragged. If you select this option, choose whether to leave the layer on top or restore it to its original position in the stacking order from the pop-up menu.
	Enter JavaScript code or a function name (for example, monitorLayer()) in the Call JavaScript field to repeatedly execute the code or function while the layer is being dragged. For example, you might want to write a function that monitors the coordinates of the layer and displays hints such as "you're getting warmer" or "you're nowhere near the drop target" in a text field. See Gathering information about the draggable layer.
12	Enter JavaScript code or a function name (for example, evaluateLayerPos()) in the second Call JavaScript field to execute the code or function when the layer is dropped. Select the Only if Snapped option if the JavaScript should be executed only if the layer has reached the drop target.
13	Click OK.
14	Check that the default event is the one you want.
	If it isn't, select another event from the pop-up menu. If the events you want are not listed, change the target browser in the Events For pop-up menu. Remember that because layers are not supported by 3.0 browsers, 4.0 browsers, IE 4.0, and Netscape 4.0 are the only relevant options.

Note: You cannot attach the Drag Layer action to an object with the onMouseDown event.

 
Gathering information about the draggable layer

When you attach the Drag Layer action to an object, Dreamweaver inserts the MM_dragLayer() function into the HEAD of your document. In addition to registering the layer as draggable, this function defines three properties for each draggable layer—MM_LEFTRIGHT, MM_UPDOWN, and MM_SNAPPED—that you can use in your own JavaScript functions to determine the current horizontal position of the layer, the current vertical position of the layer, and whether the layer has reached the drop target.

For example, the following function displays the value of the MM_UPDOWN property (the current vertical position of the layer) in a form field called curPosField. (Form fields are useful for displaying continuously updated information because they are dynamic—that is, you can change their contents after the page has finished loading—in both Netscape Navigator and Microsoft Internet Explorer.)

function getPos(containingLayer,nestedLayer){
  var layerRef = ((navigator.appName=='Netscape')?document.layers[containingLayer].document.layers[nestedLayer]:document.all[nestedLayer]);
  var curVertPos = layerRef.MM_UPDOWN;
  document.tracking.curPosField.value = curVertPos;
}

Instead of displaying the value of MM_UPDOWN or MM_LEFTRIGHT in a form field, you could write a function that displays a message in the form field depending on how close the value is to the drop zone, or you could call another function to show or hide a layer depending on the value. How you react to the value of MM_UPDOWN or MM_LEFTRIGHT is limited only by your imagination and your JavaScript skills.

It is especially useful to read the MM_SNAPPED property when you have several layers on the page, all of which must reach their targets before the user can advance to the next page or task. For example, you could write a function to count how many layers have an MM_SNAPPED value of TRUE and call it whenever a layer is dropped. When the snapped count reaches the desired number, you can send the user to the next page or pop up a message of congratulations.

If you have attached the Drag Layer action to links within several layers using the onMouseOver event, you must make a minor change to the MM_dragLayer() function to prevent the MM_SNAPPED property of a snapped layer being reset to FALSE if it is passed over with the mouse (this can happen if you have used Drag Layer to create a picture puzzle because the user is likely to pass over snapped pieces while positioning others). MM_dragLayer() was not written to prevent this behavior because it is sometimes desirable (for example, if you want to set multiple drop targets for a single layer).

To prevent re-registration of snapped layers:

1	Choose Edit > Find.
2	Select HTML Source from the Find What pop-up menu.
3	Type (!curDrag) in the adjacent text field.
4	Click Find Next.
	If Dreamweaver asks if you would like to continue searching from the beginning of the document, click Yes. Dreamweaver finds a statement that reads:
	if (!curDrag) return false;
5	Close the Find dialog box and then modify the statement in the HTML inspector so that it reads:
	if (!curDrag || curDrag.MM_SNAPPED != null) return false;
	The two pipes (||) mean "or", and curDrag is a variable that represents the layer that is being registered as draggable. In English the statement means "if curDrag is not an object, or if it already has an MM_SNAPPED value, don't bother executing the rest of the function."