The iuembed.js helper script is a special JavaScript that is used to embed Image Uploader to the HTML page. This topic describes how to use this script.

In this topic:


How Does It Work

You may wonder why to use a separate JavaScript file instead of using standard HTML means to insert ActiveX controls and Java applets? There are several reasons:

  • With iuembed.js you can 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 iuembed.js you would have to create different pages for ActiveX and Java versions of Image Uploader.
  • With iuembed.js you can 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.
  • With iuembed.js you avoid the problem caused by the Internet Explorer security update 912945Leave site.
    This update causes all ActiveX controls inserted via the OBJECT tag to be "activated" by the user (by mouse click or keyboard). This noticeable reduces usability. However iuembed.js implements a workaround that allows to avoid this.

This script is used in the following way:

  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.

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

Using Helper Script

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

JavaScript CopyCode imageCopy Code
<script type="text/javascript" src="iuembed.js"></script>
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 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):

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

iu.writeHtml();
</script>
NoteImportant

Do not confuse ImageUploaderWriter class from iuembed.js with ImageUploader control. Do not try to call any methods or properties of ImageUploader from ImageUploaderWriter and vice versa.

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 end of this 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 CopyCode imageCopy Code
    <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 = "ImageUploader5.cab";
    iu.activeXControlVersion = "5,0,10,0";
    iu.javaAppletEnabled = false;
    
    iu.writeHtml();
    </script>
  • If you need to install only the Java version, initialize ImageUploaderWriter with these properties:
    JavaScript CopyCode imageCopy Code
    <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 = "5.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.

NoteNote

If it is necessary to verify what version of Image Uploader is used, use the getControlType method. The getActiveXInstalled method returns whether ActiveX version is already installed.

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:

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

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

iu.writeHtml();
</script>
NoteNote

Keep in mind that some parameters are not available in both ActiveX and Java version. If you add a parameter that does not exist in some version of Image Uploader, it will be merely ignored by it. You can see information whether certain parameter is available in ActiveX or Java version in the properties reference.

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 a button on the security dialog. Furthermore, if Image Uploader is loaded on Windows XP with Service Pack 2, the user should also click an information bar before the security dialog appears.

It may be quite embarrassing for the user. They may misunderstand installation instructions and reject installation when security dialog pops up.

If this happens, display re-installation instructions is a good idea. The iuembed.js exposes a number of properties that enables to do this.

The instructionsEnabled property specifies whether to display instructions. Set it to true to have instructions to appear. The instructionsCommon property specifies HTML code for those instructions which are common for all client platforms. The instructionsWinXPSP2 and instructionsNotWinXPSP2 values are appended to common instructions depending on the client platform (Windows XP with Service Pack 2 and others platforms respectively).

This code snippet demonstrates how to use it:

JavaScript CopyCode imageCopy Code
iu.instructionsEnabled=true;

iu.instructionsCommon="Image Uploader ActiveX control is necessary to upload "+
                      "your files quickly and easily. You will be able to select multiple images "+
                      "in user-friendly interface instead of clumsy input fields with Browse button. "+
                      "Installation will take up to few minutes, please be patient. To install Image Uploader, ";

iu.instructionsNotWinXPSP2="please reload page and select \"Yes\" button " +
                           "when you will see control installation dialog."

iu.instructionsWinXPSP2="please click on Information Bar. After page reloading select \"Yes\" when "+
                          "you will see control installation dialog.";
Adding 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 of the function created at the first step.

This code snippet demonstrates how it should be looking like:

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

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

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

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

iu.writeHtml();
</script>
NoteImportant

You must pass the name of the function, not the reference to it. In other words, do not forget to enclose the name within quotation marks. So iu.addEventHandler("Progress", ImageUploader_Progress) - is incorrect, but iu.addEventHandler("Progress", "ImageUploader_Progress") - is correct.

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:

JavaScript CopyCode imageCopy Code
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:

JavaScript CopyCode imageCopy Code
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:

JavaScript CopyCode imageCopy Code
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 guarantied that the applet has been initialized.

