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

In this topic:

You may wonder why to use a separate JavaScript file instead of using standard HTML means of inserting ActiveX controls? The main reason is that this approach lets you avoid the problem caused by the Internet Explorer security update 912945. This update causes all ActiveX controls inserted via the OBJECT tag to be "activated" by the user (with a mouse click or by pressing a key). This noticeably reduces usability. However, iuembed.js implements a workaround that allows avoiding this.

This script is used in the following way:

  1. Link the iuembed.js file to your HTML page.
  2. Create an instance of FileDownloaderWriter object.
  3. Initialize parameters of FileDownloader control.
  4. Add event handlers if necessary.
  5. Call the writeHtml method in the necessary part of your HTML code that will embed the FileDownloader instance into the page.
  6. After the FileDownloader 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 File Downloader SDK installation folder.

Using Helper Script

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

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

JavaScript

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

Adding File Downloader to a Web Page

To embed File Downloader into a Web page, you need to do at least the following:

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

Here is a short example of adding File Downloader to a Web page:

JavaScript

<script type="text/javascript">
var fd = new FileDownloaderWriter("FileDownloader1", 122, 44);

fd.writeHtml();
</script>
Important

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

The FileDownloaderWriter constructor has three arguments: an ID of the control, a width, and a height. You can change these values later using appropriate properties.

Full list of FileDownloaderWriter members can be found at the end of this topic.

Initializing File Downloader Parameters

To initialize parameters of File Downloader you should use the addParam method of the FileDownloaderWriter class instance before calling writeHtml.

The addParam method takes two arguments: a name of the property and its value.

The following example should make it clear:

JavaScript

<script type="text/javascript">
var fd = new FileDownloaderWriter("FileDownloader1", 122, 44);

fd.addParam("FileList", "http://localhost/filedownloader/filelist.txt");

fd.writeHtml();
</script>

Configuring an Alternate Text for the Control

It takes a while to download and install File Downloader. After download completes, the browser requires the user to click a button on the security dialog. Furthermore, if File Downloader is installed on Windows XP with Service Pack 2, the user should also click an information bar before the security dialog appears.

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

In this case, displaying installation instructions is a good idea. iuembed.js exposes a number of properties that enable this.

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

This code snippet demonstrates how to use these properties:

JavaScript

fd.instructionsEnabled=true;
fd.instructionsCommon="File Downloader ActiveX control is necessary to " +
	"download files quickly and easily. You will be able to select required " +
	"files in a user-friendly interface and simply click the \"Download\" " +
	"button. Installation will take up to few minutes, please be patient. To " +
	"install File Downloader, ";
fd.instructionsNotWinXPSP2="please reload the page and click the \"Yes\" " +
	"button when you see the control installation dialog."
fd.instructionsWinXPSP2="please click the Information Bar. After page reloads " +
	"click \"Yes\" when you see the control installation dialog.";

Adding Event Handlers

File Downloader provides a number of useful events which you can handle. To add event listeners 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 FileDownloaderWriter object. This method has two arguments: the name of the event and the name of the function created on the first step.

This example demonstrates how this should look like:

JavaScript

<script type="text/javascript">
function onError(Code, Description, HttpCode, Page, Url, Index){
    //Your code
}

var fd = new FileDownloaderWriter("FileDownloader1", 122, 44);
fd.addEventListener("Error", "onError");
</script>
Important

You must pass the name of the function, not the reference to it. In other words, do not forget to enclose the name in quotation marks. So fd.addEventHandler("Error", onError) is incorrect, but iu.addEventHandler("Error", "onError") is correct.

See the full list of all FileDownloader events in the FileDownloader Events reference section.

Getting a Reference to File Downloader by ID

The iuembed.js script contains a special function - getFileDownloader. It takes a single argument - the ID of the control, which you want to reference (for example, specified when creating an instance of FileDownloaderWriter), and returns a reference to the control.

Here is an example of obtaining a referenece:

JavaScript

var downloader = getFileDownloader("FileDownloader1");

Working with Properties Dynamically

Sometimes you need to modify File Downloader properties after initialization. The typical situation is when you need to change the file list in response to some user actions.

To do that, you should get a reference to the FileDownloader control as described above and modify the value of a required property.

The syntax of runtime property modification is the following:

