Information
The topic you requested is included in another documentation set. For convenience, it's displayed below. Choose Switch to see the topic in its original location.

About DHTML Data Transfer

Note  As of December 2011, this topic has been archived and is no longer actively maintained. For more information, see Archived Content. For information, recommendations, and guidance regarding the current version of Windows Internet Explorer, see Internet Explorer Developer Center.

As of Microsoft Internet Explorer 5, you have access to an extensive data transfer implementation. For Internet Explorer, data transfer involves writing information to and reading it from the clipboard through a data transfer object. The information transferred includes both the data format and the data itself.

Data transfer involves two processes. The first process is cut/copy/paste editing through the browser Edit and shortcut menus. This capability is important for facilitating repeated editing tasks where persisting information in the system clipboard provides ease of use. One example of this capability is pasting the same data multiple times. The second process is drag-and-drop operations. Drag-and-drop is immediate and intuitive, because the user simply selects an HTML element and drags it to a new location. This capability is best enabled for one-time operations because, once the drag operation ends, all trace of the data being transferred disappears. Taken together, these editing capabilties enable you to implement typical user-interface functions that users have come to expect of good software.

The data transfer implementation in Internet Explorer 5 provides programmatic control over what data formats get transferred from data source to data target. This control extends to data transfers within the browser window, from one instance of the browser to another, from browser to desktop, and from browser to another Component Object Model (COM) drag-and-drop application, such as Microsoft Word. Currently, for data security reasons, Internet Explorer prevents any drop target in the browser from accessing data that originates in another security domain or in another desktop application.

The data source stipulates the type of data transfer: move, copy, or link. It also stipulates the type of information—an image source path, a text string, or a URL for an anchor—to be transferred. For example, shopping-cart applications make use of this capability. Such applications display a catalogue and an order form. They allow users to drag the image of the item they want to purchase and drop it onto the order form. At that point, text associated with that image, rather than the image itself, is copied to the form. In one simple operation, the price, product, brand, and serial number are displayed. Of course, images aren't the only data sources—anchors, text, and text controls also function as data sources.

Target objects might look exactly like source objects. However, their role is very different from that of the data source. Target objects provide feedback about the data transfer operation. The feedback comes in two forms: information for the user and programmatic notifications. You can set the cursor to display the copy, move, or link system icons. These icons provide information to the user during a drag-and-drop operation. Notification events, such as onbeforepaste and ondrop, deliver information you can use to script a custom behavior. In the case of the shopping-cart application, this custom behavior first retrieves the product information associated with the image and then pastes it to the order form.

Microsoft Internet Explorer 4.0 has limited data transfer functionality. It supports default drag-and-drop behavior for images, anchors, and text controls. Your control over data transfer functionality in Internet Explorer 4.0 is limited to whether the drag-and-drop functionality is enabled at all. Internet Explorer 5 greatly improved and enhanced this functionality, as this article explains in the following sections.

New Data Transfer Features

You can use the data transfer functionality outlined in this section to code custom drag-and-drop and editing behaviors.

Data Transfer Objects

Internet Explorer 5 supports two objects for transferring data, the dataTransfer and clipboardData objects. Available through the event and window objects, respectively, each comprises a gateway through which information is set on source objects and retrieved by target objects.

The dataTransfer object offers programmatic control over drag-and-drop operations. It passes data to its own clipboard, where it persists only until the ondragend event fires. Once that event fires, the data is purged from the clipboard, regardless of whether a successful transfer of data occurred.

The dataTransfer object supports two specific drag-and-drop properties as well as some data transfer methods. The properties effectAllowed and dropEffect provide visual feedback during a drag operation and are critical to achieving consistency with the Windows user interface. Through the setData, getData, and clearData methods, you can use the dataTransfer object to access predefined data formats. These formats support user-interface manipulation of everything from text, to images, to anchors.

The clipboardData object is reserved for editing actions performed through the Edit menu, shortcut menu, and shortcut keys. In contrast to the dataTransfer object, it transfers information using the system clipboard, and retains it until data from the next editing operation supplants it. As previously mentioned, this form of data transfer is particularly suited to multiple pastes of the same data. Like the dataTransfer object, the clipboardData object supports the setData, getData, and clearData methods.

You can use custom editing code to execute any of the following editing-related event handlers: onbeforecut, onbeforecopy, onbeforepaste, oncut, oncopy, and onpaste. Cut or copy operations of the clipboardData object use the setData method to pass data from the source object; paste operations use the getData method to retrieve the data for the target object.

