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:
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:
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:
var u = $au.uploader({
id: 'Uploader1',
//...
});
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.
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.
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.
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.
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.
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.
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.
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.
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.
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.
var u = $au.uploader({
//...
uploadSettings: {actionUrl: 'upload.aspx', redirectUrl: 'gallery.aspx'},
//...
});
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:
var u = $au.uploader({
//...
converters: [{ mode: '*.*=SourceFile'}],
//...
});
For more information see the Configuring Files to be Uploaded topic.
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:
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:
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 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:
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.
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.
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.
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:
var u = $au.uploader({
//...
events: { beforeUpload: Uploader1_BeforeUpload },
//...
});
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:
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);
}
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:
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.
After you configured Image Uploader control, use the uploader.writeHtml() method to render it, like follows:
<script type="text/javascript" src="scripts/aurigma.uploader.js"> </script>
<script type="text/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>
index.html:
<script type="text/javascript" src="scripts/aurigma.uploader.js"> </script>
<script type="text/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>
index.html:
<script type="text/javascript" src="scripts/iuembed.js"> </script>
<script type="text/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>