jQueryUI Sortable

To re-order the elements in the list or grid form with the use of the mouse, the jQueryUI sortable() method is used. An operation string passed as the first parameter, is what the sorting ability of this method is based on.

Syntax:

The sortable() method can be used in two forms:

  1. $(selector, context).sortable (options) Method
  2. $(selector, context).sortable (“action”, params) Method

First Method:

To specify that an HTML element contains interchangeable elements, the sortable (options) method is used. The behavior of the elements involved during the process of reordering is specified by the options parameter.

Syntax:

$(selector, context).sortable (options);  

The popular options that can be used with this method are listed below:

Option Uses
appendto To specify the element in which the new element created with options.helper will be inserted during the time of the move/drag. The default value is parent.
axis To indicate an axis of movement (“x” is horizontal, “y” is vertical). The default value is false.
cancel To restrict the sorting of elements by clicking on any of the selector elements. The default value is “input,textarea,button,select,option”.
connectwith To identify another sortable element that can accept items from this sortable. The items are thus allowed from one list to be moved to other lists, a frequent and useful user interaction. No other element is connected, if omitted as it is a one-way relationship. The default value is false. It is a selector.
containment To indicate an element within which the displacement takes place. The selector thus represents the element (only the first item in the list will be considered), a DOM element, or the string “parent” (parent element) or “window” (html page).
cursor To define the cursor CSS property when the element moves, thus specifying the shape of the mouse pointer. The default value is “auto”.
cursorat To set the offset of the dragging helper relative to the mouse cursor. Using a combination of one or two keys, coordinates can be given as a hash: { top, left, right, bottom }. The default value is “false”.
delay To define the delay in milliseconds, after which the first movement of the mouse is taken into account and the displacement may begin after that time. The default value is “0”.
disabled To disable the sortable functionality, when set to true. The default value is false.
distance To indicate the number of pixels that the mouse must be moved before the sorting starts. Sorting will not start until after mouse is dragged beyond distance, when specified. The default value is “1”.
droponempty The items from this sortable can’t be dropped on an empty connect sortable, when set to false. The default value is true.
forcehelpersize To force the helper to have a size, when set to true. The default value is false.
forceplaceholdersize To take into account the size of the placeholder when an item is moved, when set to true. It is only useful if the options.placeholder is initialized. The default value is false.
grid To indicate the number of pixels that the sorting element moves horizontally and vertically during displacement of the mouse. The default value is false. It is an array [x, y].
handle To restrict the sort from starting unless the mousedown occurs on the specified element(s), when specified. The default value is false.
helper To be allowed for a helper element to be used for dragging display. The default value is original.
items To indicate which items inside the DOM element to be sorted. The default value is > *.
opacity To define the opacity of the helper while sorting. The default value is false.
placeholder To class name that gets applied to the otherwise white space. The default value is false.
revert To determine whether the sortable items should revert to their new positions using a smooth animation. The default value is false.
scroll To enable scrolling, thus the page scrolls when coming to an edge, when set to true. The default value is true.
scrollsenstivity To define the number of pixels the mouse must exit the visible area to cause scrolling. It is used only with options.scroll set to true. The default value is 20.
scrollspeed To define the scrolling speed of the display once the scrolling begins. The default value is 20.
tolerance To define the mode to use for testing whether the item being moved is hovering over another item. It is a string. The default value is “intersect”.
zIndex To specify the z-Index for element/helper while being sorted. The default value is 1000.

Example 1:

  
  
   jQuery UI Sortable - Example  
     
     
     
     
     
  
  

List to re-order

  • First
  • Second
  • Third
  • Fourth
  • Fifth
  • Sixth
  • Seventh

Output 1:

Output 2:

Explanation:

In the above example, we are displaying the sortable functionality. Here, we are passing no parameters to the sortable() method.

Example 2:

  
  
   jQuery UI Sortable - Example  
     
     
     
     
     
  
  
   

Delay by 1000ms

  • First
  • Second
  • Third
  • Fourth

Distance Delay by 150px

  • Fifth
  • Sixth
  • Seventh
  • Eighth

Output 1:

Output 2:

Explanation:

In the above example, we are displaying the usage of the delay and distance in jQuery UI sorting.

Example 3:

  
  
   jQuery UI Sortable - Example  
     
     
     
     
     
  
  

List to re-order

  • First
  • Second
  • Third
  • Fourth
  • Fifth
  • Sixth
  • Seventh

Output 1:

Output 2:

Output 3:

Explanation:

