Using JavaScript API

Getting Reference to ActiveX/Java Uploader by ID

When creating an UploaderUploader (ASP.NET)Uploader (PHP)uploader (JavaScript) object, we obligatorily set its identifier via the Uploader.IDID (PHP)id (JavaScript) property.

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

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

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

This identifier is used to refer to ActiveX/Java 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 Uploader instance.

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

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

Using Properties

To modify some ActiveX/Java Uploader properties after initialization, you should get a reference to the uploader 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 uploader.set(Object) method.

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

<script type="text/javascript" src="Scripts/aurigma.uploader.js">  </script>
<select id="selectView" onchange="changeView()">
    <option value="Thumbnails" selected="selected">Thumbnails</option>
    <option value="Tiles">Tiles</option>
    <option value="List">List</option>
    <option value="Details">Details</option>
</select>
<br />
<script type="text/javascript">
function changeView(){
    var selectView = document.getElementById('selectView');
    var value = selectView.options[selectView.selectedIndex].value;
    $au.uploader('Uploader1').folderPane().viewMode(value);
    $au.uploader('Uploader1').uploadPane().viewMode(value);
}

var u = $au.uploader({ id: 'Uploader1' });                 
u.writeHtml();        
</script>

Using Methods

If you need to call ActiveX/Java Uploader methods, you should do it in the same way as for properties: get a reference to the uploader 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 uploader.upload() method which initiates the upload.

<script type="text/javascript" src="Scripts/aurigma.uploader.js">  </script>
<script type="text/javascript">
function upload(){
    $au.uploader('Uploader1').upload();
}

var u = $au.uploader({ id: 'Uploader1' });                 
u.writeHtml();
</script>
<br />
<input type="button" value="upload" onclick="upload()" />

Using Events

ActiveX/Java 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 ActiveX/Java Uploader into your application.

In ActiveX/Java Uploader JavaScript event handlers can be added using the uploader.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 u = $au.uploader({ 
    id: 'Uploader1',
    events: {
        beforeUpload: beforeUploadHandler,
        afterUpload: [afterUploadHandler1, afterUploadHandler2]
    }
});
        
u.writeHtml();

ActiveX/Java Uploader ASP.NET allows configuring event handlers through the Uploader.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:Uploader 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:Uploader>

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

$uploader = new Uploader("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.uploader('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 ActiveX/Java Uploader work.

<script type="text/javascript" src="Scripts/aurigma.uploader.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.uploader('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 u = $au.uploader({
    id: 'Uploader1',
    converters: [{mode: '*.*=SourceFile'}],
    events: {beforeUpload: [beforeUpload], error: [error]},
    uploadSettings: {
        actionUrl: "upload.aspx",
    }
});
    
u.writeHtml();
</script>

Debugging ActiveX/Java Uploader on Client Side

To make development and debugging of applications using ActiveX/Java Uploader easier ActiveX/Java 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 ActiveX/Java Uploader.
• 3 shows errors, debug messages from ActiveX/Java 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 ActiveX/Java 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(['popup','console']);
</script>

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

See Also

Manual

• Quick Start with ActiveX/Java Uploader ASP.NET
• Quick Start with ActiveX/Java Uploader PHP
• Quick Start with ActiveX/Java Uploader JavaScript
• Configuring Common Upload Settings in ActiveX/Java Uploader
• Debugging ASP.NET ActiveX/Java Upload Scripts
• Debugging PHP ActiveX/Java Upload Scripts
• Debugging ActiveX/Java Upload Scripts in Other Platforms