Web Development with jQuery (2015)

Sortable Methods

Method

Description

Return Value

sortable(options)

Makes the selected element(s) sortable. Options can be specified by passing an object literal as the first argument using key, value pairs. For a complete list of options, see the “Sortable Options” section later in this appendix.

jQuery

sortable('cancel')

Cancels a change in the state of a sortable and reverts it back to what it was prior to sorting.

jQuery

sortable('destroy')

Completely removes sortable functionality from the selected element(s).

jQuery

sortable('disable')

Disables sortable functionality on the selected element(s).

jQuery

sortable('enable')

Enables sortable functionality on the selected element(s).

jQuery

sortable('option', optionName)

Returns the value of the specified option.

Mixed

sortable('option')

Returns an object containing all values of all options.

Object

sortable('option', optionName,optionValue)

Sets the specified option to the specified value.

jQuery

sortable('option', object)

Sets the specified options to the specified values by providing an object representing all of the options you'd like to set.

jQuery

sortable('refresh')

Refreshes the sortable items.

jQuery

sortable('refreshPositions')

Refreshes the cached positions of sortable items.

jQuery

sortable('serialize', options)

Returns a string of serialized IDs for each sortable item, which can then be used in an AJAX request or input form. For a complete list of options, see the “Serialize Options” section later in this appendix.

String

sortable('toArray', options)

Serializes all the sortable items' element id properties into an array.
An object of options can be provided in the second argument; the only option that can be customized is changing which attribute is used.
{
attribute : 'data-custom'
}

Array

sortable('widget')

Returns a jQuery object that contains the sortable element.

jQuery

Sortable Options

Option

Description

Type

appendTo

Defaults to the parent; defines where the helper that moves with the mouse is being appended to during the drag (for example, to resolve overlap/zIndex issues).
Default value: 'parent'

jQuery
Element
Selector
String

axis

If specified, the items can be dragged only along either the X- or Y-axis. Only allows the values 'x' or 'y'.
Default value: false

String
Boolean

cancel

Prevents sorting from the beginning on elements that match the selector.
Default selector: "input, textarea, button, select, option"

Selector

connectWith

A selector that references other sortable elements you'd like to connect a sortable with.
Default value: false

Selector
Boolean

containment

Constrains the dragging of sortable elements within the bounds of the specified or selected element. If using a string, the possible values are 'parent', 'document', and 'window'.
Default value: false

Element
Selector
String
Boolean

cursor

Specifies the cursor that should be shown while sortable elements are being dragged. The string provided should be a value suitable for the CSS cursor property.
Default value: 'auto'

String

cursorAt

Specifies coordinates for the cursor that should be shown while sortable elements are being dragged.
Default value: false

Object

delay

Defines a delay time in milliseconds (ms), which helps to prevent unwanted drags.
Default value: 0

Integer

disabled

Whether or not the sortable is disabled.
Default value: false

Boolean

distance

A tolerance in pixels, for where the threshold sorting should take place. If this option is specified, sorting won't take place until the mouse cursor is dragged beyond the specified distance.
Default value: 1

Integer

dropOnEmpty

If set to true, this option allows a sortable item to be dropped from a linked selectable.
Default value: true

Boolean

forceHelperSize

If the value provided is true, this option forces the helper element to have a size.
Default value: false

Boolean

forcePlaceholderSize

If true, this option forces the placeholder for the sortable to have a size.
Default value: false

Boolean

grid

Snaps the dragging element/helper to a grid, every x and y pixels, where x and y are specified as an Array [x, y].
Default value: false

Array

handle

Restricts sorting from starting unless it begins on the specified element.
Default value: false

Selector
Element

helper

This option allows a helper element to be displayed while dragging is taking place. If a callback function is specified, it should return a valid DOM node that can be used for display.
Default value: 'original'

Element
function(event, element)

items

Which items sorting should be applied to.
Default value: '> *'

Selector

opacity

Defines the opacity of the helper while sorting using a CSS opacity value, where 0 is fully transparent, 1 is fully opaque, and floating points between are semitransparent. For example, 0.5 would be half-transparent (or half-opaque).
Default value: 1

Float

placeholder

Applies a class name to the placeholder element (which would otherwise be empty white space).
Default value: false

String,
Boolean

revert

This option triggers the dragged item to be reverted back to its original position using a smooth animation. If the value provided is true, a default animation is used. If a number is provided, it represents the duration in milliseconds.
Default value: true

Boolean,
Number

scroll

This option causes the page to scroll when a dragged element comes to an edge.
Default value: true

Boolean

scrollSensitivity

This option defines how close to an edge a dragged element must be before scrolling occurs. Measured in pixels.
Default value: 20

Number

scrollSpeed

This option defines the speed that the container is scrolled.
Default value: 20

Number

tolerance

This option defines what mode to use to determine whether a dragged element is above another item. The possible values are 'intersect' and 'pointer'.
Default value: 'intersect'

String

zIndex

The z-index for the drag element.
Default value: 1000

Integer

Events

activate
bind('sortactivate')
on('sortactivate')

A function that executes when a drag on a sortable item begins. This function propagates to all connected lists.

function(event, ui)

beforeStop
bind('sortbeforestop')
on('sortbeforestop')

A function that executes when sorting ends, but while the placeholder or helper is still available.

function(event, ui)

change
bind('sortchange')
on('sortchange')

A function that executes when a change in sorting takes place.

function(event, ui)

create
bind('sortcreate')
on('sortcreate')

A function that executes when a sortable is created.

function(event, ui)

deactivate
bind('sortdeactivate')
on('sortdeactivate')

A function that executes when sorting ends. This function propagates to all connected lists.

function(event, ui)

out
bind('sortout')
on('sortout')

A function that executes when a sortable item is moved out of the boundaries of a sortable list.

function(event, ui)

over
bind('sortover')
on('sortover')

A function that executes when an item is moved over a connected list.

function(event, ui)

receive
bind('sortreceive')
on('sortreceive')

A function that executes when an item from this sortable list is dragged to a connected (separated) sortable list.

function(event, ui)

remove
bind('sortremove')
on('sortremove')

A function that executes when an item from this sortable list is dragged to a connected (separated) sortable list.

function(event, ui)

sort
bind('sort')
on('sort')

A function that executes while sorting is taking place.

function(event, ui)

start
bind('sortstart')
on('sortstart')

A function that executes when sorting begins.

function(event, ui)

stop
bind('sortstop')
on('sortstop')

A function that executes when sorting ends.

function(event, ui)

update
bind('sortupdate')
on('sortupdate')

A function that executes when sorting ends and the DOM position of the dragged element has changed.

function(event, ui)

Serialize Options

Option

Description

Type

attribute

The attribute value that is retrieved from each sortable element.
Default: id

String

expression

A regular expression used to extract a string from within the attribute value.
Default: /(.+)[-=_](.+)/

Regular Expression

key

The key in the URL hash. If not specified, it takes the first result of the expression.

String

UI Object

Property

Description

Type

ui.helper

A jQuery object representing the helper for the element being sorted.

jQuery

ui.item

A jQuery object representing the element being dragged.

jQuery

ui.offset

The absolute position of the helper element represented as an object with properties top and left.

Object

ui.position

The position of the helper element represented as an object with the properties top and left.

Object

ui.originalPosition

The original position of the element represented as an object with the properties top and left.

Object

ui.sender

A jQuery object containing the original sortable element, if the item is being moved to a different sortable element.

jQuery

ui.placeholder

A jQuery object representing the placeholder element, if one is in use.

jQuery