In the above example, we are displaying the use of the Placeholder in the sort() function of jQuery UI.

Example 4:

  
  
   jQuery UI Sortable - Example  
     
     
     
     
     
  
  
   

    Group A

  • First
  • Second
  • Third

    Group B

  • Fourth
  • Fifth
  • Sixth

    Group C

  • Seventh
  • Eighth
  • Ninth

Output 1:

Output 2:

Explanation:

In the above example, we are specifying the way to use the connectWith and the dropOnEmpty options in the sort function of the jQueryUI.

Second Method:

To act on the sortable elements, the sortable (action, params) method is used. It can be used to prevent displacement. Here, the first argument is the “action” which represents a string. One or multiple params can also be added based on the given action.

Syntax:

$(selector, context).sortable ("action", [params]);  

The popular actions used in this method are listed below:

Action Uses
cancel() To cancel the current sort operation. Within the handlers for the sort receive and sort stop events, it is very useful. No argument is accepted by this method.
destroy() To remove the sortability functionality completely, thus returning the element back to its pre-init state. No argument is accepted by this method.
disable() To disable the sortability of any sortable elements in the wrapped set. Only the sortability of the elements not removed is disabled which can be restored by calling the enable variant of this method. No argument is accepted by this method.
enable() To re-enable the sortability on any sortable elements in the wrapped set whose sortability has been disabled. It doesn’t add sortability to any non-sortable elements. No argument is accepted by this method.
option(optionName) To retrieve the value currently associated with the specified optionname. The name of the option to get is specified by the optionname.
option() To retrieve an object containing key/value pairs representing the current sortable options hash. No argument is accepted by this method.
option(optionName, value) To set the value of the sortable option associated with the specified optionname. The name of the option to set is specified by the optionname and the value to set for the option is specified by the value.
option(options) To set one or more options for the sortable. A map of option-value pairs to set is specified by the options parameter.
refresh() To refresh the list of items if necessary. It will be added to the sortable to be recognized, when called. No argument is accepted by this method.
toArray(options) To return an array of the id values of the sortable elements in sorted order. It takes options as parameter, to customize the serialization or sorted order.
serialize(options) To retrieve a serialized query string (submittable via ajax) formed from the sortable.
refreshPositions() To refresh the cached information of the sortable. It is used mostly internally. No argument is accepted by this method.
widget() To retrieve a jquery object containing the sortable element. No argument is accepted by this method.

Example 5:

  
  
   jQuery UI Sortable - Example  
     
     
     
     
     
  
  
   
  • First
  • Second
  • Third
  • Fourth
  • Fifth
  • Sixth
  • Seventh

Output 1:

Output 2:

Explanation:

In the above example, we are displaying the use of the toArray (options) method. Here, the ID of each item of the list is displayed in their respective sequence of appearance. The sequence of the ID also changes, each time the items are reordered in the list.

Event Management:

Event methods are also provided by the jQueryUI sortable method. Each event method can be triggered for a particular event.

The popular event methods are listed below:

Event Method Uses
activate(event, ui) Triggered when a sort operation starts on connected sortable.
beforestop(event, ui) Triggered when the sort operation is about to end, with the helper and placeholder element reference still valid.
change(event, ui) Triggered when the sorted element changes position within the dom.
create (event, ui) Triggered when the sortable is created.
deactivate (event, ui) Triggered when a connected sort stops, propagated to the connected sortable.
out(event, ui) Triggered when the sort item is moved away from a connected list.
over(event, ui) Triggered when a sort item moves into a connected list.
receive(event, ui) Triggered when a connected list has received a sort item from another list.
remove(event, ui) Triggered when the sort item is removed from a connected list and is dragged into another.
sort(event,ui) Repeatedly triggered for mousemove events during a sort operation.
start(event,ui) Triggered when a sort operation starts.
stop(event,ui) Triggered when a sort operation has concluded.
update(event, ui) Triggered when a sort operation stops and the position of the item has been changed.

Example 6:

  
  
   jQuery UI Sortable - Example  
     
     
     
     
     
  
  
   

Group A

  • First
  • Second
  • Third
  • Fourth
  • Fifth

ID

  • #1
  • #2
  • #3
  • #4
  • #5

Output 1:

Output 2:

Explanation:

In the above example, we are displaying the use of the event receive, start and stop during drop functionality. The start event is triggered every time a sort operation starts and thus a string “START” is displayed on the screen as the result of the event triggering. Similarly, the stop event is triggered every time a sort operation reach its conclusion and thus a string “STOP” is displayed on the screen as the result of the event triggering.