jquery.event.drag

A jquery special event plugin that makes the task of adding complex
drag interactions, to any element, simple and powerful.

Overview

The plugin works by using standard DOM events, and simulating custom
events to create a drag interaction. It simplifies a recurring
pattern of event interaction that can be fairly complex to design in a
consistent, cross-browser manner. The drag interaction, while simple
in most basic form, gets quite complex when introduced with issues of
distance, handles, text selection, proxy elements, click suppression,
and dropping.

This plugin is focused on correctly simulating the drag events in a very
usable way. This plugin does not add classnames, does not alter the position
or appearance of any elements, and does not alter the DOM. This plugin only
provides the essential callbacks at the correct points in the interaction
model to enable developers to have complete control over the interactions
that they create. This reduces the file size, eliminates dependencies,
and increases performance.

Events

A basic drag interaction starts when a user presses down a mouse button
with the cursor inside an element (mousedown), continues while the user
moves the mouse (mousemove), and ends when the user releases the mouse
button (mouseup). The standard DOM events (mousedown, mousemove,
mouseup) loosely translate into the special drag events. This plugin takes
these DOM events and triggers the following events at key points in the
interaction. None of these drag events bubble.

draginit
This event is fired when a mouse button is pressed (mousedown) within
the bound element. The handler can return false to cancel the rest of
the drag interaction events, or can return elements to use as the drag
targets for the rest of the drag interaction. This event will not fire
unless the options "not", "handle", and "which" are all satisfied.

dragstart
This event fires after "draginit", once the mouse has moved a minimum
"distance", which may be specificed in the options. The handler can
return false to cancel the rest of the drag interaction events, or can
return an element to set as the drag proxy for the rest of the drag
interaction. If dragging multiple elements (from "draginit"), this
event will fire uniquely on each element.

drag
This event fires after "draginit" and "dragstart" every time the mouse
moves. The handler can return false to stop the drag interaction and go
straight to "dragend" and also prevent any "drop" events. If dragging
multiple elements (from "draginit"), this event will fire uniquely on
each element.

dragend
This event fires after "draginit" and "dragstart" and "drag" when the
mouse button is released, or when a "drag" event is canceled. This event
will always fire after any "drop" events. If dragging multiple elements
(from "draginit"), this event will fire uniquely on each element.

This plugin also supports "live" event delegation... sort of. When a live event
gets bound, the plugin automatically adds a "draginit" event which makes the
interaction work correctly. It checks the event target element against any live
handlers, any matching ones get attached to the target element. After the
interaction is complete, the handlers get cleaned up. The most important point
to take from this is that live "draginit" events will not work correctly.

Methods

In the interest of maintaining consistency with the jQuery API, a helper
method has been added as shorthand for binding and triggering "drag"
event handlers. The previous version of this plugin allowed this method
to be overloaded with arguments to additionally bind handlers for
"dragstart" and "dragend" in a single call, but this is no longer supported.
Instead, an optional type argument may be included to bind or trigger the
related events (the "drag" prefix is optional). Options may also be included
as the final argument and are optional.

Options

All of these settings are optional, and may be passed in through the
"data" argument in the jQuery "bind" method, or the "options" argument
in the jQuery "drag" method.

which(Number)Default: 1
A number that matches the "which" event property to indicate the
mousebutton that is pressed. (0 = Any Button, 1 = Left Button,
2 = Middle Button, 3 = Right Button)

distance(Number)Default: 0
A number representing the length of pixels that the mouse must move
before the "dragstart" event may fire.

not(String)Default: ":input"
A jquery selector expression that matches elements where dragging
is not allowed to begin.

handle(String)Default: NULL
A jquery selector expression that matches elements where dragging
is allowed to begin.

relative(Boolean)Default: FALSE
A boolean to indicate whether to use element position relative to the
document or the offset parent. This setting affects the values offsetX,
offsetY, originalX, and originalY. (FALSE = Position Relative to the Document)

click(Boolean)Default: FALSE
A boolean to indicate whether or not "click" events are allowed to fire
after the "dragend" event. (FALSE = No Click)

drop(Boolean|String)Default: TRUE
A boolean to indicate whether or not "drag" events are considered in
the drag interaction, or a jquery selector expression that should filter
and match a subset of the registered drop targets. (FALSE = No Dropping,
TRUE = Drop Anywhere, ":expr" = Drop in targets that match this expression)

The default values are stored in the jQuery.event.special.drag.defaults object.

Properties

The following properties belong to a dragdrop callback object which is
passed as the second argument to each event handler, unique to each
dragged element, and shared throughout the drag interaction.

target(Element)
The drag element, or the drop element, to which the event handler has
been bound. (Always the same as "this" within an event handler)

drag(Element)
The dragged element for the given interaction to which the drag event
has been bound.

proxy(Element)
The dragged element, or any element returned by the "dragstart" handler.
The proxy element is used to determine the drop target tolerance.

drop(Array)
Contains all of the active drop targets for the current interaction.

available(Array)
Contains all of the available drop targets for the current interaction.

update(Function)
A helper function which updates the locations of all of the available
drop targets for the current interaction.

startX(Number)
The horizontal location of the "mousedown" event.

startY(Number)
The vertical location of the "mousedown" event.

deltaX(Number)
The horizontal distance moved from "startX".

deltaY(Number)
The vertical distance moved from "startX".

originalX(Number)
The starting horizontal position of the drag "target" element.

originalY(Number)
The starting vertical position of the drag "target" element.

offsetX(Number)
The the moved horizontal position of the drag "target" element.

offsetY(Number)
The the moved vertical position of the drag "target" element.

The callback object is extensible. You can add any property within one event
handler and it will be available in any other event handlers that follow (per
dragged element). Additional properties or methods can be added to
jQuery.event.special.drag.callback.prototype
and will be available in all event handlers for all elements.

Demos

The following examples are intended to show how the drag special events can be
configured to acheive a wide range of features for any drag interaction. I have
simplified each demo as much as possible, to really highlight the core of each
feature. If you have any problems, or want to suggest a new feature, or a new
demo, please contact me via the
ThreeDubMedia Google Group.

Basic
One of the simplest ways to create a drag interaction, with the "drag" method.