## Aurigma Image Uploader 7.0.28

# Upgrading from Image Uploader 6 in JavaScript

- Collapse All Sections
- See Also
- Language Filter ( all languages )

This topic highlights major API changes between versions 6 and 7 of Image Uploader and illustrates how to migrate a Web site to new version of the product. Image Uploader 7 has new client-side API:

- New client API utilizes JSON notation to configure Image Uploader client-side instead of addParam methods.
- JavaScript object model became more comprehensive.

The JavaScript API Changes between Versions 6 and 7 topic provides a list of API changes between Image Uploader 6 and 7 versions.

In this topic we will create two small Web sites where users can upload images using Image Uploader 6 and 7. The applications will have similar functionality, and we will see how to implement the same set of features using both uploaders and what the differences between them are. Here is the list of Image Uploader features coming into play in our sample applications:

- creating Image Uploader instance
- applying license key
- defining private-label-specific settings
- customizing pane layout and buttons
- specifying action and redirect URLs
- preprocessing files before upload
- watermarking thumbnails
- defining quality meter
- handling client-side events
- rendering Image Uploader control
- changing thumbnail settings at run-time

## Creating Image Uploader Instance

To embed Image Uploader in a web page you have to create an uploader class instance and specify its identifier via the id parameter as follows:

### JavaScript

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

## Applying License Key

As you can see from the code snippet below, format of license keys has changed in Image Uploader 7. License key(s) are set through the uploader.licenseKey property, if you have several keys, they should be separated with semicolons. Take into account that now Image Uploader Express does not allow to specify multiple license keys, if you need to specify several ones, you need to upgrade your edition.

### JavaScript

    var u = $au.uploader({
    //...
        licenseKey: 'XXXXX-XXXXX-XXXXX-XXXXX-XXXXX-XXXXXX;YYYYY-YYYYY-YYYYY-YYYYY-YYYYY-YYYYYY',
    //...
    });

For more information about licensing see the Evaluating and Registering Image Uploader topic.

## Defining Private-label-specific Settings

If you use private-label version of Image Uploader you need to specify your custom Image Uploader cab and jar files, version number, Java class name, and ActiveX control CLSID and PROGID.

Use the activeXControl.codeBase, activeXControl.codeBase64, and javaControl.codeBase properties to setup URLs (absolute or relative) to cab and jar files respectively. Pay attention to the fact that in contrast to version 6 Image Uploader 7 requires filename in URLs specified in the codeBase properties.

The minimum required version of Image Uploader control can be set using the javaControl.version and activeXControl.version properties.

To customize Java class name use the javaControl.className property.

ActiveX control CLSID and PROGID you can set via the activeXControl.classId and activeXControl.progId respectively.

Important

All the information you need to specify using these properties will be provided to you by Aurigma, Inc. If some parameters were not sent, you should use default values.

### JavaScript

    var u = $au.uploader({
    //...
        javaControl: {codeBase: 'Scripts/MyUploader7.jar', version: '7.0.11',
            className: 'com.mycompany.myuploader.MyUploader.class'},
        activeXControl: {codeBase: 'Scripts/MyUploader7.cab', codeBase64: 'Scripts/MyUploader7_x64.cab',
            version: '7.0.11', progId: 'MyCompany.MyUploader',
            classId: 'XXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX'},
    //...
    });

For more information see the Using Private-label Version of Image Uploader JavaScript topic.

## Customizing User Interface

User interface customization API has been changed in new version. Now every visual element is represented by a class in client API, and its settings are presented via properties of these classes. Find the complete list of properties aimed to customize user interface in the Customizing Appearance topic.

### Pane Layout

Now instead of two- and three-pane layouts we have introduced one layout which combines benefits of both. The user can expand/collapse different panels: upload list and/or file tree can be hidden. One-pane layout is supported also, it has minimal "drop-box" user interface.

Each pane is reproduced by corresponding object in API: folderPane, treePane, uploadPane. Panes settings can be customized through properties of these objects.

Quick overview of new approaches in user interface can be found in the Layouts article.

### Custom Buttons

As you know Image Uploader allows to change appearance of standard buttons for better integration with customers' Web sites. Button settings are specified through specially formatted strings containing information on where to find button icons, their dimensions, etc. The format of the string stays the same as in version 6. In our sample we will change appearance of the Upload button.

### JavaScript

    var u = $au.uploader({
    //...

        //Set one-pane layout
        paneLayout: 'OnePane',

        //Define custom "Upload" button
        uploadButtonImageFormat: "Width=82;Height=25;UrlNormal='../Images/UploadNormal.png';"
            + "UrlNormalFocused='../Images/UploadNormalFocused.png';UrlHover='../Images/UploadHover.png';"
            + "UrlHoverFocused='../Images/UploadHoverFocused.png';UrlPressed='../Images/UploadPressed.png';"
            + "UrlDisabled='../Images/UploadDisabled.png'",
    //...
    });

