TableDnD/stripe.html

   1 <!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN"
   2         "http://www.w3.org/TR/html4/loose.dtd">
   3 <html>
   4 <head>
   5     <title>Table Drag and Drop jQuery plugin</title>
   6     <link rel="stylesheet" href="tablednd.css" type="text/css"/>
   7 </head>
   8 <body>
   9 <div id="page">
  10 <h1>Table Drag and Drop jQuery plugin</h1>
  11 <p>This page contains documentation and tests for the TableDnD jQuery plug-in. For more information and
  12 to post comments, please go to <a href="http://www.isocra.com/2008/02/table-drag-and-drop-jquery-plugin/">isocra.com</a>.
  13 </p>
  14 <p>If you have issues or bug reports, then you can post them at the <a href="http://plugins.jquery.com/project/issues/TableDnD">TableDnD plug page</a>
  15 at plugins.jquery.com</p>
  16
  17 <h2>How do I use it?</h2>
  18 <ol>
  19         <li>Download <a href="http://jquery.com">Download jQuery</a> (version 1.2 or above), then the <a href="/articles/jquery.tablednd.js.zip">TableDnD plugin</a> (current version 0.4).</li>
  20         <li>Reference both scripts in your HTML page in the normal way.</li>
  21         <li>In true jQuery style, the typical way to initialise the tabes is in the <code>$(document).ready</code> function. Use a selector to select your table and then call <code>tableDnD()</code>. You can optionally specify a set of properties (described below).</li>
  22 </ol>
  23 <div class="tableDemo">
  24 <div id="debug" style="float:right;"></div>
  25 <table id="table-1" cellspacing="0" cellpadding="2">
  26     <tr id="1"><td>1</td><td>One</td><td>some text</td></tr>
  27     <tr id="2"><td>2</td><td>Two</td><td>some text</td></tr>
  28     <tr id="3"><td>3</td><td>Three</td><td>some text</td></tr>
  29     <tr id="4"><td>4</td><td>Four</td><td>some text</td></tr>
  30     <tr id="5"><td>5</td><td>Five</td><td>some text</td></tr>
  31     <tr id="6"><td>6</td><td>Six</td><td>some text</td></tr>
  32 </table>
  33 </div>
  34 <p>The HTML for the table is very straight forward (no Javascript, pure HTML):</p>
  35
  36 <pre>
  37 &lt;table id=&quot;table-1&quot; cellspacing=&quot;0&quot; cellpadding=&quot;2&quot;&gt;
  38     &lt;tr id=&quot;1&quot;&gt;&lt;td&gt;1&lt;/td&gt;&lt;td&gt;One&lt;/td&gt;&lt;td&gt;some text&lt;/td&gt;&lt;/tr&gt;
  39     &lt;tr id=&quot;2&quot;&gt;&lt;td&gt;2&lt;/td&gt;&lt;td&gt;Two&lt;/td&gt;&lt;td&gt;some text&lt;/td&gt;&lt;/tr&gt;
  40     &lt;tr id=&quot;3&quot;&gt;&lt;td&gt;3&lt;/td&gt;&lt;td&gt;Three&lt;/td&gt;&lt;td&gt;some text&lt;/td&gt;&lt;/tr&gt;
  41     &lt;tr id=&quot;4&quot;&gt;&lt;td&gt;4&lt;/td&gt;&lt;td&gt;Four&lt;/td&gt;&lt;td&gt;some text&lt;/td&gt;&lt;/tr&gt;
  42     &lt;tr id=&quot;5&quot;&gt;&lt;td&gt;5&lt;/td&gt;&lt;td&gt;Five&lt;/td&gt;&lt;td&gt;some text&lt;/td&gt;&lt;/tr&gt;
  43     &lt;tr id=&quot;6&quot;&gt;&lt;td&gt;6&lt;/td&gt;&lt;td&gt;Six&lt;/td&gt;&lt;td&gt;some text&lt;/td&gt;&lt;/tr&gt;
  44 &lt;/table&gt;
  45 </pre>
  46 <p>To add in the "draggability" all we need to do is add a line to the <code>$(document).ready(...)</code> function
  47 as follows:</p>
  48 <pre>
  49 <span class="comment">&lt;script type=&quot;text/javascript&quot;&gt;</span>
  50 $(document).ready(function() {
  51     <span class="comment">// Initialise the table</span>
  52     $(&quot;#table-1&quot;).tableDnD();
  53 });
  54 <span class="comment">&lt;/script&gt;</span>
  55 </pre>
  56 <p>In the example above we're not setting any parameters at all so we get the default settings. There are a number
  57         of parameters you can set in order to control the look and feel of the table and also to add custom behaviour
  58         on drag or on drop. The parameters are specified as a map in the usual way and are described below:</p>
  59
  60 <dl>
  61         <dt>onDragStyle</dt>
  62         <dd>This is the style that is assigned to the row during drag. There are limitations to the styles that can be
  63                 associated with a row (such as you can't assign a border&mdash;well you can, but it won't be
  64                 displayed). (So instead consider using <code>onDragClass</code>.) The CSS style to apply is specified as
  65                 a map (as used in the jQuery <code>css(...)</code> function).</dd>
  66         <dt>onDropStyle</dt>
  67         <dd>This is the style that is assigned to the row when it is dropped. As for onDragStyle, there are limitations
  68                 to what you can do. Also this replaces the original style, so again consider using onDragClass which
  69                 is simply added and then removed on drop.</dd>
  70         <dt>onDragClass</dt>
  71         <dd>This class is added for the duration of the drag and then removed when the row is dropped. It is more
  72                 flexible than using onDragStyle since it can be inherited by the row cells and other content. The default
  73                 is class is <code>tDnD_whileDrag</code>. So to use the default, simply customise this CSS class in your
  74                 stylesheet.</dd>
  75         <dt>onDrop</dt>
  76         <dd>Pass a function that will be called when the row is dropped. The function takes 2 parameters: the table
  77             and the row that was dropped. You can work out the new order of the rows by using
  78             <code>table.tBodies[0].rows</code>.</dd>
  79         <dt>onDragStart</dt>
  80         <dd>Pass a function that will be called when the user starts dragging. The function takes 2 parameters: the
  81                 table and the row which the user has started to drag.</dd>
  82         <dt>scrollAmount</dt>
  83         <dd>This is the number of pixels to scroll if the user moves the mouse cursor to the top or bottom of the
  84                 window. The page should automatically scroll up or down as appropriate (tested in IE6, IE7, Safari, FF2,
  85                 FF3 beta)</dd>
  86 </dl>
  87 <p>This second table has has an onDrop function applied as well as an onDragClass. The javascript to set this up is
  88 as follows:</p>
  89 <pre>
  90 $(document).ready(function() {
  91
  92         // Initialise the first table (as before)
  93         $("#table-1").tableDnD();
  94
  95         // Make a nice striped effect on the table
  96         $("#table-2 tr:even').addClass('alt')");
  97
  98         // Initialise the second table specifying a dragClass and an onDrop function that will display an alert
  99         $("#table-2").tableDnD({
 100             onDragClass: "myDragClass",
 101             onDrop: function(table, row) {
 102             var rows = table.tBodies[0].rows;
 103             var debugStr = "Row dropped was "+row.id+". New order: ";
 104             for (var i=0; i&lt;rows.length; i++) {
 105                 debugStr += rows[i].id+" ";
 106             }
 107                 $(#debugArea).html(debugStr);
 108             },
 109                 onDragStart: function(table, row) {
 110                         $(#debugArea).html("Started dragging row "+row.id);
 111                 }
 112         });
 113 });
 114 </pre>
 115 <div class="tableDemo">
 116 <div id="debugArea" style="float: right">&nbsp;</div>
 117 <table id="table-2" cellspacing="0" cellpadding="2">
 118     <tr id="2.1"><td>1</td><td>One</td><td><input type="text" name="one" value="one"/></td></tr>
 119     <tr id="2.2"><td>2</td><td>Two</td><td><input type="text" name="two" value="two"/></td></tr>
 120     <tr id="2.3"><td>3</td><td>Three</td><td><input type="text" name="three" value="three"/></td></tr>
 121     <tr id="2.4"><td>4</td><td>Four</td><td><input type="text" name="four" value="four"/></td></tr>
 122     <tr id="2.5"><td>5</td><td>Five</td><td><input type="text" name="five" value="five"/></td></tr>
 123     <tr id="2.6"><td>6</td><td>Six</td><td><input type="text" name="six" value="six"/></td></tr>
 124     <tr id="2.7"><td>7</td><td>Seven</td><td><input type="text" name="seven" value="7"/></td></tr>
 125     <tr id="2.8"><td>8</td><td>Eight</td><td><input type="text" name="eight" value="8"/></td></tr>
 126     <tr id="2.9"><td>9</td><td>Nine</td><td><input type="text" name="nine" value="9"/></td></tr>
 127     <tr id="2.10"><td>10</td><td>Ten</td><td><input type="text" name="ten" value="10"/></td></tr>
 128     <tr id="2.11"><td>11</td><td>Eleven</td><td><input type="text" name="eleven" value="11"/></td></tr>
 129     <tr id="2.12"><td>12</td><td>Twelve</td><td><input type="text" name="twelve" value="12"/></td></tr>
 130     <tr id="2.13"><td>13</td><td>Thirteen</td><td><input type="text" name="thirteen" value="13"/></td></tr>
 131     <tr id="2.14"><td>14</td><td>Fourteen</td><td><input type="text" name="fourteen" value="14"/></td></tr>
 132 </table>
 133 </div>
 134 <h2>What to do afterwards?</h2>
 135 <p>Generally once the user has dropped a row, you need to inform the server of the new order. To do this, we've
 136         added a method called <code>serialise()</code>. It takes no parameters but knows the current table from the
 137         context. The method returns a string of the form <code><i>tableId</i>[]=<i>rowId1</i>&amp;<i>tableId</i>[]=<i>rowId2</i>&amp;<i>tableId</i>[]=<i>rowId3</i>...</code>
 138         You can then use this as part of an Ajax load.
 139 </p>
 140 <p>This third table demonstrates calling the serialise function inside onDrop (as shown below). It also
 141         demonstrates the "nodrop" class on row 3 and "nodrag" class on row 5, so you can't pick up row 5 and
 142         you can't drop any row on row 3 (but you can drag it).</p>
 143 <pre>
 144     $('#table-3').tableDnD({
 145         onDrop: function(table, row) {
 146             alert($.tableDnD.serialize());
 147         }
 148     });
 149 </pre>
 150 <div class="tableDemo">
 151 <div id="AjaxResult" style="float: right; width: 250px; border: 1px solid silver; padding: 4px; font-size: 90%">
 152         <h3>Ajax result</h3>
 153         <p>Drag and drop in this table to test out serialise and using JQuery.load()</p>
 154 </div>
 155 <table id="table-3" cellspacing="0" cellpadding="2">
 156     <tr id="3.1"><td>1</td><td>One</td><td><input type="text" name="one" value="one"/></td></tr>
 157     <tr id="3.2"><td>2</td><td>Two</td><td><input type="text" name="two" value="two"/></td></tr>
 158     <tr id="3.3" class="nodrop"><td>3</td><td>Three (Can't drop on this row)</td><td><input type="text" name="three" value="three"/></td></tr>
 159     <tr id="3.4"><td>4</td><td>Four</td><td><input type="text" name="four" value="four"/></td></tr>
 160     <tr id="3.5" class="nodrag"><td>5</td><td>Five (Can't drag this row)</td><td><input type="text" name="five" value="five"/></td></tr>
 161     <tr id="3.6"><td>6</td><td>Six</td><td><input type="text" name="six" value="six"/></td></tr>
 162 </table>
 163 </div>
 164 <p>This table has multiple TBODYs. The functionality isn't quite working properly. You can only drag the rows inside their
 165 own TBODY, you can't drag them outside it. Now this might or might not be what you want, but unfortunately if you then drop a row outside its TBODY you get a Javascript error because inserting after a sibling doesn't work. This will be fixed in the next version. The header rows all have the classes "nodrop" and "nodrag" so that they can't be dragged or dropped on.</p>
 166 <div class="tableDemo">
 167 <table id="table-4" cellspacing="0" cellpadding="2">
 168         <tbody>
 169                 <tr id="4.0" class="nodrop nodrag"><th>H1</th><th>H2</th><th>H3</th></tr>
 170         <tr id="4.1"><td>4.1</td><td>One</td><td><input type="text" name="one" value="one"/></td></tr>
 171         <tr id="4.2"><td>4.2</td><td>Two</td><td><input type="text" name="two" value="two"/></td></tr>
 172         <tr id="4.3"><td>4.3</td><td>Three</td><td><input type="text" name="three" value="three"/></td></tr>
 173         <tr id="4.4"><td>4.4</td><td>Four</td><td><input type="text" name="four" value="four"/></td></tr>
 174         <tr id="4.5"><td>4.5</td><td>Five</td><td><input type="text" name="five" value="five"/></td></tr>
 175         <tr id="4.6"><td>4.6</td><td>Six</td><td><input type="text" name="six" value="six"/></td></tr>
 176         </tbody>
 177         <tbody>
 178                 <tr id="5.0" class="nodrop nodrag"><th>H1</th><th>H2</th><th>H3</th></tr>
 179         <tr id="5.1"><td>5.1</td><td>One</td><td><input type="text" name="one" value="one"/></td></tr>
 180         <tr id="5.2"><td>5.2</td><td>Two</td><td><input type="text" name="two" value="two"/></td></tr>
 181         <tr id="5.3"><td>5.3</td><td>Three</td><td><input type="text" name="three" value="three"/></td></tr>
 182         <tr id="5.4"><td>5.4</td><td>Four</td><td><input type="text" name="four" value="four"/></td></tr>
 183         <tr id="5.5"><td>5.5</td><td>Five</td><td><input type="text" name="five" value="five"/></td></tr>
 184         <tr id="5.6"><td>5.6</td><td>Six</td><td><input type="text" name="six" value="six"/></td></tr>
 185         </tbody>
 186         <tbody>
 187                 <tr id="6.0" class="nodrop nodrag"><th>H1</th><th>H2</th><th>H3</th></tr>
 188         <tr id="6.1"><td>6.1</td><td>One</td><td><input type="text" name="one" value="one"/></td></tr>
 189         <tr id="6.2"><td>6.2</td><td>Two</td><td><input type="text" name="two" value="two"/></td></tr>
 190         <tr id="6.3"><td>6.3</td><td>Three</td><td><input type="text" name="three" value="three"/></td></tr>
 191         <tr id="6.4"><td>6.4</td><td>Four</td><td><input type="text" name="four" value="four"/></td></tr>
 192         <tr id="6.5"><td>6.5</td><td>Five</td><td><input type="text" name="five" value="five"/></td></tr>
 193         <tr id="6.6"><td>6.6</td><td>Six</td><td><input type="text" name="six" value="six"/></td></tr>
 194         </tbody>
 195 </table>
 196 </div>
 197 <p>
 198 The following table demonstrates the use of the default regular expression. The rows have IDs of the
 199 form table5-row-1, table5-row-2, etc., but the regular expression is <code>/[^\-]*$/</code> (this is the same
 200 as used in the <a href="http://plugins.jquery.com/project/NestedSortable">NestedSortable</a> plugin for consistency).
 201 This removes everything before and including the last hyphen, so the serialised string just has 1, 2, 3 etc.
 202 You can replace the regular expression by setting the <code>serializeRegexp</code> option, you can also just set it
 203 to null to stop this behaviour.
 204 </p>
 205 <pre>
 206     $('#table-5').tableDnD({
 207         onDrop: function(table, row) {
 208             alert($.tableDnD.serialize());
 209         },
 210         dragHandle: "dragHandle"
 211     });
 212 </pre>
 213 <div class="tableDemo">
 214 <table id="table-5" cellspacing="0" cellpadding="2">
 215     <tr id="table5-row-1"><td class="dragHandle">&nbsp;</td><td>1</td><td>One</td><td>some text</td></tr>
 216     <tr id="table5-row-2"><td class="dragHandle">&nbsp;</td><td>2</td><td>Two</td><td>some text</td></tr>
 217     <tr id="table5-row-3"><td class="dragHandle">&nbsp;</td><td>3</td><td>Three</td><td>some text</td></tr>
 218     <tr id="table5-row-4"><td class="dragHandle">&nbsp;</td><td>4</td><td>Four</td><td>some text</td></tr>
 219     <tr id="table5-row-5"><td class="dragHandle">&nbsp;</td><td>5</td><td>Five</td><td>some text</td></tr>
 220     <tr id="table5-row-6"><td class="dragHandle">&nbsp;</td><td>6</td><td>Six</td><td>some text</td></tr>
 221 </table>
 222 </div>
 223 <p>In fact you will notice that I have also set the dragHandle on this table. This has two effects: firstly only
 224 the cell with the drag handle class is draggable and secondly it doesn't automatically add the <code>cursor: move</code>
 225 style to the row (or the drag handle cell), so you are responsible for setting up the style as you see fit.</p>
 226 <p>Here I've actually added an extra effect which adds a background image to the first cell in the row whenever
 227 you enter it using the jQuery <code>hover</code> function as follows:</p>
 228 <pre>
 229     $("#table-5 tr").hover(function() {
 230           $(this.cells[0]).addClass('showDragHandle');
 231     }, function() {
 232           $(this.cells[0]).removeClass('showDragHandle');
 233     });
 234 </pre>
 235 <p>This provides a better visualisation of what you can do to the row and where you need to go to drag it (I hope).</p>
 236 <h2>Version History</h2>
 237 <table class="versionHistory">
 238         <tr><td>0.2</td><td>2008-02-20</td><td>First public release</td></tr>
 239         <tr><td>0.3</td><td>2008-02-27</td><td>Added onDragStart option<br/>Made the scroll amount configurable (default is 5 as before)</td></tr>
 240         <tr><td>0.4</td><td>2008-03-28</td><td>Fixed the scrollAmount so that if you set this to zero then it switches off this functionality<br/>Fixed the auto-scrolling in IE6 thanks to Phil<br/>Changed the NoDrop attribute to the class "nodrop" (so any row with this class won't allow dropping)<br/>Changed the NoDrag attribute to the class "nodrag" (so any row with this class can't be dragged)<br/>Added support for multiple TBODYs--though it's still not perfect<br/>Added onAllowDrop to allow the developer to customise this behaviour<br/>Added a serialize() method to return the order of the rows in a form suitable for POSTing back to the server</td></tr>
 241     <tr><td>0.5</td><td>2008-06-04</td><td>Changed so that if you specify a dragHandle class it doesn't make the whole row<br/>draggable<br/>Improved the serialize method to use a default (and settable) regular expression.<br/>Added tableDnDupate() and tableDnDSerialize() to be called when you are outside the table</td></tr>
 242 </table>
 243 </div>
 244 <script type="text/javascript" src="//ajax.googleapis.com/ajax/libs/jquery/1.8.2/jquery.min.js"></script>
 245 <script type="text/javascript" src="js/jquery.tablednd.js"></script>
 246 <script type="text/javascript">
 247     $(document).ready(function() {
 248         alert("Here I am");
 249         // Initialise the first table (as before)
 250         $("#table-1").tableDnD();
 251         // Make a nice striped effect on the table
 252         $("#table-2 tr:even").addClass("alt");
 253         // Initialise the second table specifying a dragClass and an onDrop function that will display an alert
 254         $("#table-2").tableDnD({
 255             onDragClass: "myDragClass",
 256             onDrop: function(table, row) {
 257                 var rows = table.tBodies[0].rows;
 258                 var debugStr = "Row dropped was "+row.id+". New order: ";
 259                 for (var i=0; i<rows.length; i++) {
 260                     debugStr += rows[i].id+" ";
 261                 }
 262                 $("#debugArea").html(debugStr);
 263             },
 264             onDragStart: function(table, row) {
 265                 $("#debugArea").html("Started dragging row "+row.id);
 266             }
 267         });
 268
 269         $('#table-3').tableDnD({
 270             onDrop: function(table, row) {
 271                 alert("Result of $.tableDnD.serialise() is "+$.tableDnD.serialize());
 272                 $('#AjaxResult').load("server/ajaxTest.php?"+$.tableDnD.serialize());
 273             }
 274         });
 275
 276         //$('#table-4').tableDnD(); // no options currently
 277         $('#table-4 tr:even').css('background', '#ecf6fc');
 278
 279         $('#table-5').tableDnD({
 280             onDrop: function(table, row) {
 281                 alert($('#table-5').tableDnDSerialize());
 282             },
 283             dragHandle: "dragHandle"
 284         });
 285
 286         $("#table-5 tr").hover(function() {
 287             $(this.cells[0]).addClass('showDragHandle');
 288         }, function() {
 289             $(this.cells[0]).removeClass('showDragHandle');
 290         });
 291     });
 292 </script>
 293 </body>
 294 </html>