Sort a list with drag and drop. :: Legacy Documentation

Use jQuery.UI to make a list sortable by drag and drop. Variations of this technique are used throughout Concrete5 and various add-ons to allow the user to sort lists by dragging and dropping elements.

sortable list

The example sorts a list of names, so first some initial values for the list.

<?php
$all_names = array ('Franz', 'Andrew', 'Greg', 'Ryan', 'Matt');
?>

These names will be displayed as a list of table rows . As we will be making the list sortable we will add icons to act as a drag-handle. This is not required, but is a nice touch.

<?php
$sort_icon = '<img src="'.ASSETS_URL_IMAGES.'/icons/up_down.png" class="sort_handle" height="14" width="14" style="cursor:move;">';
?>

Now we turn the list of names into rows of a table, with hidden input elements used to note each name. Alternatively, text input elements could be used to make the names both editable and sortable. For simplicity, the surrounding form and submit controls have been left out of the example.

<table>
<tr><td><?php echo 'Sort Names';?></td><td></td></tr>
<?php 
foreach($all_names as $a_name) { ?>
  <tr class="sortable_row">
  <td><input type="hidden" name="all_names[]" value="<?php  echo $a_name ?>" ><?php echo $a_name ?></td>
  <td><?php echo $sort_icon;?></td>
  </tr><?php  
}?>
</table>

The list is made sortable by attaching the jQuery.UI sortable widget to the table. See http://jqueryui.com/demos/sortable/.

In an edit form, jQuery.ui will already be loaded by Concrete5. However, jQuery.ui will not necessarily be loaded when viewing a page, so developers need to use addHeaderItem to load jquery.js, jquery.ui.css and jquery.ui.js. This can be done in a template header, a single page controller or block controller. Another option is to use the Load jQuery.UI add-on.

When the move icon is clicked, the sortable widget takes care of everything, allowing the user to drag the row up or down the table. The two important parameters are:

'items', which tells the widget that it is rows with the class 'sortable_row' that it will be sorting.
'handle', which selects the icon that is used as a handle to make the sort (by the class 'sort_handle').

(Note that css classes have a '.' prepended when they are used as jQuery selectors)

<script type="text/javascript">
$(document).ready(function(){
  $("table").sortable(
    { items : '.sortable_row',
      handle: '.sort_handle'
  });
});
</script>

sorting in progress

sorting done

On the server, the controller or tool handling the submitted form can get the sorted rows as an array of the hidden input values from $_POST.

$all_names = $_POST['all_names'];

As already noted above, a form and submit button are needed to wrap the table. This is a useful technique for combining with a dynamic list of input elements.

Like most jQuery.ui widgets, sortable has numerous events. For example, an update event can be used to run processing whenever a sort/move is completed.

The application of the sortable widget is not limited to table rows, it can just as easily be attached to any other list, including HTML list elements. Table rows were only used in the example to make it easier to combine this how-to with the dynamic list how-to.

Tags