deconcept

STOP! Don't use this. You are probably looking for SWFObject instead!

FlashObject: Javascript Flash detection and embed script

FlashObject is a small Javascript file used for embedding Macromedia Flash content. The script can detect the Flash plug-in in all major web browsers (on Mac and PC) and is designed to make embedding Flash movies as easy as possible. It is also very search engine friendly, degrades gracefully, can be used in valid HTML and XHTML 1.0 documents*, and is forward compatible, so it should work for years to come.
* Pages sent as text/html, not application/xhtml+xml.

Table of Contents

What's new in this version?

For a full list of changes, please see my FlashObject 1.3 blog post.

How it works

[For the über nerds, you can view the raw javascript here.]

Using FlashObject is easy. Simply include the flashobject.js Javascript file, then use a small amount of Javascript on your page to embed your Flash movie. Here is an example showing the minimum amount of code needed to embed a Flash movie:

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

<div id="flashcontent">
  This text is replaced by the Flash movie.
</div>

<script type="text/javascript">
   var fo = new FlashObject("movie.swf", "mymovie", "200", "100", "7", "#336699");
   fo.write("flashcontent");
</script>

Here is a breakdown of what the code does:

<div id="flashcontent">[...]</div>

Prepare an HTML element that will hold our Flash movie. The content placed in the 'holder' element will be replaced by the Flash content, so users with the Flash plug-in installed will never see the content inside this element. This feature has the added bonus of letting search engines index your alternate content.

var fo = new FlashObject("movie.swf", "mymovie", "200", "100", "7", "#336699");

Create a new FlashObject and pass in the required parameters:

  • swf - The file path and name to your swf file.
  • id - The ID of your object or embed tag. The embed tag will also have this value set as it's name attribute for files that take advantage of swliveconnect.
  • width - The width of your Flash movie.
  • height - The height of your Flash movie.
  • version - The required player version for your Flash content. This can be a string in the format of 'majorVersion.minorVersion.revision'. An example would be: "6.0.65". Or you can just require the major version, such as "6".
  • background color - This is the hex value of the background color of your Flash movie.

Optional parameters are:

  • useExpressInstall - If you would like to upgrade users using the ExpressInstall feature, use 'true' for this value.
  • quality - The quality you wish your Flash movie to play at. If no quality is specified, the default is "high".
  • xiRedirectUrl - If you would like to redirect users who complete the ExpressInstall upgrade, you can specify an alternate URL here
  • redirectUrl - If you wish to redirect users who don't have the correct plug-in version, use this parameter and they will be redirected.
  • detectKey - This is the url variable name the FlashObject script will look for when bypassing the detection. Default is 'detectflash'. Example: To bypass the Flash detection and simply write the Flash movie to the page, you could add ?detectflash=false to the url of the document containing the Flash movie.
fo.write("flashcontent");

