Customizable Drag-and-Drop Table Sorting Plugin - jQuery TableDnD

File Size: 122 KB
Views Total: 15237
Last Update:
Publish Date:
Official Website: Go to website
License: MIT
   
Customizable Drag-and-Drop Table Sorting Plugin - jQuery TableDnD

TableDnD is a simple yet highly customizable jQuery table sorting plugin which enables you to reorder table rows using drag and drop. Supports both sever side and client side handling.

Basic usage:

1. To get started, include both jQuery JavaScript library and the jQuery TableDnD plugin's script on the html page.

<script src="https://code.jquery.com/jquery-1.12.4.min.js" 
        integrity="sha384-nvAa0+6Qg9clwYCGGPpDQLVpLNn0fRaROjHqs13t4Ggj3Ez50XnGQqc/r8MhnRDZ" 
        crossorigin="anonymous">
</script>
<script src="jquery.tablednd.js"></script>

2. Just call the function on the existing html table and done.

<table id="example">
  <tr id="1">
    <td>1</td>
    <td>One</td>
    <td>some text</td>
  </tr>
  <tr id="2">
    <td>2</td>
    <td>Two</td>
    <td>some text</td>
  </tr>
  <tr id="3">
    <td>3</td>
    <td>Three</td>
    <td>some text</td>
  </tr>
  <tr id="4">
    <td>4</td>
    <td>Four</td>
    <td>some text</td>
  </tr>
  <tr id="5">
    <td>5</td>
    <td>Five</td>
    <td>some text</td>
  </tr>
  <tr id="6">
    <td>6</td>
    <td>Six</td>
    <td>some text</td>
  </tr>
</table>
$(document).ready(function() {
  $("#example").tableDnD();
});

3. Add class="nodrop" to any rows for which you don't want to allow dropping, and class="nodrag" to any rows that you don't want to be draggable.

<table id="example">
  <tr id="1">
    <td>1</td>
    <td>One</td>
    <td>some text</td>
  </tr>
  <tr id="2" class="nodrop">
    <td>2</td>
    <td>Two</td>
    <td>some text</td>
  </tr>
  <tr id="3" class="nodrag">
    <td>3</td>
    <td>Three</td>
    <td>some text</td>
  </tr>
  <tr id="4">
    <td>4</td>
    <td>Four</td>
    <td>some text</td>
  </tr>
  <tr id="5">
    <td>5</td>
    <td>Five</td>
    <td>some text</td>
  </tr>
  <tr id="6">
    <td>6</td>
    <td>Six</td>
    <td>some text</td>
  </tr>
</table>

4. Configuration options and event handlers:

  • onDragStyle: This is the style that is assigned to the row during drag. There are limitations to the styles that can be associated with a row (such as you can't assign a border--well you can, but it won't be displayed). (So instead consider using onDragClass.) The CSS style to apply is specified as a map (as used in the jQuery css(...) function).
  • onDropStyle: This is the style that is assigned to the row when it is dropped. As for onDragStyle, there are limitations to what you can do. Also this replaces the original style, so again consider using onDragClass which is simply added and then removed on drop.
  • onDragClass: This class is added for the duration of the drag and then removed when the row is dropped. It is more flexible than using onDragStyle since it can be inherited by the row cells and other content. The default is class is tDnD_whileDrag. So to use the default, simply customise this CSS class in your stylesheet.
  • onDrop: Pass a function that will be called when the row is dropped. The function takes 2 parameters: the table and the row that was dropped. You can work out the new order of the rows by using table.rows.
  • onDragStart: Pass a function that will be called when the user starts dragging. The function takes 2 parameters: the table and the row which the user has started to drag.
  • onDragStop: Pass a function that will be called when the user stops dragging regardless of if the rows have been rearranged. The function takes 2 parameters: the table and the row which the user was dragging.
  • onAllowDrop: Pass a function that will be called as a row is over another row. If the function returns true, allow dropping on that row, otherwise not. The function takes 2 parameters: the dragged row and the row under the cursor. It returns a boolean: true allows the drop, false doesn't allow it.
  • scrollAmount: This is the number of pixels to scroll if the user moves the mouse cursor to the top or bottom of the window. The page should automatically scroll up or down as appropriate.
  • dragHandle: This is a jQuery mach string for one or more cells in each row that is draggable. If you specify this, then you are responsible for setting cursor: move in the CSS and only these cells will have the drag behaviour. If you do not specify a dragHandle, then you get the old behaviour where the whole row is draggable.
$("#example").tableDnD({
  onDragStyle: null,
  onDropStyle: null,
  onDragClass: null,
  onDrop: null,
  onDragStart: null,
  onDragStop: null
  scrollAmount: 5,
  sensitivity: 10,
  hierarchyLevel: 0,
  indentArtifact: '<div class="indent">&nbsp;</div>',
  autoWidthAdjust: true,
  autoCleanRelations: true,
  jsonPretifySeparator: '\t',
  serializeRegexp: /[^\-]*$/,
  serializeParamName: false,
  dragHandle: null
});

5. Inside the onDrop method you can also call $.tableDnD.serialize() this returns a string of the form <tableID>[]=<rowID1>&<tableID>[]=<rowID2> so that you can send this back to the server. The table must have an ID as must all the rows.

6. More API methods.

// Will update all the matching tables, that is it will reapply the mousedown method to the rows (or handle cells).
// This is useful if you have updated the table rows using Ajax and you want to make the table draggable again.
// The table maintains the original configuration (so you don't have to specify it again).
$("...").tableDnDUpdate();

// Will serialize and return the serialized string as above, but for each of the matching tables
// So it can be called from anywhere and isn't dependent on the currentTable being set up correctly before calling
$("...").tableDnDSerialize();

Changelog:

2020-08-26

  • v1.0.5

This awesome jQuery plugin is developed by isocra. For more Advanced Usages, please check the demo page or visit the official website.