The JavaScript API

SWFObject 2 contains an API that enables JavaScript developers to reuse its internal functions like a box of Lego toys. In total, 11 methods are available. In the static and dynamic publishing sections above, I have already shown you two of them; and in this section, I will discuss five new methods.

Retrieving Flash Player version info

The swfobject.getFlashPlayerVersion method returns a JavaScript object that contains the major, minor, and release version numbers of an installed Flash Player.

Note: A version string like WIN 9,0,124,0 as retrieved with ActionScript from within Flash is formatted as OS major,minor,release,build.

The following lines of JavaScript code in the head of your web page will show an alert box indicating your Flash Player version:

<script type="text/javascript" src="swfobject.js"></script>
<script type="text/javascript">
var playerVersion = swfobject.getFlashPlayerVersion();
var output = "You have Flash player " +
playerVersion.major + "." + playerVersion.minor + "." +
playerVersion.release + " installed";
alert(output);
</script>

If you browse to the example_3 folder and open index_getflashplayerversion.html in your web browser, you will see an alert like Figure 8.

Figure 8. Alert showing the current version of Flash Player installed

Creating a SWF file the non-automatic way

The swfobject.createSWF method exposes SWFObject's internal cross-browser function to create a SWF file dynamically. This "low level" dynamic publishing method can be very useful when combining it with other JavaScript libraries. It has three required arguments:

1. attObj is a JavaScript object that contains the name-value pairs of the object element's attributes and values.
2. parObj is a JavaScript object that contains the name-value pairs to define nested param elements.
3. replaceElemIdStr is the id attribute of the HTML element that you want to have replaced by your SWF.

Note: You should omit the classid, type, or codebase attributes and movie param element.

The method returns the newly created HTML object element that represents your SWF. Be ware that you should only call this method when the DOM of a web page is available (Tip: use the swfobject.addDomLoadEvent method).

It is wise to always use the swfobject.hasFlashPlayerVersion(versionStr) method in tandem with swfobject.createSWF to ensure that the required minimal Flash Player version is available. The versionStr argument can be formatted as such: "major.minor.release" or "major".

You can use the following lines of JavaScript code in the head of your web page to dynamically embed a SWF file:

<script type="text/javascript" src="swfobject.js"></script>
<script type="text/javascript">
window.onload = function() {
    if (swfobject.hasFlashPlayerVersion("9")) {
        var att = { data:"test.swf", width:"300", height:"120" };
        var par = { menu:"false" };
        var id = "myAlternativeContent";
        var myFlashContent = swfobject.createSWF(att, par, id);
    }
};
</script>

If you browse to the example_3 folder and open index_createswf.html in your web browser, you will see your test SWF file. It will look just like the first instance you saw (Figure 2).

Removing SWFs from a loaded page

The swfobject.removeSWF method helps to safely remove a loaded SWF file from a web page to avoid broken references and avoid memory leaks in Internet Explorer. Simply pass in the id of the object element with which the SWF file is associated and voila! The following code snippet contains the JavaScript code used in index_removeswf.html from the example_3 folder:

<script type="text/javascript" src="swfobject.js"></script>
<script type="text/javascript">
var flashvars = {};
var params = {};
var attributes = { id:"myFlashContent" };
swfobject.embedSWF("test.swf",
"myAlternativeContent", "300", "120",
"9", false, flashvars, params, attributes);
 
function addClickHandler() {
   
document.getElementById("remove").onclick = function() {
        if (document.getElementById("myFlashContent")) {
           swfobject.removeSWF("myFlashContent");
        }
        return false;
    };
}
window.onload = addClickHandler;
</script>

When you click the link in this example your SWF file will be removed from your web page (see Figure 9).

Figure 9. Displaying the Remove SWF link below the SWF file

Grabbing parameters from the URL query string and passing them to your SWF file

The swfobject.getQueryParamValue(paramStr) method returns the value of the paramStr parameter in the URL query string or hash string. This method is often used in tandem with FlashVars to pass values from the query string into your SWF, for example:

<script type="text/javascript" src="swfobject.js"></script>
<script type="text/javascript">
var flashvars = {};
if (swfobject.getQueryParamValue("name1")) {
    flashvars.name1 = swfobject.getQueryParamValue("name1");
}
var params = {};
var attributes = {};
swfobject.embedSWF("test_flashvars.swf",
"myAlternativeContent", "300", "120",
"9.0.0", false, flashvars, params, attributes);
</script>

If you browse to the example_4 folder and open index_getqueryparamvalue.html in your web browser, you will see the SWF file showing the names of the FlashVars, as shown in Figure 10.

Figure 10. Displaying the SWF file with FlashVar names showing

When you append the following string to the query string in the location bar of your web browser:

?name1=getQueryParamValue&name2=is&name3=cool!

And press Return, you will see the SWF file updated to show the values added to the FlashVars.

To secure the method from possible cross-site scripting abuse, SWFObject 2 will encode the returned value—using the JavaScript encodeURIComponent function—if the query string includes one of the following characters: [\"<>.;]

Where to go from here

This tutorial should have given you a good overview of how you can use SWFObject 2 to embed SWF files into HTML pages. For further reading, I recommend the following resources:

• SWFObject 2 wiki on Google Code for documentation and examples
• Providing alternative content for SWF files
• Flash Embedding Cage Match

If you have any questions about SWFObject 2 or have problems with an implementation, please consult the SWFObject 2 FAQ or use the SWFObject 2 Discussion Group.

Page 6 of 6

Previous Page