Tell the FlashObject script to write the Flash content to the page (if the correct version of the plug-in is installed on the user's system) by replacing the content inside the specified HTML element.

The Details

FlashObject works quietly in the background of your HTML document. When developing pages that use FlashObject, you should start with your alternate (non-Flash) content first. Get your pages working without your Flash movies, then add them in later with little Javascript snippets that replace your alternate content with the Flash movies. This ensures that the alternate content will be indexed by search engines, and that users without the Flash plug-in will still see a working HTML page. Whether you provide upgrade instructions or not is up to you. If your alternate content can suffice, there may be no reason at all to tell people they are missing out on Flash content.

FlashObject works in all the current web browsers, including, on PC: IE5/5.5/6, Netscape 7/8, Firefox, Mozilla, and Opera. On Mac: IE5.2, Safari, Firefox, Netscape 6/7, Mozilla, and Opera 7.5+, and should continue to work well into the future.

FlashObject detects Flash player versions in these browsers from version 3 and up, and will allow users to interactive with your Flash content without 'activating' it first. For more information on this, see this blog post on the Internet Explorer Eolas patent dispute.

FlashObject can detect minor versions and revision versions of the Flash Player as well, simply by passing the string value of the version you want. An example of requiring Flash player v.6.0 r65 (or 6,0,65,0) would be:

var fo = new FlashObject("movie.swf", "mymovie", "200", "100", "6.0.65", "#336699");

FlashObject's built in plug-in detection can be bypassed. If a new browser is ever launched or for some reason the plug-in detection fails on a user's system, you can include a bypass link that will disable the detection built into FlashObject, and it will always write the Flash content to the page. To use the bypass link, simply link to the page with your Flash content on it, and include a single url variable called 'detectflash' and set it to 'false.' Here is an example of what that link would look like:

<a href="mypage.html?detectflash=false">Bypass link</a>

FlashObject Examples

The example given above is what you need for the bare bones use of FlashObject, but what if you want to use some of the other parameters the Flash plug-in has to offer? FlashObject makes it very easy to add any extra parameter you may need. The examples below are a number of different methods you may wish to use to embed your Flash content.

A simple example adding a few extra parameters

<script type="text/javascript">
   var fo = new FlashObject("movie.swf", "mymovie", "200", "100%", "7", "#336699");
   fo.addParam("quality", "low");
   fo.addParam("wmode", "transparent");
   fo.addParam("salign", "t");
   fo.write("flashcontent");
</script>

Here is a full list of the current parameters and their possible values on macromedia.com.

Passing variables into your movies using the "Flashvars" parameter:

Using Flashvars is the easiest way to get data from your HTML into your Flash movie, but you can only pass the data in when your movie first loads. Normally, you would add a parameter called "flashvars" and then for the value, you passing a string of name/value pairs like this: variable1=value1&variable2=value2&variable3=value3 and so on. FlashObject makes this a bit easier by allowing you to add as many variables as you like in a similar manner in which you add additional parameters. Here is an example of passing values into your Flash movie using Flashvars:

<script type="text/javascript">
   var fo = new FlashObject("movie.swf", "mymovie", "200", "100", "7", "#336699");
   fo.addVariable("variable1", "value1");
   fo.addVariable("variable2", "value2");
   fo.addVariable("variable3", "value3");
   fo.write("flashcontent");
</script>

Once this is done, all of the variables you pass in will be available immediately inside the Flash movie. Just access them as you would any variable on the _root timeline.

The FlashObject script also comes with an extra function which allows you to pull variable values from the url string. An example is you have a url that looks like this: http://www.example.com/page.html?variable1=value1&variable2=value2. Using the function getQueryParamValue() you can easily pull these values from the url and then pass them into your Flash movie. Here is an example, we'll assume that the url looks like the above example:

<script type="text/javascript">
   var fo = new FlashObject("movie.swf", "mymovie", "200", "100", "7", "#336699");
   fo.addVariable("variable1", getQueryParamValue("variable1"));
   fo.addVariable("variable2", getQueryParamValue("variable2"));
   fo.write("flashcontent");
</script>

The getQueryParamValue() function also supports reading variables from the location.hash, as used sometimes when deep linking into your Flash applications. For an example of how deep linking to your Flash movies using the location.hash variable, check out this demo of Slideshow Pro, which uses the FlashObject embed.

Using Express Install with FlashObject

FlashObject has full support for the Macromedia Flash Player Express Install feature. Included with the FlashObject script is an actionscript file that works with FlashObject to start the upgrade process in your Flash movies. Your users never have to leave your site to upgrade their player, and when the upgrade is complete, they will be redirected back to the page that started the upgrade.

To use ExpressInstall, you must first include the expressinstall.as file in your fla and at the start of your movie do a simple check to see if the user needs to be upgraded:

#include "expressinstall.as"

// initialize the ExpressInstall object
var ExpressInstall = new ExpressInstall();

// if the user needs to upgrade, show the 'start upgrade' button
if (ExpressInstall.needsUpdate) {

	// this is optional, you could also automatically start the
	// upgrade by calling ExpressInstall.init() here instead of the following lines

	// attach the custom upgrade message and center it
	var upgradeMsg = attachMovie("upgradeMsg_src", "upgradeMsg", 1);
	upgradeMsg._x = Stage.width / 2;
	upgradeMsg._y = Stage.height / 2;

	// attach the button actions that will start the ExpresInstall updater
	upgradeMsg.upgradeBtn.onRelease = function() {
		// the ExpressInstall.init() method is what kicks off the actual update
		ExpressInstall.init();
	}
	// if expressinstall is invoked, stop the timeline.
	stop();
}

It's important to not place any content on the first frame (or wherever your ExpressInstall check happens) that requires Flash player 7 or higher.

For a 'live' example of this code, open the source/fo_tester.fla included in the FlashObject zip file. Or, if you want to see ExpressInstall in action, you can install Flash player 7 (or 6.0.65) and visit this page.

If your Flash movie is in a popup window, or you wish to redirect the user to a different location after they complete the ExpressInstall update, you can use the xiRedirectUrl attribute to redirect the user back to your landing page instead of the actual page with your Flash movie.

<script type="text/javascript">
   var fo = new FlashObject("movie.swf", "mymovie", "200", "100", "8", "#336699", true);
   fo.setAttribute('xiRedirectUrl', 'http://www.example.com/upgradefinished.html'); // must be the absolute URL to your site
   fo.write("flashcontent");
</script>

Download

FlashObject is released under the MIT License. This means (basically) that you can use it for whatever you want with no restrictions.

Download FlashObject 1.3 - Zip file, includes flashobject.js and the example html templates below.

Or, if you are more of a hands on type, you can view my example pages:

* Pages are sent as text/html, not application/xhtml+xml.

While you're at it, you may want to sign up for the FlashObject mailing list. This list is a discussion list for asking questions about problems you might be having using FlashObject or to request and discuss new features.

Why it's is better than the rest

Over the years there have been many methods to detect Flash player versions and embed Flash movies into HTML documents. This section will take a look at each of the most popular methods and point out the problems with each.

1) The default Macromedia provided embed

