Library Overview

How Does It Work

Image Uploader embedding scripts library consists of the following JavaScript files:

• iuembed.js is a main script, it contains classes that are directly meant to embed Image Uploader to the page.
• iuembed.InstallationProgress.js includes ActiveX installation progress functionality.
• iuembed.Intellisense.js is intended for development purposes only. When it is linked with the page Intellisense tooltips for all Image Uploader members will be shown in Visual Studio.
• iuembed.Localization_X.js (where X is a language code) is a set of Image Uploader localization scripts.
• iuembed.AmazonS3.js and iuembed.Nirvanix.js contain classes which implement Image Uploader extenders.

You may wonder why to use a separate JavaScript files instead of using standard HTML means to insert ActiveX controls and Java applets? These scripts allow you to:

• Work with both versions of Image Uploader using the same code. ActiveX controls and Java applets are embedded into HTML code in different way. The iuembed.js script analyzes the browser, which is used to open Image Uploader and automatically produce correct HTML code. Without this script you would have to create different pages for ActiveX and Java versions of Image Uploader.
• Use single Java version-related code for all browsers. Syntax of Java applet embedding differs for different browsers. Even if you used different code for ActiveX and Java, you would have a huge headache writing the code for Java version which would work in all browsers.
• Develop and debug a web application which uses Image Uploader in more convenient way. The library supports Intellisense and shows warnings if Image Uploader is configured incorrectly.
• Display special instructions helping users to download and install the ActiveX control.
• Switch between predefined translations of Image Uploader interface or add your own ones.
• Allow users to upload files from browser directly to cloud storage.

Embedding Image Uploader

To embed Image Uploader to a page using Image Uploader embedding scripts library you should perform the following steps:

1. Link the iuembed.js file with your HTML page.
2. Create an instance of ImageUploaderWriter object (appropriate writer objects exist for other controls included in Image Uploader; see below for more details).
3. Initialize parameters of ImageUploader control.
4. Add event handlers if necessary.
5. Call the writeHtml method in the necessary part of your HTML code that will embed the ImageUploader instance on the page.
6. After ImageUploader control is embedded, you can get an instance of this control, edit its properties, and call its methods dynamically.

Here we will consider these steps in detail.

Linking iuembed.js

To be able to use iuembed.js, it is necessary to link it with your page. You can do it in the same way as you do for other JavaScript files, i.e. by using SCRIPT element with src attribute set to the URL to the iuembed.js.

In other words you should insert the following string into the beginning of the HTML page (before any other JavaScript code):

<script type="text/javascript" src="iuembed.js"></script>

You can find iuembed.js in the Scripts folder of the Image Uploader SDK installation folder.

Adding Image Uploader to Page

To embed the Image Uploader in the page, you need to do at least the following:

1. Create new ImageUploaderWriter class instance.
2. Call the writeHtml method of this object to generate the code which will embed Image Uploader and write it into the page. Alternatively you can use the getHtml method to get it as a string.

Here is a simple code snippet demonstrating this (it installs both versions of Image Uploader):

<script type="text/javascript">
var iu = new ImageUploaderWriter("ImageUploader1", 610, 500);

iu.writeHtml();
</script>

As you see, the ImageUploaderWriter constructor has three arguments: ID of the control (or applet), width, and height. You can change these values later using appropriate properties.

You can also configure other properties of the ImageUploaderWriter, for example choose which version to install: ActiveX, Java or both.

Full list of members can be found at the Helper Script Members topic.

Choosing Between ActiveX, Java, and Dual

Depending on your license, you may need only ActiveX version or only Java version or both of them (Dual). If you need to install only the ActiveX version or only the Java version, do one of the following:

• If you need to install only the ActiveX version, initialize ImageUploaderWriter with these properties:
  JavaScript

  <script type="text/javascript">
  var iu = new ImageUploaderWriter("ImageUploader1", 610, 500);
  
  // Use these values to install only the ActiveX version
  iu.activeXControlEnabled = true;
  iu.activeXControlCodeBase = "ImageUploader6.cab";
  iu.activeXControlVersion = "6,0,10,0";
  iu.javaAppletEnabled = false;
  
  iu.writeHtml();
  </script>

• If you need to install only the Java version, initialize ImageUploaderWriter with these properties:
  JavaScript

  <script type="text/javascript">
  var iu = new ImageUploaderWriter("ImageUploader1", 610, 500);
  
  // Use these values to install only the Java version
  iu.javaAppletEnabled = true;
  iu.javaAppletCodeBase = "./";
  iu.javaAppletCached = true;
  iu.javaAppletVersion = "6.0.10.0";
  iu.activeXControlEnabled = false;
  
  iu.writeHtml();
  </script>

If you need to install both versions at the same time, combine these code snippets removing the activeXControlEnabled and javaAppletEnabled instructions.

Initializing Image Uploader Parameters

To initialize parameters of Image Uploader you should use the addParam method of the ImageUploaderWriter class instance before you call writeHtml.

The addParam method has two arguments: the name of the parameter and its value.

Here is a code example:

<script type="text/javascript">
var iu=new ImageUploaderWriter("ImageUploader1", 610, 500);

iu.addParam("Action", "Upload.aspx");

iu.writeHtml();
</script>

Configuring Alternative Text for Control

It takes a while to download and install Image Uploader. After download completes, the browser requires the user to click an information bar and accept the security warning. It may be quite embarrassing for the user. They may misunderstand installation instructions and reject installation when security dialog pops up.

If this happens, displaying re-installation instructions is a good idea. Image Uploader embedding scripts library includes the InstallationProgressExtender class which enables this feature. This class is defined in the iuembed.InstallationProgress.js file and exposes a number of properties that allow you not only to specify text instructions, but also customize theirs appearance using CSS styles and put animated wait indicator. See the Using Image Uploader Installation Progress topic for the detailed information about this feature.

