UiBinder Support

As of version 2.0, GWT offers the UiBinder framework - a declarative means of composing application UI widgets with XML files in a manner similar to developing HTML pages.

The following sections describe the ways of using the player widgets with UiBinder

The required module

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

<inherits name="com.bramosystems.oss.player.uibinder.UiBinder"/>

However, it should be obvious, the module requires GWT 2.0 or later.

The widgets namespace

The player widgets with UiBinder support are placed in the com.bramosystems.oss.player.uibinder.client package. Consequently, in order to use the player widgets in a ui.xml template file, you need to tie the package to an XML namespace prefix. 

<ui:UiBinder xmlns:ui='urn:ui:com.google.gwt.uibinder'
    xmlns:player='urn:import:com.bramosystems.oss.player.uibinder.client'>
    ...
</ui:uibinder>

The supported players

The following widgets are supported:

Instance name Description
WinMediaPlayer Embeds Windows Media Player plugin
QuickTimePlayer Embeds QuickTime plugin
Flash Embeds a generic Adobe Flash application
FlashMediaPlayer Embeds Adobe Flash plugin for playing Flash supported file formats
VLCPlayer Embeds VLC Media Player plugin
Native Embeds media with HTML 5 video handler in supported browsers
DivXPlayer Embeds DivX® Web Player plugin
YouTube Embeds YouTube video
Chromeless Embeds YouTube video using the Chromeless player
Auto Embeds media using any of the avaliable media plugins on the client
PlaylistSupport Embeds media using any available media plugin that supports client side playlist management
MatrixSupport Embeds media using any available media plugin that supports matrix transformation

Note: For BST Player 1.2.1 and earlier, the use of YouTube and Chromeless widgets require the com.bramosystems.oss.player.uibinder.client.youtube XML namespace.

Enhanced UiBinder support

As of BST Player 1.3, all the widgets specified in the previous section (except Flash) have been deprecated in favour of the new Player widget. The widget wraps all players available to the API (includng any provided by third parties) out-of-the-box.

The supported attributes

Each of the widgets support the following attributes (except stated otherwise)

Attribute Required Type Default Comment
name true String - The name of the player, in the format "<playerProviderName>:<playerName>"
Note: Supported only by the Player widget (BST Player API 1.3 and later) .
mediaURL true String - The URL of the media.
Note: The YouTube widget uses videoURL instead
height true String - The height of the widget (CSS units)
width true String - The width of the widget (CSS units)
autoplay true boolean - If the media should be played automatically.
Note: Flash widget does not support this attribute
showLogger false boolean false If the Logger widget should show
Note: Flash widget does not support this attribute
resizeToVideoSize false boolean false If the player should resize to match the size of the video (if embedded media is a video file).
Note: Flash widget does not support this attribute
controllerVisible false boolean true If the player controls should be visible
Note: Flash, YouTube and Chromeless widgets does not support this attribute
loopCount false int 1 Number of times to repeat playback before stopping
Note: Flash, YouTube and Chromeless widgets does not support this attribute
params false String - Supported ONLY by Flash widget. A comma separated list of name/value pairs of Adobe Flash parameters. E.g. params='allowScriptAccess=sameDomain,bgcolor=#000000'
Note: Do not pass flashVars parameter with this attribute, use the flashVars attribute instead.
flashVars false String - Supported ONLY by Flash widget. A list of name/value pairs parameters that is passed to the Flash application. E.g. flashVars='param1=value1&param2=value2'

Relative URLs

The player widgets define special URL prefixes to make media files relative to the application host page accessible. The prefixes are resolved to the fully qualified names during compilation.

Prefix Fully Qualified Name
gwt-host:: The URL of the application's host page as returned by GWT.getHostPageBaseURL()
gwt-module:: The URL of the application's module as returned by GWT.getModuleBaseURL()

Example Usage

The examples below illustrates how to embed player widgets (BST Player 1.2.1 and earlier) 

Embed media with Windows Media Player plugin

<ui:UiBinder xmlns:ui='urn:ui:com.google.gwt.uibinder'
    xmlns:g='urn:import:com.google.gwt.user.client.ui'
    xmlns:player='urn:import:com.bramosystems.oss.player.uibinder.client'>
        ...
        <player:WinMediaPlayer autoplay='true' height='50px' width='100%'
            mediaURL='gwt-host::media/applause.mp3' />
        ...
</ui:UiBinder>

Embed MP3 media with the HTML 5 video elements with the logger showing

<ui:UiBinder xmlns:ui='urn:ui:com.google.gwt.uibinder'
    xmlns:g='urn:import:com.google.gwt.user.client.ui'
    xmlns:player='urn:import:com.bramosystems.oss.player.uibinder.client'>
        ...
        <player:Native autoplay='true' height='20px' width='100%'
            showLogger='true' mediaURL='gwt-host::media/o-na-som.mp3' />
        ...