That's why iuembed.js exposes a special event, which is raised when the page is loaded the control is completely ready to be used. This event handler can be assigned to the fullPageLoadListenerName property of the ImageUploaderWriter class as follows:

JavaScript CopyCode imageCopy Code
<script type="text/`javascript">
function fullPageLoad() {
    //Your code..
}

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

iu.fullPageLoadListenerName="fullPageLoad";

iu.writeHtml();
</script>

Helper Script Members

Classes

For each control included into Image Uploader, the iuembed.js exposes an appropriate class:

  • ImageUploaderWriter class - for ImageUploader.
  • ShellComboBoxWriter class - for ShellComboBox.
  • UploadPaneWriter class - for UploadPane.
  • ThumbnailWriter class - for Thumbnail.

All these classes has the same members (see below). This reference will mention only ImageUploaderWriter for brevity, however keep in mind that other classes also have members.

NoteNote

Some members have effect on ActiveX or Java version only. The following marking is used.

  • ActiveX label. - a member has effect on ActiveX only.
  • Java label. - a member has effect on Java only.

Members that work for both versions are not marked.

Methods
Name Arguments Description
public method addParam
  1. paramName - a parameter name.
  2. paramValue - a parameter value.

Adds a parameter with the specified name and value. It takes into effect when writeHtml or getHtml method is run.

public method addEventListener
  1. eventName - an event name.
  2. eventListener - a name of the JavaScript function which is the event listener.

Subscribes the specified JavaScript function to the specified event.

NoteNote

You should specify the name of the function, not the reference to this function.

ActiveX label. public method getActiveXInstalled N/A

Verifies whether ActiveX control is installed. If yes, it returns true; otherwise it returns false.

NoteNote

This method works in Internet Explorer only.

public method getControlType N/A

Returns a value that specifies what kind of platform is currently used - ActiveX, Java, or none (i.e. neither ActiveX nor Java can be used in the current browser). It may return one of the following strings:

  • ActiveX
  • Java
  • None
NoteNote

Unlike the controlType property it can be used every time after the writer object is created (not just after the writeHtml or getHtml method call).

public method getHtml N/A

Generates the HTML code which will embed Image Uploader and returns it as a string. It will write all parameters added with the addParam method and append all event handlers specified by the addEventListener method.

public method writeHtml N/A

Generates the HTML code which will embeds Image Uploader and writes this code directly into the page. It will write all parameters added with the addParam method and append all event handlers specified by the addEventListener method.

Properties
Name Default value Description
ActiveX label. public property activeXControlCodeBase ImageUploader5.cab

The URL that specifies where to download the ActiveX version of Image Uploader from. It is an analogue of the codebase attribute of the OBJECT element.

ActiveX label. public property activeXControlEnabled true

Value that specifies whether to use ActiveX version of Image Uploader. If true, the ImageUploaderWriter analyzes the browser, and if it is Internet Explorer and operating system is Windows, the writeHtml method generates the code for the ActiveX version. For other platform, the code for the Java version is generated. If you want to use the Java version regardless to the browser, set this property to false.

ActiveX label. public property activeXControlVersion empty string

The minimum required version of the ActiveX version ( ImageUploader5.cab file). If the user has an older version installed, Internet Explorer downloads the ImageUploader5.cab file from the URL provided by the activeXControlCodeBase property automatically. See the Updating Image Uploader on the Client Side topic for more details.

NoteImportant

The subversions should be separated only by commas (unlike the Java version). For example, 4,0,132,0 .

public property controlType N/A (depends on the browser)

Value that specifies what kind of platform is currently used - ActiveX, Java, or none (i.e. neither ActiveX nor Java can be used in the current browser). It may return one of the following strings:

  • ActiveX
  • Java
  • None
NoteNote

This property can be used only after writeHtml or getHtml method call. If you need to do it before, use the getControlType method instead.

public property height N/A (provided in the constructor)

Height of the control. You should provide an integer number. Syntax like 100% is acceptable, however keep in mind that it is not cross-browser compatible. That's why it is highly recommended to avoid it.