Adding and Removing Event Handlers

To add event handlers do the following:

1. Create a JavaScript function that has the same list of arguments as the event.
2. Use the addEventListener method of the ImageUploaderWriter object. This method has two arguments: the name of the event and the name or reference to the function created at the first step.

This code snippet demonstrates how it should be looking like:

<script type="text/javascript">
function ImageUploader1_Progress(Status, Progress, ValueMax, Value, StatusText) {
	//Your code
}

function ImageUploader1_BeforeUpload() {
	//Your code
}

var iu = new ImageUploaderWriter("ImageUploader1", 710, 500);

iu.addParam("SilentMode", "true");

iu.addEventListener("Progress", "ImageUploader1_Progress");
iu.addEventListener("BeforeUpload", ImageUploader1_BeforeUpload);

iu.writeHtml();
</script>

To remove some previously added event listeners use the removeEventListener method which accepts the same parameters as the addEventListener.

Getting a Reference to Image Uploader by ID

A traditional way to obtain a reference to an object from a JavaScript is to use document.getElementById(id). However it will not work with certain browsers (in particular, Safari). That is why iuembed.js script contains a special function - getImageUploader. It has the single argument - ID of the control, which you get a reference for (for example, specified when creating an instance of ImageUploaderWriter), and returns a reference to the control or the applet.

Here is an example of usage:

var imageUploader1 = getImageUploader("ImageUploader1");

Working with Properties Dynamically

Sometimes you need to modify Image Uploader properties after initialization. The typical situation is when you need to change the view mode between detailed list and thumbnails using the HTML dropdown list.

To do it, you should get a reference to the ImageUploader control as described above, and modify the property value.

The syntax of runtime property modification is the following:

object.setPropertyName, where PropertyName is a name of the property as specified in the properties reference.

To read a property value, use object.getPropertyName property instead.

This code snippet demonstrates how to work with properties after initialization:

var imageUploader1 = getImageUploader("ImageUploader1");
imageUploader1.setUploadView(imageUploader1.getFolderView());

Calling Methods

To call methods of ImageUploader, you should use the same approach as you use for properties: get a reference to the ImageUploader and call the method using the following syntax:

object.MethodName(argument1, argument2, ...), where MethodName is a name of the method as specified in the methods reference.

Here is a code example:

var imageUploader1 = getImageUploader("ImageUploader1");
imageUploader1.Send();

Page Loading and Control Initializing Events

Quite often it is necessary to work with Image Uploader controls when you are sure that the page has been fully loaded and ActiveX control or Java applet has been completely created and initialized.

Although you might use the window.onload to determine whether ActiveX control is loaded, it will not work for Java applet. Java applets are loaded asynchronously, and when the window.onload event is raised, it is not guaranteed that the applet has been initialized.

That is why iuembed.js exposes the FullPageLoad event, which is raised when the page is loaded and the control is completely ready to be used. To add handler for this event use the addEventListener method with the "FullPageLoad" event name parameter value:

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

var iu = new ImageUploaderWriter("ImageUploader1", 610, 500);

iu.addEventListener("FullPageLoad", "fullPageLoad");

iu.writeHtml();
</script>

Debugging Image Uploader Embedding Script

Image Uploader embedding scripts library makes development and debugging of Image Uploader embedding script easier. It supports Intellisense and shows warnings if Image Uploader has wrong configuration.

To enable Intellisense tooltips just link the iuembed.Intellisense.js file with your page. If so you will see tooltips for Image Uploader members when typing them in Visual Studio.

To make debugging more efficient iuembed.js exposes three debug levels:

• 0 - show no warnings at all;
• 1 - show critical warnings only;
• 2 - show all.

To specify the debug level you can use the code below before creating the ImageUploaderWriter object.

IUCommon.debugLevel = 2;

If debug messages are enabled (the debug level is 1 or 2) you will get warnings in the following cases:

• addParam or addEventListener methods have wrong call syntax.
• Image Uploader has not the property or event passed to these methods.
• The property passed to the addParam method is already added to the list of Image Uploader parameters.
• Event listener function does not exist.
• and others...

It is recommended to use iuembed.Intellisense.js script and set the debug level to greater than 0 value on the development stage only. Disable Intellisene and debug messages on production application.

Using Localization

Image Uploader embedding scripts library includes the following predefined localizations:

• Chinese (simplified)
• Chinese (traditional)
• Czech
• Dutch
• English
• French
• German
• Italian
• Japanese
• Korean
• Norwegian
• Russian
• Swedish
• Turkish
• Ukrainian

Each localization is represented with a iuembed.Localization_X.js file, where X is a language code of this localization.

To apply localization to your Image Uploader you should perform the following steps:

1. Link the necessary localization script to your page. For example, if you want to translate Image Uploader into Italian take the iuembed.Localization_it.js file.
   
   JavaScript

   <script type="text/javascript" src="iuembed.Localization_it.js"></script>
   

2. Call the addParams method of the it_resources class and pass the ImageUploaderWriter object to it:
   
   JavaScript

   <script type="text/javascript">
       var iu = new ImageUploaderWriter("ImageUploader1", 610, 500);
   
       //Configure Image Uploader
   
       it_resources.addParams(iu);
   
       iu.writeHtml();
   </script>
   

To add you own localization just create a localization script analogous to existing ones. See the Localization topic for details.

See Also

Reference

• Image Uploader API Reference

Manual

• Inserting Image Uploader into Web Page
• Adding a Custom Progress Bar
• Updating Image Uploader on the Client Side
• Upgrading Minor Versions
• Using Image Uploader Installation Progress
• Localization