Drag and Drop

From HTML5 Builder
Jump to: navigation, search

Webpages can implement a drag and drop interaction, both between controls of the page itself and interacting with other elements from the browser window and even outside.

Implementation

Make controls draggable

The first step, unless you only want to support content dragged from outside your webpage, is to make a control or controls draggable.

You can make an entire control draggable by setting its Draggable property to true.

If a control does not provide a Draggable property, or the implementation of the property does not fit your use case, you can always make the element draggable using JavaScript: $('Target Element Selector').attr('draggable', true);.

It is usually a good idea to also set the controls’ Cursor property to crMove, so users can guess the control is draggable when placing the mouse cursor over it.

Define the events

In HTML, drag and drop is implemented through handlers associated to a series of JavaScript events:

OnDragStart

This event is triggered on the source element, accessible from the event handler through the variables this and event.target.

It is triggered when a drag operation starts, and is used mainly to configure the data to be dragged. You do so using the dataTransfer.setData() method. It expects two values: the type of data, and the data itself.

For example, to transfer plain text:

event.dataTransfer.setData("text", "This text is to be transferred to the drop location.");

You can call setData() as many times as you wish, but you can only set a single value for each type of data.

The only types supported by every major browser are text and url, which are the types defined by Internet Explorer 10. The rest of the browsers usually support any MIME type.

Firefox requires that some data is defined on the dataTransfer object (see onDragStart). If you do not want to use the object to exchange data between the drag and drop points, you can define dumb data: event.dataTransfer.setData("text", "asdf");.

When dragging, there are three different types of operations to be performed:

  • Copy. The data is copied from the source location to the drop location.
  • Move. The data is moved from the source location to the drop location.
  • Link. The data between the source location to the drop location is somehow associated.

By default, when a drag operation starts, it allows all the operation types above. You can define the types of operations supported configuring the value of the dataTransfer.effectAllowed property in the OnDragStart event handler: event.dataTransfer.effectAllowed = '<types>';. Replace <types> with none, copy, copyLink, copyMove, link, linkMove, move, all or uninitialized.

OnDragEnter, OnDragLeave

These events are triggered on an element when the cursor enters or leaves the element during a drag operation. They can be used to change the style of the element, for example.

OnDragOver

Triggered along with OnDragEnter, on the same element, this event must be associated to a handler with an implementation similar to this one:

function handleDragOver($sender, $params)
{
    ?>
    //begin js
 
    if (event.preventDefault) {
        event.preventDefault();
    }
 
    event.dataTransfer.dropEffect = '<type>';
 
    return false;
 
    //end
    <?php
}

You should define the operation that every drop location performs. That is what the central statement is for. Replace <type> with a type of operation (copy, move, link), or none.

As for the if and return statements, they are used to prevent the web browser from performing its default handling of the drop event. For example, if you drop an URL on any element and don’t include this code in the element’s OnDragOver event handler, the browser might just open the target URL, instead of OnDrop.

OnDrop

This event is triggered on the element at the drop location, accessible from the event handler through the variables this and event.target.

The event handler for this event should look like this:

function handleDragOver($sender, $params)
{
    ?>
    //begin js
 
    if (event.stopPropagation) {
        event.stopPropagation(); // stops the browser from redirecting.
    }
 
    // Do whatever you want with the dropped data.
 
    return false;
 
    //end
    <?php
}

The if and return statements are used again to prevent the web browser from performing its default handling of the drop event.

Between them, you can retrieve data from the dataTransfer object and do whatever you want with it.

For example, you could retrieve the dropped text and set it as the content of the element where it was dropped: $(this).html(event.dataTransfer.getData("text"));

OnDragEnd

This event is triggered on the source element once the drag operation stops, whether or not the data was successfully dropped somewhere. The source element is accessible from the event handler through the variables this and event.target.

You can use this event to restore any style changes you might have performed when the drag operation started.

Help Resources

Sample Applications

On the Features/MouseEvents/DragAndDrop folder inside the sample applications directory you will find applications showcasing the drag and drop feature.

Documentation

See Also

Personal tools