Configure the drag and drop class. The drag and drop mechanism is implemented in a single static class named DragAndDrop. There are five settings that control the behavior of the drag and drop and upload mechanisms and dictate which features are enabled during initialization. The default settings should be sufficient for most use cases, so you may not need to explicitly set any configuration parameters.
Add event listeners. The DragAndDrop class emits nine different events, each of which is an instance of the DragAndDropEvent class. Add listeners for the events you would like your application to receive:
Set callback functions. There are two events in the lifecycle of the drag and drop control that are implemented as callbacks so the application can specify a return value synchronously.
The first of these is a callback function that will be invoked repeatedly as the user drags items over the Flash player. This function, set using the DragAndDrop.dragOverCallback parameter, gives the application the opportunity to do hit testing and set the mouse icon that the browser displays. It has the following signature:
function DragOverCallback(clientX:int, clientY:int):String
The clientX and clientY parameters are relative to the upper left corner of the stage. The callback should return one of the four drop effect constants defined in the DragAndDrop class: DROPEFFECT_NONE, DROPEFFECT_COPY, DROPEFFECT_LINK, or DROPEFFECT_MOVE. If a callback function is not specified then the control will default to DROPEFFECT_MOVE.
The second callback is a function that will be invoked once for every file the user drops on the Flash player or chooses using the native file selection dialog. This function, set using the DragAndDrop.dropFileCallback parameter, receives a DragAndDropFile object that contains information regarding the dropped file including the file contents if they have been loaded, the number of files that have been loaded, and the total number of files in the load operation. The latter two parameters are useful for displaying total progress to the user. The callback has the following signature:
function DropFileCallback(file:DragAndDropFile, filesLoaded:int, filesTotal:int):Boolean
The callback function should return true if it wants the JavaScript code to cache a reference to the file, a requirement for uploading the file later using the native browser mechanism. The default behavior if a callback function is not specified is to not cache file references.
Initialize. Once everything above is squared away, initialize the drag and drop control by calling DragAndDrop.initialize(). This function will return an empty string if successful or a description of the error otherwise. At this point, you’re ready to go! Simply drag and drop files and watch the events and callbacks fly. Refer the section below for a more detailed description of what happens internally during initialization.
Browse for files. Your application can open the native file selection dialog by calling DragAndDrop.browseForFiles(). Files that are selected will be loaded by the JavaScript code and transferred to your application in the same manner as those added by drag and drop. The reason to select files this way instead of using the normal Flash framework is to have a common mechanism for loading and uploading files regardless of whether they were selected by drag and drop or the browser dialog. The sample application shown below is opening the native file browser dialog in response to the user clicking a button in the Flash player:
See the section below for a more detailed description of how browsing for files works.
Upload files. File references that have been cached by the JavaScript code can be uploaded asynchronously using the native browser upload framework by calling DragAndDrop.uploadFiles(fileList:Array). The fileList parameter is an array of BrowserUploadFile objects, each of which contains the file name, target upload URL, and upload mechanism (e.g. POST). The JavaScript code will locate each cached file reference based on the name field, so it is important that this matches the original file name specified by the browser. See the section below for a more detailed description of how uploading files works.
The first step in initialization is to inject the necessary JavaScript functions into the DOM. I first got acquainted with this technique when extending the functionality of FlexIFrame, so it was already familiar when I read Verweirder's code. However, his idea to use this technique here is a great one because of the simplification it provides to deployment. The functions injected by this project are:
The only downside to injecting JavaScript functions this way is it makes debugging more difficult, as most debugging tools (e.g. Firebug) don't seem to acknowledge the existence of functions added through such a mechanism.
Second, a number of Actionscript functions are exposed to the JavaScript code by registering them with ExternalInterface. These functions allow the JavaScript code to communicate drag, drop, and upload events to the Flash player:
The third step in initialization is to disable drag and drop operations on the main window of the web page, i.e. the background of the page outside of the Flash player. As described above, this is important if the Flash application doesn't occupy the entire browser window to prevent accidental navigation away from the HTML page that contains the SWF. The screenshot below demonstrates that the page surrounding the Flash player no longer functions as a drop target, but the application does:
Fourth, the control checks to make sure the browser supports the FileReader interface if file content loading is enabled so the file contents can be loaded and pass to the Flash player. The configuration parameters described above enable an application to load small files for preview without grinding the whole system to a halt if a large file is added.
Fifth, once everything has been injected and all checks have passed, the control invokes a JavaScript function that adds the drag and drop event listeners to the Flash player. The fact that ExternalInterface knows the ID of the Flash player object makes it easy for the JavaScript to locate the object.
Sixth, an HTML input control is injected so the browser's file selection dialog can be opened programmatically. This allows the application to load and upload files the same way regardless of whether there were added by drag and drop or through the file selection dialog.
Finally, an HTML form is injected to enable the application to use the browser's native mechanism to upload files to a server. The step is essential for transferring large files without the overhead of loading them into memory all at once.
A series of drag and drop events are detected by the JavaScript functions and passed to the Actionscript code through ExternalInterface. The first events to consider are drag enter and leave, each of which is only emitted once, and whose handlers invoke the functions asOnDragEnter and asOnDragLeave in the control. Drag enter is triggered when the user drags something over the Flash player, and drag leave is emitted when he drags it away without dropping. Security restrictions in the HTML specification prevent the JavaScript code from getting any significant information about any files the user may be dragging at this point.
The next event to consider is the drag over event. This event is emitted continuously while the user is dragging something over the Flash player. The JavaScript code calculates the coordinates of the mouse pointer relative to the upper left corner of the stage and passes them to the Actionscript function asOnDragOver to allow hit testing. The mouse pointer can be changed by the application by returning one of the drop effects defined in the DragAndDrop class: DROPEFFECT_NONE, DROPEFFECT_COPY, DROPEFFECT_LINK, or DROPEFFECT_MOVE. The sample application below illustrates using hit testing and the drop effect to visually indicate that the grid is a valid target but the rest of the application is not:
Like the drag enter and leave events, security restrictions prevent the application from getting any significant details regarding files the user may be dragging.
The JavaScript drop event handler first invokes the Actionscript function asOnDropStart to notify the application that one or more files will be transferred. The handler then loads each file using the FileReader interface if two conditions are met: the configuration settings allow for the loading of file contents and the file size is below the threshold. Regardless of whether the file contents are loaded, the Actionscript function asOnDropFile is invoked once for each file, either immediately or after the load completes. The parameters passed to this function contain the file name, size, type, modified date, contents (if loaded), the number of files that have been loaded, and the total number of files that are being loaded. It returns a Boolean value that indicates to the JavaScript if the reference to the file should be cached for upload at a later time. The function asOnDropStop is invoked once all files have been transferred to the application.
The functions asOnDropStart and asOnDropStop are useful because the drop operation will take a significant amount of time if the files are large and the contents are being loaded and transferred to the Flash player. An application should listen for the events emitted by these function and provide a visual indication that a transfer is in progress so the user is not frustrated by a UI which appears to hang. The file counts provided to the asOnDropFile function allows the application to inform the user of the progress of the drop operation:
A hidden HTML input is injecting into the DOM during initialization of the drag and drop control by the JavaScript function jsInjectBrowseInput if this feature is enabled. The format of the input tag is:
<input type='file' multiple='true' />
This simple tag enables the Actionscript code to programmatically open the browser’s native file selection dialog by calling the JavaScript function jsBrowseForFiles. The same code that loads the files added by the drag and drop mechanism also handles files selected use the browser dialog, providing a common way to conveniently address two use cases without any extra effort on the part of the application developer.
A hidden HTML form is injecting into the DOM during initialization of the drag and drop control by the JavaScript function jsInjectUploadForm in a mechanism similar to that used to browse for files. The format of the form tag is:
<form enctype='multipart/form-data' />
The Actionscript code calls the JavaScript function jsUploadFiles with an array of files it would like uploaded to specific URLs. This JavaScript function locates the cached reference for each file and employs a combination of the hidden form and XMLHttpRequest to asynchronously upload each file to the corresponding target URL. The contents of the file are loaded by the browser framework and passed to the server in the filedata field that is added to the form dynamically. This mechanism allows large files to be read from the disk in a series of small chunks during upload and avoids the need to load the entire file into memory at once. JavaScript event listeners detect upload progress, completion, and error events and pass them to the Actionscript code where they can be presented to the user:
