This document introduces you to the basics of Flowplayer scripting. The following items are covered.
When Flowplayer is set up with an initial splash image (or any other HTML content) as follows:
The player is not loaded until the containing wrapper element is clicked.
Before that Flowplayer API is not fully usable and you cannot use all of the
available API methods. Most notably you don't have access to plugins. If you
want to do things right after player is loaded you have to place your
onLoad event in configuration or you can do it
programmatically as in here.
You can add as many onLoad handlers as you want. Another way of
loading is to do it programmatically using an API call
function accepts a function argument that will be called when player
is loaded. Here is an example.
Click on the player to see onLoad in action. Below the video is the embedding script.
As you saw it was possible to add this
onLoad function into the
player before the actual Flash component is embedded into the
page. The same goes for other event listeners as well. This way all
player is loaded.
Here is a full list of functions that can be called before player is loaded.
registering event listeners:
onLoad, onStart, onFinish, onCuepoint ...
access to clips and playlists:
these API methods:
id, getVersion, load, isLoaded, getState, play
Flowplayer function returns a handle to the player instance when it is installed
When you have a player instance in your hands you'll have an access to
its programming interface (API) which is documented
here. So for example if you want to make a HTML
button that uses api method
pause you'll write following code.
You can also retrieve players after they have been created in following ways
BTW: these players were installed by the following jQuery fuelled code. More about using jQuery later.
Accessing all players
If you want to do operations to all players you can use a special
$f("*") call that works as follows:
Players have id's
player2 respectively. If
you have Firebug command line in your
hands you can play with all available API methods against these player
Most of the time you will supply your event functions to upon
configuration. That is the easiest way. However
here we discuss about adding event listeners using Flowplayer API. It
allows you to add multiple listeners of the same event type such as
onStart. This makes it possible to have many scripts and plugins
that don't know about each other to add their own event listeners
wihtout disturbing each other.
In this example we will get our player and add
listener to the common clip.
Of course you can do lot's of usefull stuff inside event functions other than this silly example. You can send notification to Google Analytics, launch plugins, manipulate surrounding HTML document (DOM), use powerfull libraries such as jQuery, communicate with server using AJAX… it's all about your imagination (and coding skills).
Here is an example listener that will send a notification to Google Analytics that a clip was started.
And here is an example that will make the player more visible on the
page using our
This was just a very brief introduction to events and there are milloins of way you can use them. Full list of events is given here.
Using Flash plugins
Flash plugins are usually loaded upon
configuration. You can also load them
loadPlugin method as follows.
Loading plugin dynamically
This is how plugin loading was achieved. We used cuepoints to do the timing.
This way you will download the plugin only when it's really needed. In typical
scenario you want to show suggestions to other video clips at the end of the
clip. You have a specific suggestions plugin for that task and by using
loadPlugin method at clip's
onFinish event you will only load it if clip is
really watched to the end.
When you have configured your player with plugins you'll use
method to access them. In this example our plugin is configured in the player
and it is shown on the first second of the playback
Just some talk. As you may have noticed Flowplayer API is not just a flat list of functions. We have objects with methods and those methods can return other objects. And all the time we are communicating with a real Flash object. This kind of programming has not been very common in Flash world.
In previous example we used
fadeIn method to change plugin's
transparency, but you are allowed to change multiple display
properties in the same
way and at the same time. Here is a simple example.
If you want to do something after animation finishes you can supply a
callback function as third argument. (Or second argument if you are
happy with the default speed
There are example animations in our demo page.
Any flash component as plugin
It's very interesting to realize that you can use any displayable
Flash component that is coded with ActionScript 3 as a Flowplayer
plugin. Here is an example of a random swf file
clock.swf I found
from the net.
methods are documented in Plugin's own documentation. Our content
plugin for example has a public method called
setHtml which will
replace current HTML with a new one. You can call that method just
like any other plugin's method. It is really that simple!
In this example we will call
setHtml method anytime user moves her
mouse over and out of the video screen.
All content plugin's methods are documented here.
Here are some examples that show you the possibilities what you can do with jQuery.
jQuery has a fantastic query language that you can use to select elements from the page. Flowplayer has a support for that language and here are some examples.
jQuery makes it easy to make AJAX calls in cross- browser manner. Here are few examples.
Here we use AJAX to load following flowplayer configuration from the server.
Here is the working example and after that you can see how this all is accomplished using jQuery. We should see a green background gradient in the canvas.
Under tricks and tips you'll see an alternate way of loading external configuration without jQuery.
Tricks and tips
Waiting for the DOM to load
test variable to be
null because the
DIV has not been loaded
at the time the script is run. A (poor) workaround for this is following:
A major drawback in
window.onload is that it is the last function called
after everything else has been downloaded, including images. Secondly
there can be only one load event on the page. Here are two good solutions.
It is recommended that you wrap all your scripts that you want to execute upon page load inside previous code blocks. You will find more about this important topic from here.
flowplayer function takes care of these issues automatically so
following will work
This was implemented so that our installation documents are easier to gasp. However it is recommended to use those previous domReady functions so that every other script on your page will work correctly.
Overriding click action
Sometimes you want something cool to happen when user clicks on the splash image before starting the playback. In this jQuery example we will make a custom animation to the container before loading the player.
Here is this code in action.
You can also override click action without jQuery by using standard
Sometimes you may find yourself confused with those dollar signs all
over the place. Remember that instead of
$f you can always use
flowplayer and instead of
$ you can use
jQuery. This makes your
code more readable but you have to make more typing.