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
Flash Embeds a generic Adobe Flash application
Player Embeds any and all players available to the API (including any provided by 3rd parties)

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 .
mediaURL true String - The URL of the media.
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
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 widget does not support this attribute
loopCount false int 1 Number of times to repeat playback before stopping
Note: Flash widget 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 

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 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='bst.youtube:YouTube' height='350px' width='100%'
                    mediaURL='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'>        
        ...
        <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 Player player;

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

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

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