---
title: "Using JavaScript API"
canonical: https://www.aurigma.com/docs/us8/using-javascript-api.htm
product: "Upload Suite 8"
---

# Using JavaScript API
 
ActiveX/Java Uploader JavaScript is used not only to embed ActiveX/Java Uploader into web page but also to interact with it dynamically. Here it provides a number of properties, methods, and events, which can be used after ActiveX/Java Uploader is initialized. The present topic describes and illustrates the most significant aspects of ActiveX/Java Uploader runtime usage.

## Getting Reference to ActiveX/Java Uploader by ID
 
When creating an Uploader[Uploader (ASP.NET)](https://www.aurigma.com/docs/us8/JA_T_Aurigma_ImageUploader_Uploader.htm.md)[Uploader (PHP)](https://www.aurigma.com/docs/us8/JA_T_P_Uploader.htm.md)[uploader (JavaScript)](https://www.aurigma.com/docs/us8/JA_T_J_$au_uploader.htm.md) object, we obligatorily set its identifier via the Uploader.ID[ID (PHP)](https://www.aurigma.com/docs/us8/JA_P_P_BaseControl_ID.htm.md)[id (JavaScript)](https://www.aurigma.com/docs/us8/JA_P_J_$au_uploader_id.htm.md) property.
 ```
$au.uploader({
    id: 'Uploader1',
    // ...
});
``` ```aspx-cs
<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](https://www.aurigma.com/docs/us8/JA_T_J_$au_uploader.htm.md) 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)](https://www.aurigma.com/docs/us8/JA_M_J_$au_uploader_set_1_8419e710.htm.md) method.
 
**Note** 
Not all ActiveX/Java Uploader properties can be modified at runtime. See [ActiveX/Java Uploader JavaScript Reference](https://www.aurigma.com/docs/us8/JA_R_J_Aurigma_ImageUploader.htm.md) for details.
 
The code sample below demonstrates how to implement a separate drop-down list containing available view modes. Here we change the [folderPane.viewMode](https://www.aurigma.com/docs/us8/JA_P_J_$au_folderPane_viewMode.htm.md) and [uploadPane.viewMode](https://www.aurigma.com/docs/us8/JA_P_J_$au_uploadPane_viewMode.htm.md) 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()](https://www.aurigma.com/docs/us8/JA_M_J_$au_uploader_upload.htm.md) 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](https://www.aurigma.com/docs/us8/JA_P_J_$au_uploader_events.htm.md) property of the [events](https://www.aurigma.com/docs/us8/JA_T_J_$au_events.htm.md) 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](https://www.aurigma.com/docs/us8/JA_P_Aurigma_ImageUploader_Uploader_ClientEvents.htm.md) property which accepts a set of [ClientEvent](https://www.aurigma.com/docs/us8/JA_T_Aurigma_ImageUploader_ClientEvent.htm.md) 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](https://www.aurigma.com/docs/us8/JA_T_Aurigma_ImageUploader_ClientEventNames.htm.md) enumeration.
 ```aspx-cs
<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](https://www.aurigma.com/docs/us8/JA_P_P_Uploader_ClientEvents.htm.md) property. By analogy with JavaScript library, this property type is [ClientEvents](https://www.aurigma.com/docs/us8/JA_T_P_ClientEvents.htm.md) 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](https://www.aurigma.com/docs/us8/JA_T_J_$au_converter.htm.md) 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](https://www.aurigma.com/docs/us8/JA_T_J_$au_debug.htm.md) 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

**Note** 
For information about handling server-side errors, please, see the Debugging Upload Scripts [Debugging ASP.NET Upload Scripts](https://www.aurigma.com/docs/us8/debugging-aspnet-upload-scripts-iu.htm.md) [Debugging PHP Upload Scripts](https://www.aurigma.com/docs/us8/debugging-php-upload-scripts-iu.htm.md) [Debugging Upload Scripts in Other Platforms](https://www.aurigma.com/docs/us8/debugging-upload-scripts-in-other-platforms-iu.htm.md)  topic.
 
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](https://www.aurigma.com/docs/us8/JA_P_J_$au_debug_level.htm.md) 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](https://www.aurigma.com/docs/us8/JA_P_J_$au_debug_mode.htm.md) 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 -&gt; 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](https://addons.mozilla.org/en-US/firefox/addon/1843/).
    - In Google Chrome click the **Wrench** icon and select **Tools -&gt; 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 -&gt; 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)](https://www.aurigma.com/docs/us8/JA_M_J_$au_debug_showError_1_007649e6.htm.md) and [showInfo(String)](https://www.aurigma.com/docs/us8/JA_M_J_$au_debug_showInfo_1_007649e6.htm.md) methods.
 
**Note** 
It is recommended to set the **level** property to greater than `0` value on the development stage only. Disable debug messages on production application.

## See Also
 
### Manual
 
- [Quick Start with ActiveX/Java Uploader ASP.NET](https://www.aurigma.com/docs/us8/quick-start-with-image-uploader-aspnet.htm.md)
- [Quick Start with ActiveX/Java Uploader PHP](https://www.aurigma.com/docs/us8/quick-start-with-image-uploader-php.htm.md)
- [Quick Start with ActiveX/Java Uploader JavaScript](https://www.aurigma.com/docs/us8/quick-start-with-image-uploader-javascript.htm.md)
- [Configuring Common Upload Settings in ActiveX/Java Uploader](https://www.aurigma.com/docs/us8/configuring-common-upload-settings-iu.htm.md)
- [Debugging ASP.NET ActiveX/Java Upload Scripts](https://www.aurigma.com/docs/us8/debugging-aspnet-upload-scripts-iu.htm.md)
- [Debugging PHP ActiveX/Java Upload Scripts](https://www.aurigma.com/docs/us8/debugging-php-upload-scripts-iu.htm.md)
- [Debugging ActiveX/Java Upload Scripts in Other Platforms](https://www.aurigma.com/docs/us8/debugging-upload-scripts-in-other-platforms-iu.htm.md)