jquery.udraggable.js

This plugin provides an API similar to jQueryUI's draggable but with support for unified mouse and touch events. It builds on Michael S. Mikowski's jquery.event.ue unified event plugin.

Zip Tar Git

Introduction

Caveats

Reference Documentation

Options
Methods

Examples

Introduction

The udraggable plugin allows you to make elements draggable with a single line of code and to use a declarative syntax to define the constraints of the dragging behaviour.

$('#star').udraggable({});

See the examples page for more complex scenarios.

The plugin is dual-licensed under the MIT and GPL licences.

Caveats

This plugin is much simpler and therefore much less capable than jQueryUI's draggable widget. It aims to provide a minimum useful subset rather than attempting to clone the full range of behaviours supported by jQueryUI. However some of the limitations can be worked around quite simply.

Positioning: The plugin will give best results when the draggable elements and their parent container elements are both positioned using either absolute or relative positioning.

Scrolling: Dragging (or 'swiping') is used to scroll on touch devices. This can lead to conflict when some user interactions are intended to scroll and some are intended to drag specific elements. The jquery.event.ue plugin effectively disables scrolling on touch devices. This can work fine if the web application fills the full screen and uses touch/mouse events to adjust element positioning to achieve scrolling. This page and the associated example pages use an experimental modified version of the plugin which supports both scrolling and dragging (test by dragging the star above).

Auto-scrolling: If you drag an element outside the current viewport, the jQueryUI draggable can automatically scroll the page to bring the element back into view. This plugin does not support auto-scrolling. You can use the drag option to supply your own function to adjust the scroll position.

Selection: When dragging an element, the click-drag-release sequence can have the side-effect of selecting text in the vicinity. To avoid the visual flash, you can set the CSS property "user-select: none". Alternatively, the experimental version of the jquery.event.ue plugin (linked above) also seems to fix this issue.

Reference Documentation

Methods

destroy
disable
enable
option

Options

When the udraggable function is called, you can provide option name/value pairs as an object literal like this:

$(selector).udraggable({opt1: value1, opt2: value2});

Name	Description
`axis`	A string value: either `"x"` or `"y"`. The drag operation will be constrained to the specified axis.
`containment`	This option is used to specify an area within which the drag operation should be contained. Acceptable values are the string `"parent"` or an array of pixel offset values defining a rectangle: `[left, top, right, bottom]`. `"parent"` refers to the 'offset parent' - the closest ancestor element that is positioned. The draggable element is assumed to be positioned relative to its offset parent element (see "caveats" above) and if the array of offsets is used, the values are relative to the offset parent. Note: it does make sense in some circumstances for the 'top' and 'left' values to be negative numbers.
`delay`	A delay value in milliseconds before the drag operation will commence. This is one way to reduce the chance of a drag operation being triggered accidentally by tapping or clicking on an element (see also `distance`).
`drag`	This option allows you to specify a callback function that will be invoked as the element is dragged. The function will be passed an `event` object and a `ui` object. Your function will be called after the position of the element has been adjusted.
`distance`	A distance value in pixels that the pointer must be moved before the drag operation will commence. This is one way to reduce the chance of a drag operation being triggered accidentally by tapping or clicking on an element (see also `delay`).
`getStartPosition`	You can use this option to replace the code that calculates the initial position of the element before the drag begins. The default implementation simply reads the `top` and `left` CSS properties. The function you provide will be passed the target element in a jQuery wrapper. Note: this option is not supported by the jQueryUI draggable.
`grid`	An array of two integers (`[x, y]`) specifying the pixel size of a grid that should be used to constrain the drag and give it a snap-to-grid behaviour.
`handle`	Optional selector for a child element to be used as a drag handle. A drag will not start unless the initial mousedown / touchstart event occurs on the selected element(s).
`longPress`	Specify a boolean `true` value if the drag should require a "long press" to start (i.e. press and hold before starting the drag). Note: this option is not supported by the jQueryUI draggable.
`positionElement`	You can use this option to replace the code that positions the element at each step of the drag. The default implementation positions the element by adjusting its `top` and `left` CSS properties. The function you provide will be passed 4 arguments: `$el` — the element to be positioned (jQuery wrapped) `dragging` — boolean indicating whether a drag is in process, this value will be false for the final update in a drag `x` — the new x (left) position `y` — the new y (top) position Note: this option is not supported by the jQueryUI draggable.
`start`	This option allows you to specify a callback function that will be called once when the drag operation begins (i.e.: after the `delay` and/or `distance` constraints have been met. The function will be passed an `event` object and a `ui` object.
`stop`	This option allows you to specify a callback function that will be called once when the drag operation completes. The function will be passed an `event` object and a `ui` object.

When the callback functions (start, drag, stop) are called, they will be passed two arguments. The first is an event object as provided by jquery.event.ue and the second is an object containing the following properties:

Property	Description
`helper`	a jQuery object containing the dragged element
`offset`	an object specifying the current `top` and `left` offsets of the dragged element.
`originalPosition`	an object specifying the `top` and `left` offsets of the dragged element before the drag operation began.
`position`	an object specifying the current `top` and `left` offsets of the dragged element.

Methods

After the widget has been initialised, you can reference it again using the same selector and call a method like this:

$(selector).udraggable('method-name', args);

Name	Description
`destroy`	This method will completely remove the `udraggable` behaviour from the target element. The element position will be left unchanged.
`disable`	This method will temporarily disable the `udraggable` behaviour on the target element. A later call to the `enable` method will restore the behaviour with the original options.
`enable`	This method will restore the `udraggable` behaviour on a target element that was turned off with the `disable` method.
`option`	This method allows you to get or set option values after the `udraggable` behaviour has been applied to an object. If called with no arguments, the current option names and values will be returned as an object. If called with two arguments, the first is assumed to be the name of the option you wish to change and the second is the new value for that option. If called with a single argument, it is assumed to be an object containing all the names and values of options you wish to change.

Examples

Example 1 - Options: Various examples demonstrating a range of different option settings to change drag constraints.
Example 2 - Methods: Examples demonstrating method calls to alter the udraggable behaviour after initial setup.
Example 3 - TKS-Web: The TKS-Web application is a web-based timesheeting system that uses jquery.udraggable.js to facilitate dragging and resizing activities on a calendar-style week view.