The FileReference class and its event handlers

To appreciate the file upload experience of Adobe AIR applications, look at the event listeners that can be registered to a FileReference instance.

FileReference instances trigger events at nearly every meaningful phase of the file upload process, from the time the file is selected by the end user to the time the file upload is complete. Errors that may be encountered at the local or server level trigger their own events. Also, a ProgressEvent is triggered during the upload process itself so that building dialog boxes to display to the user how much of a file has been uploaded, and how much remains to be uploaded, are easily accomplished.

Below is a simple application that demonstrates some of the useful event listeners that can be attached to the FileReference class:

<?xml version="1.0" encoding="utf-8"?>
<mx:WindowedApplication xmlns:mx="/2006/mxml" layout="absolute" applicationComplete="startApplication();">
   <mx:Script>
       <![CDATA[
           import flash.filesystem.File;
           import mx.events.FileEvent;
           private var fileReference:FileReference = new FileReference();
           private function startApplication():void {
               fileReference.browse();               
               fileReference.addEventListener(Event.SELECT,fileSelectHandler);
               fileReference.addEventListener(IOErrorEvent.IO_ERROR,fileErrorHandler);
               fileReference.addEventListener(DataEvent.UPLOAD_COMPLETE_DATA,fileCompleteHandler);
           }
           private function fileSelectHandler(event:Event):void {
               trace("You selected a file name "+event.target.name+" that is "event.target.size+" bytes in size");
           }
           private function fileErrorHandler(event:IOErrorEvent):void {
               trace("A file IO error has occurred: "+event);
           }
           private function fileCompleteHandler(event:Object):void {
               trace("The file upload has completed. Response from server: "event.data);
           }
       ]]>
   </mx:Script>
</mx:WindowedApplication>

Note that the DataEvent.UPLOAD_COMPLETE_DATA event passes an event of type Object to its registered handler.

Any response from the server that is articulated upon completion of the file upload process can be captured by the data property of the associated event object. The typical model employed will be to trigger the FileReference class's upload method upon the firing of an Event.SELECT event.

For example:

<?xml version="1.0" encoding="utf-8"?>
<mx:WindowedApplication xmlns:mx="http://www.adobe.com/2006/mxml" layout="absolute applicationComplete="startApplication();">
   <mx:Script>
       <![CDATA[
           import flash.filesystem.File;
           import mx.events.FileEvent;
           private var fileReference:FileReference = new FileReference();
           private function startApplication():void {
               fileReference.browse();
               fileReference.addEventListener(Event.SELECT,doUpload);
               fileReference.addEventListener(IOErrorEvent.IO_ERROR,errorHandler);
           }
           private function errorHandler(event:IOErrorEvent):void {
               trace(event.text);
           }
           private function doUpload(event:Event):void {
               var uploadURL:URLRequest = new URLRequest("http://www.airapps.net/fileUpload.pl";
               var thisFileRef:FileReference = FileReference(event.target);
               thisFileRef.upload(uploadURL);
           }
       ]]>
   </mx:Script>
</mx:WindowedApplication>

Note that in the above application a handler, errorHandler, is assigned to handle IOErrorEvent.IO_ERROR events. If there are any problems with the remote application to which you are trying to upload a file, typically, the text property of the IOErrorEvent object passed to the error handler will read "Error #2038: File I/O Error. URL: http://www.airapps.net/fileUpload.pl".

It is a good idea to implement error handling in all your file upload applications and provide users unambiguous feedback as to whether or not their file upload operations occurred successfully or if errors were encountered.

Page 3 of 6

Previous Page

Next Page