jQuery TOOLS / flashembed - Adobe Flash embedding. Your future tool to place Flash objects on your pages

Motivation

Today the role of JavaScript is rising on a tremendous speed. All major browser vendors are competing with each other to make the best JavaScript engine in the world. We can expect to see more and more JavaScript widgets and goodies to appear on the market. Not just these tools. Having said that Flash technology still has an imporant role on the Internet. Especially when you want to play videos there is virtually no competition.

Flashembed is a JavaScript tool that you can use to embed Flash objects on your website. There are other tools for embedding Flash objects, but none of them offers the same flexibility and ease of use as this one. Here are the highlights:

• Simplicity. The above example was performed with this JavaScript call:
  flashembed(this, "flash_promo.swf");
  If you don't need anything special you don't have to study much.
• JSON configuration. When supplying configuration for Flash objects, the values can be complex JavaScript objects with arrays, strings, functions and other objects. as opposed to the traditional XML-based configuration, this is simpler and much more flexible. In fact this was the main reason for developing this tool.
• jQuery support. flashembed is designed with scripters in mind. A polished programming API together with support for jQuery selectors has been built-in.
• Size. Although rich in features, this plugin weighs around 5 kb when minified. This is almost half the size of our competitors.
• Demos. We have a lot of demos and each demo is documented and has a standalone version where everything redundant has been stripped off. There you can see how things can be placed on your site. Copying-and-pasting is encouraged.

This tool is a mature project and is actively maintained. Source code is clean, professional and easy to follow. It passes Douglas Crockford's JavaScript Verifier and it assigns only one global variable: flashembed. Active forums keeps this tool alive and you can expect to see new releases coming out in the future.

Flashembed and jQuery Tools

Apart from other tools this tool does not depend on jQuery. You can use it as a standalone tool for embedding Flash. The jQuery syntax is supported but not required. For this reason, this tool lacks some of the features available in other tools such as callback functions and the ability to write plugins.

This tool is also not included in the official jQuery Tools package because we want to support web standards and not promote a high level of Flash usage. At the moment, the only true exception is video playback because there are no good alternate technologies available.

Demos

We have seen that the best way to learn is through demos. Each of the following examples contain both documented source code and a standalone version of the demo that you can use to get flashembed working on your site:

• Basics of Flash embedding
• Flashembed and jQuery
• Loading Flash on mouse click
• Placing HTML on top of a Flash object
• Handling old Flash versions
• Flashembed and Flowplayer

Usage

flashembed is a function and it accepts following arguments:

flashembed(container, configuration, flashvars);

1. container identifies where the Flash object is placed on the document.
2. configuration specifies the path to the Flash object and optionally how it is embedded.
3. flashvars is an optional argument and it configures the actual Flash object.

1st argument: container

This is either a DOM element or a string representing some element's id attribute. The Flash object is placed inside this container. It's important to note that you don't have to care where you place your container on the page and where you place your flashembed call. This tool takes care of finding your container you specify.

2nd argument: configuration

The second argument specifies the path to the Flash object and optionally how it is embedded. This is either a simple string representing the path to the embedded flash object or an object that has many different configuration options including the path to the Flash object.

In case you give the second argument as an object, you can find a list of available options here. The options before the grey line are specific to flashembed and below that you can see the most popular Flash parameters that are understood by the Flash technology itself.

3rd argument: flashvars

The third argument configures the Flash object you have defined in the second argument. This is optional because not all Flash objects are not configurable. This is given as a JavaScript object as follows:

// supply configuration (flashvars) for the Flash object
flashembed("flash", "my_object.swf", {

	my_param: 'foobar',
	my_other_param: 'Hello world'

});

Flashembed has the unique feature of configuring your Flash objects with JSON. This gives you the ability to supply complex configurations directly upon embedding. JSON is a JavaScript-based syntax and is much more flexible and simpler than XML which has historically been used for Flash configuration. Here is an example of a JSON-based configuration:

flashembed("flash", "my_object.swf", {

	/*
		a JSON-based configuration variable.
		enter the modern world of Flash configuration!
	*/
	my_param: {
		my_array: [1, 2, 3], ,
		my_other_param: 'Hello world',
		nested_object: {
			another_array: ["foo", "bar", 30.3]
		}
	}

});