object.setPropertyName(value), where PropertyName is a name of the property as specified in the FileDownloader Properties reference.

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

The code snippet below shows how to work with properties after initialization:

JavaScript

var downloader = getFileDownloader("FileDownloader1");
downloader.setFileList(downloader.getFileList());

Calling Methods

To call methods of FileDownloader, use the same approach as you use for properties: get a reference to the FileDownloader instance and call methods:

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

Here is a code example:

JavaScript

var downloader = getFileDownloader("FileDownloader1");
downloader.DownloadFileList();

Page Load and Initialization Events

Quite often it is necessary to work with the File Downloader control when you are sure that the page has been fully loaded and the control itself has been completely created and initialized.

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

JavaScript

<script language="javascript">
function onFullPageLoad(){
	// ... Add necessary code ...
}

var fd = new FileDownloaderWriter("FileDownloader", 122, 44);
fd.fullPageLoadListenerName = "onFullPageLoad";
// ... Configure File Downloader ...
fd.writeHtml();
</script>

Helper Script Members

Classes

iuembed.js exposes only one class, FileDownloaderWriter, which corresponds to the only class of File Downloader, FileDownloader.

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. The settings take effect when the 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.

Note

You should specify the name of the function, not the reference to this function.
public method getActiveXInstalled N/A

Verifies whether ActiveX control is installed. If yes, it returns true; otherwise it returns false.
public method getHtml N/A

Generates the HTML code which will embed File Downloader 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 embed File Downloader, 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
public property activeXControlCodeBase FileDownloader7.cab

The URL that specifies where to download the ActiveX version of File Downloader from. It is an analogue of the codebase attribute of the <object> element.
public property activeXControlCodeBase64 FileDownloader7_x64.cab

The URL that specifies where to download the 64-bit ActiveX version of File Downloader from. It is an analogue of the codebase attribute of the <object> element.
public property activeXControlEnabled true

Switch that specifies whether to use the ActiveX version of File Downloader.
public property activeXControlVersion empty string

The minimum required version of the ActiveX version of File Downloader.

Important

The subversions should be separated only by commas (unlike the Java version). For example, 7,0,1,0.
public property javaAppletCodeBase ./

The URL that specifies the folder where to download the Java version of File Downloader from.
public property javaAppletJarFileName FileDownloader7.jar

Name of the .jar file.
public property javaAppletEnabled true

Switch that specifies whether to use the Java version of File Downloader.
public property javaAppletVersion empty string

The minimum required version of the Java version of File Downloader.

Important

The subversions should be separated only by dots (unlike ActiveX version). For example, 7.0.1.0.
public property height N/A (provided in the constructor)

Height of the control. You should provide an integer number. Syntax like 100% is acceptable.
public property id N/A (provided in the constructor)

ID of the control that is used to get a reference with the help of the getFileDownloader function.
public property instructionsEnabled true

Value that specifies whether to display instructionsCommon , instructionsNotWinXPSP2, and instructionsWinXPSP2 when File Downloader fails to be installed.
public property instructionsCommon See code snippet above

Common part of instructions displayed during download failure (regardless of the Windows version). Can contain any HTML code.
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.
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.
public property width N/A (provided in the constructor)

Width of the control. You should provide an integer number. Syntax like 100% is acceptable.

Standalone Functions

Name Arguments Description
public function getFileDownloader
  1. ID - an ID of the control specified in the FileDownloaderWriter constructor.

Returns a reference to the control with the specified ID.

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
public property activeXControlCodeBase Name of the .cab file.
public property activeXControlCodeBase64 Name of the x64 .cab file.
public property activeXClassId CLSID of the ActiveX control.
public property activeXProgId PROGID of the ActiveX control.
public property javaAppletJarFileName Name of the .jar file.
public property javaAppletClassName Java applet class name.

The following code snippet demonstrates how to use these properties:

JavaScript

<script type="text/javascript">
var fd = new FileDownloaderWriter("FileDownloader1", 122, 44);

fd.activeXControlCodeBase = "MyDownloader.cab";
fd.activeXClassId = "B8144F57-C240-4012-A5AE-6E06019EDA5F";
fd.activeXProgId = "MyCompany.MyDownloader";
fd.javaAppletCodeBase = "MyDownloader.jar";

fd.writeHtml();
</script>