jQuery Sortable Plugin

Drag

[item_name]

Quick Installation Guide

Download the plugin and unpack the .js and .css files.

Add tags (make sure they point to your files)

<link rel="stylesheet" type="text/css" href="jquery.sortable-1.0.0.css"/>
</head>
...
<script src="jquery.sortable-1.0.0.js"></script>
</body>

Add the HTML template

<body>
...
<div class="dd" id="sortable-0">
  <button class="dd-new-item">+</button>
  <li class="dd-item-blueprint">
    <button class="collapse" data-action="collapse" type="button" style="display: none;">–</button>
    <button class="expand" data-action="expand" type="button" style="display: none;">+</button>
    <div class="dd-handle dd3-handle">Drag</div>
    <div class="dd3-content">
      <span class="item-name">[item_name]</span>
      <div class="dd-button-container">
        <button class="item-add">+</button>
        <button class="item-remove" data-confirm-class="item-remove-confirm">&times;</button>
      </div>
      <div class="dd-edit-box" style="display: none;">
        <input type="text" name="title" autocomplete="off" placeholder="Item"
               data-placeholder="Any nice idea for the title?"
               data-default-value="Sortable List Item. {?numeric.increment}">
        <i class="end-edit">save</i>
      </div>
    </div>
  </li>
  <ol class="dd-list"></ol>
</div>
...
</body>

Add the initialization code

<script>
$(document).ready(function() {
  $('#sortable-0').sortable({
    data: '[{"title":"Hi, drag me!","customSelect":"select something...","select2ScrollPosition":{"x":0,"y":0}},{"title":"No! Wait, drag me instead!","customSelect":"http://test.com","select2ScrollPosition":{"x":0,"y":0}}]'
  }).parseJson()
});
</script>

You're done!

Introduction

This example represents an integrated Sortable instance with Select2. This instance of Sortable takes advantage of the robust customization capabilities of the plugin where we have created a custom edit button, created custom input fields and integrated Select2. Try opening your browser console to see a log of the fired events.

Things to try out:

Drag (using gray handle on the left) the second list item named Settings horizontally to the right to make it a child of Account To unset a child drag it horizontally to the left.
Now you should be able to collapse and expand Account by clicking on – and + respectively, next to the item's name. In your HTML markup you might change the appearance of the button editing the .dd-item-blueprint template.
```
<button class="expand" data-action="expand" type="button" style="display: none;">+</button>
```
Hover your mouse cursor over the Settings list item and click on the pencil button on the right to enter the edit mode. You might also click directly on the item's name to enter the edit mode.
Click on the select and enter a custom URL press the enter key to confirm. Then click on save and observe on the right how the Sortable generated JSON changes. In the edit mode you can specify the values for the input fields as specified in your .dd-item-blueprint template. Currently we have specified one text input for the title of the item and an additional select input named custom-select for everything else. Using integrated Select2 with tags turned on you can create new options in realtime.
```
<select name="custom-select">
  <option>select something...</option>
  <optgroup label="Pages">
    <option value="1">http://example.com/page/1</option>
    ...
  </optgroup>
  <optgroup label="Categories">
    <option value="3">News</option>
    ...
  </optgroup>
</select>
```
Drag an item from User menu to the Shop menu. You can mix items from different instances together, Sortable will handle that.
Have fun with Sortable.

Drag

[item_name]

JSON Output Preview (User menu)

Keep changes after page reload (localStorage)

Shop menu

Here is an example of a Sortable instance with just few custom input fields added. Everything else comes out of the box with Sortable.

Drag

[item_name]

JSON Output Preview (Shop menu)

Keep changes after page reload (localStorage)

Options

Specify your options to the sortable(options) call e.g.:

$('#sortable-0').sortable({
 listNodeName: 'ol',
 itemNodeName: 'li',
 rootClass: 'dd',
 listClass: 'dd-list',
 itemClass: 'dd-item',
 ...
})

Default options

