Changeset 1070

Timestamp:

05/25/10 19:18:02 (3 years ago)

Author:

pablo

Message:

Adding additional developer documentation

Location:

trunk/fl5/doc

Files:

• developers/buildingplugins.rst (modified) (2 diffs)
• developers/pluginapi.rst (modified) (1 diff)
• publishers/fmsdvr.rst (added)
• publishers/images/fmsdvr (added)
• publishers/images/fmsdvr/FMSDVR_1.png (added)
• publishers/images/fmsdvr/FMSDVR_2.png (added)
• publishers/images/fmsdvr/FMSDVR_3.png (added)
• publishers/images/fmsdvr/FMSDVR_4.png (added)
• publishers/images/fmsdvr/FMSDVR_5.png (added)
• publishers/options.rst (modified) (5 diffs)
• publishers/releasenotes.rst (added)
• publishers/startup.rst (added)

trunk/fl5/doc/developers/buildingplugins.rst

@@ -13 +13 @@
 
 
-.. code-block:: javascript
+.. code-block:: html
 
         <script type="text/javascript">
@@ -178 +178 @@
 Basic configuration parameters for a specific plugin can be loaded through the same flashvars mechanism the player uses itself. Variables for a specific plugin must be prepended with the name of the plugin and a dot. So if your plugin is called *delicious*, your variable names must start with the *delicious.* string. Example:
 
-.. code-block:: javascript
+.. code-block:: html
 
         <script type="text/javascript">

trunk/fl5/doc/developers/pluginapi.rst

@@ -1 +1 @@
 .. _pluginapi:
 
-Plugin API
-==========
+=======================
+Actionscript Plugin API
+=======================
 
-This is about the plugin API
+JW Player 5 supports a flexible API for :ref:`plugins <buildingplugins>`, that can be  written in `actionscript <http://en.wikipedia.org/wiki/ActionScript>`_. It is possible to read the config/playlist variables of the player, call player functions, and listen for :ref:`Flash Events <pluginevents>`.
+
+Version 5 also supports a :ref:`JavaScript API <javascriptapi>`, and it can load `Version 4 plugins <http://developer.longtailvideo.com/trac/wiki/Player4Api>`_ as well.
+
+Initialization
+==============
+
+All plugins have to define a function called *initPlugin(player, config)*. This function will be called by the player when it is :ref:`initialized <startup>` . A reference to the `Player <http://developer.longtailvideo.com/trac/browser/trunk/fl5/src/com/longtailvideo/jwplayer/player/IPlayer.as>`_ is passed to this function, so the plugin can instantly read the config/playlist, call player functions and assign event listeners.  A `PluginConfig <http://developer.longtailvideo.com/trac/browser/trunk/fl5/src/com/longtailvideo/jwplayer/plugin/PluginConfig.as>`_ object, which contains plugin-specific configuration parameters, is passed in as an argument to *initPlugin* as well.
+
+Plugins also need to implement a *resize(width, height)* function and an *id* getter.  Here is an example of a valid (but empty) plugin:
+
+.. code-block:: actionscript
+
+        import com.longtailvideo.jwplayer.player.IPlayer;
+        import com.longtailvideo.jwplayer.plugins.PluginConfig;
+        
+        public class MyPlugin extends Sprite implements IPlugin {
+        
+                private static var myID:String = "myplugin";
+        
+                private var api:IPlayer;
+                private var config:PluginConfig;
+        
+                public function initPlugin(player:IPlayer, conf:PluginConfig):void {    
+                        this.api = player;
+                        this.config = conf;
+                }
+        
+                public function get id():String {       
+                        return myID;
+                }
+        
+                public function resize(width:Number, height:Number):void {      
+                        // Implement resizing if necessary
+                }
+        }
+
+
+Reading variables
+=================
+
+There are three variable calls you can make through the player API:
+
+ * **config** returns a `PlayerConfig <http://developer.longtailvideo.com/trac/browser/trunk/fl5/src/com/longtailvideo/jwplayer/model/PlayerConfig.as>`_ object with all of the :ref:`settings <options>` loaded into the player.
+ * **playlist** returns a `Playlist <http://developer.longtailvideo.com/trac/browser/trunk/fl5/src/com/longtailvideo/jwplayer/model/Playlist.as>`_ object containing all of its `PlaylistItems <http://developer.longtailvideo.com/trac/browser/trunk/fl5/src/com/longtailvideo/jwplayer/model/PlaylistItem.as>`_. For a single file, the list will have only one entry. 
+ * **config.pluginConfig(name)** returns a `PluginConfig <http://developer.longtailvideo.com/trac/browser/trunk/fl5/src/com/longtailvideo/jwplayer/plugins/PluginConfig.as>`_ object with all the flashvars for a particular plugin (for example the included *controlbar* or the externally loaded *yousearch*). Additionally, every plugin config will contain an *x*, *y*, *width*,*height* and *visible* variable that pertain to its positioning.
+
+Here are three calls to the player which illustrate reading variables from the player API
+
+.. code-block:: actionscript
+
+        // See what the repeat flashvar was configured to
+        var repeat:String = player.config.repeat
+        // The title of the second playlist item
+        var title:String = player.playlist.getItemAt(1).title;
+        // The current width of the controlbar
+        var barWidth:Number = player.pluginConfig('controlbar')['width'];
+
+
+Player commands
+===============
+
+The ActionScript API exposes the following player commands:
+
+ * fullscreen(state:Boolean)
+ * load(item:*)
+ * mute(state:Boolean)
+ * pause()
+ * play()
+ * playlistItem(i:Number)
+ * playlistNext()
+ * playlistPrev()
+ * redraw()
+ * seek(pos:Number)
+ * stop()
+ * volume(vol:Number)
+
+Here are some examples of how to call these functions:
+ 
+.. code-block:: actionscript
+
+        // Mute the player
+        player.mute(true);
+        // Load a new video into the player
+        player.load("http://www.mysite.com/mycoolvideo.mp4");
+
+
+Setting listeners
+=================
+
+Any of the events described in the :ref:`Player Events <pluginevents>` page can be listened for using the Flash Event model.  To listen for a player event, simply call the *addEventListener()* function on the player API.
+
+An example:
+
+.. code-block:: actionscript
+
+        import com.longtailvideo.jwplayer.events.*;
+
+        private function muteTracker(evt:MediaEvent) { 
+            trace('the new mute state is: '+evt.mute); 
+        }
+
+player.addEventListener(MediaEvent.JWPLAYER_MEDIA_MUTE, muteTracker);
+
+
+And an example removal call:
+
+.. code-block:: actionscript
+
+        player.removeEventListener(MediaEvent.JWPLAYER_MEDIA_MUTE, muteTracker);
+
+.. note:: Your plugin will need to include the `com.longtailvideo.jwplayer.events package <http://developer.longtailvideo.com/trac/browser/trunk/fl5/src/com/longtailvideo/jwplayer/events/>`_  in order to avoid compilation errors.
+
+
+Player Controls
+===============
+
+The player contains several built-in user controls, which have their own APIs.  For example:
+
+ * The **controlbar** offers an *addButton()* call, used to insert a custom button in the controlbar.
+ * The **dock** offers an *addButton()* call, used to insert a custom button in the dock.
+
+Here's example code that tries to insert a button in the dock and then in the controlbar:
+ 
+.. code-block:: actionscript
+
+        var api:IPlayer;
+        var icon:DisplayObject;
+        
+        function clickHandler(evt:MouseEvent):void { 
+                trace('Demo button clicked!');
+        }
+        
+        function initPlugin(player:IPlayer, conf:PluginConfig):void {
+            api = player;
+            if(api.config.dock) { 
+                api.controls.dock.addButton(icon, "Click here", clickHandler);
+            } else {
+                api.controls.controlbar.addButton(icon, "Click here", clickHandler);
+            }
+        }

