[[PlayerToc(flash)]]

= JW Player: API Calls =

The 4.0 version of the player for Flash supports an extremely flexible API, both externally (for [http://en.wikipedia.org/wiki/JavaScript javascript]) and internally (for [wiki:PluginsBuilding plugins], that can be  built in [http://en.wikipedia.org/wiki/ActionScript actionscript]). It is possible to read the config/playlist variables of the player, send events to the player and assign functions as listeners. Plugins can also access specific calls/variables of one another. A small initialization routine is needed to connect your apps to the player.

== Initialization ==
 
=== Javascript ===

Please note that the player will NOT be available the instant your HML page is loaded and the first javascript is executed. The SWF file (40k) has to be loaded and instantiated first! You can catch this issue by defining a simple global javascript function. It is called playerReady(obj) and every player that's succesfully instantiated will call it. The 'obj' object will contain the ''id'', ''version'' and ''client'' of the player, so you immediately know what player it is an where to subscribe to. Use the ''id'' variable to get a reference to the player itself. Example:

{{{
var player;
function playerReady(obj) {
	alert('the videoplayer '+obj['id']+' has been instantiated');
	player = document.getElementById(obj['id']);
};
}}}

If you are not interested in calling the player when the page is loading, you won't need this function. You can then simply use the ID of the embed/object tag that embeds the player to get a reference. A simple getElementById() function will do the trick, so it can be called. This function needs the ID of the object/embed tag as a reference. So for example with this embed tag:

{{{
<embed id="myplayer" name="myplayer" src="/upload/player.swf" width="400" height="200" />
}}}

You can get a pointer to the player with this line of code:

{{{
var player = document.getElementById('myplayer');
}}}

'''Note you must add both the id and name attributes in the <embed> in order to get back an ID in all browsers.'''

=== Plugins ===

All plugins have to define a function called ''initializePlugin(view)''. This function will be called by the player when it is [wiki:FlashOverview#Initialization initialized]. A reference to the [browser:trunk/as3/com/jeroenwijering/player/View.as View] is passed to this function, so the plugin can instantly read the config/playlist, send events and assign listeners.


{{{
public class MyPlugin extends Sprite implements PluginInterface {
	private var view:AbstractView;

	public function initializePlugin(vw:AbstractView):void {	
		view = vw;
	};
}
}}}

You need to include the [browser:trunk/as3/com/jeroenwijering/events/ com.jeroenwijering.events package] in your plugin project in order to be able to strong-type your code and avoid compilation errors.

== Reading variables ==

There's three variable calls  you can make through the API:

 * '''getConfig''' returns an object with all the variables ([wiki:FlashVars]) loaded into the player.
 * '''getPlaylist''' returns an array with all the entries in a playlist. For a single file, the list will indeed have just one entry. Every entry in the '''playlist''' is an object too, with a ''file'', ''type'', ''duration'' etc. [FlashVars#Fileproperties property]. 
 * '''getPluginConfig(name)''' returns an object with all the flashvars of a certain plugin (for example the included ''controlbar'' or the externally loaded ''yousearch''). Additionally, every plugin will have an ''x'', ''y'', ''width'',''height'' and ''visible'' variable that contains its positioning.

=== Javascript ===

If, for example, you want to know the value of the ''autostart'' variable of the player, you can request it like this:

{{{
var start = player.getConfig().autostart;
}}}

getPlaylist() returns an array of all playlist-items with their properties. If, for example, you want to know the title of the second video in your playlist, you can request it like this:

{{{
var title = player.getPlaylist()[1].title;
}}}

=== Plugins ===

The same call for plugins in actionscript looks like this:

{{{
var start = view.getconfig()['autostart'];
var title = view.getPlaylist()[1]['title'];
}}}


== Sending events ==

Of course it is also possible to send events to the player. This is done through a ''sendEvent()'' call. You can send all events defined by the View (e.g. ''STOP'' or ''VOLUME''). Some of the event need a parameter and some don't.  An overview of all events can be found  [FlashEvents#Viewevents on this page]. Here's also a [source:trunk/as3/player.pdf  single sheet overview] of all events.

=== Javascript ===

An example is the sending of a play event:

{{{
player.sendEvent("PLAY","true");
}}}

Note that you '''must string representations of a function for the function parameter'''!

=== Plugins ===

For plugins, events are again sent through the View. Also, there is the possiblity of strong typing the events through the included ''events'' package:
 
{{{
view.sendEvent(ViewEvent.PLAY);
view.sendEvent(ViewEvent.LOAD,'http://www.mysite.com/mycoolvideo.mp4');
}}}


== Setting listeners ==

Each language can assign listener functions to any event the Model, View or Controller fires. Whenever the event is fired, the function gets called, with a key:value populated object as parameters. The values in this object depend on the type of event. An overview of all events can be found  [FlashEvents#Viewevents on this page]. 

It is recommended to not listen to events of the View, but only to the corresponding event of the Controller. The Controller generally checks the event of the View and fires a corrected version itself. 

The 4.4 player introduced the possibility to also remove the listeners.

=== Javascript ===

Listeners can be set through three different functions:

 * player.addControllerListener(''EVENT'',''myFunction'');
 * player.addModelListener(''EVENT'',''myFunction'');
 * player.addViewListener(''EVENT'',''myFunction'');

Once again, here's an example.  Note that you '''must string representations of a function for the function parameter'''!

{{{
function muteTracker(obj) { alert('the new mute state is: '+obj.state); };
player.addControllerListener("MUTE","muteTracker");
}}}

Removal of listeners works just the same (4.4+ compatible):
{{{
player.removeControllerListener("MUTE","muteTracker");
}}}


=== Plugins  ===

Again, the setup is similar to javascript:

 * view.addControllerListener(EVENT,myFunction);
 * view.addModelListener(EVENT,myFunction);
 * view.addViewListener(EVENT,myFunction);

An example:
{{{
private function muteTracker(evt:ControllerEvent) { 
    trace('the new mute state is: '+evt.data['state']); 
};

view.addControllerListener(ControllerEvent.MUTE,muteTracker);
}}}

And an example removal call (4.4+ compatible):
{{{
view.removeControllerListener(ControllerEvent.MUTE,muteTracker);
}}}

Again note that you need to include the [browser:trunk/as3/com/jeroenwijering/events/ com/jeroenwijering/events package] in your plugin project in order to be able to strong-type your code and avoid compilation errors.


== Plugin methods ==

In order to facilitate richer plugin interaction, the '''4.3''' player introduced an API method related to plugins. It is only available to other plugins; not to javascript:

 * '''getPlugin''': returns the reference to a specific plugin. It can be used to call public methods or get public properties of a certain plugin.


=== Plugins ===

Here's an example call:

{{{
var mtv:Object = view.getPlugin('controlbar');
}}}

=== Built-in plugin methods ===

There's two built-in player plugins that offer a public method:

 * The '''controlbar''' offers an ''addButton()'' call, used to insert a custom button in the controlbar. Available since 4.3
 * The '''dock''' offers an ''addButton()'' call, used to insert a custom button in the dock. Available since 4.5

Here's example code that tries to insert a button in the dock and then in the controlbar:
 
{{{
var view:AbstractView;
var icon:DisplayObject;

function clickHandler(evt:MouseEvent):void { 
	trace('Demo button clicked!');
}; 

function initializePlugin(vie:AbstractView):void {
    view = vie;
    if(view.getPlugin('dock') && view.config['dock']) { 
        view.getPlugin('dock').addButton(icon,'click me!',clickHandler);
    } else if (view.getPlugin('controlbar')) {
        view.getPlugin('controlbar').addButton(icon,'myplugin',clickHandler);
    }
};
}}}