Options supplied to a Sortable instance by default.


    {
      listNodeName:           'ol',
      itemNodeName:           'li',
      rootClass:              'dd',
      listClass:              'dd-list',
      itemClass:              'dd-item',
      itemBlueprintClass:     'dd-item-blueprint',
      dragClass:              'dd-dragel',
      handleClass:            'dd-handle',
      collapsedClass:         'dd-collapsed',
      placeClass:             'dd-placeholder',
      noDragClass:            'dd-nodrag', // Items with this class will be undraggable
      emptyClass:             'dd-empty',
      contentClass:           'dd3-content',
      itemAddBtnClass:        'item-add',
      removeBtnClass:         'item-remove',
      itemRemoveBtnConfirmClass: 'confirm-class',
      addBtnSelector:         '', // Provide a global selector for an add button
      addBtnClass:            'dd-new-item',
      editBoxClass:           'dd-edit-box',
      inputSelector:          'input, select, textarea', // Selects input fields to serialize to JSON
      collapseBtnClass:       'collapse',
      expandBtnClass:         'expand',
      endEditBtnClass:        'end-edit',
      itemBtnContainerClass:  'dd-button-container',
      itemNameClass:          'item-name',

      data:                   '', // JSON data to build an instance from (don't forget to call parseJson)
      allowListMerging:       false,  // Accept incoming items from foreign lists e.g:
                                      // true – accept all
                                      // false – deny all
                                      // ['sortable-2'] – accept from instances matching #sortable-2
      select2: {

        support:     false, // Enable Select2 support
        selectWidth: '45%', // Any CSS-supported value is valid
        params:      {}     // Provide Select2 params
      },
      slideAnimationDuration: 0,
      maxDepth:               5,    // Item nesting limit
      threshold:              20,   // Dragging sensitivity
      refuseConfirmDelay:     2000, // Time (in ms) to wait on confirmation of an item removal
      newItemFadeIn:          350,  // Set 0 for no fadeIn effect
      event:                  {
        onToJson:           [],
        onParseJson:        [],
        onSaveEditBoxInput: [],
        onItemDrag:         [],
        onItemAddChildItem: [],
        onItemDrop:         [],
        onItemAdded:        [],
        onItemExpanded:     [],
        onItemCollapsed:    [],
        onItemRemoved:      [],
        onItemStartEdit:    [],
        onItemEndEdit:      [],
        onCreateItem:       [],
        onItemMaxDepth:     [],
        onItemSetParent:    [],
        onItemUnsetParent:  []
      },
      paramsDataKey:          '__sortable_params' // The property under which internal settings will be serialized
    }

Tokens & Attributes

Tokens and attributes work together to supply you with precomputed variables which you might use with your input fields.

Tokens

Use tokens inside of your attributes e.g. data-placeholder and data-default-value. E.g.:

<input type="text" name="title" placeholder="Item" data-placeholder="Item {?numeric.increment}" data-default-value="Item {?numeric.increment}">

{?date.gregorian-slashed-DMY} current date in gregorian DMY format
{?date.mysql-datetime} valid MySQL datetime format
{?numeric.increment} increments itself and outputs a number
{?value} current value of the input

Attributes

Adding attributes to your input fields allows you to make them more dynamic.

data-placeholder works like the placeholder attribute but has a higher priority and supports Tokens
data-default-value the value of this attribute will be used by toJson as a default value when no user supplied value is present

Quick API

Access the PublicPlugin API with:

$('#your-sortable-element').sortable()

Usage example

$('#sortable-0').sortable().onItemAdded(function() {
  alert('An item has been added');
});

Quick overview

