Skip to content

HTTPS clone URL

Subversion checkout URL

You can clone with
or
.
Download ZIP
Fetching contributors…

Cannot retrieve contributors at this time

484 lines (479 sloc) 25.048 kB
<?xml version="1.0"?>
<entry name="sortable" type="widget" widget-element="sortable element" event-prefix="sort">
<title>Sortable Widget</title>
<desc>Reorder elements in a list or grid using the mouse.</desc>
<longdesc>
<p>The jQuery UI Sortable plugin makes selected elements sortable by dragging with the mouse.</p>
<p><em>Note: In order to sort table rows, the <code>tbody</code> must be made sortable, not the <code>table</code>.</em></p>
<h3>Dependencies</h3>
<ul>
<li><a href="/category/ui-core/">UI Core</a></li>
<li><a href="/jQuery.widget/">Widget Factory</a></li>
<li><a href="/mouse/">Mouse Interaction</a></li>
</ul>
</longdesc>
<added>1.0</added>
<options>
<option name="appendTo" default='"parent"' example-value='document.body'>
<desc>Defines where the helper that moves with the mouse is being appended to during the drag (for example, to resolve overlap/zIndex issues).</desc>
<type name="jQuery">
<desc>A jQuery object containing the element to append the helper to.</desc>
</type>
<type name="Element">
<desc>The element to append the helper to.</desc>
</type>
<type name="Selector">
<desc>A selector specifying which element to append the helper to.</desc>
</type>
<type name="String">
<desc>The string <code>"parent"</code> will cause the helper to be a sibling of the sortable item.</desc>
</type>
</option>
<option name="axis" type="String" default='false' example-value='"x"'>
<desc>If defined, the items can be dragged only horizontally or vertically. Possible values: <code>"x"</code>, <code>"y"</code>.</desc>
</option>
<option name="cancel" type="Selector" default='":input,button"' example-value='"a,button"'>
<desc>Prevents sorting if you start on elements matching the selector.</desc>
</option>
<option name="connectWith" type="Selector" default='false' example-value='"#shopping-cart"'>
<desc>A selector of other sortable elements that the items from this list should be connected to. This is a one-way relationship, if you want the items to be connected in both directions, the <code>connectWith</code> option must be set on both sortable elements.</desc>
</option>
<option name="containment" default="false" example-value='"parent"'>
<desc>
<p>Defines a bounding box that the sortable items are contrained to while dragging.</p>
<p>Note: The element specified for containment must have a calculated width and height (though it need not be explicit). For example, if you have <code>float: left</code> sortable children and specify <code>containment: "parent"</code> be sure to have <code>float: left</code> on the sortable/parent container as well or it will have <code>height: 0</code>, causing undefined behavior.</p>
</desc>
<type name="Element">
<desc>An element to use as the container.</desc>
</type>
<type name="Selector">
<desc>A selector specifying an element to use as the container.</desc>
</type>
<type name="String">
<desc>A string identifying an element to use as the container. Possible values: <code>"parent"</code>, <code>"document"</code>, <code>"window"</code>.</desc>
</type>
</option>
<option name="cursor" type="String" default='"auto"' example-value='"move"'>
<desc>Defines the cursor that is being shown while sorting.</desc>
</option>
<option name="cursorAt" type="Object" default="false" example-value='{ left: 5 }'>
<desc>Moves the sorting element or helper so the cursor always appears to drag from the same position. Coordinates can be given as a hash using a combination of one or two keys: <code>{ top, left, right, bottom }</code>.</desc>
</option>
<option name="delay" type="Integer" default="0" example-value='150'>
<desc>Time in milliseconds to define when the sorting should start. Adding a delay helps preventing unwanted drags when clicking on an element.</desc>
</option>
<xi:include href="../includes/widget-option-disabled.xml" xmlns:xi="http://www.w3.org/2003/XInclude"/>
<option name="distance" type="Number" default="1" example-value='5'>
<desc>Tolerance, in pixels, for when sorting should start. If specified, sorting will not start until after mouse is dragged beyond distance. Can be used to allow for clicks on elements within a handle.</desc>
</option>
<option name="dropOnEmpty" type="Boolean" default="true" example-value='false'>
<desc>If <code>false</code>, items from this sortable can't be dropped on an empty connect sortable (see the <a href="#option-connectWith"><code>connectWith</code></a> option.</desc>
</option>
<option name="forceHelperSize" type="Boolean" default="false" example-value='true'>
<desc>If <code>true</code>, forces the helper to have a size.</desc>
</option>
<option name="forcePlaceholderSize" type="Boolean" default="false" example-value='true'>
<desc>If true, forces the placeholder to have a size.</desc>
</option>
<option name="grid" type="Array" default="false" example-value='[ 20, 10 ]'>
<desc>Snaps the sorting element or helper to a grid, every x and y pixels. Array values: <code>[ x, y ]</code>.</desc>
</option>
<option name="handle" default="false" example-value='".handle"'>
<desc>Restricts sort start click to the specified element.</desc>
<type name="Selector"/>
<type name="Element"/>
</option>
<option name="helper" default='"original"' example-value='"clone"'>
<desc>Allows for a helper element to be used for dragging display.</desc>
<type name="String">
<desc>If set to <code>"clone"</code>, then the element will be cloned and the clone will be dragged.</desc>
</type>
<type name="Function">
<desc>A function that will return a DOMElement to use while dragging. The function receives the event and the element being sorted.</desc>
</type>
</option>
<option name="items" type="Selector" default='"> *"' example-value='"> li"'>
<desc>Specifies which items inside the element should be sortable.</desc>
</option>
<option name="opacity" type="Number" default="false" example-value='0.5'>
<desc>Defines the opacity of the helper while sorting. From <code>0.01</code> to <code>1</code>.</desc>
</option>
<option name="placeholder" type="String" default="false" example-value='"sortable-placeholder"'>
<desc>A class name that gets applied to the otherwise white space.</desc>
</option>
<option name="revert" default="false" example-value='true'>
<desc>Whether the sortable items should revert to their new positions using a smooth animation.</desc>
<type name="Boolean">
<desc>When set to <code>true</code>, the items will animate with the default duration.</desc>
</type>
<type name="Number">
<desc>The duration for the animation, in milliseconds.</desc>
</type>
</option>
<option name="scroll" type="Boolean" default="true" example-value='false'>
<desc>If set to true, the page scrolls when coming to an edge.</desc>
</option>
<option name="scrollSensitivity" type="Number" default="20" example-value='10'>
<desc>Defines how near the mouse must be to an edge to start scrolling.</desc>
</option>
<option name="scrollSpeed" type="Number" default="20" example-value='40'>
<desc>The speed at which the window should scroll once the mouse pointer gets within the <a href="#option-scrollSensitivity"><code>scrollSensitivity</code></a> distance.</desc>
</option>
<option name="tolerance" type="String" default='"intersect"' example-value='"pointer"'>
<desc>
Specifies which mode to use for testing whether the item being moved is hovering over another item. Possible values:
<ul>
<li><code>"intersect"</code>: The item overlaps the other item by at least 50%.</li>
<li><code>"pointer"</code>: The mouse pointer overlaps the other item.</li>
</ul>
</desc>
</option>
<option name="zIndex" type="Integer" default="1000" example-value='9999'>
<desc>Z-index for element/helper while being sorted.</desc>
</option>
</options>
<events>
<xi:include href="../includes/widget-event-create.xml" xmlns:xi="http://www.w3.org/2003/XInclude"/>
<event name="start">
<desc>This event is triggered when sorting starts.</desc>
<argument name="event" type="Event"/>
<argument name="ui" type="Object">
<property name="helper" type="jQuery">
<desc>The jQuery object representing the helper being sorted</desc>
</property>
<property name="item" type="jQuery">
<desc>The jQuery object representing the current dragged element</desc>
</property>
<property name="offset" type="Object">
<desc>The current absolute position of the helper represented as <code>{ top, left }</code></desc>
</property>
<property name="position" type="Object">
<desc>The current position of the helper represented as <code>{ top, left }</code></desc>
</property>
<property name="originalPosition" type="Object">
<desc>The original position of the element represented as <code>{ top, left }</code></desc>
</property>
<property name="sender" type="jQuery">
<desc>The sortable that the item comes from if moving from one sortable to another</desc>
</property>
</argument>
</event>
<event name="sort">
<desc>This event is triggered during sorting.</desc>
<argument name="event" type="Event"/>
<argument name="ui" type="Object">
<property name="helper" type="jQuery">
<desc>The jQuery object representing the helper being sorted</desc>
</property>
<property name="item" type="jQuery">
<desc>The jQuery object representing the current dragged element</desc>
</property>
<property name="offset" type="Object">
<desc>The current absolute position of the helper represented as <code>{ top, left }</code></desc>
</property>
<property name="position" type="Object">
<desc>The current position of the helper represented as <code>{ top, left }</code></desc>
</property>
<property name="originalPosition" type="Object">
<desc>The original position of the element represented as <code>{ top, left }</code></desc>
</property>
<property name="sender" type="jQuery">
<desc>The sortable that the item comes from if moving from one sortable to another</desc>
</property>
</argument>
</event>
<event name="change">
<desc>This event is triggered during sorting, but only when the DOM position has changed.</desc>
<argument name="event" type="Event"/>
<argument name="ui" type="Object">
<property name="helper" type="jQuery">
<desc>The jQuery object representing the helper being sorted</desc>
</property>
<property name="item" type="jQuery">
<desc>The jQuery object representing the current dragged element</desc>
</property>
<property name="offset" type="Object">
<desc>The current absolute position of the helper represented as <code>{ top, left }</code></desc>
</property>
<property name="position" type="Object">
<desc>The current position of the helper represented as <code>{ top, left }</code></desc>
</property>
<property name="originalPosition" type="Object">
<desc>The original position of the element represented as <code>{ top, left }</code></desc>
</property>
<property name="sender" type="jQuery">
<desc>The sortable that the item comes from if moving from one sortable to another</desc>
</property>
</argument>
</event>
<event name="beforeStop">
<desc>This event is triggered when sorting stops, but when the placeholder/helper is still available.</desc>
<argument name="event" type="Event"/>
<argument name="ui" type="Object">
<property name="helper" type="jQuery">
<desc>The jQuery object representing the helper being sorted</desc>
</property>
<property name="item" type="jQuery">
<desc>The jQuery object representing the current dragged element</desc>
</property>
<property name="offset" type="Object">
<desc>The current absolute position of the helper represented as <code>{ top, left }</code></desc>
</property>
<property name="position" type="Object">
<desc>The current position of the helper represented as <code>{ top, left }</code></desc>
</property>
<property name="originalPosition" type="Object">
<desc>The original position of the element represented as <code>{ top, left }</code></desc>
</property>
<property name="sender" type="jQuery">
<desc>The sortable that the item comes from if moving from one sortable to another</desc>
</property>
</argument>
</event>
<event name="stop">
<desc>This event is triggered when sorting has stopped.</desc>
<argument name="event" type="Event"/>
<argument name="ui" type="Object">
<property name="helper" type="jQuery">
<desc>The jQuery object representing the helper being sorted</desc>
</property>
<property name="item" type="jQuery">
<desc>The jQuery object representing the current dragged element</desc>
</property>
<property name="offset" type="Object">
<desc>The current absolute position of the helper represented as <code>{ top, left }</code></desc>
</property>
<property name="position" type="Object">
<desc>The current position of the helper represented as <code>{ top, left }</code></desc>
</property>
<property name="originalPosition" type="Object">
<desc>The original position of the element represented as <code>{ top, left }</code></desc>
</property>
<property name="sender" type="jQuery">
<desc>The sortable that the item comes from if moving from one sortable to another</desc>
</property>
</argument>
</event>
<event name="update">
<desc>This event is triggered when the user stopped sorting and the DOM position has changed.</desc>
<argument name="event" type="Event"/>
<argument name="ui" type="Object">
<property name="helper" type="jQuery">
<desc>The jQuery object representing the helper being sorted</desc>
</property>
<property name="item" type="jQuery">
<desc>The jQuery object representing the current dragged element</desc>
</property>
<property name="offset" type="Object">
<desc>The current absolute position of the helper represented as <code>{ top, left }</code></desc>
</property>
<property name="position" type="Object">
<desc>The current position of the helper represented as <code>{ top, left }</code></desc>
</property>
<property name="originalPosition" type="Object">
<desc>The original position of the element represented as <code>{ top, left }</code></desc>
</property>
<property name="sender" type="jQuery">
<desc>The sortable that the item comes from if moving from one sortable to another</desc>
</property>
</argument>
</event>
<event name="receive">
<desc>This event is triggered when a connected sortable list has received an item from another list.</desc>
<argument name="event" type="Event"/>
<argument name="ui" type="Object">
<property name="helper" type="jQuery">
<desc>The jQuery object representing the helper being sorted</desc>
</property>
<property name="item" type="jQuery">
<desc>The jQuery object representing the current dragged element</desc>
</property>
<property name="offset" type="Object">
<desc>The current absolute position of the helper represented as <code>{ top, left }</code></desc>
</property>
<property name="position" type="Object">
<desc>The current position of the helper represented as <code>{ top, left }</code></desc>
</property>
<property name="originalPosition" type="Object">
<desc>The original position of the element represented as <code>{ top, left }</code></desc>
</property>
<property name="sender" type="jQuery">
<desc>The sortable that the item comes from if moving from one sortable to another</desc>
</property>
</argument>
</event>
<event name="remove">
<desc>This event is triggered when a sortable item has been dragged out from the list and into another.</desc>
<argument name="event" type="Event"/>
<argument name="ui" type="Object">
<property name="helper" type="jQuery">
<desc>The jQuery object representing the helper being sorted</desc>
</property>
<property name="item" type="jQuery">
<desc>The jQuery object representing the current dragged element</desc>
</property>
<property name="offset" type="Object">
<desc>The current absolute position of the helper represented as <code>{ top, left }</code></desc>
</property>
<property name="position" type="Object">
<desc>The current position of the helper represented as <code>{ top, left }</code></desc>
</property>
<property name="originalPosition" type="Object">
<desc>The original position of the element represented as <code>{ top, left }</code></desc>
</property>
<property name="sender" type="jQuery">
<desc>The sortable that the item comes from if moving from one sortable to another</desc>
</property>
</argument>
</event>
<event name="over">
<desc>This event is triggered when a sortable item is moved into a connected list.</desc>
<argument name="event" type="Event"/>
<argument name="ui" type="Object">
<property name="helper" type="jQuery">
<desc>The jQuery object representing the helper being sorted</desc>
</property>
<property name="item" type="jQuery">
<desc>The jQuery object representing the current dragged element</desc>
</property>
<property name="offset" type="Object">
<desc>The current absolute position of the helper represented as <code>{ top, left }</code></desc>
</property>
<property name="position" type="Object">
<desc>The current position of the helper represented as <code>{ top, left }</code></desc>
</property>
<property name="originalPosition" type="Object">
<desc>The original position of the element represented as <code>{ top, left }</code></desc>
</property>
<property name="sender" type="jQuery">
<desc>The sortable that the item comes from if moving from one sortable to another</desc>
</property>
</argument>
</event>
<event name="out">
<desc>This event is triggered when a sortable item is moved away from a connected list.</desc>
<argument name="event" type="Event"/>
<argument name="ui" type="Object">
<property name="helper" type="jQuery">
<desc>The jQuery object representing the helper being sorted</desc>
</property>
<property name="item" type="jQuery">
<desc>The jQuery object representing the current dragged element</desc>
</property>
<property name="offset" type="Object">
<desc>The current absolute position of the helper represented as <code>{ top, left }</code></desc>
</property>
<property name="position" type="Object">
<desc>The current position of the helper represented as <code>{ top, left }</code></desc>
</property>
<property name="originalPosition" type="Object">
<desc>The original position of the element represented as <code>{ top, left }</code></desc>
</property>
<property name="sender" type="jQuery">
<desc>The sortable that the item comes from if moving from one sortable to another</desc>
</property>
</argument>
</event>
<event name="activate">
<desc>This event is triggered when using connected lists, every connected list on drag start receives it.</desc>
<argument name="event" type="Event"/>
<argument name="ui" type="Object">
<property name="helper" type="jQuery">
<desc>The jQuery object representing the helper being sorted</desc>
</property>
<property name="item" type="jQuery">
<desc>The jQuery object representing the current dragged element</desc>
</property>
<property name="offset" type="Object">
<desc>The current absolute position of the helper represented as <code>{ top, left }</code></desc>
</property>
<property name="position" type="Object">
<desc>The current position of the helper represented as <code>{ top, left }</code></desc>
</property>
<property name="originalPosition" type="Object">
<desc>The original position of the element represented as <code>{ top, left }</code></desc>
</property>
<property name="sender" type="jQuery">
<desc>The sortable that the item comes from if moving from one sortable to another</desc>
</property>
</argument>
</event>
<event name="deactivate">
<desc>This event is triggered when sorting was stopped, is propagated to all possible connected lists.</desc>
<argument name="event" type="Event"/>
<argument name="ui" type="Object">
<property name="helper" type="jQuery">
<desc>The jQuery object representing the helper being sorted</desc>
</property>
<property name="item" type="jQuery">
<desc>The jQuery object representing the current dragged element</desc>
</property>
<property name="offset" type="Object">
<desc>The current absolute position of the helper represented as <code>{ top, left }</code></desc>
</property>
<property name="position" type="Object">
<desc>The current position of the helper represented as <code>{ top, left }</code></desc>
</property>
<property name="originalPosition" type="Object">
<desc>The original position of the element represented as <code>{ top, left }</code></desc>
</property>
<property name="sender" type="jQuery">
<desc>The sortable that the item comes from if moving from one sortable to another</desc>
</property>
</argument>
</event>
</events>
<methods>
<method name="cancel">
<desc>Cancels a change in the current sortable and reverts it to the state prior to when the current sort was started. Useful in the stop and receive callback functions.</desc>
</method>
<xi:include href="../includes/widget-method-destroy.xml" xmlns:xi="http://www.w3.org/2003/XInclude"/>
<xi:include href="../includes/widget-method-disable.xml" xmlns:xi="http://www.w3.org/2003/XInclude"/>
<xi:include href="../includes/widget-method-enable.xml" xmlns:xi="http://www.w3.org/2003/XInclude"/>
<xi:include href="../includes/widget-method-option.xml" xmlns:xi="http://www.w3.org/2003/XInclude"/>
<method name="refresh">
<desc>Refresh the sortable items. Triggers the reloading of all sortable items, causing new items to be recognized.</desc>
</method>
<method name="refreshPositions">
<desc>Refresh the cached positions of the sortable items. Calling this method refreshes the cached item positions of all sortables.</desc>
</method>
<method name="serialize" return="String" example-return-var="sorted" example-params='{ key: "sort" }'>
<desc>
<p>Serializes the sortable's item <code>id</code>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.</p>
<p>It works by default by looking at the <code>id</code> of each item in the format <code>"setname_number"</code>, and it spits out a hash like <code>"setname[]=number&amp;setname[]=number"</code>.</p>
<p><em>Note: If serialize returns an empty string, make sure the <code>id</code> attributes include an underscore. They must be in the form: <code>"set_number"</code> For example, a 3 element list with <code>id</code> attributes <code>"foo_1"</code>, <code>"foo_5"</code>, <code>"foo_2"</code> will serialize to <code>"foo[]=1&amp;foo[]=5&amp;foo[]=2"</code>. You can use an underscore, equal sign or hyphen to separate the set and number. For example <code>"foo=1"</code>, <code>"foo-1"</code>, and <code>"foo_1"</code> all serialize to <code>"foo[]=1"</code>.</em></p>
</desc>
<argument name="options" type="Object">
<desc>Options to customize the serialization.</desc>
<property name="key" type="String" default="the part of the attribute in front of the separator">
<desc>Replaces <code>part1[]</code> with the specified value.</desc>
</property>
<property name="attribute" type="String" default='"id"'>
<desc>The name of the attribute to use for the values.</desc>
</property>
<property name="expression" type="RegExp" default="/(.+)[-=_](.+)/">
<desc>A regular expression used to split the attribute value into key and value parts.</desc>
</property>
</argument>
</method>
<method name="toArray" return="Array" example-return-var="sortedIDs">
<desc>Serializes the sortable's item id's into an array of string.</desc>
</method>
<xi:include href="../includes/widget-method-widget.xml" xmlns:xi="http://www.w3.org/2003/XInclude"/>
</methods>
<example>
<height>150</height>
<desc>A simple jQuery UI Sortable.</desc>
<code><![CDATA[$("#sortable").sortable();]]></code>
<html><![CDATA[
<ul id="sortable">
<li>Item 1</li>
<li>Item 2</li>
<li>Item 3</li>
<li>Item 4</li>
<li>Item 5</li>
</ul>
]]></html>
</example>
<category slug="interactions"/>
</entry>
Jump to Line
Something went wrong with that request. Please try again.