The effectAllowed and dropEffect Properties

In contrast to Windows, the Internet Explorer 5 implementation of data transfer does not support CTRL and SHIFT keyboard modifiers for drag-and-drop operations. In other words, the user cannot choose whether to copy, move, or link the object using any of these modifiers. Instead, you must use the effectAllowed property to stipulate drag functionality, and the dropEffect property to notify the end user.

The effectAllowed property specifies which data transfer operations are allowed for the object. This property is generally set in the ondragstart event for the source object, because that is the last event fired before a drag-and-drop operation begins. The effectAllowed property supports a flexible set of values, including copy, move, link, copyMove, copyLink, linkMove, all, and none. For compound values like copyMove, which name two different data transfer operations, the target object default determines which of the two values is implemented.

The effectAllowed property also can override the default behavior of other applications. For example, the browser script can set this property to copy and thereby override the Word default of move. Within the browser, copy is the default effectAllowed behavior, except for anchors, which are set to link by default.

Both effectAllowed and dropEffect are available only through the dataTransfer object and must be used together for dropEffect to work.

The dropEffect property stipulates which standard system cursor to display during a drag-and-drop operation. The value of this property is set for the target object in the ondragenter or ondragover event. The exception arises when an image, an anchor in a frame, a textArea object, or a text input object comprises the source element. These objects have supported drag-and-drop by default since Internet Explorer 4.0. Consequently, the target object cannot override the drop-effect setting.

Note  To display the desired cursor until the final drop, you must cancel the default action of the ondragenter, ondragover, and ondrop events, and you must set the dropEffect property. Otherwise, the copy, move, or link cursor set by this property displays only until the mouse is moved over the first valid drop target, at which point it is replaced by the drop/no-drop cursor for the duration of the drag operation.

The setData, getData, and clearData Methods

All parameters for the setData, getData, and clearData methods are case-insensitive, and the first parameter is always a string value. Both the dataTransfer and clipboardData objects support these methods.

The setData method specifies which data format and information to transfer through dataTransfer or clipboardData. The setData method is typically invoked in the ondragstart event for the drag source or the onbeforecut or onbeforecopy event for editing. The first parameter accepts a string value of Text or URL, with Text as the default. The second parameter, a variant, associates information with the source object. This information can be descriptive text, a source path to an image, or a URL for an anchor. The second parameter is required when information about the location of the object being transferred is needed. Such situations include providing URLs for anchors or desktop shortcuts as well as source paths for images.

The getData method specifies which data format to retrieve from the clipboard using the dataTransfer object. This method is invoked by the target object and takes a single, required parameter. The parameter is a string representing the data format that the drop target should read. This parameter must match the data format passed into the setData method, namely, Text or URL. The value of the parameter determines how the getData method interprets the information passed through the second parameter of the setData method. When the data formats passed in setData and getData are mismatched, the drag operation fails.

The clearData method of the dataTransfer object removes one or more data formats from the dataTransfer object. This method recognizes more formats than the other two, including Text, URL, File, HTML, and Image. All formats are cleared when no parameter is passed. In general, this method is most useful in source events, such as the ondragstart event. However, clearData can override the default behavior of the target object when invoked in the ondrop event.

New Data Transfer Events

To complement the new features outlined above, Internet Explorer 5 has a rich set of notification events on both data source and target objects. All data transfer events support bubbling and cancellation of the default action. Consequently, you can make the data transfer code modular by handling the events at the container level. When coding a custom behavior, you must cancel default actions of all data transfer events that are handled, so that browser default behaviors cannot override your custom code.

The following drag-and-drop events fire on the source object. Notice that the source object receives notification when the drag operation ends—in the form of the ondragend event—yet not of whether the selection has been dropped to a valid target. That information is provided by the ondrop event of the target object.

The following events fire on the target object.

The following events fire on the source object for editing events. Use the setData method of the clipboardData object to transfer information.

The following events fire on the target object for editing events. Use the getData method of the clipboardData object to transfer information.

You can use any of the preceding events to override the browser default behavior in favor of custom event handling in a Web application. All you need to do is cancel the default action in the event by including event.returnValue = false in the appropriate event handler.

