Voynex Object Embedding Library User's Guide

Voynex Object Embedding is a cross-browser library designed to embed objects into HTML documents.

Voynex Object Embedding Library Official Page

Include JavaScript library

The Voynex Object Embedding (OE) library consists of one external JavaScript file. To use it include the library JavaScript file in the head of the HTML document:


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

The JavaScript code will be ready to use as soon as it will read. No initialization or onload event handling is needed.

Embed Objects with JavaScript

How to embed Windows Media Player, Shockwave Flash, Quicktime Player

Embedding objects with the Voynex OE library is easy and can be done with the following functions:

vxEmbedWmp - embeds Microsoft Windows Media Player 7.1 +
vxEmbedSwf - embeds Adove ShockWave Flash Object
vxEmbedQt - embeds Apple Quick Time
vxEmbedSl - embeds Microsoft Silverlight

Each of these functions has the same agruments:


		vxEmbedXxx(sId, sUrl, oParams, oAttr)

where

sId (String, Required) - specifies the id of the HTML element (containing your alternative content) which will be replaced by embedded object. The content is replaced inside the referenced HTML container.
sUrl (String, Optional) - the URL or filename of the embedded object.
oParams (Object, Optional) - object element params with name:value pairs. If the object element will fail parameters will be added as attributes of the embed element.
oAttr (Object, Optional) - additional attributes which do not depend on the object type and will be added to object and embed elements. Any attribues such as id, width, height can be defined and set using name:value pairs.

Note: The optional parameters can be omitted, as long as the parameter's order is kept. If an optional parameter is not used, but a following one do, you can simply pass null as a value of the first parameter. For the optional parameters wich are JavaScript Objects an empty object can be passed instead: {}.

How to embed other formats

It is possible to extend the library and add new functions to embed more types of objects. If the embedding of the object is supported by the browser, then this object can be embedded with Voynex OE too. See Developer's Guide for more details.

How to use JavaScript Objects to define object's params and attributes

You can best define JavaScript Objects using the Object literal notation, which looks like:


	<script type="text/javascript">

	var oParams = {
			allowScriptAccess: "always",
			allowFullScreen: true
		};
		var oAttributes = {
			id: "Player",
			width: "800",
			height: "600"
		};
		vxEmbedSwf("myContent.swf", oParams, oAttributes);
        </script>

As you can see name:value pairs are added in the definition of an object. More shorthand version of the above can be written:


	<script type="text/javascript">
		vxEmbedSwf("myContent.swf", {allowScriptAccess: "always", allowFullScreen: true}, {id: "Player", width: "800", height: "600"});
	</script>

Note: make sure not to put a comma behind the last name:value pair inside an object.

How to configure the appearance and perfomance of the embedded content

The content appearance can be configured using attributes and/or CSS.

By using the oAttr param, the following often-used optional attributes can be added:

id (Note: when undefined, the object embedding tags inherit the id of the alternative content's container).
name
width, height
styleclass (used instead of class, because this is also an ECMA4 reserved keyword)

Note: Adobe advises not to use the codebase attribute to point to the URL of the Flash plugin installer on Adobe's servers, because this is illegal according to the specifications which restrict its access to the domain of the current document only. Adobe recommends the use of alternative content with a subtle message that a user can have a richer experience by downloading the Flash plugin instead.

Configuration by means of CSS can be done using

type selectors: audio, video, object, embed. All those selectors has to be specified. Example:


		<style type="text/css">
			audio, video, object, embed {
				width: 800px;
				height: 600px;
			}
		</style>

id selector. To use it the id attribute has to be set. It can be done by via oAttr param. Example:


		<style type="text/css">
			#player	{
				width: 800px;
				height: 600px;
			}
		</style>
		<script type="text/javascript">
			vxEmbedSwf("myContent.swf", {play: true}, {id: "player"});
		</script>

class selector. To use it the styleclass attribute has to be set. Use oAttr parameter.
style attribute. Can be passed using oAttr parameter.

