Helper Script Reference (iuembed.js)

The iuembed.js helper script is a special JavaScript that is used to embed Video 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? This file allows inserting and configuring Video Uploader, as well as provides some handy features, such as checking the configuration and displaying instructions in order to help users to install the control.

This script is used in the following way:

  1. Link the iuembed.js file with your HTML page.
  2. Create an instance of VideoUploaderWriter object (appropriate writer object exists for the ShellComboBox controls included in Video Uploader; see below for more details).
  3. Initialize parameters of VideoUploader control.
  4. Add event handlers if necessary.
  5. Call the writeHtml method in the necessary part of your HTML code that will embed the VideoUploader instance on the page.
  6. After VideoUploader 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 of the Video Uploader 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
<script type="text/javascript" src="iuembed.js"></script>

Adding Video Uploader to Page

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

  1. Create new VideoUploaderWriter class instance.
  2. Call writeHtml method of this object to generate the code which will embed Video 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:

JavaScript
<script type="text/javascript">
var vu = new VideoUploaderWriter("VideoUploader1", 610, 500);

vu.writeHtml();
</script>
Important

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

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

You can also configure other properties of the VideoUploaderWriter, for example a path to the VideoUploader file and its version number. See a full list of VideoUploaderWriter members at the end of this topic.

Initializing Video Uploader Parameters

To initialize parameters of Video Uploader you should use the addParam method of the VideoUploaderWriter 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
<script type="text/javascript">
var vu = new VideoUploaderWriter("VideoUploader1", 610, 500);

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

vu.writeHtml();
</script>

Configuring Alternative Text for Control

It takes a while to download and install Video Uploader. After download completes, the browser requires the user to click a button on the security dialog. Furthermore, if Video 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, instructionsNotWinXPSP2, and instructionsVista values are appended to common instructions depending on the client platform (Windows Vista, Windows XP with Service Pack 2, and others platforms respectively).

This code snippet demonstrates how to use it:

JavaScript
vu.instructionsEnabled = true;

vu.instructionsCommon = "<p>Video 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 <strong>Browse</strong> button. "
    + "Installation will take up to a few minutes, please, be patient. To install Video Uploader, ";
vu.instructionsNotWinXPSP2 = "please, reload the page and click the <strong>Yes</strong> button "
    + "when you see the control installation dialog.";
vu.instructionsWinXPSP2 = "please click the <strong>Information Bar</strong>. After page reload click "
    + "<strong>Install</strong> when you see the control installation dialog.";
vu.instructionsVista = "please click on the <strong>Information Bar</strong> and select "
    + "<strong>Install ActiveX Control</strong> from the dropdown menu. After page reload click " 
    + "<strong>Continue</strong> and then <strong>Install</strong> when you see the control "
    + "installation dialog.";

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

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

function VideoUploader1_BeforeUpload() {
    //Your code
}

var vu = new VideoUploaderWriter("VideoUploader1", 610, 500);

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

vu.addEventListener("Progress", "VideoUploader1_Progress");
vu.addEventListener("BeforeUpload", VideoUploader1_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 Video Uploader by ID

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

Here is an example of usage:

JavaScript
var videoUploader1 = getVideoUploader("VideoUploader1");

Working with Properties Dynamically

Sometimes you need to modify Video 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 VideoUploader 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
var videoUploader1 = getVideoUploader("VideoUploader1");
videoUploader1.setUploadView(videoUploader1.getFolderView());

Calling Methods

To call methods of VideoUploader, you should use the same approach as you use for properties: get a reference to the VideoUploader 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
var videoUploader1 = getVideoUploader("VideoUploader1");
videoUploader1.Send();

Page Loading and Control Initializing Events

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

Although you might use the window.onload to determine whether ActiveX control is loaded, it is recommended to use the FullPageLoad event defined in the iuembed.js file. It 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:

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

var iu = new VideoUploaderWriter("VideoUploader1", 610, 500);

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

iu.writeHtml();
</script>

Debugging Video Uploader Embedding Script

The iuembed.js makes development and debugging of Video Uploader embedding script easier. It shows warnings if Video Uploader has wrong configuration.

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 VideoUploaderWriter 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.
  • The property passed to the addParam method is already added to the list of Video Uploader parameters.
  • Event listener function does not exist.
  • and others...

It is recommended to set the debug level to greater than 0 value on the development stage only. Disable debug messages on production application.

Helper Script Members

Classes

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

  • VideoUploaderWriter class - for VideoUploader.
  • ShellComboBoxWriter class - for ShellComboBox.

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

Methods

Name Arguments Description
public method addParam paramName - a parameter name.
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 eventName - an event name.
eventListener - a name or reference to the JavaScript function which is the event listener.

Subscribes the specified JavaScript function to the specified event.

public method getActiveXInstalled N/A

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

public method getActiveXInstalledToUpdate N/A

Verifies whether the control is installed and needed to be updated (if an earlier version of the control is already installed). If yes, it returns true; otherwise it returns false.

public method getHtml N/A

Generates the HTML code which will embed Video 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 getParam paramName - a parameter name.

Returns parameter with a specified name.

public method removeEventListener eventName - an event name.
eventListener - a name or reference to the JavaScript function which is the event listener.

Unsubscribes a specified JavaScript function from a specified event.

public method removeParam paramName - a parameter name.

Removes parameter with a specified name.

public method writeHtml N/A

Generates the HTML code which will embed Video 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
public property activeXControlCodeBase VideoUploader.cab

The URL that specifies where to download the Video Uploader control from. It is analogous to the codebase attribute of the <object> element.

public property activeXControlVersion empty string

The minimum required version of the VideoUploader.cab. If the user has an older version installed, Internet Explorer downloads the VideoUploader.cab file from the URL provided by the activeXControlCodeBase property automatically.

Important

The subversions should be separated only by commas. For example, 1,0,10,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 a help of the getVideoUploader function.

public property showNonemptyResponse off

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

  • off - no response will be shown;
  • alert - the response will be displayed in an alert window;
  • dump - the response will be displayed at the bottom of the Web page with Video Uploader.

This feature may be useful when debugging server scripts.

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 getVideoUploader ID - an ID of the control specified in the VideoUploaderWriter constructor.

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