public property id N/A (provided in the constructor)

ID of the control that is used to get a reference with a help of the getImageUploader function.

ActiveX label. public property instructionsEnabled true

Value that specifies whether to display instructionsCommon, instructionsNotWinXPSP2, and instructionsWinXPSP2 when Image Uploader fails to be installed.

ActiveX label. public property instructionsCommon see code snippet above

Common part of instructions displayed during upload failure (regardless of the Windows version). Can contain any HTML code.

ActiveX label. public property instructionsNotWinXPSP2 see code snippet above

Part of instructions which is displayed if the current Windows is not Windows XP with Service Pack 2. Appended to the instructionsCommon string. Can contain any HTML code.

ActiveX label. public property instructionsWinXPSP2 see code snippet above

Part of instructions which is displayed if the current Windows is Windows XP with Service Pack 2. Appended to the instructionsCommon string. Can contain any HTML code.

Java label. public property javaAppletCached false

Value which enables or disables caching for the Java version of Image Uploader. If true, then the caching is enabled, and the Java applet is not re-downloaded until you update it on the server. Otherwise the applet is re-downloaded every time the user visits this page. See the Updating Image Uploader on the Client Side topic for more details.

Java label. public property javaAppletCodeBase ./

Path to the virtual directory on your server where ImageUploader5.jar file is located. Unlike activeXControlCodeBase it should be a path to a directory, but not to the file.

Java label. public property javaAppletEnabled true

Value that specifies whether to use Java version of Image Uploader. If true, the ImageUploaderWriter will generate the code for Java version when the ActiveX cannot be used. If false, and the ActiveX version cannot be used, the message stating that the browser is not supported will be displayed.

Java label. public property javaAppletVersion empty string

The minimum required version of the ImageUploader5.jar . If the user has older version installed, the browser downloads the ImageUploader5.jar from the directory specified by the javaAppletCodeBase property. See the Updating Image Uploader on the Client Side topic for more details.

NoteImportant

If an empty string is specified, applet caching will not work regardless of the javaAppletCached value.

The subversions should be separated only by dots (unlike ActiveX version). For example, 2.0.152.0 .

public property showNonemptyResponse off

Specifies whether and how Image Uploader will display a received server response. Possible values are:

  • off
  • alert
  • dump

If off, no response will be shown. If alert, the response will be displayed in an alert window. If dump, the response will be displayed at the bottom of the Web page with Image Uploader.

This feature may be useful when debugging server scripts. See the Debugging Server Scripts topic for more details.

public property width N/A (provided in the constructor)

Width of the control. You should provide an integer number. Syntax like 100% is acceptable, however keep in mind that it is not cross-browser compatible. That's why it is highly recommended to avoid it.

Standalone Functions
Name Arguments Description
public function getImageUploader
  1. ID - an ID of the control specified in the ImageUploaderWriter constructor.

Returns a reference to the control by specified ID. Unlike document.getElementById, it overcomes compatibility problems on certain browsers.

Members for Private-Label Versions

When private-label version is used, you need to customize the following properties (that should not be changed in the standard version):

Name Description
ActiveX label. public property activeXControlCodeBase Name of the .cab file.
ActiveX label. public property activeXClassId CLSID of the ActiveX control.
ActiveX label. public property activeXProgId PROGID of the ActiveX control.
Java label. public property javaAppletJarFileName Name of the .jar file.
Java label. public property javaAppletClassName Applet class name.

This code snippet demonstrates how to do it:

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

iu.activeXControlCodeBase = "MyUploader.cab";
iu.activeXClassId = "B8144F57-C240-4012-A5AE-6E06019EDA5F";
iu.activeXProgId = "MyCompany.MyUploader";
iu.javaAppletJarFileName = "MyUploader.jar";
iu.javaAppletClassName="com.mycompany.myuploader.MyUploader.class";

iu.writeHtml();
</script>

Do not forget to modify these properties for other writer classes if you use them.

See Also

Reference

API Reference

Manual

Quick Start
Adding a Custom Progress Bar
Updating Image Uploader on the Client Side