To customize buttons of Image editor and Description editor use the properties of corresponding classes.

## Specifying Action URL and Redirect URL

Specify an URL to a server page where Image Uploader posts all selected files via the actionUrl property. That page should contain server code which saves files to necessary folders server-side.

To redirect a user to another page after upload is successfully completed use the redirectUrl property.

For more information see the Configuring Common Upload Settings topic.

### JavaScript

    var u = $au.uploader({
    //...
        uploadSettings: {actionUrl: 'upload.aspx', redirectUrl: 'gallery.aspx'},
    //...
    });

## Configuring Files to Upload

New concept of converters were added to version 7. A converter defines how Image Uploader preprocesses files client-side before upload. You can specify uploading original files, creating thumbnails of specified dimensions and quality, or ZIP format compression via the converter.mode.

The following code configures uploader to send original files:

### JavaScript

    var u = $au.uploader({
    //...
        converters: [{ mode: '*.*=SourceFile'}],
    //...
    });

For more information see the Configuring Files to be Uploaded topic.

### Thumbnails

To upload transformed (e.g. resized or watermarked) images you should specify a converter in thumbnail mode. Thumbnail parameters are specified through the set of converter.thumbnailXXX properties.

The following sample illustrates how to configure a 120x120 thumbnail converter:

### JavaScript

    var u = $au.uploader({
    //...
        converters: [{ mode: '*.*=Thumbnail', thumbnailWidth: 120, thumbnailHeight: 120}],
    //...
    });

Often it is useful to upload a source file along with a thumbnail. You can do it by combining converters from the previous two samples, like this:

### JavaScript

    var u = $au.uploader({
    //...
        converters: [
            //Add sourceFile converter
            { mode: '*.*=SourceFile'},
            //Add thumbnail converter
            { mode: '*.*=Thumbnail', thumbnailWidth: 120, thumbnailHeight: 120}
        ],
    //...
    });

To know more see the Uploading Images section.

### Watermarks

Watermarks are specified through the converter.thumbnailWatermark property and can be applied only to the converters which generate thumbnails.

The following sample shows how to create a converter generating a watermarked thumbnail:

### JavaScript

    var u = $au.uploader({
    //...
        converters: [{ mode: '*.*=Thumbnail', thumbnailWidth: 800, thumbnailHeight: 600,
            thumbnailJpegQuality: 80, thumbnailFitMode: 'Fit',
            //Configure watermark
            thumbnailWatermark: 'Opacity=100;ImageUrl=../Images/Watermark.png;'
                + 'ImageWidth=155;ImageHeight=30;Position=BottomRight;'}],
    //...
    });

You can find a full review of Image Uploader watermarking capabilities in the Applying Watermarks article.

## Defining Quality Meter

The quality meter is now represented by a separate class, qualityMeter. Quality indicators parameters are set using the formats property via specially formatted string. See the code snippet below illustrating how to adjust quality meter.

### JavaScript

    var u = $au.uploader({
    //...
        paneItem: {qualityMeter: { formats: '4 x 6,1800,1200,1.5;5 x 7,2100,1500,1.5;'
            +'8 x 10,3000,2400,1.5;16 x 20,4000,3200,2;30 x 20,6000,4000,2'}},
    //...
    });

For more information see the Using Quality Meter topic.

## Modifying Application Behavior at Run-time

### Handling Client-side Events

Image Uploader 7 exposes a number of JavaScript events which are fired on different uploader activities. This way, you can add additional logic to your Web page, and display custom progress bar, for example. As well, you can use events to modify Image Uploader settings at run-time based on selected files or user input. You can find the complete list of client-side events in the reference. To set an event handler use the uploader.events property like follows:

### JavaScript

    var u = $au.uploader({
    //...
        events: { beforeUpload: Uploader1_BeforeUpload },
    //...
    });

### Changing Converter Settings at Run-time

In our example we will examine how to reinitialize thumbnail settings at run-time. We subscribe to BeforeUpload event and add event handler function to the code. In the function we firstly find the appropriate thumbnail to modify. As you can see from code snippet below, we get access to converters by 0-based indices. Thus, we get the first of converters as follows: $au.uploader('uploader1').converters().get(0), where uploader1 is the uploader.id. After we got the converter, we change its settings.

The following snippet changes thumbnail size at run-time according to paper size format chosen beforehand:

### JavaScript

    function Uploader1_BeforeUpload() {

        var size = paperSize.split('x');
        var pixelWidth = size[1] * 300;
        var pixelHeight = size[0] * 300;

        //Get the second converter
        var converter = $au.uploader('uploader1').converters().get(1);

        //Specify thumbnail size
        converter.thumbnailWidth(pixelWidth);
        converter.thumbnailHeight(pixelHeight);
    }

### Adding Converter at Run-time

The previous paragraph shows how to change the existing converter, but sometimes there is a necessity to create a new one. For instance, if your Web site accepts thumbnails and you want to give a user an option to upload source image as well. In fact, the only difference from changing existing converter is that you should use converters.add() method to create a new converter. After that you can access it via the converters.get(Number) method. The following BeforeUpload event handler adds the SourceFile converter:

### JavaScript

    function Uploader1_BeforeUpload() {

        if (uploadSourceFile){

            //Add new converter
            uploader.converters().add();

            //The "count" method returns the number of converters actually contained in the collection
            var convertersCount = uploader.converters().count();

            //Get the newly created converter, which is the last in converters collection
            var converter = uploader.converters().get(convertersCount);

            //Specify converter mode
            converter.mode("*.*=SourceFile");
        }
    }

For more information see the Using JavaScript API topic.

## Rendering Image Uploader Control

After you configured Image Uploader control, use the uploader.writeHtml() method to render it, like follows:

### JavaScript

    <script language="javascript" src="Scripts/aurigma.uploader.js"> </script>
    <script language="javascript">

    var u = $au.uploader({
        id: 'Uploader1',
        licenseKey: 'XXXXX-XXXXX-XXXXX-XXXXX-XXXXX-XXXXXX;YYYYY-YYYYY-YYYYY-YYYYY-YYYYY-YYYYYY',
    //...
    });

    //Render Image Uploader control
    u.writeHtml();

    </script>

## Complete Code of Application with Image Uploader 7

index.html:

### JavaScript

    <script language="javascript" src="scripts/aurigma.uploader.js">  </script>
    <script language="javascript">

    var u = $au.uploader({

        //Specify the id of this Uploader instance
        id: 'uploader1',

        //Set width and height of Image Uploader control
        width: 650, height: 450,

        //Apply license keys, semicolon is used to separate several keys
        licenseKey: 'XXXXX-XXXXX-XXXXX-XXXXX-XXXXX-XXXXXX;YYYYY-YYYYY-YYYYY-YYYYY-YYYYY-YYYYYY',

        //Private-label-specific settings
        //Set codeBase and minimum required version of java control
        javaControl: {codeBase: 'Scripts/ImageUploader7.jar', version: '7.0.11' },
        //Set codeBase and minimum required version of activeX control
        activeXControl: {codeBase: 'Scripts/ImageUploader7.cab', version: '7.0.11' },

        //Specify one-pane layout
        paneLayout: 'OnePane',

        //Define custom "Upload" button
        uploadButtonImageFormat: "Width=82;Height=25;UrlNormal='../Images/UploadNormal.png';"
            + "UrlNormalFocused='../Images/UploadNormalFocused.png';UrlHover='../Images/UploadHover.png';"
            + "UrlHoverFocused='../Images/UploadHoverFocused.png';UrlPressed='../Images/UploadPressed.png';"
            + "UrlDisabled='../Images/UploadDisabled.png'",

        //Specify a page containing server code to handle uploaded files (actionUrl)
        uploadSettings: {actionUrl: 'upload.aspx'},

        //Add two converters
        converters: [
            //The first one uploads a source file itself
            { mode: '*.*=SourceFile'},
            //The second converter creates a 800x600 thumbnail
            { mode: '*.*=Thumbnail', thumbnailWidth: 800, thumbnailHeight: 600,
                thumbnailJpegQuality: 60, thumbnailFitMode: 'Fit',
                //watermarked with the "Watermark.png" image
                thumbnailWatermark: 'Opacity=100;ImageUrl=../Images/Watermark.png;'
                    + 'ImageWidth=155;ImageHeight=30;Position=BottomRight;'}],

        //Configure quality meter
        paneItem: {qualityMeter: { formats: '4 x 6,1800,1200,1.5;5 x 7,2100,1500,1.5;'
            +'8 x 10,3000,2400,1.5;16 x 20,4000,3200,2;30 x 20,6000,4000,2'}},

        //Set the "Uploader1_BeforeUpload" function as a beforeUpload event handler
        events: { beforeUpload: Uploader1_BeforeUpload }
    })

    //Render Image Uploader control
    u.writeHtml();

    var paperSize = '4x6';

    //BeforeUpload event handler
    function Uploader1_BeforeUpload() {

        var size = paperSize.split('x');
        var pixelWidth = size[1] * 300;
        var pixelHeight = size[0] * 300;

        //Get reference to the Uploader instance
        var uploader = $au.uploader('uploader1');

        //Add new converter
        uploader.converters().add();

        //The "count" method returns the number of converters actually contained in the collection
        var convertersCount = uploader.converters().count();

        //Get the newly created converter, which is the last in converters collection
        var converter = uploader.converters().get(convertersCount-1);

        //Specify converter settings
        converter.mode("*.*=Thumbnail");
        converter.thumbnailFitMode("Fit");
        converter.thumbnailWidth(pixelWidth);
        converter.thumbnailHeight(pixelHeight);
        converter.thumbnailJpegQuality("80");
    }
    </script>

