Package com.bramosystems.oss.player.script.client

Provides classes and interface to export the API as a Javascript library in non-GWT applications such as traditional page-based web applications.

See: Description

Class Summary

Class	Description
AbstractExportProvider	Abstract implementation for providers of the player and seekbar widgets exported as Javascript objects.
ExportUtil	Utility class to export the player and seek bar widgets as Javascript objects that can be used in non-GWT applications.

Package com.bramosystems.oss.player.script.client Description

Provides classes and interface to export the API as a Javascript library in non-GWT applications such as traditional page-based web applications. This enables the players to be used as widgets on websites.

Exporting the player widgets

Exporting widgets requires some simple steps:

• inherit the Script module in your application
• extend the AbstractExportProvider class
• add a GWT type-replacement mapping for the AbstractExportProvider implementation
• use the ExportUtil class to export the widgets when ready

These steps are further explained:

Inherit the Script module

As required by the GWT compiler, the com.bramosystems.oss.player.script.Script module should be inherited to use the class and interface in this package.

    <!-- MyGWTApp.gwt.xml -->
    <inherits name="com.bramosystems.oss.player.script.Script" />
 

Extend the AbstractExportProvider class

The AbstractExportProvider class defines methods to retrieve the widgets to be exported as Javascript objects. Therefore, create a class that extend the class and return the player widgets of your choice. The following sample shows a basic implementation:

    public class MyCoolProvider extend AbstractExportProvider {
       private Plugin plugin;

       public AbstractMediaPlayer getPlayer(String playerProvider, String playerName, 
                 String mediaURL, boolean autoplay, String width,
                 String height, HashMap<String, String> options)
                 throws PluginNotFoundException, PluginVersionException {
          return new MyCoolPlayer(mediaURL, autoplay, height, width);
       }

       public Widget getMissingPluginWidget() {
          return PlayerUtil.getMissingPluginNotice(plugin);
       }

       public Widget getMissingPluginVersionWidget() {
          return PlayerUtil.getMissingPluginNotice(plugin);
       }

       public MediaSeekBar getSeekBar(int height, HashMap<String, String> options) {
          return new CSSSeekBar(height);
       }
    }
 

Add a GWT type-replacement mapping

The AbstractExportProvider implementation is instantiated by the ExportUtil class using deferred binding while exporting the players. For the process to be a success, a type-replacement mapping is required in your modules' definition.

A sample is shown below:

   <!-- MyGWTApp.gwt.xml -->
   <replace-with class="com.example.MyCoolProvider">
      <when-type-is class="com.bramosystems.oss.player.script.client.AbstractExportProvider"/>
   </replace-with>
 

Of course, other GWT type-replacement conditions could be used as required.

Export the widgets

The ExportUtil class defines static methods to export the player and seekbar widgets. The class could be used in module entry implementations as shown below:

   public class Xporter implements EntryPoint {

     public Xporter() {
        ExportUtil.exportPlayer();
        ExportUtil.exportSeekBar();
     }

     public void onModuleLoad() {
        ExportUtil.signalAPIReady();
     }
   }
 

The ExportUtil.exportPlayer() method instantiates the ExportProvider implementation and exports the player widget returned by the getPlayer() method. If the required plugin is not found the getMissingPluginWidget() method is called while the getMissingPluginVersionWidget() is called when the required plugin version is not found.

The player widget is exported as a bstplayer.Player(plugin,mediaURL,autoplay,width,height,options) object where:

• plugin [String] - is one of the defined Plugins (Note: case-sensitive)
• mediaURL [String] - the URL of the media
• autoplay [boolean] - true to autoplay the media, false otherwise
• width [String] - the width of the widget (in CSS units)
• height [String] - the height of the widget (in CSS units)
• options [Javascript Object] - used to pass user-defined map of values to the ExportProvider implementation

See sample usage below.

Similary, the ExportUtil.exportSeekBar() method instantiates the ExportProvider implementation and exports the seekbar widget returned by the getSeekBar() method.

The seekbar widget is exported as a bstplayer.SeekBar(height,containerId,options) object where:

• height [String] - the height of the widget (in CSS units)
• containerId [String] - the HTML element id, where the widget will be placed
• options [Javascript Object] - used to pass user-defined map of values to the ExportProvider implementation

See sample usage below.

