Sortable v1.0.0

Seamlessly create draggable lists

  • Drag
    [item_name]
    1. Quick Installation Guide

      1. Download the plugin and unpack the .js and .css files.
      2. 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>
      3. 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>
      4. 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>
      5. 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:

      1. 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.
      2. 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>
      3. 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.
      4. 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>
      5. Drag an item from User menu to the Shop menu. You can mix items from different instances together, Sortable will handle that.
      6. Have fun with Sortable.

      User menu

    2. Drag
      [item_name]
      1. 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.

      2. Drag
        [item_name]
        1. 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}">  

          Attributes

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

          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

          Copyright © 2016-2017 Mateusz Zawartka