Javascript - Draggable Elements

Draggable elements in javascript have been done hundreds of times before - from tutorials to packages to hacked up half working code files. But, hey, I have decided to throw my two cents in anyway - because we all know you wanted yet another option for dragging in javascript, right? Joking aside, what will will cover today are the detailed inner workings of a homegrown solution to draggable elements. Depending on your level of javascript knowledge, you might want to read two previous tutorials on this site: Javascript Objects - A Useful Example (which covers some basics about how objects work in javascript), and Javascript - Working With Events (which covers how to work with events and event objects). The techniques (and some of the code) from both of those articles will be used in this tutorial.

The capabilities of the solution in this tutorial are pretty small compared to some of the big packages out there now for javascript dragging. But it covers the basics. You can set bounds for dragging, and hand custom functions to be called at the start and end of dragging, as well as after every move. The element that gets moved and the element that has the initial hook can be different (i.e, the draggable element can have a drag handle. And of course, dragging can be detached from an object at any time (and any active dragging canceled).

Below is an extremely simple example of what can be done with what we will cover today. The red box, when dragged, is forced to stay inside the outer box, and when dragging is finished an alert box pops up saying that the drag has ended. The blue box can only be dragged by the red handle at the top of it, but it can be dragged out of the outer box. The button in the upper left turns on and off the ability to drag either box.

So how is all this done? Well, lets start off from the very top - the initialization of a drag object. Here is the function declaration:

When declaring a drag object, you hand it first the element that is going to be dragged (either the element id (a string) or the element itself). Then it wants the attachElement - which is the element that will be the drag handle. This can also be a string or an element, and if null is passed in, the drag element will be used. Then it takes a lower bound and an upper bound, which are the constraints on where the object can be dragged to. If these are null, there are no bounds. The last three arguments are the callbacks - startCallback gets called at the start of dragging, moveCallback is called after each mouse movement during a drag, and endCallback is called when the drag has completed. Any or all of these can be null. The argument attachLater lets the drag object know if it should start listening for drag events immediately or not. If false or null, it starts listening immediately, but if true, you will have to tell the drag object at a later point to start listening.

You may be wondering what exactly gets passed in for lower and upper bounds - since there need to be 4 values (x and y for both maximum and minimum) and there are only two arguments. Well, to make the dragging code simpler to work with, we us a pretty standard position object:

This object, while it has a decent amout of code, is pretty simple. It stores two values, an X and a Y coordinate. You can add and substract other position objects using the Add and Subtract functions, which return a new position object with the computed values. There are also the functions Max, Min and Bound. Max will compute the point that is the maximum of the current point object and the point given, and Min will compute the minimum. Bound will constrain the current point within the area given by two arguments - the lower bound and the upper bound. This function uses the Max and Min functions, and returns the constrained point. The function Check just returns a point with the current point's values - but first makes sure that the current point is holding actual numerical values (and if not, sets those values to 0). The Apply function is a useful little one - calling Apply with a element id or an element object wil set the position of the given element to the values held in the current position.

So, back to the original reason this was brought up - the lower and upper bounds passed in when creating a new instance of dragObject are Position objects. As you will see later on in the code, the Position object (and its functions) are used a number of times.

Looking a little bit deeper, we see what happens when a drag object is initialized:

Nothing that exciting here - we resolve the element and attachElement to actual nodes (if they are id strings). As an error check, we make sure that the upper and lower bounds are actually the upper and lower bounds (and not flipped). We also set up some variables that will be used throughout the drag object. The cursorStartPos gets set when a drag starts with a position object holding the position of the cursor at that time. The elementStartPos also gets set at the start of a drag, and holds a position object filled with the position of the element at the that time. The variables dragging, listening, and disposed are state variables for the drag object - listening means that the drag object is listening for drag start events, dragging means the element is currently being dragged, and disposed means that this drag object has been cleaned up and can no longer be used for dragging. At the end of the code here, we see that if attachLater is not true, we call the function StartListening. That is a public function defined in the drag object, so lets take a look at what it does:

The first two lines are just checks - if we are already listening for drag events or we are disposed, do nothing and return. Otherwise, set the listening variable to true (because we are about to start listening), and hook the dragStart function into the mousedown event of the attachElement. You may recognize the function hookEvent from the Javascript - Working With Events tutorial, but just as a refresher, here is what hookEvent (and its counterpart, unhookEvent) look like:

If you don't understand what is going on in those functions, you should go take a look at that tutorial.

So we hooked the dragStart function - well, what is the dragStart function? It is a private function on drag object:

So this function gets called when the attachElement gets a mousedown event. The first thin we do is make sure that the object is in the right state to do any dragging - if we are already dragging, or are not listening, or are disposed, we do nothing and return. If everything is ok in that department, we set the dragging flag to true and get down to business. If the startCallback is not null, we call it with the mousedown event object and the drag element as arguments. Once that finishes, we determine the absolute position of the cursor and store it (I'll explain that function in a moment). Then we determine the current position of the drag element by parsing the appropriate style tags. If those style tags are parsed incorrectly for whatever reason, we assume the value is 0. Then there are two more hookEvent calls - one for movement, where we hook the dragGo function to the mousemove event of the document, and the other for ending the drag, where we hook the dragStopHook function to the mouseup event of the document. The reason we hook these events to the document, and not to, say, the drag element itself, is that it is very easy for the browser to get a little bit behind and for the cursor to slip out of the area contained by the drag element. When that happens, the mousemove and mouseup events do not get fired for the drag element - and if we were listening to those events, the drag would stop working. So instead, we hook to the events for the document - which means that dragging will work as long as the cursor does not leave the browser window. Finally, we cancel the event and return (we don't want anyone else who might listen to the mousedown event interfering with the drag - for instance, text selection). The cancelEvent function is again from the Javascript - Working With Events tutorial, but heres the code for it anyway:

There were a couple functions in that dragStart function that we haven't defined yet - so lets go through them one at a time. First, we have absoluteCursorPostion. This function takes an event object and returns a position object containing the position of the cursor:

The reason we need this function is because of scrolling - Internet Explorer has a non-standard way of getting how much the window is scrolled. The top block of the if statement is for Internet Explorer, and the bottom block is for most other browsers.

Next we get to the real meat of dragging - a private function part of the drag object called dragGo. Here we have the code for that function:

Surprisingly, this function is not that complicated. Like the others, first we check to make sure that we are in the correct state - if we aren't supposed to be dragging, or we are disposed, we return without doing anything. Then we calculate the current position of the cursor, again using the absoluteCursorPostion function. Using the new cursor position, we calculate the new element position using the original element position and the original cursor position. There are a number of dragging scripts out there that don't do absolute calculations on every move - they do moves relative from the last cursor and last element position. But I've found that its generally better to always calculate the new position for the very original position - it reduces the risk of errors building up over time as the user continues to drag the object without ever dropping it. Mostly, its just a personal preference.

After the new position is calculated, we call Bound on it to make sure it is within the bounds given to the drag object. Once that is all done, we use the Apply function on the new postion to set the position of the element. Then, if the moveCallback isn't null, we call it, and give it the new position and the drag element as arguments. Finally, as always, we cancel the event.

One more function was referenced back in the dragStart code - dragStopHook. This function is a private function of the drag object, and is hooked into the mouseup event to end the dragging:

This is really just a wrapper function around dragStop, but it also, as always, cancels the event. So lets take a look at dragStop:

Here, if we aren't in the correct state (i.e., if we aren't dragging or we are disposed) we return without doing anything. Otherwise, we continue and unhook the dragGo and dragStopHook from the mousemove and mouseup events. We clear out the cursorStartPos and elementStartPos, because they are no longer valid. If the endCallback is not null, we call it with the drag element as the argument. Finally, we set the dragging flag to false.

