Web Development with jQuery (2015)
Part IV. Appendices
Appendix K. Sortable
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. |
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). |
jQuery |
axis |
If specified, the items can be dragged only along either the X- or Y-axis. Only allows the values 'x' or 'y'. |
String |
cancel |
Prevents sorting from the beginning on elements that match the selector. |
Selector |
connectWith |
A selector that references other sortable elements you'd like to connect a sortable with. |
Selector |
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'. |
Element |
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. |
String |
cursorAt |
Specifies coordinates for the cursor that should be shown while sortable elements are being dragged. |
Object |
delay |
Defines a delay time in milliseconds (ms), which helps to prevent unwanted drags. |
Integer |
disabled |
Whether or not the sortable is disabled. |
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. |
Integer |
dropOnEmpty |
If set to true, this option allows a sortable item to be dropped from a linked selectable. |
Boolean |
forceHelperSize |
If the value provided is true, this option forces the helper element to have a size. |
Boolean |
forcePlaceholderSize |
If true, this option forces the placeholder for the sortable to have a size. |
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]. |
Array |
handle |
Restricts sorting from starting unless it begins on the specified element. |
Selector |
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. |
Element |
items |
Which items sorting should be applied to. |
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). |
Float |
placeholder |
Applies a class name to the placeholder element (which would otherwise be empty white space). |
String, |
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. |
Boolean, |
scroll |
This option causes the page to scroll when a dragged element comes to an edge. |
Boolean |
scrollSensitivity |
This option defines how close to an edge a dragged element must be before scrolling occurs. Measured in pixels. |
Number |
scrollSpeed |
This option defines the speed that the container is scrolled. |
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'. |
String |
zIndex |
The z-index for the drag element. |
Integer |
Events |
||
activate |
A function that executes when a drag on a sortable item begins. This function propagates to all connected lists. |
function(event, ui) |
beforeStop |
A function that executes when sorting ends, but while the placeholder or helper is still available. |
function(event, ui) |
change |
A function that executes when a change in sorting takes place. |
function(event, ui) |
create |
A function that executes when a sortable is created. |
function(event, ui) |
deactivate |
A function that executes when sorting ends. This function propagates to all connected lists. |
function(event, ui) |
out |
A function that executes when a sortable item is moved out of the boundaries of a sortable list. |
function(event, ui) |
over |
A function that executes when an item is moved over a connected list. |
function(event, ui) |
receive |
A function that executes when an item from this sortable list is dragged to a connected (separated) sortable list. |
function(event, ui) |
remove |
A function that executes when an item from this sortable list is dragged to a connected (separated) sortable list. |
function(event, ui) |
sort |
A function that executes while sorting is taking place. |
function(event, ui) |
start |
A function that executes when sorting begins. |
function(event, ui) |
stop |
A function that executes when sorting ends. |
function(event, ui) |
update |
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. |
String |
expression |
A regular expression used to extract a string from within the attribute value. |
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 |