Flexible jQuery Drag and Drop Sorting Plugin - Sortable

Flexible jQuery Drag and Drop Sorting Plugin - Sortable
File Size: 104 KB
Views Total:
Last Update:
Publish Date:
Official Website: Go to website
License: MIT
   

Sortable is a jQuery based plugin that allows you to drag and drop any items to sort them in any contains.

You might also like:

Features:

  • Drop animation support
  • Nested containers support
  • Current container highlighting support

Basic Usage:

1. Include jQuery library and jQuery.Sortable on your web page

<script src="http://ajax.googleapis.com/ajax/libs/jquery/1.9.1/jquery.min.js"></script>
<script src='source/js/jquery-sortable.js'></script> 

2. Markup

<ul class='example'>
<li>First</li>
<li>Second</li>
<li>Third</li>
</ul>

3. The CSS

body.dragging, body.dragging * {
cursor: move !important;
}
.dragged {
position: absolute;
opacity: 0.5;
z-index: 2000;
}
ul.example li.placeholder {
position: relative;/** More li styles **/
}
ul.example li.placeholder:before {
position: absolute;/** Define arrowhead **/
}

4. Call the plugin

$(function  () {
  $("ul.example").sortable()
})

5. Container options with defaults.

// If true, items can be dragged from this container
drag: true,

// If true, items can be droped onto this container
drop: true,

// Exclude items from being draggable, if the
// selector matches the item
exclude: "",

// If true, search for nested containers within an item.If you nest containers,
// either the original selector with which you call the plugin must only match the top containers,
// or you need to specify a group (see the bootstrap nav example)
nested: true,

// If true, the items are assumed to be arranged vertically
vertical: true

6. Group options with defaults.

// This is executed after the placeholder has been moved.
// $closestItemOrContainer contains the closest item, the placeholder
// has been put at or the closest empty Container, the placeholder has
// been appended to.
afterMove: function ($placeholder, container, $closestItemOrContainer) {
},
// The exact css path between the container and its items, e.g. "> tbody"
containerPath: "",
// The css selector of the containers
containerSelector: "ol, ul",
// Distance the mouse has to travel to start dragging
distance: 0,
// Time in milliseconds after mousedown until dragging should start.
// This option can be used to prevent unwanted drags when clicking on an element.
delay: 0,
// The css selector of the drag handle
handle: "",
// The exact css path between the item and its subcontainers.
// It should only match the immediate items of a container.
// No item of a subcontainer should be matched. E.g. for ol>div>li the itemPath is "> div"
itemPath: "",
// The css selector of the items
itemSelector: "li",
// The class given to "body" while an item is being dragged
bodyClass: "dragging",
// The class giving to an item while being dragged
draggedClass: "dragged",
// Check if the dragged item may be inside the container.
// Use with care, since the search for a valid container entails a depth first search
// and may be quite expensive.
isValidTarget: function ($item, container) {
  return true
},
// Executed before onDrop if placeholder is detached.
// This happens if pullPlaceholder is set to false and the drop occurs outside a container.
onCancel: function ($item, container, _super, event) {
},
// Executed at the beginning of a mouse move event.
// The Placeholder has not been moved yet.
onDrag: function ($item, position, _super, event) {
  $item.css(position)
},
// Called after the drag has been started,
// that is the mouse button is being held down and
// the mouse is moving.
// The container is the closest initialized container.
// Therefore it might not be the container, that actually contains the item.
onDragStart: function ($item, container, _super, event) {
  $item.css({
    height: $item.outerHeight(),
    width: $item.outerWidth()
  })
  $item.addClass(container.group.options.draggedClass)
  $("body").addClass(container.group.options.bodyClass)
},
// Called when the mouse button is being released
onDrop: function ($item, container, _super, event) {
  $item.removeClass(container.group.options.draggedClass).removeAttr("style")
  $("body").removeClass(container.group.options.bodyClass)
},
// Called on mousedown. If falsy value is returned, the dragging will not start.
// Ignore if element clicked is input, select or textarea
onMousedown: function ($item, _super, event) {
  if (!event.target.nodeName.match(/^(input|select|textarea)$/i)) {
    event.preventDefault()
    return true
  }
},
// The class of the placeholder (must match placeholder option markup)
placeholderClass: "placeholder",
// Template for the placeholder. Can be any valid jQuery input
// e.g. a string, a DOM element.
// The placeholder must have the class "placeholder"
placeholder: '<li class="placeholder"></li>',
// If true, the position of the placeholder is calculated on every mousemove.
// If false, it is only calculated when the mouse is above a container.
pullPlaceholder: true,
// Specifies serialization of the container group.
// The pair $parent/$children is either container/items or item/subcontainers.
serialize: function ($parent, $children, parentIsContainer) {
  var result = $.extend({}, $parent.data())

  if(parentIsContainer)
    return [$children]
  else if ($children[0]){
    result.children = $children
  }

  delete result.subContainers
  delete result.sortable

  return result
},
// Set tolerance while dragging. Positive values decrease sensitivity,
// negative values increase it.
tolerance: 0

7. Public methods.

// Enable all instantiated sortables in the set of matched elements
.sortable("enable")

// Disable all instantiated sortables in the set of matched elements
.sortable("disable")

// Reset all cached element dimensions
.sortable("refresh")

// Remove the sortable plugin from the set of matched elements
.sortable("destroy")

// Serialize all selected containers. 
// Returns a jQuery object . 
// Use .get() to retrieve the array, if needed.
.sortable("serialize")

Change log:

v0.9.13 (2014-06-28)

  • fix hovering over empty container
  • allow custom drag classes
  • support text areas inside sortables
  • fix drag with placeholder issue 
  • user outer dimensions for dragged item
  • support npm and bower
  • fix issue with legacy jQuery 1.10
  • fix for mobile chrome

v0.9.12 (2014-04-20)

  • expose mouse events in callbacks
  • add refresh method
  • add destroy method
  • add delay option
  • falsy return value in onMousedown prevents dragging
  • fix exclusion of items
  • fix ignore for select element (abixalmon)
  • fix touch events (prateekjadhwani)
  • fix itemPath issues (appending and dragInit)
  • improve documentation

v0.9.11 (2013-07-16)

  • option tolerance accepts negative values
  • rewrote enable/disable logic
  • added (item|container)Path

This awesome jQuery plugin is developed by johnny. For more Advanced Usages, please check the demo page or visit the official website.