FlashPlayer Plugin

  • Tags : audio, video, flash
  • Latest : 1.4
  • Last Updated: 30 October 2011
  • Grails version : 1.3.7 > *
  • Authors : Paul Fernley
2 votes
Dependency :
compile ":flash-player:1.4"

Documentation

Summary

Installation

Installation

Execute the following from your application directory:

grails install-plugin flash-player

The installation process creates an swf directory in the web-app directory of your application and copies various files to this swf directory. It also copies the swfobject.js JavaScript library to the js directory under the web-app directory of your application overwriting any file of the same name (users of the OpenLaszlo plugin take note!).

The installaion process also creates a movies directory in the web-app directory of your application and places a small sample Flash video file called video.flv in this movies directory. If you have your own flv video files for testing purposes, you may delete the video.flv file and the movies directory also, if you wish, since they are only for testing purposes.

Description

Flash Player Plugin

Description

The flash-player plugin provides a Grails TagLib wrapper around the JW FLV Media Player (an Adobe Flash Player which is free for non-commercial use). It dynamically embeds the flash player using the swfobject JavaScript library. The plugin includes a sample skin for the player, the Adobe expressInstall system for automatically updating a browser's Flash Player plugin version, and a proxy YouTube player.

Installation

Execute the following from your application directory:

grails install-plugin flash-player

The installation process creates an swf directory in the web-app directory of your application and copies various files to this swf directory. It also copies the swfobject.js JavaScript library to the js directory under the web-app directory of your application overwriting any file of the same name (users of the OpenLaszlo plugin take note!).

The installaion process also creates a movies directory in the web-app directory of your application and places a small sample Flash video file called video.flv in this movies directory. If you have your own flv video files for testing purposes, you may delete the video.flv file and the movies directory also, if you wish, since they are only for testing purposes.

Usage

Assuming you will test the flash-player plugin using the sample Flash video file called video.flv in the movies directory created during installation, then getting the video to play is a three step process...

Firstly, in the <head> section of your GSP, include the swfobject JavaScript library with the following tag:

<g:javascript src="swfobject.js"/>

The swfobject library is responsible for creating the objects in memory that are needed to play the video and, in the case of the Adobe Flash Player browser plugin itself, ensuring that it is an acceptable version, updating it if it is not.

Secondly, in the body of the page we need to create an HTML element (usually a <div>, <span> or <p>) that will contain the alternative content if the user's browser does not have the Adobe Flash Player plugin or does not have JavaScript enabled. If the user's browser does have the Flash Player plugin and JavaScript enabled, the contents of this element will be replaced by the player. We will use a <div> for our alternative content element:

<div id="test">
  <p>You need <a href="http://www.adobe.com/go/getflashplayer">Flash Player</a>
     installed and JavaScript enabled to play this media.</p>
</div>

In the above example, the contents of the <div> will be replaced by the player if the user's browser has the Adobe Flash Player plugin and JavaScript enabled. Otherwise, the user will be shown the alternative content which explains the problem and provides a link for them to get the Adobe Flash Player browser plugin. In real life, our <div> element would probably be given additional attributes to allow for enhanced formatting and positioning of the content (usually via css), but our example uses the bare minimum. We must have an id and, if there is to be more than one player on the same HTML page, each id must be unique within that page.

Thirdly, just underneath the HTML element that is to hold the player (the <div> from our previous example), we place the tag provided by this flash-player plugin:

<div id="test">
  <p>You need <a href="http://www.adobe.com/go/getflashplayer">Flash Player</a>
     installed and JavaScript enabled to play this media.</p>
</div>
<g:flashPlayer id="test"
               varFile="${resource(dir: 'movies', file: 'video.flv')}"/>

The above <g:flashPlayer.../> tag requires at a minimum two attributes: the id of the alternative content HTML element in which it is to place the player ('test' in our example) and the location of the file that is to be played (video.flv in the movies directory in our example).

When the HTML page is displayed to the end user, one of three things will happen: 1) they will be shown the alternative content asking them to install Adobe Flash Player and ensure that their browser has JavaScript enabled; 2) if all is well with their browser, but the the version of the Adobe Flash Player they have is too old, they will see an image asking the to click it to update their browser(s) plugin; 3) the movie player will appear.

Tag Attributes

