More to come…

One of the first examples available on the web was a Drag and Drop example provided by Jonathan Snook on his blog (See example here). After I played around with his example, I was interested in testing out the Sortable List functionality available in the effects portion of mootools. I put together a quick example of a Sortable List implementation, so feel free to check it out and view the source.

I tried to go a bit farther than simply implementing the Sortable List functionality by adding an Opacity effect and making additions to the onDrag and onComplete functions of the dragger. For a more in-depth explanation of the code, read the full post.

Creating a Sortable List

Creating a Sortable List with the mootools framework is fairly straight-forward. However, some of the code in the Sortables class has been stripped out to allow the list to sort properly. When I first started playing with the Sortables, I was using Revision 57 of mootools. I noticed that the sorting of the list was very buggy and not working properly at all, so I updated to Revision 64 and everything worked fine. Well… sorta. In Revision 58, the droppables logic was stripped out of the Sortables class because it was apparrently causing problems. With this change, the basic functionality of Sortable Lists is available, but it will be nice when the droppables are added back in so we can make use of the onOver, onLeave and onDrop functions.

To create a Sortable List with mootools, all you need to do is create a new Sortables object and have each sortable element extend that object. So first, I defined my list of sortable elements and gave each of them a className of “sort” so I can easily fetch them from the DOM:

<ul>
    <li class="sort">Item 1</li>
    <li class="sort">Item 2</li>
    <li class="sort">Item 3</li>
    <li class="sort">Item 4</li>
</ul>

Now, we just need to create our Sortables object and loop through our array of sort items to have each of them extend that Sortables object. I like the concept of having a single function to call to make a Sortable List, similar to the way you can call makeDraggable() on an element. To give myself this ability for Sortable Lists as well, I extended Array and added a makeSortable() function that takes in a sortableOptions object to use when instantiating our Sortables object:

Array.extend({
	makeSortable: function(options){
		var Sortable = new Sortables(this, options);
		this.each(function(el){
			el.style.cursor = 'move';
			el.extend(Sortable);
		})
	}
});

The makeSortable() function just creates our Sortables object, then loops through the Array of sort items it has been called on to perform some additional logic. In this case, it sets the cursor style of each sort item to ‘move’ to indicate that a user can drag it, and then has each sort item extend the Sortables object we just created.

Now that we have the new makeSortable() function, all we have to do is use the helpful $S() function to grab all of our sort items and call makeSortable on them with any additional options we might want. This is done in the window.onload() function so our Sortable List is ready to go as soon as the window is done loading.

window.onload = function() {
	$S('#container li.sort').makeSortable(sortableOptions);
}

Using onStart, onComplete and onDrag

At this point, we have a perfectly functioning Sortable List. But that’s a little too easy, so I decided to add a status indicator below the list that informs the user of the current operation being performed on the list. This is just an empy span element in the source with the id ’status’ so I can get a handle on it later.

I will update the contents of that span element with information while the user is sorting the list.
To do this, I need to add logic to the onDrag and onComplete functions of the dragger object that is created in the Sortables class. Unfortunately, Sortables is not setup to accept function definitions for onStart, onComplete and onDrag. It would be nice if you could specify custom functionality for these events in the sortableOptions that are used to initialize the Sortables object and then have the base logic of those functions extend whatever was passed in with the sortableOptions.

Since that doesn’t seem to be possible right now, I decided to use the implement() feature of mootools to create a new implementation of the initialize function in the Sortables class. This isn’t very efficient because I want to keep most of the functionality of the Sortables class and only need to add a few lines of code for my custom behavior, but I can’t think of a better way to do it right now. Below is my custom implementation of the initialize function in the Sortables class:

Sortables.implement({
		initialize: function(elements, options){
			this.setOptions(options);
			this.options.handles = this.options.handles || elements;
			var trash = new Element('div').injectInside($(document.body));
			$A(elements).each(function(el, i){
				var copy = $(el).clone().setStyles({
					'position': 'absolute',
					'opacity': '0',
					'display': 'none'
				}).injectInside(trash);
				var elEffect = el.effect('opacity', {
					duration: this.options.fxDuration,
					wait: false,
					transition: this.options.fxTransition
				}).set(1);
				var copyEffects = copy.effects({
					duration: this.options.fxDuration,
					wait: false,
					transition: this.options.fxTransition,
					onComplete: function(){
						copy.setStyle('display', 'none');
					}
				});
				var dragger = new Drag.Move(copy, {
					xModifier: false,
					onStart: function(){
						copy.setHTML(el.innerHTML).setStyles({
							'display': 'block',
							'opacity': this.options.maxOpacity,
							'top': el.getTop()+'px',
							'left': el.getLeft()+'px'
						});
						elEffect.custom(elEffect.now, this.options.maxOpacity);
					}.bind(this),
					onComplete: function(){
						copyEffects.custom({
							'opacity': [this.options.maxOpacity, 0],
							'top': [copy.getTop(), el.getTop()]
						});
						elEffect.custom(elEffect.now, 1);
						$('status').setHTML('Sorting complete!');
						statusFade.custom(1,0);
					}.bind(this),
					onDrag: function(){
						if (el.getPrevious() && copy.getTop() < (el.getPrevious().getTop()))
							el.injectBefore(el.getPrevious());
						else if (el.getNext() && copy.getTop() > (el.getNext().getTop()))
							el.injectAfter(el.getNext());
                                                statusFade.clearTimer();
                                                $('status').setOpacity(1).setHTML('Sorting in progress...');
					}
				});
				this.options.handles[i].onmousedown = dragger.start.bind(dragger);
			}, this);
		}
});

The lines of code highlighted in red are the only additions I made to the initialize function in my implementation. Now, the code that initializes my Sortables object will automatically use my implementation and it will get the benefits of the custom logic I have added.

You’ll notice that in the onComplete and onDrag functions I am updating the contents of the status element I created earlier through the use of the setHTML() function which is really just a wrapper around innerHTML.

$('status').setHTML('Sorting complete!');

You’ll also notice that I am doing some other stuff with an Opacity effect that I created. When a user is sorting the list, the status element will displaying the text Sorting in progress.... When they are finished, it will display the text Sorting complete!, but I don’t want that status to just sit there forever. Therefore, I created an Opacity effect that will cause the status text to slowly fade out after a set delay.

Creating an effect

To do this, I created the effect in the window.onload event so it is available to use as soon as the page is done loading:

statusFade = new Fx.Opacity('status', {duration: 2000, transition: Fx.cubic});

This basically says that I want to create an Opacity effect on the element with id of ’status’ and then specifies some options for that effect. Since I want my status text to fade slowly, I gave the effect a duration of 2000 milliseconds. I also specified a cubic transition which will cause the fade to perform slowly at first and speed up toward the end.

When I want to use this effect, I can call the custom() function on it and specify beginning and ending parameters. In this case, I want to go from zero Opacity (fully visible) to 100% Opacity, I call my effect like so:

onComplete: function(){
    copyEffects.custom({
	'opacity': [this.options.maxOpacity, 0],
	'top': [copy.getTop(), el.getTop()]
    });
    elEffect.custom(elEffect.now, 1);
    $('status').setHTML('Sorting complete!');
    statusFade.custom(1,0);
}

In the above code, when a user drops the item they are sorting, the onComplete function is executed. At this time, the contents of the span element with an id of ’status’ are updated and then the effect is called to cause the status to fade out slowly. Calling custom(1,0) will execute my Opacity effect and cause the element to go from fully visible (Opacity of 1) to invisible (Opacity of 0).

I also want to update the contents of the status element while a user is sorting the list. The problem is, after I fade out the status element, any subsinquent sorting status will not be visible to the user since that element is still invisible. Also, another problem is that once the status text starts fading, it won’t stop. So if a user drags an item to a new location and drops it, the text “Sorting complete!” will be displayed and begin to fade. But if the user then starts dragging an item again, the “Sorting in progress…” text will be displayed but continue to fade until it is gone. The following code illustrates how I dealt with both of those issues:

onDrag: function(){
    if (el.getPrevious() && copy.getTop() < (el.getPrevious().getTop()))
        el.injectBefore(el.getPrevious());
    else if (el.getNext() && copy.getTop() > (el.getNext().getTop()))
	el.injectAfter(el.getNext());
    statusFade.clearTimer();
    $('status').setOpacity(1).setHTML('Sorting in progress...');
}