If you are developing a Flash object and want to configure it with JSON, you can find JSON parsers for Flash from as3corelib.

A few embedding examples

// install Flash object inside an element whose id is "flash"
flashembed("flash", "myfolder/my_flash_object.swf");

// install Flash inside a certain DOM element
var domElement = getElementById("flash");
flashembed(domElement, "my_flash_object.swf");

// tweak embedding options
flashembed("flash", {
	src: 'my_object.swf',
	allowfullscreen: false
});

jQuery support

Flashembed has support for jQuery. This means that it can work as both a standalone script or as a jQuery plugin. You can use jQuery selectors to select elements from the page and place Flash objects inside them. Here is the generic jQuery syntax for flashembed:

$("jquery_selector").flashembed(configuration, flashvars);

As you can see, there are a maximum of 2 arguments here and flashvars is optional as before. You can find information about jQuery selectors here. Here is an example that will search all DIV elements with the class name "flash" and place a Flash object inside them:

$("div.flash").flashembed("my_object.swf");

Simple and powerful.

Flashembed API

Here you can see the two different ways of accessing the Flashembed API:

// the API is returned by the flashembed call
var api = flashembed("flash", "myfolder/my_flash_object.swf");

// inside the onFail function, the "this" variable is a pointer to the API
flashembed("container", {src: 'my_object.swf', version: [9, 115], onFail: function() {

	// use API methods here
	var conf = this.getConf();

});

This API has following methods available for your use:

Static methods

Flashembed exposes three static methods for your use:

// get current flash version. returns an array [major, fix]
flashembed.getVersion();

// check if version [9, 0] is supported
flashembed.isSupported([9, 0]);

// use this when you want to perform JavaScript when the document is fully scriptable
flashembed.domReady(function()  {
	// place your code here

});

// return embedding code for a given configuration and optional flashvars
flashembed.getHTML({src: 'my_object.swf', w3c: true}, {
	param1: 'foobar',
	param2: 'baz'
});

The last method getHTML is useful when you want to generate the OBJECT tag for your Flash objects so that you don't need to use JavaScript on your pages.

Generated HTML

This chapter describes what happens "behind the scenes" and what kind of HTML is generated for the client when the Flash object is embedded. This is quite technical and if you are not interested in W3C standards you can freely skip this section.

When studying what HTML will be produced we are using the following flashembed call:

flashembed("clock", "/swf/clock.swf");

Which will generate a Flash-based clock as seen below:

This will generate the following HTML for Mozilla, Safari, Opera and Chrome:

<object data="/swf/clock.swf" type="application/x-shockwave-flash" width="100%" height="100%">

	<!-- these parameters are generated by default -->
	<param name="allowfullscreen" value="true">
	<param name="allowscriptaccess" value="always">
	<param name="quality" value="high">
</object>

This is a standards-based syntax as specified on this W3C specification. It's no surprise that Internet Explorer does not support this syntax and this browser is supplied with the following HTML instead.

<object height="100%" width="100%" classid="clsid:D27CDB6E-AE6D-11cf-96B8-444553540000">
	<param value="/swf/clock.swf" name="movie"/>
	<param value="true" name="allowfullscreen"/>
	<param value="always" name="allowscriptaccess"/>
	<param value="high" name="quality"/>
</object>

This works only in IE and not in other browers.

W3C configuration option

Flashembed comes with a W3C option that will generate a standards-based syntax that works on all browsers. This syntax is specified in this A List Apart document and you can generate similar code like this:

// enable W3C object code syntax
flashembed("clock", {src: "/swf/clock.swf", w3c: true});

The generated HTML looks like this:

<object height="100%" width="100%" type="application/x-shockwave-flash" data="/swf/clock.swf">
	<param value="/swf/clock.swf" name="movie"/>
	<param value="true" name="allowfullscreen"/>
	<param value="always" name="allowscriptaccess"/>
	<param value="high" name="quality"/>
</object>

This would appear to be a perfect solution, but there is one drawback. While every other browser is getting it right, IE/Windows is not streaming — it waits for the entire movie to download before playing it. This is fine for small movies, but for anything serious, the lack of streaming is unacceptable. This is why this flag is only suitable for standard freaks that are using small SWF files. The A List Apart document describes a workaround for this called "Flash satay" and you can read about it in the document.

Release Notes

  follow jQuery Tools on