Export your custom player widgets

After creating custom player controls, it may be desirable to take advantage of GWTs' edge and use the widgets in non-GWT applications.

The following sections describe how to export player widgets as Javascript objects.

The required module

For this description to work, your application should inherit the com.bramosystems.oss.player.script.Script module. This is as simple as putting the following line in your module XML file: 

<inherits name="com.bramosystems.oss.player.script.Script"/>

The module contains the classes that define the contract between the ExportUtil utility class and the player widgets provider.

Implement the player widget provider

The ExportProvider interface define methods to get the required widgets during the 'export to Javascript' process.

With the introduction of the provider framework in BST Player 1.3, the ExportProvider interface is deprecated in favour of the AbstractExportProvider class. The AbstractExportProvider class provides means of exporting all player widgets registered with the API including 3rd parties.

The following snippet implements the ExportProvider interface. 

public class MyProvider implements ExportProvider {

    @Override
    public AbstractMediaPlayer getPlayer(Plugin plugin, String mediaURL,
            boolean autoplay, String width,
            String height, HashMap<String, String> options)
            throws LoadException, PluginNotFoundException, PluginVersionException {
        // return an AbstractMediaPlayer implementation using the
        // specified parameters.  Here, we are using the
        // custom player defined earlier
        return new MyPlayer(mediaURL, height, width);
    }

    @Override
    public Widget getMissingPluginWidget() {
        // if the getPlayer method throws a missing plugin exception,
        // this method is called to get the widget to use instead
        return PlayerUtil.getMissingPluginNotice(plugin);
    }

    @Override
    public Widget getMissingPluginVersionWidget() {
        // if the getPlayer method throws a missing plugin version
        // exception, this method is called to get the widget to use instead
        return PlayerUtil.getMissingPluginNotice(plugin);
    }

    @Override
    public MediaSeekBar getSeekBar(int height, HashMap<String, String> options) {
        // this method is called to get a seek bar implementation
        return new CSSSeekBar(height);
    }
}

The following example shows the AbstractExportProvider implementation. 

public class MyProvider2 extends AbstractExportProvider {

    @Override
    public AbstractMediaPlayer getPlayer(String playerProvider, String playerName,
            String mediaURL, boolean autoplay, String width,
            String height, HashMap<String, String> options)
            throws LoadException, PluginNotFoundException, PluginVersionException {
        // return an AbstractMediaPlayer implementation using the
        // specified parameters.  Here, we are using the
        // custom player defined earlier
        return new MyPlayer(mediaURL, height, width);
    }

    @Override
    public Widget getMissingPluginWidget() {
        // if the getPlayer method throws a missing plugin exception,
        // this method is called to get the widget to use instead
        return PlayerUtil.getMissingPluginNotice(plugin);
    }

    @Override
    public Widget getMissingPluginVersionWidget() {
        // if the getPlayer method throws a missing plugin version
        // exception, this method is called to get the widget to use instead
        return PlayerUtil.getMissingPluginNotice(plugin);
    }

    @Override
    public MediaSeekBar getSeekBar(int height, HashMap<String, String> options) {
        // this method is called to get a seek bar implementation
        return new CSSSeekBar(height);
    }
}

Export the widgets

The ExportUtil class performs the actual job of exporting these widgets with three static methods.

- ExportUtil.exportPlayer(): binds the player widget as a bstplayer.Player Javascript object.

- ExportUtil.exportSeekBar(): binds the seekbar widget as a bstplayer.Seekbar Javascript object.

- ExportUtil.signalAPIReady(): calls the onBSTPlayerReady() callback function on the host page. Obviously, this method is called only after the player and/or seekbar widgets have been exported to the host page.

A sample export implementation: 

public class MyExporter implements EntryPoint {
    public MyExporter() {
        ExportUtil.exportPlayer(); // export the player
        ExportUtil.exportSeekBar(); // export the seekbar
    }

    @Override
    public void onModuleLoad() {
        ExportUtil.signalAPIReady(); // tell the host page we're good to go
    }
}

But for the ExportUtil to succeed, it needs to know the widget provider implementation. This is achieved using GWTs' type-replacement feature.

If using the ExportProvider interface, the following line should be in your module XML file: 

<replace-with class="com.example.foo.MyProvider">
  <when-type-is class="com.bramosystems.oss.player.script.client.ExportProvider"/>
</replace-with>

But if using the AbstractExportProvider implementation, the required configuration is slightly different: 

<!-- Enable the provider framework for scripts.              -->
<!-- It is disabled by default for backwards compatibility.  -->
<set-property name="bstplayer.script.useProviderFramework" value="true"/>

<replace-with class="com.example.foo.MyProvider2">
  <when-type-is class="com.bramosystems.oss.player.script.client.AbstractExportProvider"/>
</replace-with>

Using the widgets

How to use the widget as Javascript objects is fully described here. Obviously your application replaces the BST Player JS library.