In the onDrag function, I want to interrupt the fade effect if a user begins to sort the list again. To do this, we can use the clearTimer() method on the effect. By calling this method on the fade effect, it causes the effect to finish immediately. Once that is done, I simply set the Opacity of the element back to 1 (fully visible) before updating the contents of its innerHTML. Now the user will always be able to see the proper status of their operations.

Conclusion

That pretty much explains the logic behind all the pieces of this Sortable List example. I know it’s not very flashy, but the purpose of this example was to illustrate some of the cool things that can be done with a Sortable List and when they will be executed. I also figured it would be nice to explain a bit about using an effect as well. In reality, instead of updating a status element with different text when a user is sorting or finishes sorting, a back-end process would probably be triggered via an Ajax request to update a datasource or something similiar in order to store the state of the list.

I hope this lengthy explanation is helpful to some people and feel free to leave comments or suggestions for improvements to the code.

In my original example, I was passing an empty sortableOptions object into the initialization for the Sortable list because I didn’t need to override any options at the time. However, I was forced to use the implement functionality in mootools to change the initialize function of the Sortables class just to add three or four lines of code to the onStart and onComplete functions. This resulted in about 50 lines of duplicated code… yuck!

If you view the source of my example now, you will see a greatly simplified setup. In the sortableOptions object that used to be empty, I have defined new onStart and onComplete functions as seen below:

var sortableOptions = {
	onStart: function() {
		statusFade.clearTimer();
		$('status').setOpacity(1).setHTML('Sorting in progress...')
	},
	onComplete: function() {
		$('status').setHTML('Sorting complete!');
		statusFade.custom(1,0);
	}
};

Now, when I pass that sortableOptions object into the Sortables object, the onStart and onComplete functions are executed in addition to the existing code for those functions in the dragger object. Feel free to take a look at the updated example.

Also of note, the transitions in mootools have been changed. Instead of specifying my transition as Fx.cubic, I now have to say Fx.Transitions.cubicIn. It’s not too much trouble to add the reference to the new Transitions class, but it is somewhat annoying that some effects that existed previously do not exist under the same name anymore. For example, the old Fx.sinoidal is now Fx.Transitions.sineInOut.

I can’t really complain though, there are way more transitions now than there used to be and some of them are very cool!

A couple of people have commented on my original Sortable List example expressing the need for this serialize function and Jessica from jesirose.com posted a function on her blog that accomplishes serialization for her specific needs.

I checked around on the mootools forums and didn’t see any posts on the topic, so I went ahead and wrote a serialize function that could be added to the Sortables class:

serialize: function(element, options){
    var str = [];
    var key = encodeURIComponent(options.key || element.id);
    var elements = $A(element.getElements(options.tag || ''));
    elements.each(function(el, i) {
        str.push(key+'['+i+']='+el.id);
    });
    return str.join('&');
}

This function takes in an element which is the parent element for all of the Sortable List items that you want serialized. You can also pass in two optional params in the options object:

• key - the string to use as the key in the key/value pair
• tag - the type of tag that should be serialized under the parent element

If you do not specify a key or a tag, the id of the passed-in element will be used as the key and all tags under the the parent element will be serialized, regardless of their type. For a quick example, say you have a block of HTML like the following:

<div id="container">
    <div id="listitem1">ListItem 1</div>
    <div id="listitem2">ListItem 2</div>
    <div id="listitem3">ListItem 3</div>
</div>

If you want to serialize that list in the onComplete function of your Sortables object, you can use the following code:

this.serialize($('container'), {key: 'exampleKey', tag: 'div'});

This would generate a serialized output of the format:

exampleKey[0]=listitem1&exampleKey[1]=listitem2&exampleKey[2]=listitem3

The output above can be passed through an Ajax POST request and provide the necessary information needed on the backend to update a database storing the state of the list. I’ve posted the example on the mootools forums as well and I think it should be included in Sortables, but for now you’ll have to add this to your own implementation of the Sortables class to use the functionality.