joe-loco edited this page Sep 12, 2010 · 2 revisions

Behaviours > Draggable

To make an element draggable, create a new instance of class Draggable.
For additional built-in functionality, make a Sortable instead.

There is also a class named Draggables that exposes functions for observing drag actions.


new Draggable('id_of_element', [options]);


Option Since Description
handle 1.0 string or DOM reference, not set by default. Sets whether the element should only be draggable by an embedded handle. The value must be an element reference or element id.
handle 1.5. string or DOM reference, not set by default. As above, except now the value may be a string referencing a CSS class value. The first child/grandchild/etc. element found within the element that has this CSS class value will be used as the handle.
revert 1.0 boolean, defaults to false. If set to true, the element returns to its original position when the drags ends.
revert 1.5 boolean or function reference, defaults to false. Revert can also be an arbitrary function reference, called when the drag ends.
snap 1.5 If set to false no snapping occurs. Otherwise takes the forms – xy or [x, y] or function(x, y) { return [x, y]; }.
zindex 1.5 integer value, defaults to 1000. The css z-index of the draggable item.
constraint 1.0 string, not set by default. If set to 'horizontal' or 'vertical' the drag will be constrained to take place only horizontally or vertically.
ghosting ?? boolean, defaults to false. Clones the element and drags the clone, leaving the original in place until the clone is dropped.
starteffect ?? Effect, defaults to Effect.Opacity. Defines the effect to use when the draggable starts being dragged.
reverteffect ?? Effect, default to Effect.Move. Defines the effect to use when the draggable reverts back to its starting position.
endeffect ?? Effect, defaults to Effect.Opacity. Defines the effect to use when the draggable stops being dragged.

Additionally, the options parameter accepts any of the following callback functions:

Callback Description
onStart Called when a drag is initiated.
onDrag Called repeatedly a mouse moves, if mouse position changed from previous call.
change Called just as onDrag (which is the preferred callback). Gets the Draggable instance as its parameter.
onEnd Called when a drag is ended.

Except for the change callback, each of these callbacks accepts two parameters: the Draggable object, and the mouse event object.


// revert
new Draggable('product_1', { revert: true });

// constrain direction and give a handle
new Draggable('my_div', { constraint: 'horizontal', handle: 'handle' });

To disable draggables later on, store it in a variable like:

var mydrag = new Draggable('product_1', { revert: true });
// then destroy it when you don't need it anymore

This way, you can enable and disable dragging at will.


A demo with the default options

A demo with { revert: true, snap: [40, 40] } set as options

Source code of the demo

Demo 1 (default options)

<div id="drag_demo_1" style="width:100px; height:100px; background:#7baaaed; border:1px solid #333;"></div>
  <script type="text/javascript">
    new Draggable('drag_demo_1');

Demo 2 (with revert and snap set)

<div id="drag_demo_2" style="width:100px; height:100px; background:#fff85d; border:1px solid #333;"></div>
  <script type="text/javascript">
    new Draggable('drag_demo_2', { revert: true, snap: [40, 40] });