The ExportUtil.signalAPIReady() method notifies the host page that the Javascript objects are now available and can be created and used as required. This method calls the onBSTPlayerReady() Javascript function, which SHOULD be defined on the host page. The Player and/or SeekBar objects SHOULD be created within this function.

Using the exported widgets

The exported API should be available as a GWT compilation in its module folder/directory. Using the widgets is thereafter simple:

Add the module script to the host page

GWT applications end up as an module-name.nocache.js javascript file, hence add this to the HTML host page.

      <script type="text/javascript" src="module-name/module-name.nocache.js"></script>
 

Create the widgets HTML container elements

Create the HTML elements that will contain the widgets. This can be as simple as defining HTML <div> tags at required places.

      <div id="my-player" />
      <div id="_progress" />
 

Define the onBSTPlayerReady() function

This function will be called when the Player and/or SeekBar objects are bound to the host page

      <script type="text/javascript">
          var onBSTPlayerReady = function() {
          }
      </script>
 

Create the widgets and use as required

Create the Player object within the defined onBSTPlayerReady() function. Once the object is created, the widget can be attached to the page by calling the inject() method. The inject() method takes the id of the HTML element as a parameter. Following is an example:

      <script type="text/javascript">
          var onBSTPlayerReady = function() {
              player = new bstplayer.Player("Auto", "some-cool-sound.mp3", false, "100%", "50px", null);
              player.inject('my-player');

              seekbar = new bstplayer.SeekBar(10, '_progress', null);
          }
      </script>
 

The Player object supports all the public methods defined in the AbstractMediaPlayer class, except all the addXXXHandler methods.

Instead of the addXXXHandler methods, the Player object defines an addEventListener(name, function) method with the following event names:

• onPlayerState - for PlayerStateEvent events
• onPlayState - for PlayStateEvent events
• onLoadingProgress - for LoadingProgressEvent events
• onMediaInfo - for MediaInfoEvent events
• onError - for DebugEvent events of the Error type
• onDebug - for DebugEvent events of the Info type

The SeekBar object supports the following methods:

• setLoadingProgress(loadingProgress) - set the progress of the media loading operation
• setPlayingProgress(playingProgress) - set the progress of the media playback operation

Also, an addEventListener(name, function) method is defined with the following event name:

• onSeekChanged - for SeekChangeEvent events

The example below illustrates a custom player implementation:

         <script type="text/javascript">
             var player;
             var seekbar;
             var onBSTPlayerReady = function() {
                 seekbar = new bstplayer.SeekBar(10, '_progress', null);
                 seekbar.addEventListener("onSeekChanged", function(evt){
                     player.setPlayPosition(evt.seekPosition * player.getMediaDuration());
                 });

                 player = new bstplayer.Player("Auto", "nice.mp3", false, null, null, null);
                 player.addEventListener("onPlayState", function(evt){
                     switch(evt.playState) {
                         case 'Paused':
                             document.getElementById("playButton").disabled = false;
                             document.getElementById("pauseButton").disabled = true;
                             document.getElementById("stopButton").disabled = false;
                             break;
                         case 'Started':
                             document.getElementById("playButton").disabled = true;
                             document.getElementById("pauseButton").disabled = false;
                             document.getElementById("stopButton").disabled = false;
                             break;
                         case 'Stopped':
                         case 'Finished':
                             document.getElementById("playButton").disabled = false;
                             document.getElementById("pauseButton").disabled = true;
                             document.getElementById("stopButton").disabled = true;
                             break;
                     }
                 });
                 player.addEventListener("onPlayerState", function(evt){
                     if(evt.playerState == 'Ready') {
                         document.getElementById("playButton").disabled = false;
                         document.getElementById("pauseButton").disabled = true;
                         document.getElementById("stopButton").disabled = true;

                         playTimer = window.setInterval(function(){
                             seekbar.setPlayingProgress(player.getPlayPosition() / player.getMediaDuration());
                         }, 1000);
                     }
                 });
                 player.addEventListener("onLoadingProgress", function(evt){
                     seekbar.setLoadingProgress(evt.progress);
                 });
                 player.inject('_pid');
             }
         </script>

         <div style="width:350px">
             <div id="_pid"></div>
             <div>
                 <button id="playButton" onclick="player.playMedia()" disabled >Play</button>
                 <button id="pauseButton" onclick="player.pauseMedia()" disabled >Pause</button>
                 <button id="stopButton" onclick="player.stopMedia()" disabled >Stop</button>
             </div>
             <div id="_progress"></div>
         </div>