Everyone knows the default Macromedia provided Flash embed. It consists of an Object tag with an Embed tag placed inside as a fallback mechanism. This is the most popular Flash embed method and is the default choice when publishing your Flash movie from the Macromedia Flash IDE. This is the most compatible way to embed a Flash movie, and will work in the widest range of browsers. Here is a sample of the default Flash embed code:

<object classid="clsid:d27cdb6e-ae6d-11cf-96b8-444553540000"
   codebase="http://fpdownload.macromedia.com/pub/shockwave/cabs/flash/swflash.cab#version=7,0,0,0"
   width="550" height="400" id="Untitled-1" align="middle">
<param name="allowScriptAccess" value="sameDomain" />
<param name="movie" value="mymovie.swf" />
<param name="quality" value="high" />
<param name="bgcolor" value="#ffffff" />
<embed src="mymovie.swf" quality="high" bgcolor="#ffffff" width="550"
   height="400" name="mymovie" align="middle" allowScriptAccess="sameDomain"
   type="application/x-shockwave-flash" pluginspage="http://www.macromedia.com/go/getflashplayer" />
</object>

While this is the most common method of embedding your Flash movies, it does have a few issues.

  • There is noplug-in detection. - With no plug-in detection, users may see broken or no content, and if there is no plug-in installed at all, they will either get the 'ActiveX install' dialog box on IE —a box many users now fear because of rampant spyware and malware— or the 'strange puzzle piece' box in Mozilla based browsers. Neither of these plug-in install systems are very user friendly, and usually don't explain themselves very well as to what exactly a user is installing.
  • With changes from the Eolas patent dispute, users will have to first click on your Flash content to 'activate' it before interacting with it. More info here.
  • It is not valid HTML or XHTML - There is no such thing as an embed tag in any version of HTML or XHTML. However, since many browsers handle object tags differently (or not at all, or the implementation is too buggy), the embed tag was needed as a fallback mechanism.

2) Object tag only / Flash satay

This method gained popularity after the A List Apart article came out back in 2002. Here are two examples of 'object tag only' embedding and Flash satay:

'Object tag only'

<object classid="clsid:D27CDB6E-AE6D-11cf-96B8-444553540000"
   codebase="http://download.macromedia.com/pub/shockwave/cabs/flash/swflash.cab#version=6,0,40,0"
   width="300" height="120">
 <param name="movie" value="http://www.macromedia.com/shockwave/download/triggerpages_mmcom/flash.swf">
 <param name="quality" value="high">
 <param name="bgcolor" value="#FFFFFF">
 <!--[if !IE]> <-->
 <object data="http://www.macromedia.com/shockwave/download/triggerpages_mmcom/flash.swf"
		 width="300" height="120" type="application/x-shockwave-flash">
  <param name="quality" value="high">
  <param name="bgcolor" value="#FFFFFF">
  <param name="pluginurl" value="http://www.macromedia.com/go/getflashplayer">
  FAIL (the browser should render some flash content, not this).
 </object>
 <!--> <![endif]-->
</object>

Flash satay

<object type="application/x-shockwave-flash
data="c.swf?path=movie.swf"
width="400" height="300">
<param name="movie"
value="c.swf?path=movie.swf" />
<img src="noflash.gif"
width="200" height="100" alt="" />
</object>
  • Accessibility issues. - Using Flash Satay, some screen readers (like JAWS) will ignore your Flash content.
  • With changes from the Eolas patent dispute, users will have to first click on your Flash content to 'activate' it before interacting with it. More info here.
  • There is noplug-in detection. - Same as above - With no plug-in detection, users may see broken or no content. When the Flash player encounters a Flash movie embedded in a page, it will try to play it no matter what the version is. So if you have Flash player 6 installed, and encounter a Flash 7 movie, your plug-in will try to play it, possibly causing odd behavior.
  • Some methods of Flash satay don't stream the Flash movie to the player - So this method may require 'holder' swf movies that your movie is loaded in to. This makes passing variables from FlashVars parameters a hassle and make it a pain to maintain Flash content as you now have twice as many swf files floating around your web server.
  • Older Safari versions ignore param tags - Up until version 2.0 (on Tiger) or 1.3 (on Panther) and possibly 1.2.8 (pre Panther) Safari would completely ignore the param tag. This meant that if you tried to set other options using them, like Flashvars or Align, Salign, etc. Safari would not see those values.