There are a couple other simple functions that the drag object has, in order to add a bit more functionality. First off, we have these three very simple public property functions:

These functions allow outside javascript code to determine the current state of a drag object.

We also have the public StopListening function - which is the counterpart to the StartListening function:

This function tells the drag object to stop listening for drag events. If the object is disposed, or already not listening, it does nothing and returns. Otherwise, it unhooks the dragStart function from the mouseDown event on attachElement. Then we set the listening flag to false. There is always a possibility that the element is actually currently being dragged when this function is called - so it takes an argument to determine if the current drag operation should be stopped. If the argument (stopCurrentDragging) is true, and the object is current in the dragging state, we call the dragStop function.

Finally, we have the dispose function (which is also public):

This is just a cleanup function - for when you don't need the drag object anymore. It makes sure all events are unhooked, and clears out all its element references and variables. Not a necessary function, but if creating and discarding a lot of drag objects, its a good thing to have (and to remember to call).

And if you take all of that code and put it together, this is what the drag object (and its helper functions) looks like:

Now that we have this wonderful drag object, how do we use it? Below is the javascript and html code for creating the example above:

The bottom two lines (where the drag objects are created) are the most important. For the first one, we want to drag the element "exampleA". The attach element will be the same as the drag element, so we pass null for that argument. Then we pass the lower and upper bounds. We have no start and move callbacks, so we pass null for both of those, but we pass exampleAEnd for the end callback (which is simple little function defined right above). And finally, we want the drag object to start listening immediately, so we pass false for the last argument (attachLater).

The code for creating the drag object for the element "exampleB" is even simpler. Here, we take advantage of the fact that since we don't intend to pass anything for the last 6 arguments, we can leave them off the call altogether (the arguments will get the value of undefined in the drag object, which is equal to null). So here the only things we pass are the string "exampleB" (the element to drag) and the string "exampleBHandle" (the id of the handle div on top of the exampleB div).

So now those two elements are listening for drag events. The example gets a bit more meat to it with the buttonClicked method - which turns on and off listening for drag events on the two objects. If we are listening (by checking the IsListening function), we call StopListening on both drag objects (and we change the text of the button). Otherwise, we call StartListening (and again change the text on the button). And thats all the code you need!

Hopefully, you found this detailed look in to dragging in javascript interesting and informative. If you would like a copy of the javascript code, here is a link. Feel free to play with it, use it, pretty much do whatever you want. And, as always, comments and questions are welcome - just leave them in the comments.