```
array getLists()
```
Returns the Sortable instance list element.
parseJson(string jsonData[, bool override = false])
```
string parseJson(string data[, bool override = false])
```
Converts JSON output to a Sortable instance. jsonData takes valid JSON as argument. If override is set to true then the current jsonData will replace the current list items. If override is set to false then the current jsonData be appended to the current list.
toJson()
```
string toJson()
```
Serializes the instance and returns it as JSON.
expandAll()
```
PublicPlugin expandAll()
```
Expands all items in a recursive fashion.
collapseAll()
```
PublicPlugin collapseAll()
```
Collapses all items in a recursive fashion.
expand(callback)
```
PublicPlugin expand(callback)
```
The callback takes item element as argument. If the callback will return true then the item will get expanded.
collapse(callback)
```
PublicPlugin collapse(callback)
```
The callback takes item element as argument. If the callback will return true then the item will get collapsed.
onParseJson(callback)
```
PublicPlugin onParseJson(callback)
```
Fires after the parseJson() call.
onToJson(callback)
```
PublicPlugin onToJson(callback)
```
Fires after a toJson() call.
onSaveEditBoxInput(callback)
```
PublicPlugin onSaveEditBoxInput(callback)
```
Fires after the input fields are saved just before exiting the edit mode. The callback takes jQuery $item of the item being edited and array inputCollection containing input fields of the item being edited as arguments.
onItemDrag(callback)
```
PublicPlugin onItemDrag(callback)
```
Fires after an item has been dragged. The callback takes jQuery $item of the item being dragged as argument.
onItemDrop(callback)
```
PublicPlugin onItemDrop(callback)
```
Fires after an item has been dropped. The callback takes jQuery $item of the item being dropped as argument.
onItemAdded(callback)
```
PublicPlugin onItemAdded(callback)
```
Fires after an item has been added. The callback takes jQuery $item of the added item as argument.
onItemRemoved(callback)
```
PublicPlugin onItemRemoved(callback)
```
Fires after an item has been removed. The callback takes jQuery $item of the removed item as argument.
onItemStartEdit(callback)
```
PublicPlugin onItemStartEdit(callback)
```
Fires after an item has entered the edit mode. The callback takes jQuery $item of the item in edit mode as argument.
onItemEndEdit(callback)
```
PublicPlugin onItemEndEdit(callback)
```
Fires after an item has exited the edit mode. The callback takes jQuery $item of the item exiting edit mode as argument.
onItemAddChildItem(callback)
```
PublicPlugin onItemAddChildItem(callback)
```
Fires after an item has added an item. The callback takes jQuery $item of the added item as argument.
onCreateItem(callback)
```
PublicPlugin onCreateItem(callback)
```
Fires just before an item has been created. The callback takes jQuery $item of the item which is being created as argument.
onItemCollapsed(callback)
```
PublicPlugin onItemCollapsed(callback)
```
Fires after an item has been collapsed. The callback takes jQuery $item of the item which has been collapsed as argument.
onItemExpanded(callback)
```
PublicPlugin onItemExpanded(callback)
```
Fires after an item has been expanded. The callback takes jQuery $item of the item which has been expanded as argument.
onItemMaxDepth(callback)
```
PublicPlugin onItemMaxDepth(callback)
```
Fires when the max depth of an item prevents nesting additional children. The callback takes jQuery $item of the item which is being dragged as argument.
onItemSetParent(callback)
```
PublicPlugin onItemSetParent(callback)
```
Fires after an item becomes a parent. The callback takes jQuery $item of the item which has become a parent as argument.
onItemUnsetParent(callback)
```
PublicPlugin onItemUnsetParent(callback)
```
Fires after a parent item becomes an item without child items. The callback takes jQuery $item of the parent item as argument.
on(eventBag, callback)
```
PublicPlugin on(eventBag, callback)
```
Allows you to setup a callback for multiple events. string || array || '*' eventBag carries the name of the events you want the callback to be subscribed to. '*' will subscribe the callback for all events. function callback the function to be applied on the subscribed set of events after an event fires.

Example
```
.on(['onItemCollapsed', 'onItemExpanded'], function(a, b, c) {
  $jsonOutput.val(sortable.toJson());
  if($keepChanges.is(':checked')) window.localStorage.setItem('sortable-2Json', sortable.toJson());
});
```
Register an event listener for onItemCollapsed and onItemExpanded.
getListNodes()
```
array getListNodes()
```
Returns all elements within the Sortable instance of type listNodeName
getPluginOptions()
```
Object getPluginOptions()
```
Returns the current set of options of a Sortable instance.

Sortable v1.0.0

Quick Installation Guide

Introduction

User menu

JSON Output Preview (User menu)

Shop menu

JSON Output Preview (Shop menu)

Options

Default options

Tokens & Attributes

Tokens

Attributes

Quick API

Usage example

Quick overview

parseJson(string jsonData[, bool override = false])

toJson()

expandAll()

collapseAll()

expand(callback)

collapse(callback)

onParseJson(callback)

onToJson(callback)

onSaveEditBoxInput(callback)

onItemDrag(callback)

onItemDrop(callback)

onItemAdded(callback)

onItemRemoved(callback)

onItemStartEdit(callback)

onItemEndEdit(callback)

onItemAddChildItem(callback)

onCreateItem(callback)

onItemCollapsed(callback)

onItemExpanded(callback)

onItemMaxDepth(callback)

onItemSetParent(callback)

onItemUnsetParent(callback)

on(eventBag, callback)

Example

getListNodes()

getPluginOptions()

Sortable ^v1.0.0