trunk/fl5/doc/publishers/options.rst

@@ -16 +16 @@
 
 So if, fore example, your *file* flashvar is at the location *getplaylist.php?id=123&type=flv*, you must set the file flashvar to *getplaylist.php%3Fid%3D123%26type%3Dflv*.
+
+.. _options-playlist:
 
 Playlist properties
@@ -47 +49 @@
 In addition to these default **providers**, the player has specific support for certain streaming servers or CDNs. A full list of mediafile types can be found on the :ref:`supported filetypes <mediaformats>` page.
 
+.. _options-layout:
+
 Layout
 ======
@@ -52 +56 @@
 These flashvars control the look and layout of the player. 
 
- * **backcolor** (*undefined*): background color of the controlbar and playlist. This is white with the default skin.
  * **controlbar** (*bottom*): position of the controlbar. Can be set to *bottom*, *over* and *none*.
  * **dock** (*false*): set this to *true* to show the dock with large buttons in the top right of the player. Available since 4.5. 
- * **frontcolor** (*undefined*): color of all icons and texts in the controlbar and playlist.
  * **height** (*400*): height of the display in pixels. 
  * **icons** (*true*): set this to *false* to hide the play button and buffering icon in the middle of the video. Available since 4.2.
- * **lightcolor** (*undefined*): color of an icon or text when you rollover it with the mouse.
  * **logo.file** (*undefined*): location of an external jpg, png or gif image which replaces the watermark image (**Licensed players only**)
  * **logo.link** (*undefined*): link to direct to when the watermark image is clicked on (**Licensed players only**)
@@ -66 +67 @@
  * **playlistsize** (*180*): when *below* this refers to the height, when *right* this refers to the width of the playlist. 
  * **skin** (*undefined*): location of a [wiki:Player5Skinning skin file] containing the player graphics.  The [/browser SVN repository] contains [browser:skins a couple of example skins].
- * **screencolor** (*undefined*): background color of the display
  * **width** (*280*): width of the display in pixels.
 
-The four color flashvars must be entered using hexadecimal values, as is common for [http://en.wikipedia.org/wiki/Web_colors#Hex_triplet web colors] (e.g. *FFCC00* for bright yellow).  They are not supported by [wiki:Player5Skinning bitmap skins].
+.. _options-colors:
+
+Colors
+======
+
+These flashvars are available when using 4.x (SWF) skins.  They will be deprecated once SWF skinning support is dropped in a future release.
+
+ * **backcolor** (*undefined*): background color of the controlbar and playlist. This is white with the default skin.
+ * **frontcolor** (*undefined*): color of all icons and texts in the controlbar and playlist.
+ * **lightcolor** (*undefined*): color of an icon or text when you rollover it with the mouse.
+ * **screencolor** (*undefined*): background color of the display
+
+The four color flashvars must be entered using hexadecimal values, as is common for [http://en.wikipedia.org/wiki/Web_colors#Hex_triplet web colors] (e.g. *FFCC00* for bright yellow).
+
+.. _options-behavior:
 
 Behavior
@@ -100 +114 @@
  * **id** (*undefined*): This flashvar is necessary for javascript interaction on linux platforms..  It should be set to the id of the player's DOM element.
 
-The former flashvars, **client**, **id** and **version** are sent as parameters with every [wiki:Player5Events event the player broadcasts].
+.. _options-config-xml:
 
 Config XML