This documentation is for the old version. Go to the latest Upload Suite docs

Using JavaScript API

Image Uploader JavaScript is used not only to embed Image 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 Image Uploader is initialized. The present topic describes and illustrates the most significant aspects of Image Uploader runtime usage.

Getting Reference to Image 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.

JavaScript
$au.uploader({
    id: 'Uploader1',
    // ...
});
ASP.NET
<aur:Uploader ID="Uploader1" runat="server">
    <!-- ... -->
</aur:Uploader>
PHP
$uploader = new Uploader("Uploader1");
// ...

This identifier is used to refer to Image 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.

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

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

Using Properties

To modify some Image 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.

Note

Not all Image Uploader properties can be modified at runtime. See Image Uploader JavaScript Reference 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 and uploadPane.viewMode properties respectively to the selected option.

JavaScript
<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 Image 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.

JavaScript
<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

Image 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:

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

The following actions depend on the way used to embed Image Uploader into your application.

In Image 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.

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

Image 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.

ASP.NET
<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 Image Uploader PHP add event handlers via the Uploader.ClientEvents property. By analogy with JavaScript library, this property type is ClientEvents which implements properties representing Image Uploader events. Every property accepts a string containing a name of the handler for corresponding event or an array of handler names.

PHP
$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:

JavaScript
$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 Image Uploader work.

JavaScript
<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 Image Uploader on Client Side

To make development and debugging of applications using Image Uploader easier Image 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 Image Uploader.
  • 3 shows errors, debug messages from Image 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 Image Uploader will print all debug messages to the console or to the pop-up window if the console is not available.

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

Besides messages from Image Uploader you can send your own custom messages to the debug console via the showError(String) and showInfo(String) 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