18f4388f9909487b198704745e4b61f884df1e81Dav Glass<div class="intro">
18f4388f9909487b198704745e4b61f884df1e81Dav Glass<p> The Sortable Utility allows you to create a sortable list from a container and a group of children. It also allows you to join lists together in various ways.</p>
18f4388f9909487b198704745e4b61f884df1e81Dav Glass{{>getting-started}}
cf8d258dad6b67aaddce8ebdc54e9ae70e7b2b9cDav Glass<h2 id="basic">A Basic Sortable List</h2>
18f4388f9909487b198704745e4b61f884df1e81Dav Glass<p>The most common use case of a sortable list is an Unordered List.</p>
18f4388f9909487b198704745e4b61f884df1e81Dav Glass<p>Below is the sample markup used to create a `container` and a list.</p>
18f4388f9909487b198704745e4b61f884df1e81Dav Glass<div id="demo">
18f4388f9909487b198704745e4b61f884df1e81Dav Glass <li>Item #1</li>
18f4388f9909487b198704745e4b61f884df1e81Dav Glass <li>Item #2</li>
18f4388f9909487b198704745e4b61f884df1e81Dav Glass <li>Item #3</li>
18f4388f9909487b198704745e4b61f884df1e81Dav Glass <li>Item #4</li>
18f4388f9909487b198704745e4b61f884df1e81Dav Glass <li>Item #5</li>
18f4388f9909487b198704745e4b61f884df1e81Dav Glass <li>Item #6</li>
18f4388f9909487b198704745e4b61f884df1e81Dav Glass <li>Item #7</li>
18f4388f9909487b198704745e4b61f884df1e81Dav Glass <li>Item #8</li>
18f4388f9909487b198704745e4b61f884df1e81Dav Glass <li>Item #9</li>
18f4388f9909487b198704745e4b61f884df1e81Dav Glass <li>Item #10</li>
18f4388f9909487b198704745e4b61f884df1e81Dav Glass<p>To turn this into a sortable list, you just need to create the `Sortable` object and tell it the `container` and the `nodes`.</p>
18f4388f9909487b198704745e4b61f884df1e81Dav Glass<p>The `nodes` can be any selector string that matches a child of the `container`. For performance reasons you will want to make the `container` an element that is as close to the `nodes` as possible. The farther away in the DOM the `container` is from the `nodes` the worse the performance will be.</p>
18f4388f9909487b198704745e4b61f884df1e81Dav GlassYUI().use('sortable', function(Y) {
18f4388f9909487b198704745e4b61f884df1e81Dav Glass var sortable = new Y.Sortable({
18f4388f9909487b198704745e4b61f884df1e81Dav Glass container: '#demo',
18f4388f9909487b198704745e4b61f884df1e81Dav Glass nodes: 'li',
18f4388f9909487b198704745e4b61f884df1e81Dav Glass opacity: '.1'
5c5f5643ee2dfbf7de92a5beb9d3de882cebdbf9Dav Glass<p><strong>Note:</strong> `Sortable` does not auto find your drop target items, if you change the `nodes` under the hood (add or remove) you need to call `sortable.sync()` to manage them.</p>
cf8d258dad6b67aaddce8ebdc54e9ae70e7b2b9cDav Glass<h2 id="events">Events</h2>
18f4388f9909487b198704745e4b61f884df1e81Dav Glass<p>Sortable uses `DD.Delegate` under the hood to handle the Drag and Drop operations. It sets itself as the `bubbleTarget` of the `Delegate` instance, so all `DD`-related events are bubbled to it.</p>
18f4388f9909487b198704745e4b61f884df1e81Dav Glass<p>For more information on `DD` related events, see the <a href="../dd/#events">events section on the Drag and Drop page</a>.</p>
cf8d258dad6b67aaddce8ebdc54e9ae70e7b2b9cDav Glass<h2 id="joining">Joining Lists</h2>
18f4388f9909487b198704745e4b61f884df1e81Dav Glass<p>By default, a `Sortable` list can only interact with itself; you can't drag from one `Sortable` list to another. But a `Sortable` instance can be configured to be joined with another `Sortable` instance.</p>
18f4388f9909487b198704745e4b61f884df1e81Dav Glass<p>There are four ways a `Sortable` list can be joined: `inner`, `outer`, `full` and `none` (`none` is the default).</p>
18f4388f9909487b198704745e4b61f884df1e81Dav Glass <th nowrap="nowrap">Join Type</th>
18f4388f9909487b198704745e4b61f884df1e81Dav Glass <th>Description</th>
18f4388f9909487b198704745e4b61f884df1e81Dav Glass <td nowrap="nowrap">`inner`</td>
18f4388f9909487b198704745e4b61f884df1e81Dav Glass <td>Items in the joined list can be moved into the main list but items in the main list can not be moved to the joined list.</td>
18f4388f9909487b198704745e4b61f884df1e81Dav Glass <tr class="odd">
18f4388f9909487b198704745e4b61f884df1e81Dav Glass <td nowrap="nowrap">`outer`</td>
18f4388f9909487b198704745e4b61f884df1e81Dav Glass <td>Items in the main list can be moved into the joined list but items in the joined list can not be moved to the main list.</td>
18f4388f9909487b198704745e4b61f884df1e81Dav Glass <td nowrap="nowrap">`full`</td>
18f4388f9909487b198704745e4b61f884df1e81Dav Glass <td>All items in both lists can be moved into and out of any other joined list.</td>
18f4388f9909487b198704745e4b61f884df1e81Dav Glass <tr class="odd">
18f4388f9909487b198704745e4b61f884df1e81Dav Glass <td nowrap="nowrap">`none`</td>
18f4388f9909487b198704745e4b61f884df1e81Dav Glass <td>The default join type. No interaction with other lists.</td>
18f4388f9909487b198704745e4b61f884df1e81Dav GlassYUI().use('sortable', function(Y) {
18f4388f9909487b198704745e4b61f884df1e81Dav Glass var sortable1 = new Y.Sortable({
18f4388f9909487b198704745e4b61f884df1e81Dav Glass container: '#demo1',
18f4388f9909487b198704745e4b61f884df1e81Dav Glass nodes: 'li',
18f4388f9909487b198704745e4b61f884df1e81Dav Glass opacity: '.1'
18f4388f9909487b198704745e4b61f884df1e81Dav Glass var sortable2 = new Y.Sortable({
18f4388f9909487b198704745e4b61f884df1e81Dav Glass container: '#demo2',
18f4388f9909487b198704745e4b61f884df1e81Dav Glass nodes: 'li',
18f4388f9909487b198704745e4b61f884df1e81Dav Glass opacity: '.1'
18f4388f9909487b198704745e4b61f884df1e81Dav Glass sortable1.join(sortable2, 'full');
18f4388f9909487b198704745e4b61f884df1e81Dav Glass<p>You can also join multiple lists in multiple ways to get the experience you are looking for.</p>
18f4388f9909487b198704745e4b61f884df1e81Dav GlassYUI().use('sortable', function(Y) {
18f4388f9909487b198704745e4b61f884df1e81Dav Glass var sortable1 = new Y.Sortable({
18f4388f9909487b198704745e4b61f884df1e81Dav Glass container: '#demo1',
18f4388f9909487b198704745e4b61f884df1e81Dav Glass nodes: 'li',
18f4388f9909487b198704745e4b61f884df1e81Dav Glass opacity: '.1'
18f4388f9909487b198704745e4b61f884df1e81Dav Glass var sortable2 = new Y.Sortable({
18f4388f9909487b198704745e4b61f884df1e81Dav Glass container: '#demo2',
18f4388f9909487b198704745e4b61f884df1e81Dav Glass nodes: 'li',
18f4388f9909487b198704745e4b61f884df1e81Dav Glass opacity: '.1'
18f4388f9909487b198704745e4b61f884df1e81Dav Glass var sortable3 = new Y.Sortable({
18f4388f9909487b198704745e4b61f884df1e81Dav Glass container: '#demo3',
18f4388f9909487b198704745e4b61f884df1e81Dav Glass nodes: 'li',
18f4388f9909487b198704745e4b61f884df1e81Dav Glass opacity: '.1'
18f4388f9909487b198704745e4b61f884df1e81Dav Glass sortable1.join(sortable2, 'inner');
18f4388f9909487b198704745e4b61f884df1e81Dav Glass sortable2.join(sortable3, 'outer');
18f4388f9909487b198704745e4b61f884df1e81Dav Glass sortable3.join(sortable1, 'full');
18f4388f9909487b198704745e4b61f884df1e81Dav Glass sortable3.join(sortable2, 'full');
cf8d258dad6b67aaddce8ebdc54e9ae70e7b2b9cDav Glass<h2 id="plugins">Using DD Plugins</h2>
18f4388f9909487b198704745e4b61f884df1e81Dav Glass<p>The `DD.Delegate` object bound to a `Sortable` instance is exposed to allow you to easily attach plugins to a `Sortable` instance.</p>
18f4388f9909487b198704745e4b61f884df1e81Dav Glass<p>The `Sortable` instance has a `delegate` namespace, which is a reference to the internal `DD.Delegate` instance.</p>
18f4388f9909487b198704745e4b61f884df1e81Dav Glassvar sortable = new Y.Sortable({
18f4388f9909487b198704745e4b61f884df1e81Dav Glass container: '#demo',