Using HTML5/Flash Uploader at Runtime

Getting Reference to HTML5/Flash Uploader by ID

When creating an ImageUploaderFlashImageUploaderFlash (ASP.NET)ImageUploaderFlash (PHP)imageUploaderFlash (JavaScript) object, we obligatorily set its identifier via the ImageUploaderFlash.IDID (PHP)id (JavaScript) property.

$au.imageUploaderFlash({
        id: 'Uploader1',
        // ...
    });

<aur:ImageUploaderFlash ID="Uploader1" runat="server">
    <!-- ... -->
</aur:ImageUploaderFlash>

$uploader = new ImageUploaderFlash("Uploader1");
// ...

This identifier is used to refer to HTML5/Flash Uploader at runtime and, thus, modify its parameters, call methods, and handle events through JavaScript. The code snippet below demonstrates how to get reference to the ImageUploaderFlash instance.

var uploader = $au.imageUploaderFlash('Uploader1');

The following sections describe how to use HTML5/Flash Uploader properties, methods, and events at runtime.

Using Properties

To modify some HTML5/Flash Uploader properties after initialization, you should get a reference to the imageUploaderFlash object as described above, and modify these properties. If you need to modify several properties at once you can either change them one by one or call the imageUploaderFlash.set(Object) method.

The code sample below demonstrates how to implement a separate drop-down list containing available view modes. Here we change the uploadPane.viewMode property respectively to the selected option.

<select id="selectView" onchange="changeView()">
    <option value="Tiles" selected="selected">Tiles</option>
    <option value="Thumbnails">Thumbnails</option>
    <option value="Icons">Icons</option>
</select>
<br />
<script type="text/javascript">
    function changeView(){
        var selectView = document.getElementById('selectView');
        var value = selectView.options[selectView.selectedIndex].value;
        $au.imageUploaderFlash('Uploader1').listView().view(value);
    }
        
    var fu = $au.imageUploaderFlash('Uploader1');
    fu.writeHtml();
</script>

Using Methods

If you need to call HTML5/Flash Uploader methods, you should do it in the same way as for properties: get a reference to the imageUploaderFlash and call the method you need.

To demonstrate how to call methods we implement a custom Upload button which works in the same manner as the embedded one. When a user clicks it, we call the imageUploaderFlash.upload() method which initiates the upload.

<script type="text/javascript">
    function send(){
        $au.imageUploaderFlash('Uploader1').send();
    }

    var fu = $au.imageUploaderFlash('Uploader1');
    fu.writeHtml();
</script>
<br />
<input type="button" value="send" onclick="send()" />

Using Events

HTML5/Flash Uploader exposes a number of events which are handled in JavaScript. These events are intended to trace interactions between the user and the control from the initialization to the upload completion.

Adding Event Handlers

To add an event handler you need to write it in JavaScript:

<script type="text/javascript">
function beforeUploadHandler() {
    // ... Your code
}
</script>

The following actions depend on the way used to embed HTML5/Flash Uploader into your application.

In HTML5/Flash Uploader JavaScript event handlers can be added using the imageUploaderFlash.events property of the events type. This class exposes a number of properties representing available events. Each property accepts a string containing a name of the handler for corresponding event or an array of handler names.

var fu = $au.imageUploaderFlash({
    id: 'Uploader1',
    events: {
        beforeUpload: beforeUploadHandler,
        afterUpload: [afterUploadHandler1, afterUploadHandler2]
    }
});
        
fu.writeHtml();

HTML5/Flash Uploader ASP.NET allows configuring event handlers through the ImageUploaderFlash.ClientEvents property which accepts a set of ClientEvent instances. Each instance specifies the event name and name of the JavaScript function which will handle it. Names of supported events are contained in the ClientEventNames enumeration.

<aur:ImageUploaderFlash ID="Uploader1" runat="server">
    <ClientEvents>
        <aur:ClientEvent EventName="BeforeUpload" HandlerName="beforeUploadHandler" />
        <aur:ClientEvent EventName="AfterUpload" HandlerName="afterUploadHandler1" />
        <aur:ClientEvent EventName="AfterUpload" HandlerName="afterUploadHandler2" />
    </ClientEvents>
</aur:ImageUploaderFlash>

If you use HTML5/Flash Uploader PHP add event handlers via the ImageUploaderFlash.ClientEvents property. By analogy with HTML5/Flash Uploader JavaScript, this property type is ClientEvents which implements properties representing HTML5/Flash Uploader events. Every property accepts a string containing a name of the handler for corresponding event or an array of handler names.

$uploader = new ImageUploaderFlash("Uploader1");

$uploader->getClientEvents()->setBeforeUpload("beforeUploadHandler");
$uploader->getClientEvents()->setAfterUpload(array("afterUploadHandler1", "afterUploadHandler2"));

