Sortables

Behaviours > Sortable

A Sortable consists of item elements in a container element. When you create a new Sortable, it takes care of the creation of the corresponding Draggables and Droppables.

Creating Sortables

Syntax


Sortable.create('id_of_container',[options]);

Options

Option Description
tag string, represents a tagname, defaults to 'li', sets the kind of tag (of the child elements of the container) that will be made sortable. For UL and OL containers, this is ‘li’, you have to provide the tag kind for other sorts of child tags.
only Further restricts the selection of child elements to only encompass elements with the given CSS class (or, if you provide an array of strings, on any of the classes).
overlap string, defaults to 'vertical', can also be ‘horizontal’. For floating sortables or horizontal lists, choose ‘horizontal’. Vertical lists should use ‘vertical’.
constraint string, defaults to 'vertical', restricts the movement of Draggables, see the constraint option of Draggable.
containment Enables dragging and dropping between Sortables. Takes an array of elements or element-ids (of the containers). Important note: To ensure that two way dragging between containers is possible, place all Sortable.create calls after the container elements.
handle Makes the created Draggables use handles, see the handle option on Draggable.
hoverclass Gives the created Droppables a hoverclass (see Droppables).
ghosting boolean, defaults to false, if set to true, dragged elements of the Sortable will be cloned and appear as “ghost”, i.e. a representation of their original element, instead of directly dragging the original element.
dropOnEmpty boolean, defaults to false, if set to true, the Sortable container will be made into a Droppable, that can receive a Draggable (as according to the containment rules) as a child element when there are no more elements inside.
scroll When the sortable is contained in an element with style overflow:scroll, this value can be set to the ID of that container (or the container’s DOM object). The scroll position of the container will now move along when the sortable is dragged out of the viewable area. The container must have overflow:scroll set to include scroll bars.
scrollSensitivity Will start scrolling when element is x pixels from the bottom, where x is the scrollSensitivity.
scrollSpeed Will scroll the element in increments of scrollSpeed pixels.
tree boolean, defaults to false, if true, sets sortable functionality to elements listed in treeTag
treeTag string, defaults to 'ul', the element type tree nodes are contained in.

Callbacks

Callback Description
onChange Called whenever the sort order changes while dragging. When dragging from one Sortable to another, the callback is called once on each Sortable. Gets the affected element as its parameter.
onUpdate Called when the drag ends and the Sortable’s order is changed in any way. When dragging from one Sortable to another, the callback is called once on each Sortable. Gets the container as its parameter. Note that the id attributes of the elements contained in the Sortable must be named as described in Sortable.serialize

Notes

You can use Sortable.create on any container element that contains Block Elements, with the exception of TABLE, THEAD, TBODY and TR. This is a technical restriction with current browsers.
A sortable nested somewhere inside a table won’t work well under IE unless the table has a position:relative style. If you use the CSS display: table property, sortable lists will work a little, but doesn’t allow true drag and drop of the elements.

If you want your sortable list to be scrollable, wrap the list in a div and set the div to scrollable as apposed to making the ul element scrollable. Also, in IE you must set position:relative on the scrollable div.

Serializing Sortables

The Sortable object also provides a function to serialize the Sortable in a format suitable for HTTP GET or POST requests. This can be used to submit the order of the Sortable via an Ajax call.

Syntax


var poststring = Sortable.serialize('id_of_container',[options]);
// poststring now contains key[]=value pairs separated by &

Important: For this to work, the elements contained in your Sortable must have id attributes in the following form:


id="string_identifier" 
// example: id="image_1"

Only the identifier part of the id attribute will be serialized. If you want to use an other form of id attributes, you need to implement your own serialization.

Options

Option Description
tag string, defaults to the tag originally used when calling Sortable.create, Sets the kind of tag (of the child elements of the container) that will be serialized.
name string, defaults to id of the container, sets the name of the key that will be used to create the key/value pairs for serializing in HTTP GET/POST format (that is, key[]=value&key[]=value …)

Disabling Sortables

Use Sortable.destroy to completely remove all event handlers and references to a Sortable created by Sortable.create. It does not remove or alter the referenced element in any other way.

Syntax


Sortable.destroy(element);

Notes

A call to Sortable.create implicitly calls on Sortable.destroy if the referenced element was already a Sortable.