jQuery: The Write Less, Do More JavaScript Library

UI/Sortables/sortable

From jQuery JavaScript Library

Jump to: navigation, search

« Back to UI/Sortables

sortable( options )

Creates new sortable on the nodeset supplied by the query.
This jQuery plugin makes DOM nodes sortable by mouse. You can additionally supply a great range of options to make them fit your needs.

All callbacks receive two arguments: The original browser event and a prepared ui object, view below for a documentation of this object (if you name your second argument 'ui'):

  • ui.instance - the internal instance of the sortable
  • ui.options - options used to initialize the sortable
  • ui.position - current position of the helper
  • ui.absolutePosition - current absolute position of the helper
  • ui.helper - the current helper element (most often a clone of the item)
  • ui.placeholder - the placeholder (if you defined one)
Arguments:
optionsOptions
A set of key/value pairs that configure the sortable. All options are optional.

Options:
NameType
itemsSelector
Items to apply sorting to. Default: '> *'.
connectWithArray
Takes an array of jQuery selectors that also have sortables applied. If used, the sortable is now connected to the other one-way, so you can drag from this sortable to the other.
handleSelector, Element
See draggable options for an explanation.
helperElement function()
Allows for a helper element to be used for dragging display. The supplied function should return a valid DOM node to be used as a custom proxy helper.
revertBoolean
If set to true, the item will be reverted to its new DOM position with a smooth animation. Default: true.
axis"x"/"y"
If defined, the items can be dragged only horizontally or vertically.
scrollBoolean
If set to true, the page scrolls when coming to an edge. Default: true.
scrollSpeedInteger
Defines how many pixels the page will scroll when coming to an edge. Default: 20.
scrollSensitivityInteger
Defines how near the mouse must be to an edge to start scrolling. Default: 20.
containmentString
Constrains dragging to within the bounds of the specified element. Possible values: 'parent', 'document', jQuery String.
zIndexInteger
z-index for element/helper while being sorted.
cursorString
Defines the cursor that is being shown while sorting.
opacityInteger
Defines the opacity of the helper while sorting.
placeholderString
Class that gets applied to the otherwise white space.
startfunction(e, ui)
Function that gets called when sorting starts.
stopfunction(e, ui)
Function that gets called when sorting stops.
updatefunction(e, ui)
Function that gets called when the user stopped sorting and the DOM position has changed.
sortfunction(e, ui)
Function that gets called during sorting.
changefunction(e, ui)
Function that gets called during sorting, but only when the DOM position has changed.


sortable( "disable" )

Temporarily disable the sortable functionality.
This method temporarily disables sortable functionality. It can later be reenabled by calling $(..).sortable("enable").
Arguments:
"disable"String

sortable( "enable" )

Enable the sortable functionality.
This method re-enables a previously disabled sortable.
Arguments:
"enable"String

sortable( "destroy" )

Completely remove the sortable functionality.
This method removes the sortable functionality completely.
Arguments:
"destroy"String

sortable( "serialize", options )

Serializes the sortable's item id's into a form/ajax submittable string.
Calling this method produces a hash that can be appended to any url to easily submit a new item order back to the server.

It works by default by looking at the id of each item in the format 'setname_number', and it spits out a hash like "setname[]=number&setname[]=number".

You can also give in a second argument to custom define how the function works.
Arguments:
"serialize"String
optionsHash
a key/value hash defining how serialize works.

Options:
NameType
attributeString
the attribute that is parsed. Default: 'id'.
expressionRegexp
the expression used to parse the attribute. The default expression used is "(.+)[-=_](.+)".
keyString
The key in the url hash. If not specified, it will take the first result of the expression.


sortable( "refresh" )

Refresh the sortable items.
Custom trigger the reloading of all sortable items, causing new items to be recognized.
Arguments:
"refresh"String

sortable( "refreshPositions" )

Refresh the cached positions of the sortables' items.
Calling this method refreshs the cached item positions of all sortables. This is usually done automatically by the script and slows down performance. Use wisely.
Arguments:
"refreshPositions"String