Aurigma Video Uploader 1.0
Helper Script Reference (iuembed.js)
In this topic:
- How Does It Work
- Using Helper Script
- Debugging Video Uploader Embedding Script
- Helper Script Members
This script is used in the following way:
- Link the iuembed.js file with your HTML page.
- Create an instance of VideoUploaderWriter object (appropriate writer object exists for the ShellComboBox controls included in Video Uploader; see below for more details).
- Initialize parameters of VideoUploader control.
- Add event handlers if necessary.
- Call the writeHtml method in the necessary part of your HTML code that will embed the VideoUploader instance on the page.
- 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.
Adding Video Uploader to Page
To embed the Video Uploader in the page, you need to do at least the following:
- Create new VideoUploaderWriter class instance.
- 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:
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:
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:
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:
- 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:
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:
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:
var videoUploader1 = getVideoUploader("VideoUploader1"); videoUploader1.setUploadView(videoUploader1.getFolderView());
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:
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:
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.
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.
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.
eventName - an event name.
Verifies whether the control is installed. If yes, it returns true; otherwise it returns false.
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.
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.
|getParam||paramName - a parameter name.||
Returns parameter with a specified name.
eventName - an event name.
|removeParam||paramName - a parameter name.||
Removes parameter with a specified name.
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.
The URL that specifies where to download the Video Uploader control from. It is analogous to the codebase attribute of the <object> element.
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.
|height||N/A (provided in the constructor)||
Height of the control. You should provide an integer number. Syntax like 100% is acceptable.
|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.
Specifies whether and how Video Uploader will display a received server response. Possible values are:
This feature may be useful when debugging server scripts.
|width||N/A (provided in the constructor)||
Width of the control. You should provide an integer number. Syntax like 100% is acceptable.
|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.