$uploader->render();

Removing Event Handlers

Event handlers can be removed at runtime only, thus to remove previously added beforeUploadHandler just execute the following code:

$au.imageUploaderFlash('Uploader1').events().beforeUpload().remove(beforeUploadHandler);

Example

The following code sample demonstrates how to use the BeforeUpload event to configure a converter at runtime. Here a user can specify what should be uploaded for each original image - the image as is or its downsized copy. Moreover, this code handles all possible errors which can be occurred during HTML5/Flash Uploader work.

<script type="text/javascript" src="Scripts/aurigma.imageuploaderflash.js">  </script>
<select id="selectSize">
    <option value="original" selected="selected">original</option>
    <option value="100x100">100x100</option>
    <option value="320x240">320x240</option>
    <option value="640x480">640x480</option>
    <option value="800x600">800x600</option>
    <option value="1024x768">1024x768</option>
    <option value="1280x1024">1280x1024</option>
    <option value="1600x1200">1600x1200</option>
</select>
<br />
<script type="text/javascript">
function beforeUpload() {
    var selectSize = document.getElementById('selectSize');
    var value = selectSize.options[selectSize.selectedIndex].value;
    var converter = $au.imageUploaderFlash('Uploader1').converters().get(0);
    if (value == "original") {
        converter.mode("*.*=SourceFile");
    } else {
        value = value.split("x");
        var width = parseInt(value[0]);
        var height = parseInt(value[1]);

        converter.set({mode: "*.*=Thumbnail", thumbnailWidth: width, thumbnailHeight: height});
    }
}

function error(errorCode, httpResponseCode, errorPage, additionalInfo){
    alert(errorCode + "\n" + additionalInfo);
}
    
var fu = $au.imageUploaderFlash({
    id: 'Uploader1',
    converters: [{mode: '*.*=SourceFile'}],
    events: {beforeUpload: [beforeUpload], error: [error]},
    uploadSettings: {
        actionUrl: "upload.aspx",
    }
});
    
u.writeHtml();
</script>

Debugging HTML5/Flash Uploader on Client Side

To make development and debugging of applications using HTML5/Flash Uploader easier HTML5/Flash Uploader JavaScript provides the debug class. It allows you to find the problem in the following cases:

• assigning values to read-only properties
• using an unsupported property or method
• an error is detected in the event handler function
• and other

Using the debug class you can view error, warning, debug messages, and response from the upload processing script. To filter these messages you can use the debug.level property which supports the following values:

• 0 shows no messages at all.
• 1 shows errors only.
• 2 shows errors and debug messages from HTML5/Flash Uploader.
• 3 shows errors, debug messages from HTML5/Flash Uploader, and information messages.

If the level property is greater or equal to 2 you will also get response from the upload processing script.

You can specify debug information output via the debug.mode value. The following values are available:

• console means debug messages are shown in the debug console of a browser. Here are the ways to open console in the most popular browsers:
  • In Internet Explorer 8 open Tools -> Developer Tools (or press F12), then select Script tab in the left pane and click Console in the right pane.
  • In Mozilla Firefox we recommend to use Firebug.
  • In Google Chrome click the Wrench icon and select Tools -> JavaScript Console (or press Ctrl+Shift+J).
  • In Safari turn on the Develop menu in the Advanced pane of Safari Preferences, after that go to Develop -> Show Error Console (or press Cmd+Alt+C).
• pop-up window means the new pop-up window is created and debug messages are shown in it. Do not forget to allow pop-up windows beforehand.
• alert means each debug message is shown in a separate alert dialog.

You can set one (like 'console') or several modes for displaying debug messages. In case of several debug modes, messages will be shown in the first available mode. For instance, if set the mode to ['popup','console'] messages will be shown in the console only if pop-up window failed to open (pop-ups are blocked frequently).

The following code inserted before rendering HTML5/Flash Uploader will print all debug messages to the console or to the pop-up window if the console is not available.

<script type="text/javascript">
    $au.debug().level(3);
    $au.debug().mode(['console','popup']);
</script>

Besides messages from HTML5/Flash Uploader you can send your own custom messages to the debug console via the showError(String) and showInfo(String) methods.

See Also

Reference

• HTML5/Flash Uploader Client-Side Events Reference

Manual

• Quick Start with HTML5/Flash Uploader ASP.NET
• Quick Start with HTML5/Flash Uploader PHP
• Quick Start with HTML5/Flash Uploader JavaScript
• Configuring Common Upload Settings in HTML5/Flash Uploader
• Configuring Files to be Uploaded in HTML5/Flash Uploader
• Debugging ASP.NET HTML5/Flash Upload Scripts
• Debugging PHP HTML5/Flash Upload Scripts