## Complete Code of Application with Image Uploader 6.5

index.html:

### JavaScript

    <script language="javascript" src="scripts/iuembed.js">  </script>
    <script language="javascript">

    //Specify the id of this Image Uploader instance, and size of Image Uploader control
    var iu = new ImageUploaderWriter("ImageUploader1", 650, 450);

    //Apply license keys, semicolon is used to separate several keys
    iu.addParam("LicenseKey", "XXXXX-XXXXX-XXXXX-XXXXX-XXXXX;YYYYY-YYYYY-YYYYY-YYYYY-YYYYY");

    //Private-label-specific settings
    //Set code base and minimum required version of activeX control
    iu.activeXControlCodeBase = "ImageUploader6.cab";
    iu.activeXControlVersion = "6,5,1,0";

    //Set code base, filename and minimum required version of java control
    iu.javaAppletCodeBase = "Scripts/";
    iu.javaAppletJarFileName = "ImageUploader6.jar";
    iu.javaAppletVersion = "6.5.1.0";

    //Specify one-pane layout
    iu.addParam("PaneLayout", "OnePane");

    //Define custom "Upload" button
    iu.addParam("ButtonSendImageFormat", "Width=82;Height=25;UrlDisabled='../Images/UploadDisabled.png';"
        + "UrlNormal='../Images/UploadNormal.png';UrlNormalFocused='../Images/UploadNormalFocused.png';"
        + "UrlHover='../Images/UploadHover.png';UrlHoverFocused='../Images/UploadHoverFocused.png';"
        + "UrlPressed='../Images/UploadPressed.png'");

    //Specify a page containing server code to handle uploaded files
    iu.addParam("Action", "upload.aspx");

    //Configure the first thumbnail settings
    iu.addParam("UploadThumbnail1FitMode", "Fit");
    iu.addParam("UploadThumbnail1Width", "800");
    iu.addParam("UploadThumbnail1Height", "600");
    iu.addParam("UploadThumbnail1JpegQuality", "60");

    //Set thumbnail watermark
    iu.addParam("UploadThumbnail1Watermark", "opacity=100;ImageUrl=../Images/Watermark.png;"
        + "ImageWidth=155;ImageHeight=30;Position=BottomRight;");

    //Configure quality meter
    iu.addParam("QualityMeterFormats", "4 x 6,1800,1200,1.5;5 x 7,2100,1500,1.5;"
        + "8 x 10,3000,2400,1.5;16 x 20,4000,3200,2;30 x 20,6000,4000,2");

    //Set the "Uploader1_BeforeUpload" function as a beforeUpload event handler
    iu.addEventListener("BeforeUpload", "ImageUploader1_BeforeUpload");

    //Render Image Uploader control
    iu.writeHtml();

    var paperSize = '4x6';

    //BeforeUpload event handler
    function ImageUploader1_BeforeUpload() {

        var size = paperSize.split('x');
        var pixelWidth = size[1] * 300;
        var pixelHeight = size[0] * 300;

        //Get reference to the Image Uploader instance
        imageUploader1 = getImageUploader('ImageUploader1');

        //Specify the second converter settings
        imageUploader1.setUploadThumbnail2FitMode("Fit");
        imageUploader1.setUploadThumbnail2Width(pixelWidth);
        imageUploader1.setUploadThumbnail2Height(pixelHeight);
        imageUploader1.setUploadThumbnail2JpegQuality("80");
    }
    </script>

## See Also

### Manual

- ASP.NET API Changes between Versions 6 and 7
- PHP API Changes between Versions 6 and 7
- Evaluating and Registering Image Uploader
- Customizing Appearance
- Layouts
- Configuring Common Upload Settings
- Configuring Files to be Uploaded
- Uploading Images
- Using Quality Meter
- Using JavaScript API
- Sending All Files at Once or in Several Parts