</ui:UiBinder>

Embed YouTube video with the YouTube widget

<ui:UiBinder xmlns:ui='urn:ui:com.google.gwt.uibinder'
    xmlns:g='urn:import:com.google.gwt.user.client.ui'
    xmlns:player='urn:import:com.bramosystems.oss.player.uibinder.client.youtube'>
        ...
        <player:YouTube height='350px' width='100%' showLogger='true'
                    videoURL='http://www.youtube.com/v/QbwZL-EK6CY' />
        ...
</ui:UiBinder>

The following examples illustrates the previous with BST Player 1.3 or later: 

Embed media with Windows Media Player plugin

<ui:UiBinder xmlns:ui='urn:ui:com.google.gwt.uibinder'
    xmlns:g='urn:import:com.google.gwt.user.client.ui'
    xmlns:player='urn:import:com.bramosystems.oss.player.uibinder.client'>
        ...
        <player:Player name='core:WinMediaPlayer' autoplay='true' height='50px' width='100%'
            mediaURL='gwt-host::media/applause.mp3' >
                <player:missingPluginNotice>
                    <!-- 
                        Replace the default missing plugin notice with a custom GWT
                        widget of choice                        
                    -->
                    <g:Label styleName='mystyles'>Oopss, you do not have the required plugin !
                    Download 'ThePlugin' </g:Label>
                </player:missingPluginNotice>
                <player:missingPluginVersionNotice>
                    <!--
                        A custom GWT widget can also be used instead of the default
                        missing plugin version notice                        
                    -->
                    <g:Label>Oopss, you actually need a higher version of 'ThePlugin' 
                    to see this media !</g:Label>
                </player:missingPluginVersionNotice>
        </player:Player>
        ...
</ui:UiBinder>

Embed MP3 media with the HTML 5 video elements with the logger showing

<ui:UiBinder xmlns:ui='urn:ui:com.google.gwt.uibinder'
    xmlns:g='urn:import:com.google.gwt.user.client.ui'
    xmlns:player='urn:import:com.bramosystems.oss.player.uibinder.client'>
        ...
        <player:Native autoplay='true' height='20px' width='100%'
            showLogger='true' mediaURL='gwt-host::media/o-na-som.mp3' />
        ...
</ui:UiBinder>

Embed YouTube video with the YouTube widget

<ui:UiBinder xmlns:ui='urn:ui:com.google.gwt.uibinder'
    xmlns:g='urn:import:com.google.gwt.user.client.ui'
    xmlns:player='urn:import:com.bramosystems.oss.player.uibinder.client'>
        ...
        <player:Player name='yt:YouTube' height='350px' width='100%' showLogger='true'
                    mediaURL='http://www.youtube.com/v/QbwZL-EK6CY' />
        ...
</ui:UiBinder>

Programmatic Access

UiBinder offers owner classes programmatic access to widgets defined in UI templates. The player can be injected into the owner class with the ui:field attribute.

With UiBinder, the player widgets only support the methods defined in the AbstractMediaPlayer class and the PlaylistSupport / MatrixSupport interfaces. However, you can access player specific methods by calling player.getEngine(). The following example demonstrates this: 

<!-- WMPExample.ui.xml -->
<ui:UiBinder xmlns:ui='urn:ui:com.google.gwt.uibinder'
    xmlns:g='urn:import:com.google.gwt.user.client.ui'
    xmlns:player='urn:import:com.bramosystems.oss.player.uibinder.client'>

    <g:VerticalPanel spacing='10'>        
        ...
        <!-- pre BST Player 1.3 -->
        <player:WinMediaPlayer autoplay='true' height='50px' width='100%'
            mediaURL='gwt-host::media/applause.mp3' ui:field='player' />
        ...
        <!-- for BST Player 1.3+ -->        
        <player:Player name="core:WinMediaPlayer" autoplay='true' height='50px' width='100%'
            mediaURL='gwt-host::media/applause.mp3' ui:field='player' />
        ...    
    </g:VerticalPanel>
</ui:UiBinder>


<!-- WMPExample.java -->
public class WMPExample extends Composite {
  interface WMPBinder extends UiBinder<VerticalPanel, WMPExample> {}

  private static WMPBinder _binder = GWT.create(WMPBinder.class);
  
  // UiBinder injects the created instance...
//  @UiField WinMediaPlayer player;   pre BST Player 1.3
  @UiField Player player;   // for BST Player 1.3+...

  public WMPExample() {
    initWidget(_binder.createAndBindUi(this));

    // access general methods directly
    player.addPlayerStateHandler( ... );

    // access WinMediaPlayer specific methods...
    ((WinMediaPlayer)player.getEngine()).setUIMode(UIMode.MINI);
  }
}