• If you are citizen of an European Union member nation, you may not use this service unless you are at least 16 years old.

  • You already know Dokkio is an AI-powered assistant to organize & manage your digital files & messages. Very soon, Dokkio will support Outlook as well as One Drive. Check it out today!

View
 

Sortable

This version was saved 15 years, 2 months ago View current version     Page history
Saved by Paul Bakaus
on January 20, 2009 at 11:26:23 am
 

 

type: interaction

release: 1.0

priority: -

status: complete

documentation: http://docs.jquery.com/UI/Sortables

demo: http://ui.jquery.com/demos/sortable

 


 

1 - Description:

 

Sortables gives any HTML element the ability to be dragged and dropped to re-order them.

 


 

2 - Visual Design:

 

N/A

 


 

 

3 - Functional Specifications/Requirements:

 

Options/Methods/Callbacks

  • options:
    • accurateIntersection (boolean, default: true)
    • appendTo (string[selector] or 'parent', default: 'parent')
    • cancel (string[selector], default: ':input, option')
    • connectWith (array with strings[selector], default: false)
    • delay (integer, default: 0)
    • distance (integer, default: 1)
    • dropOnEmpty (boolean, default: true)
    • forcePlaceholderSize (boolean, default: false)
    • forceHelperSize (boolean, default: false)
    • helper ('original', 'clone' or function returning a valid node, default: 'original')
    • items (string[selector], default: 'original')
    • placeholder (string, default: false)
    • scope (string, default: 'default')
    • scroll (boolean, default: true)
    • scrollSensitivity (integer, default: 20)
    • scrollSpeed (integer, default: 20)
    • sortIndicator (function, default: $.ui.sortable.prototype._rearrange)
    • tolerance ('intersect' or 'pointer', default: 'intersect')
    • zIndex (integer or false, default: 1000)
  • methods:
    • sortable('refresh' [, event])
    • sortable('refreshPositions' [, justPositions = bool])
    • sortable('serialize' [, options])
      • options.connected (boolean, default: false)
      • options.item (string[selector], default: [[current element]])
      • options.expression (regexp, default: /(.+)[-=_](.+)/)
      • options.key (string, default: [[$1 of options.expression]])
    • sortable('toArray' [, options])
      • options.connected (boolean, default: false)
      • options.item (string[selector], default: [[current element]])
      • options.attribute (string, default: 'id')
    • sortable('cancel')
  • callbacks:
    • start (event: mousedown)
    • activate (event: mousedown)
    • deactivate (events: mousemove, mouseup)
    • change (event: mousemove)
    • sort (event: mousemove)
    • over (event: mousemove)
    • out (events: mousemove, mouseup)
    • receive (event: mouseup)
    • update (event: mouseup)
    • remove (event: mouseup)
    • beforeStop (event: mousemove, mouseup)
    • stop (event: mousemove, mouseup)
  • 'ui' object:
    • helper (object[jQuery])
    • placeholder (object[jQuery])
    • position (hash with top/left integers)
    • absolutePosition (hash with top/left integers)
    • item (object[jQuery])
    • sender (object[jQuery] or null)

 

Specifications

  • returning false from any user callback cancels the actual sortable (which means it reverts everything to the state before the drag)
  • The positioning logic is exactly the same than draggable's with the exception that the helper has to always be 'absolute'
  • option 'helper'
    • original: the current clicked item keeps its DOM position but is positioned absolute and used as the drag helper. A placeholder is moved in the DOM instead. At mouseup, the placeholder and current item switch DOM positions and position absolute is removed again from the helper.
    • clone: the current clicked item is cloned and the original item is hidden during drag, again the placeholders DOM position moves during the drag, not the helpers, and at mouseup they are toggled.
  • option 'tolerance'
    • pointer: checks if the current pointer location intersects by more than 50% of one of the current checked adjacent items
    • intersect: checks if the pointer is on top of the item (to avoid overlaps) and also checks if the actual edge of the current item overlaps more than 50% of the checked item
  • option 'placeholder'
    • false: Creates an element with the same tag name than the current clicked item and adds the class names of the current item + 'ui-sortable-placeholder', then sets its visibility to hidden to only take the visible space. Updates itself in height/width whenever a change event occurs - if then the width/height is not automatically given by the class names / hierarchy in CSS, a smart logic hard copies the inner width of the current item to the placeholder.
    • string: does the above but adds the string specified as class name instead of the original class names
  • callbacks
    • start: triggered when the user picks up a sortable item or a draggable is dragged into the list
    • activate: triggered for other sortables connected to the current list if a user starts dragging
    • deactivate: triggered for other sortables connected to the current list if a user ends dragging
    • change: triggered during the drag whenever the order of elements in the list changes
    • sort: triggered on every mousemove
    • over: triggered for the current list and all connected lists when the pointer intersects with the list
    • out: triggered for the current list and all connected lists when the pointer does not intersect anymore with the list
    • receive: triggered on drop for a connected list if the user moved an item from the current list into a connected list
    • update: triggered if the order of items in the current or connected lists was changed due to the user's drag
    • remove: triggered on drop for the current list if the user moved an item from the current list into a connected list
    • beforeStop: triggered onmouseup, but before all other mouseup events were fired
    • stop: triggered onmouseup after all other events were fired

 


 

4 - Markup & Style:

 

     4.1 Initial markup examples

 

     (not applicable)

 

     4.2 Recommended transformed HTML markup

 

     (not applicable)

 

     4.3 Accessibility recommendation

 

    See http://build.fluidproject.org/fluid/sample-code/reorderer/image-reorderer/image-reorderer.html

 

     4.4 CSS & Theme

 

    (not applicable)

 


 

5 - Latest version of plugin:

 

(Link to the latest version in the jQuery UI trunk here)

 


 

6 - Open issues being discussed

 

(Use this area to place things that we're hashing out like featuresand options we're not sure we should include, questions about how this fits into UI and relates to other widgets and utilities, known problems, whether features should be broken across multiple releases, etc.)

 


 

 

 

 

Comments (0)

You don't have permission to comment on this page.