This product was discontinued
Read Blog Post

How to migrate uploader from Java to HTML5

This article describes how to switch from Java uploader to its HTML5 sibling, as well as how to use both uploader together. It describes using JavaScript API.

First of all, you should take into account that the functionality of Java uploader is wider than HTML5 counterpart. This is the main reason why Java uploader is still alive. So before you start, I would recommend to check out an overview of features you will lose after switching to HTML5 uploader.

Another question you may worry about is whether HTML5/Flash uploader is a separate product and whether you should  purchase anything extra. The good news is that the answer is no, both Java/ActiveX and HTML5/Flash are included to Upload Suite. When you download and install it, both uploaders can be found in the SDK package.

So, I will presume that none of aforementioned features are critical for you and you are ready to proceed. What's next?

Copying HTML5/Flash uploader to the server

When you were deploying Java/ActiveX uploader, you copied its .js, .cab and .jar files to your server. You should do the same with the HTML5/Flash uploader files.

Note, it is not recommended to mix all files in the same folder. Imagine, you have a /Scripts/ folder with all your JavaScript files. I recommend the following folder structure: 

  • /Scripts/aurigma/fh - for Flash/HTML5
  • /Scripts/aurigma/aj - for ActiveX/Java

If you need to manage multiple versions (e.g. after we release Upload Suite update you don't switch to the new version immediately), you can also add a version number to the folder structure: 

  • /Scripts/aurigma/8.1.12/fh
  • /Scripts/aurigma/8.1.12/aj

As a result, the fh folder should contain the content of the %US8 INSTALL FOLDER%\HTML5-Flash\Scripts folder and the aj folder should contain %US8 INSTALL FOLDER%\ActiveX-Java\Scripts content.

Rewriting the uploader page

Imagine you have the following page with Java/ActiveX uploader:

<script src="/Scripts/aurigma/aj/aurigma.uploader.js" type="text/javascript"></script>
<div id="aurigma">
  <script type="text/javascript">

  var uploader = $au.uploader({
	id: 'Uploader1',
	width: '100%',
	height: '500px',
	licenseKey: 'XXXXX-XXXXX-XXXXX-XXXXX-XXXXX-XXXXXX;ZZZZZ-ZZZZZ-ZZZZZ-ZZZZZ-ZZZZZ-ZZZZZZ',
	enableAutoRotation: true,
	activeXControl: {
		codeBase: '/Scripts/aurigma/aj/Uploader8.cab',
		codeBase64: '/Scripts/aurigma/aj/Uploader8_x64.cab'
	},
	javaControl: {
		codeBase: '/Scripts/aurigma/aj/Uploader8.jar'
	},
	uploadSettings: {
	  actionUrl: '/upload_url',
	  redirectUrl: '/redirect_url',
	  filesPerPackage: 1
	},
	restrictions: {
		fileMask: '*.jpg;*.jpeg;*.png;*.gif;*.bmp'
	},
	converters: [
		{ mode: '*.*=SourceFile' },
		{ 
			mode: "*.*=Thumbnail", 
			thumbnailHeight: 300, 
			thumbnailWidth: 300, 
			thumbnailJpegQuality: 70 
		}
	],
	metadata: {
		exif: 'ExifGpsLatitude;ExifGpsLongitude;ExifGpsLatitudeRef;ExifGpsLongitudeRef'
	},
	uploadPane: {
		viewMode: 'Details'
	},
	folderPane: {
		height: 500
	},
	imageEditor: {
	  enableCrop: false
	}
  });
  uploader.writeHtml();  
  </script>
</div>

First of all, you should replace the uploader script links, i.e. replace this line:

<script src="/Scripts/aurigma/aj/aurigma.uploader.js" type="text/javascript"></script>

with these ones:

<link href="/Scripts/aurigma/fh/css/aurigma.htmluploader.control.css" rel="stylesheet" type="text/css" />
<script src="/Scripts/aurigma/fh/aurigma.imageuploaderflash.min.js" type="text/javascript"></script>
<script src="/Scripts/aurigma/fh/aurigma.htmluploader.control.js" type="text/javascript"></script>

After that, instead of the $au.uploader object, the uploader should be inserted with $au.imageUploaderFlash.

Don’t be misled with the Flash word in the class name. It contains both HTML5 and Flash uploader (switched automatically). This name mentions Flash by historical reasons.

The API of $au.imageUploaderFlash is very close to $au.uploader. The following properties can be copied from old uploader:

  • Basic params like width, height, id, etc.
  • Converters
  • UploadSettings
  • Restrictions
  • Metadata (including EXIF fields)
  • UploadPane settings
  • The following event handlers:
    • AfterUpload/AfterPackageUpload
    • BeforeUpload/BeforePackageUpload
    • Error
    • InitComplete
    • PreRender
    • Progress
    • RestrictionFailed

The following changes are required:

  • Instead of activeXControl and javaControl, add a flashControl with a codebase pointing to .swf file in the fh folder.
  • File mask may have a slightly different syntax, see an example.
  • Modify params that configure the user interface. For example, UploadPane's view mode supports only three values: 'Thumbnails', 'Tiles' and 'Icons'.
  • Remove params that enable features which are not available in HTML5 uploader.
  • If you change the user interface language, load localization .js files from the fh folder instead of aj. 
  • Replace a license key in the licenseKey param (or add it separated with a semicolon). You can find your HTML5/Flash uploader key in your account.
  • If you use the type param, specify a combination of 'html' and 'flash' instead of 'java' and 'activex'. Or remove it at all, if you want to keep the default behavior.

As a result, your code will look like this:

<link href="/Scripts/aurigma/fh/css/aurigma.htmluploader.control.css" rel="stylesheet" type="text/css" />
<script src="/Scripts/aurigma/fh/aurigma.imageuploaderflash.min.js" type="text/javascript"></script>
<script src="/Scripts/aurigma/fh/aurigma.htmluploader.control.js" type="text/javascript"></script>

<div id="aurigma">
  <script type="text/javascript">

  var uploader = $au.imageUploaderFlash({
	id: 'Uploader1',
	width: '100%',
	height: '500px',
	licenseKey: 'YYYYY-YYYYY-YYYYY-YYYYY-YYYYY-YYYYYY;AAAAA-AAAAA-AAAAA-AAAAA-AAAAA-AAAAAA',
	enableAutoRotation: true,
	flashControl: {
		codeBase: '/Scripts/aurigma/fh/aurigma.imageuploaderflash.swf'
	},
	uploadSettings: {
	  actionUrl: '/upload_url',
	  redirectUrl: '/redirect_url',
	  filesPerPackage: 1
	},
	restrictions: {
		fileMask: ['Images', '*.jpg;*.jpeg;*.png;*.gif;*.bmp']
	},
	converters: [
		{ mode: '*.*=SourceFile' },
		{ 
			mode: "*.*=Thumbnail", 
			thumbnailHeight: 300, 
			thumbnailWidth: 300, 
			thumbnailJpegQuality: 70 
		}
	],
	metadata: {
		exif: 'ExifGpsLatitude;ExifGpsLongitude;ExifGpsLatitudeRef;ExifGpsLongitudeRef'
	}
	uploadPane: {
		viewMode: 'Tiles'
	}
  });
  uploader.writeHtml();  
  </script>
</div>

Using both uploaders on the same page

If you want to use both uploaders on the same page, you may have two questions: 

  1. Will scripts from the fh and aj folder conflict? If yes, how to resolve it? 
  2. How to initialize the uploader settings without code duplication?

Resolving conflict

Unfortunately, the conflict exists. The problem is that the $au namespace is redefined in each of script. A good news that this is just a shortcut for a long namespace which is unique in each library: 

  • Aurigma.ImageUploader - for Java/ActiveX
  • Aurigma.ImageUploaderFlash - for HTML5/Flash

So if you want to add both uploaders to the page, the code will look like this:

<!DOCTYPE html>
<html>
<head>
	<link rel="stylesheet" type="text/css" href="/Scripts/aurigma/fh/css/aurigma.htmluploader.control.css" />
	<script src="/Scripts/aurigma/fh/aurigma.imageuploaderflash.js"></script>
	<script src="/Scripts/aurigma/fh/aurigma.htmluploader.control.js"></script>
	<script src="/Scripts/aurigma/aj/aurigma.uploader.js"></script>
</head>
<body>
	<script type="text/javascript">
		var aj = Aurigma.ImageUploader.uploader({
				id: "aurigma-aj1",
				javaControl:
					{
						codeBase: "/Scripts/aurigma/aj/Uploader8.jar"
					}
		});
		aj.writeHtml();

		var fh = Aurigma.ImageUploaderFlash.imageUploaderFlash({
				id: "aurigma-fh1"
		});
		fh.writeHtml();
	</script>
</body>
</html>

Reusing settings

Now let's talk how to reduce the code duplication. Both uploader and imageUploaderFlash classes have a set method which accepts a JSON with settings. This method is used to change localization settings, but we can use it to apply shared params as well:

<!DOCTYPE html>
<html>
<head>
	<link rel="stylesheet" type="text/css" href="/Scripts/aurigma/fh/css/aurigma.htmluploader.control.css" />
	<script src="/Scripts/aurigma/fh/aurigma.imageuploaderflash.js"></script>
	<script src="/Scripts/aurigma/fh/aurigma.htmluploader.control.js"></script>
	<script src="/Scripts/aurigma/aj/aurigma.uploader.js"></script>
</head>
<body>
	<script type="text/javascript">
		
		// Java/ActivX-specific params 
		var aj = Aurigma.ImageUploader.uploader({
				id: "aurigma-aj1",
				javaControl:
						 {codeBase: "/Scripts/aurigma/aj/Uploader8.jar"}
			});
			
		// HTML5/Flash-specific params 
		var fh = Aurigma.ImageUploaderFlash.imageUploaderFlash({
					id: "aurigma-fh1"
					
			});
			
		// Shared params
		var params = {
			converters: [
				{
					mode: "Thumbnail", 
					thumbnailWidth: "600", 
					thumbnailHeight: "600"
				}
			],
			uploadSettings: {
				actionUrl: '/destination_url',
				redirectUrl: '/redirect_url' 
			}
		};
		
		// Add shared params to both uploaders
		aj.set(params);
		fh.set(params);
		
		// Display uploaders
		aj.writeHtml();
		fh.writeHtml();
	</script>
</body>
</html>

Selecting an uploader based on a browser

You may want to use HTML5 uploader in Chrome and continue using old uploader in other browsers. It is quite easy to implement:

<!DOCTYPE html>
<html>
<head>
	<link rel="stylesheet" type="text/css" href="/Scripts/aurigma/fh/css/aurigma.htmluploader.control.css" />
	<script src="/Scripts/aurigma/fh/aurigma.imageuploaderflash.js"></script>
	<script src="/Scripts/aurigma/fh/aurigma.htmluploader.control.js"></script>
	<script src="/Scripts/aurigma/aj/aurigma.uploader.js"></script>
</head>
<body>
	<script type="text/javascript">
		
		// Browser detection method is found at 
		// http://stackoverflow.com/questions/9847580/how-to-detect-safari-chrome-ie-firefox-and-opera-browser
		var isChrome = !!window.chrome && navigator.userAgent.indexOf(' OPR/') < 0;
				
		var uploader;
		if (!isChrome) {
			uploader = Aurigma.ImageUploader.uploader({
					id: "aurigma-aj1",
					javaControl:
							 {codeBase: "/Scripts/aurigma/aj/Uploader8.jar"}
					// insert Java/ActivX-specific params here
					});
		} else {
			uploader = Aurigma.ImageUploaderFlash.imageUploaderFlash({
					id: "aurigma-fh1"
					// insert HTML5/Flash-specific params here
			});
		}
		uploader.set({
			converters: [
				{
					mode: "Thumbnail", 
					thumbnailWidth: "600", 
					thumbnailHeight: "600"
				}
			],
			uploadSettings: {
				actionUrl: '/destination_url',
				redirectUrl: '/redirect_url' 
			}
		});
		uploader.writeHtml();
	</script>
</body>
</html>

You can additionally optimize this code, e.g. avoid loading aj scripts if you load fh or vice versa, however I omit it for brevity. The whole idea is the same.

Alternative upload page

Many Aurigma customers provide a tiny link on the bottom of the uploader page saying "if you have problems with Java, try our alternative uploader". Even if some Java uploader features are critical, sometimes it is better to give a poorer upload option than leaving the user with non-functional Java applet.

If you find this idea worthy, you can implement it in the following way:

<!DOCTYPE html>
<html>
<head>
	<link rel="stylesheet" type="text/css" href="/Scripts/aurigma/fh/css/aurigma.htmluploader.control.css" />
	<script src="/Scripts/aurigma/fh/aurigma.imageuploaderflash.js"></script>
	<script src="/Scripts/aurigma/fh/aurigma.htmluploader.control.js"></script>
	<script src="/Scripts/aurigma/aj/aurigma.uploader.js"></script>
</head>
<body>
	<script type="text/javascript">
		
		// Taken from here: http://stackoverflow.com/a/5158301
		function getParameterByName(name) {
			var match = RegExp('[?&]' + name + '=([^&]*)').exec(window.location.search);
			return match && decodeURIComponent(match[1].replace(/\+/g, ' '));
		}
		
		var uploader;
		// If the page is opened as http://yoursite.com/upload?uploader=aj, it will open 
		// Java/ActiveX uploader, otherwise it will open Flash/HTML5 uploader
		if (getParameterByName('uploader')=='aj') {
			uploader = Aurigma.ImageUploader.uploader({
					id: "aurigma-aj1",
					javaControl:
							 {codeBase: "/Scripts/aurigma/aj/Uploader8.jar"}
					// insert Java/ActivX-specific params here
					});
		} else {
			uploader = Aurigma.ImageUploaderFlash.imageUploaderFlash({
					id: "aurigma-fh1"
					// insert HTML5/Flash-specific params here
			});
		}
		uploader.set({
			converters: [
				{
					mode: "*.*=SourceFile"
				}
			],
			uploadSettings: {
				actionUrl: '/destination_url',
				redirectUrl: '/redirect_url' 
			}
		});
		uploader.writeHtml();
	</script>
</body>
</html>

Both uploaders are located on the same page, but you use a query string to select an uploader (e.g. http://yoursite.com/upload?uploader=fh or http://yoursite.com/upload?uploader=aj).

What is about a server-side part?

This question consists of three subquestions: 

  1. Should I rewrite a server code? 
  2. If I use ASP.NET DLL or PHP library, may I continue using its Java/ActiveX version?
  3. Should I configure anything extra for HTML5/Flash? 

Short answers are:

  1. Most likely your old code will work without any changes.
  2. Most likely uploads from HTML5 uploader will be handled properly with ASP.NET DLL or PHP library of Java/ActiveX. 
  3. Additional configuration is required if you are going to use Flash uploader (by default, only in outdated browsers like IE8 or Safari 5) and process images before the upload.

Now, let's elaborate.

Code changes

Server-side API of HTML5/Flash uploader is a subset of Java/ActiveX server API. In 95% cases, the code written for Java/ActiveX will work without any changes. The remaining 5% may be affected if you expect some Java uploader specific fields like file chunks, etc.

If you are stilll concerned, check out POST field reference of HTML5/Flash uploader. If you are using any Aurigma's POST variables which are not mentioned here, you need to fix it.

If you don't use POST variables directly and use ASP.NET DLL or PHP library instead, you won't be affected.

What if for any reason you want to distinguish uploads sent from Java/ActiveX and HTML5/Flash? The simplest way to do it is to set different id to those uploaders and analyze the UploaderID POST variable:

ASP.NET (C#): Request.Form["UploaderID"]
 PHP: $_POST["UploaderID"]
 Classic ASP: objUpload.Form("UploaderID")
 ColdFusion: <cfset uploaderId=(#Form.UploaderID#) />
 ...

ASP.NET DLL or PHP library replacement

ASP.NET DLL and PHP library of Java/ActiveX and HTML5/Flash uploaders are based on the same codebase and in general they are identical, except of some subtle changes. The uploads sent by HTML5/Flash will be successfully processed by DLL or PHP library of Java/ActiveX. However if you are not going to use both uploaders together, I would recommend to replace the library or DLL just in case.

Additional configuration for Flash uploader

There is a problem with Flash platform - it does not allow sending the binary data created programmatically as files. In case of Flash uploader, it happens during image manipulations, for example, when creating resized copies of an original image or apply a watermark. Those files should be sent as binary fields. That's why the POST requests sent by Flash uploader should be preprocessed.

Fortunately, it is not as complicated as you may think. We have already prepared all the code, and all you need is to do the following:

ASP.NET

  1. Put Aurigma.ImageUploaderFlash.dll to the bin folder of your application.
  2. Add the line <add name="UploaderModule" type="Aurigma.ImageUploaderFlash.UploaderModule"/> to the <httpModules> and <modules> sections of web.config.
<configuration>
   <!-- other sections -->
   <system.web>
        <!-- other sections -->
        <httpModules>
            <!-- other modules -->
            <add name="UploaderModule" type="Aurigma.ImageUploaderFlash.UploaderModule"/>
        </httpModules>
        <!-- other sections -->
   </system.web>
   <!-- other sections -->
   <system.webServer>
        <!-- other sections -->
        <modules>
            <!-- other modules -->
            <add name="UploaderModule" type="Aurigma.ImageUploaderFlash.UploaderModule"/>
        </modules>
        <!-- other sections -->
   </system.webServer>
   <!-- other sections -->
</configuration>

PHP

If you are using PHP library, no need to do anything extra. However if you prefer to access $_FILES and $_POST yourself, you should use the flashrequestfix.php script which can be found among the PHP library files. The usage is explained in documentation. In short:

  1. Include this script to your page.
  2. Before starting the processing, call the preProcessRequest function.
  3. Use the moveFile($source, $destination) to save files, where $source should be $_FILES["FileN_M]["tmp_name"] collection and $destination is the destination path.
  4. At the end of your script call the postProcessRequest to clean up all temporary files.

Classic ASP

The simplest way to do it in classic ASP is to use pure VBScript upload parser instead of Dundas/Persits/ABCUpload with a small modification:

  1. Download Upload Files Without COM v3
  2. Put clsField.asp, clsProgress.asp, clsUpload.asp files in the /clsUpload folder.
  3. Insert this code to the clsUpload.asp file starting from line #609: 
    'If it is not found, check whether the file is uploaded by Aurigma Flash Uploader
	If llngStart = 0 Then
		llngStart = InStr(1, pstrDisposition, "filenam_=""", vbTextCompare)
	End If

Coldfusion and Java

A small .jar file and instructions can be found in %US8 INSTALL FOLDER%\HTML5-Flash\Coldfusion\Binaries folder.

Important

Some servers may be configured to reject POST requests containing binary fields. So if you add preprocessing, but files sent by Flash uploader still don’t go through, this is a first thing you should check (especially if your server has strict security protection).

* * *

This article contains enough information to complete the migration from Java to HTML5 uploader. However if you have any questions or anything does not work, don't hesitate to submit a support ticket.

Get a free 30-day trial

Upload Suite includes premium uploaders based on various technologies (HTML5, Flash, Java, ActiveX) for any server technology – ASP.NET and PHP, classic ASP and JSP, Ruby-on-rails and node.js.
Why Upload Suite?