A brief description of the drag-and-drop events follows, organized by the order in which they fire.

  1. The ondragstart event initiates the drag operation. Returning false in this event disables all drag functionality. It is also the key event for using setData and effectAllowed effectively.
  2. The ondrag event fires continuously, regardless of whether the mouse pointer is over a source, target, or invalid object.
  3. The ondragenter event fires before ondragover on a target. The ondragenter event is a good place to use getData. To maintain the drag/drop cursor, set dropEffect and cancel the browser default behavior in this event.
  4. The ondragover event fires continuously while the drag selection is over a valid drop target. To maintain the drag/drop cursor, set dropEffect and cancel the browser default behavior in this event.
  5. The ondragleave event fires if the mouse pointer leaves the drop target.
  6. The ondrop event fires if the user drops the selection on a valid drop target. It is the most effective event for invoking getData. To maintain the drag/drop cursor, set dropEffect and cancel the browser default behavior in this event.
  7. The ondragend event fires when the drag operation ends, whether through a successful drop or not.

Compatibility

In Internet Explorer 4.0, programmatic control over data transfer operations is limited. No data transfer object, methods, or properties exist. Moreover, what drag-and-drop capability does exist is hardwired into the browser. Anchors and images create a link when the user drags them to the desktop. If the user drags an anchor to another browser window, the second browser navigates to the anchor's URL. An image dragged to another browser window is displayed alone on a page. You can use text controls to move content between text controls on the same page as well as from page to page. You can cancel any of these default actions or send notification that a drag operation has been initiated in the ondragstart event. No programmatic control over editing through the Edit menu, shortcut menu, or keyboard accelerators is available in Internet Explorer 4.0. This functionality was added to Internet Explorer 5 and later in the form of new cut, copy, and paste events.

Internet Explorer 5 honors the Internet Explorer 4.0 implementation of default drag-and-drop functionality. To substitute custom code for the version 4.0 defaults of these objects, simply cancel the return value in ondragstart. At this point, images, anchors, and text controls require the same amount of coding as, say, a div or span object. In short, if you move text in a textArea object, you must remove the text in the source textArea, and then you must update the source textArea and the target textArea. The innerText property is suited to this purpose.

If you're interested in writing script for browsers released prior to Internet Explorer 5, you can perform one simple check to prevent scripting errors from occurring in Web pages that contain data transfer functionality. All that is required is a conditional statement, which bases code execution on the existence of the dataTransfer and clipboardData objects, as shown in the following example.


if ( event.dataTransfer && window.clipboardData)
    .
    .
    .

Security

You can use Internet Explorer security settings to control scripted copy and paste operations that use the dataTransfer and clipboardData objects. By default, there is no restriction on the ability of script to modify the system clipboard, and all supported data formats can be transferred freely between Internet Explorer and other applications running on the system. The user has the option of disabling this feature by modifying the "Allow paste operations via script" radio button group in the Security Settings dialog box, available through the Internet Options Control Panel applet. The user can customize the settings for each security zone.

Sample

The following example shows the basic code for programming a drag-and-drop operation. This code represents the foundation of a shopping-cart application in which the user drags the icon to the order form and receives textual feedback about the item.


<HEAD>
<SCRIPT>

/* ----------------------------------------------
    fnSetInfo sets the data format in the first 
    parameter and provides the text to drop in second.
    The second line copies text.
 ----------------------------------------------*/
                                   
function fnSetInfo() {                                                             
  event.dataTransfer.setData("Text", "Microsoft Golf 1998"); 
  event.dataTransfer.effectAllowed = "copy";                 
}

/* ----------------------------------------------
   fnGetInfo is called by the target
   object in the ondrop event.
   It cancels the default action and
   sets the cursor to the system copy icon.  
   Then it specifies the data format to retrieve.
   Last, it sets the value property of oTarget 
   object to the information from getData. 
 ----------------------------------------------*/ 

function fnGetInfo() {
  event.returnValue = false;                           
  event.dataTransfer.dropEffect = "copy";              
  oTarget.value = event.dataTransfer.getData("Text");  
}

/* ----------------------------------------------
    fnCancelDefault
    Cancels the default action in ondragenter
    and ondragover so that the copy cursor is
    displayed until the selection is dropped.
 ----------------------------------------------*/

function fnCancelDefault() {                                            
  event.returnValue = false;                  
  event.dataTransfer.dropEffect = "copy";  
}

</SCRIPT>
</HEAD>
<BODY>
<IMG ID=oSource SRC="Golf98.gif" ondragstart="fnSetInfo()">
<P>Drag the image and drop it onto the text box below. Text data will be pasted into the text box.</P>
<INPUT ID=oTarget VALUE="[drop text here]"
       ondragenter="fnCancelDefault()" 
       ondrop="fnGetInfo()"
       ondragover="fnCancelDefault()">
</BODY>

Click to view sample.

 

 

Show:
© 2014 Microsoft