Confusingly, there are four independent sets of attributes that can be used with the <g:flashPlayer.../> tag: 1) arguments to the swfobject.js library to tell it what object to create in memory and how; 2) attributes that the swfobject.js library should apply to the object it created in the preceding point; 3) flashvars that player.swf file needs to configure itself and 4) parameters to be passed to the Adobe browser plugin. To add to the misery, various of these attributes can conflict, can differ from player to player, and can change over a period of time. On the bright side, the arguments to the swfobject.js library are fairly fixed and are relatively straightforward, so we will deal with those first (note that in the following table, 'myApp' refers to the name of your Grails application):

AttributeDescription
idThe id of the 'alternative content' HTML element where the player is to go. There is no default for this and so a value must be supplied that matches the id of an alternative content HTML element.
widthThe width of the player in pixels. The default is 425. Note that if you intend to use the expressInstall system (described below), the minimum width should be 310.
heightThe height of the player in pixels. The default is 355. Note that if you intend to use the expressInstall system (described below), the minimum height should be 137.
playerThe name and location of the player.swf file. Defaults to /myApp/swf/player.swf. Note that this parameter means that you are not limited to using the JW FLV Media Player but can substitute a player of your own choosing.
versionThe minimum version of the Adobe Flash Player browser plugin needed to play the media. Defaults to "10". You can specify just the major version (as in "10"), the major and minor version (as in "10.0") or the major and minor versions plus the release (as in "10.0.12").
expressInstallIf the the user's Adobe Flash Player browser plugin does not meet the minimum version specified above, you can give the user the opportunity to upgrade it and then continue with playing the chosen media. The default for the expressInstall attribute is /myApp/swf/expressInstall.swf. If you do not wish to give the user the opportunity to upgrade their browser plugin, you can set this to an empty string, as in expressInstall="".

Note that you can set configuration variables in Config.groovy to replace the defaults on all of the above - except the id tag attribute, of course - with values of your own choosing. For example, to change the standard width and height defaults and to change the player to something other than the supplied JW FLV Media Player, you would enter configuration entries such as:

swf.width=200
swf.height=200
swf.player="/myApp/myDir/myPlayer.swf"

Note that if you wish to set the default required browser plugin version in Config.groovy, the value is a String (such as swf.version="9.5") not a number.

Since there are three remaining sets of tag attributes (flashvars, Adobe plugin parameters and attributes to the in-memory object), and since these vary from player to player and from version to version AND can potentially have naming conflicts with one another, we need some way of generically specifying which of the three sets of tag attributes we are refering to. We do this by convering the fist character of the attribute to upper case and then adding on a prefix ('var' for flashvars, 'param' for Adobe plugin parameters and 'attrib' for in-memory object attributes). We have already seen an example of this above...

The JW FLV Media Player has the name of the media file it is to play passed to it as a flashvar with a name of 'file'. Consequently, within the flashPlayer tag, we use the following attribute: varFile="${resource(dir: 'movies', file: 'video.flv')}". Note the tag attribute name is varFile (var because it is to be passed as a flashvar and File because it is a flashvar parameter called file). Another interesting flashvar (at least with the JW FLV Media Player) is: varSkin="${resource(dir: 'swf', file: 'snel.swf')}". This sets a new skin for the player. Player skins are available for free on the JW FLV Media Player web site and one, snel.swf, is included with this flash-player plugin. The full list of flashvars that the player recognizes is also available on their web site - just remember to capitalize the first letter and prefix it with 'var' (e.g. varAutostart="true" etc).

When the swfobject.js library creates the in-memory object to actually play the media you have specified, you may give that object certain attributes. The commonest are id and name which can then be used by other JavaScript code to access the object and interact with it. Again, just remember to use the correct prefix (i.e. id becomes attribId, name becomes attribName and so forth). Refer to the w3schools web site for more details of object attributes.

Finally, there are parameters that can be passed to the Adobe Flash Player plugin and these can be found in the Adobe Flash Player documentation. There is also a brief overview on the swfobject web site. Remember to add the prefix param (as in paramAllowScriptAccess="always" etc).

Limitations

The JW FLV Media Player is free for non-commercial use. For commercial use please refer to the JW web site for licensing information. At the time of writing commercial licenses started from 30 Euros.

Compatibility

This plugin was written using Java version 1.6u18 and Grails version 1.3.0. The plugin includes the JW FLV Media Player version 5, the swfobject.js library version 2.1 and was tested with the Adobe Flash Player browser plugin version 10.0.12.

History

Version 1.3. (2010-05-12) Update to Grails v1.3

Version 1.2. (2009-12-30) Update to Grails v1.2

Version 1.1. (2009-03-31) Update to Grails v1.1

Version 1.0. (2008-10-27) Initial release