Note: according to the latest XHTML and HTML specifications it is recommended to use CSS rather then attributes to set the visual appearance of the HTML elements.

How to control the embedded object using JavaScript

If the object is embedded sucessfully, then vxEmbed and vxEmbedXxx functions return the JavaScript object representing the browser plug-in loaded to render the embedded data. Using that returned object it is possible to interact with the plug-in using its JavaScript API. That API is specific to the plug-in and the type of embedded object. The detailed description of the API can be found in the corresponding documentation.

If the object was not embedded (due to an error or incorrect input parameters), then null is returned.

If the id attribute is NOT set, then embedding functions always return null.

The id attribute can be set using optional oAttr param.

Examples

Embed Flash Animation

Embedding with Voynex OE is pretty simple.

1. Set dimensions of the video with a CSS declaration like this:


		#container{
			width: 640px;
			height: 480px;
		}

CSS declaration can be placed in the head of the HTML document or in the separate CSS file.

2. Add the HTML code for the alternative content which will contain the embedded object:


		<div id="container">
			Download and install flash from Adobe to view this object.
		</div>

It is important to set the id attribute of the container HTML code. The same id value is referenced in the CSS declaration and in the call the embedding JavaScript function.

3. Add the embedding JavaScript code:


		<script type="text/javascript">
			vxEmbedSwf("container", "jetfly.swf");
		</script>

To specify dimensions of the video as attributes without using CSS:


		<script type="text/javascript">
			vxEmbedSwf("container", "jetfly.swf", {}, {width: 640, height: 480});
		</script>

The code above is shorter but deprecated by HTML standards.

Embed Microsoft Silverlight

How to embed Microsoft Silverlight to HTML document and initialize the embedded object:


		<script type="text/javascript">
			var oParams = {
				minRuntimeVersion: "2.0.31005.0",
				autoUpgrade: "true",
				initParams: "m=videos/silverlight.wmv"
			}
			var oWmp = vxEmbedSl("container", "VideoPlayer.xap", oParams);
		</script>

The code above uses the most common silverlight parameters to set the minimum required runtime version, enable automatical update and inititalize the object.

Embed and Control Microsoft Windows Media Player

The code bellow shows how to embed and control YouTube Player utilising Voynex OE and access its JavaScript API:


		<script type="text/javascript">
			var oWmp = vxEmbedWmp("container", "jetfly.mpg", {uiMode: "none", EnableContextMenu: false});
		</script>

		<button type="button" onclick="oWmp.controls.play();">Play</button> 
		<button type="button" onclick="oWmp.controls.stop();">Stop</button> 
		<button type="button" onclick="oWmp.fullScreen = true;">Full Screen</button>

Embed and Control YouTube Flash Player

The example bellow shows how to embed and control YouTube Player utilising Voynex OE and access its JavaScript API.

The JavaScript API allows users to control the YouTube chromeless or embedded video players via JavaScript. Calls can be made to play, pause, seek to a certain time in a video, set the volume, mute the player, and other useful functions.

According to YouTube JavaScript Player API Reference, any HTML page that contains the YouTube player and accesses its API must implement a JavaScript function named onYouTubePlayerReady. The API will call this function when the player is fully loaded and the API is ready to receive calls.

The resulting code:


		<script type="text/javascript">
			var oSwf;
			function onYouTubePlayerReady(sPlayerId){
				oSwf = document.getElementById(sPlayerId);
			}

			var sId = "container";
			var sUrl = "http://www.youtube.com/apiplayer?video_id=3H8bnKdf654&version=3&enablejsapi=1&playerapiid=" + sId;
			vxEmbedSwf(sId, sUrl, {allowScriptAccess: "always", allowFullScreen: true});
		</script>

		<button type="button" onclick="oSwf.playVideo();">Play</button> 
		<button type="button" onclick="oSwf.stopVideo();">Stop</button>