Talk In Code

A sortable list is simply a list of items that can be dragged and dropped to alter the order of those elements.

There are two sortable lists available in WordPress, one from the JQuery framework and one from the Scriptaculous framework. For a sortable list you will need a list, so here is a simple one.

<ul id="sortcontainer">
<li class="sortable">Item 1</li>
<li class="sortable">Item 2</li>
<li class="sortable">Item 3</li>
<li class="sortable">Item 4</li>
</ul>


JQuery Sortable

The JQuery sortable control is actually a plugin and not part of the standard JQuery framework. The first thing we need to do is add in the correct JavaScript libraries that we need to use. We do this with the wp_enqueue_script() WordPress function. The are quite a few different things that are needed so you can use an array to pass in all of the options.

wp_enqueue_script( array("jquery", "jquery-ui-core", "interface", "jquery-ui-sortable", "wp-lists", "jquery-ui-sortable") );

Here is the JavaScript code that is needed to create the sortable list.

<script type="text/javascript">
 jQuery(function($) {
 
 var smpSortable;
 var smpSortableInit = function() {
  try { // a hack to make sortables work in jQuery 1.2+ and IE7
   $('#sortcontainer').SortableDestroy();
  } catch(e) {}
  smpSortable = $('#sortcontainer').Sortable( {
  accept: 'sortable',
  onStop: smpSortableInit
  } );
 }
 
 // initialize sortable
 smpSortableInit();
});
</script>

For more information on the sort of options available have a look at the JQuery Sortables documentation.

Scriptaculous Sortable

To use the Scriptaculous sortable list we add in the scriptaculous-dragdrop library using the wp_enqueue_script() WordPress function.

wp_enqueue_script("scriptaculous-dragdrop");

Here is the code you need to create the sortable list, you need to include this on the page below the list.

<script type="text/javascript">
  Position.includeScrollOffsets = true;
  Sortable.create('sortcontainer',{
   tag: 'li',
   scroll: window
  });
</script>

For more information on the sort of options available have a look at the Scriptaculous Sortables documentation.

If you only want to run the wp_enqueue_script() function in the admin section of WordPress you can use the is_admin() function. This returns true if the code is run in the admin section, and false if run on the front end. Using this function you can stop JavaScript libraries being included when you don’t use them.

Drag and drop is a useful mechanism to do stuff and can turn a complicated set of buttons or drop down lists into a simple elegant solution.

WordPress has lots of scripts built in, which do a lot of useful functions. However, they are not enabled by default, which means that in order to get your script to work you need to enable them.

The drag and drop functionality in WordPress is provided by the Scriptaculous framework. To get WordPress to include this in your page header just use the function wp_enqueue_script() with the parameter "scriptaculous-dragdrop".

wp_enqueue_script("scriptaculous-dragdrop");

I have had limited success running this code from within functions, so your best bet is to add it to the bottom of your plugin file, outside the scope of any functions.

If you only want to enable them in the admin section the enclose this function call in an if statement that uses the is_admin() function to see if the script is being run in the admin section.

if ( is_admin() ) {
  wp_enqueue_script("scriptaculous-dragdrop");
}

You can now create your sortable list.

<div id="container_sortable">
<div id="item_1">Item 1</div>
<div id="item_2">Item 2</div>
<div id="item_3">Item 3</div>
</div>

And add the JavaScript to get it working. The following code converts

Position.includeScrollOffsets = true;
Sortable.create('container_sortable',{
  tag: 'div',
  scroll: window,
  onChange: doSomething
});
 
function doSomething(){
 // on change code here
}


Note that the id format of "item_itemNumber" as in "item_1" is important to get Sortable class functions like sequence() working. If the items are not in this format then sequence() will return null for that item.

The line Position.includeScrollOffsets = true; is added before the call to Sortable.create() in order to get window scrolling working. If you have a large list, and you want items dragged to the top of the window to scroll upwards then use this and the option "scroll: window" to create a browser compatible mechanism of scrolling the window.

For a full list of the sort of scripts that can include see the bottom of the WordPress page on wp_enqueue_script.

Script.aculo.us is a JavaScript framework that allows you to add effects and advanced JavaScript features to any web page. Although Script.aculo.us can be a little slower than Mootools on occasion it makes up for this by having more stuff built into the library components. For example, the slider control is available of both frameworks, but the Script.aculo.us version comes with some handy features (like filling one part of the slider) where the Mootools version doesn’t.

My one problem with Script.aculo.us is the website. There are a few examples and descriptions, but most of what you need to know about seems to be poorly documented or it hasn’t been updated for many months. There is a forum where people can put questions and offer solutions, but again, this seems to be very much out of date and any solutions offered seem to only work with older versions of the framework.

Overall a good framework, with a poor site.

Creating a new Draggable object with the script.aculo.us framework is easy. You just create a new instance of the Draggable object with the element id to be made draggable as the first parameter and a set of options as the second.
<div id="dragMe"></div>
<script type="text/javascript">
new Draggable('dragMe',{revert:true});
</script>
The revert option will make the draggable element move back to the position it started from. More options can be added by separating them by commas, so to enable ghosting on the element as well as revert use the following.
new Draggable('dragMe',{revert:true,ghosting:true});
Ghosting means that when the element is dragged a ghost copy of the element moves with the mouse, where the original stays where it is until the mouse is released.
The snap parameter can be used to confine the element to a parent node. Snap is used to make the element move in blocks of a certain number rather than smoothly, this is a special parameter as it can take a number of different formats. These are as follows:
To turn snapping off set the value to false.
new Draggable('dragMe',{revert:true,ghosting:true,snap:false});
To set the same value for x and y use a single parameter.
new Draggable('dragMe',{revert:true,ghosting:true,snap:25});
To set different values for x and y use an array notation.
new Draggable('dragMe',{revert:true,ghosting:true,snap:[25,50]});
A call back function can also be used to set up your own snapping behaviour. This is where you can do set up a constraint so that the draggable element doesn’t leave the area of it’s parent element.
new Draggable('dragMe',{revert:true,ghosting:true,snap: function(x,y,draggable) {
  function constrain(n, lower, upper) {
    if (n > upper) return upper;
    else if (n < lower) return lower;
    else return n-(n%10);
  }
  element_dimensions = Element.getDimensions(draggable.element);
  parent_dimensions = Element.getDimensions(draggable.element.parentNode);
  return[
    constrain(x, 0, parent_dimensions.width - element_dimensions.width),
    constrain(y, 0, parent_dimensions.height - element_dimensions.height)];
  }
});
When the draggable element moves over the edge of the parent element the snap value is set to the upper or lower limit of the parent element (depending on where the element is being dragged). Otherwise the current position is used, which means that it snaps to where the mouse is.
This function is called every time a mouse move event is detected whilst the specified element is being dragged so be careful when adding any alert statements if you are trying to debug the code.