3) Detection: The 'small flash movie on the index page' method

This method involves placing a single Flash movie on the index page of your website, and this Flash movie then checks the $version variable in the Flash player and redirects the user either to the Flash content inside the site, or an upgrade page.

Problems with this method include:

  • There is noplug-in detection on internal pages. - If a user sends an internal url to another user, that new user bypasses the Flash detection on the index page.
  • With changes from the Eolas patent dispute, users will have to first click on your Flash content to 'activate' it before interacting with it. More info here.
  • It is not valid HTML or XHTML - Again, the embed tag required to place the Flash movies in your HTML documents will not validate.
  • Hurts your search engine ranking - Since you are now using your index page as an empty Flash detection page, when people search for you in Google or other search engines, often the description text ends up showing up as "Detecting Flash Player" or even no description at all. This is a huge waste of prime website real estate that should be used to promote your company or products. Often times developers will not include a link to the other content in the site (since the Flash movie contains the links) so the rest of the site won't be indexed either.

4) The Macromedia Flash Player Detection Kit

Macromedia has done an excellent job with the new Flash 8 detection kit - but not quite excellent enough. It contains two different ways to detect the Flash plug-in:

  1. The classic "small Flash movie on the index page" - (See above)
  2. Javascript - Yes, that's right, Flash now includes a Javascript plug-in detection template. Unfortunately, it's very not very user friendly at all, mixing Javascript, VBscript, and all your HTML all into one page. This has many of the drawbacks as past Javascript detection and embed techniques, and doesn't do anything to make your life easier as a Flash/HTML developer. And it doesn't validate as XHTML or HTML (If you care about that sort of thing).

I've put together a more in-depth look at the Macromedia detection kit over here.

5) Use raw Javascript to detect and embed your movies

It's hard to critique this method as it usually varies from site to site. However, most Javascript Flash detection schemes I have come across generally suffer from the same faults:

  • Unreliable plug-in Detection - Often the detection only works with current versions of the Flash player, and needs to be manually updated as new versions of the plug-in are released.
  • Adds more code to the page - Making it even harder to update or change your content. This method also makes it harder for designers or other people that may be working with your pages to change or add Flash movies.
  • An overly complicated solution - Many Flash embedding scripts can grow to large file sizes or be overly complicated. FlashObject is designed to be simple and small.

FAQ

Q. What is this Internet Explorer 'Active Content Update' I've been hearing about, and does FlashObject fix it?
A. The short answer is yes, FlashObject will fix the 'Activating Active Content' issues in the new IE Update. You read more about the subject here.
Q. Why does my alternate content flicker quickly on the screen before my Flash content loads? (only happens in IE on Windows)
A. This seems to be related to the FOUC bug. It can be fixed by adding a link tag in the head of your document to any stylesheet.
Q. How can I make FlashObject work in Netscape 4.x?
A. This comment has some example code that you can use to make FlashObject work in Netscape 4.x.
Q. Can I use FlashObject with my Blog?
A. Yes, there are a couple of plug-ins for Wordpress and Textpattern here.
Q. Can I use FlashObject with Dreamweaver or Golive?
A. There is a Dreamweaver extension available at CommunityMX. There is currently no Golive extension, but if you would like to make one, I'll gladly link it up from this page. You should be able to use the FlashObject script without an extension, but the extension should make it much easier.
Q. Is this page available in other languages?
A. Here is a French translation of parts of this page, a Swedish translation, Italian, and here is a Finnish translation. If anyone would like to translate this page into other languages, I would be happy to post a link here.
Q. Who uses FlashObject?
A. Websites like The Library of Congress, windows.com, skype.com, youtube.com, snapple.com, it is included with Adobe Photoshop (in the Flash web photo galleries) and thousands of others. Colin Moock also suggests it as an alternative to the Macromedia Detection kit.

Still having problems? Try reading through the previous FlashObject posts [1, 2, 3] on this blog (especially the comments), as many common questions have been covered there.

Thanks

Toby Boudreaux gave me tons of advice, helped make the code for FlashObject much cleaner and name spaced it all at the same time.

Powered by WordPress