Custom player templates are available only for Brightcove Pro or Enterprise customers. If you are interested in upgrading your Brightcove account, please contact Brightcove for more information.
A player template's components include its UI elements, such as a VideoPlayer, Label, or Image. Components are contained within layout boxes, which define how to lay out the components within the player. Except for the List and ListItem components, components do not contain child elements. Brightcove includes the following standard components, each of which is described in more detail in the BEML DTD Reference:
For information about using these components to display content and metadata, see Data binding in player templates.
You can also create custom components and include them in your player template. For more information, see Creating custom player components.
Each type of BEML component can have an optional id attribute. The id attribute is useful in cases where one component needs to refer to another component. In addition, the id attribute is necessary if you want to use the Publishing module style editor to view and edit your player; components that do not have an id attribute will not be displayed in the Publishing module style editor.
The VideoPlayer component is a combination of a video window and a set of standard Brightcove media controls including a play/pause toggle, a timeline scrubber, volume controls, maximize controls and a menu access button. For example:
<VideoPlayer id="videoPlayer" width="486" height="416"
autoStart="true" theme="Deluxe" styleFile="Dark"
style="body-color:#FF0000" />
The VideoPlayer includes special attributes that govern how the VideoPlayer behaves, including:
The VideoPlayer has a minimum size of 180x176. The controls and menu do not render correctly at less than that size.
The VideoDisplay is simply a video window without the standard media control bar. For example:
<VideoDisplay id="videoPlayer" width="486" height="416"
autoStart="true" />
The VideoDisplay includes special attributes that govern how the VideoDisplay behaves, including:
The VideoPlayer component includes a set of standard Brightcove media controls including a play/pause toggle, a timeline scrubber, volume controls, maximize controls and a menu access button. The media control components enable you to create custom media control components. The media control components include the following:
With your media controls, you will often want to display time values – for example, the duration of a video or the current position of the playhead during playback. See Time Formatters for information about how you can format and display these values.
The MediaControls element is a layout container that contains other BEML layout elements and components, including a Playhead and ToggleButtons. The MediaControls element supports ad delivery by using a non-visual element called AdvertisingContext, referenced using the id adContext. See the Player API reference for more information about properties that are accessible via this element. See MediaControls Examples for several complete example of how to create custom player controls.
The Playhead component is a scrubber bar that moves steadily during playback to show the current media position. The user can drag the Playhead back and forth to move back or forward in the media. The mediaController attribute identifies the component in which the media is playing (VideoDisplay, VideoPlayer). For example:
<Playhead id="playhead" mediaController="{videoPlayer}" />
Note that while the BEML DTD permits a Playhead component to be a child of any layout box, in fact it will only function if its parent layout box is a child of a MediaControls element.
The VolumeControl component is a vertical slider that controls audio volume during playback. The mediaController attribute identifies the component in which the media is playing (VideoDisplay, VideoPlayer). For example:
<VolumeControl id="volumeControl" mediaController="{videoPlayer}" />
Here is an example of a full set of media controls, including a VolumeControl component within a MediaControls element, together with a play button, a playhead, and a label that displays the remaining time:
<MediaControls id="controls" boxType="hbox"
width="300" height="116" vAlign="bottom"
padding="7" gutter="12" showBack="true">
<ToggleButton id="playButton" showBack="false"
iconName="play" toggledIconName="pause"
tooltip="controls play tooltip"
toggledTooltip="controls pause tooltip"
autoSize="true" iconAlignmentH="left"
click="{videoDisplay.play()}"
toggledClick="{videoDisplay.pause()}"
toggled="{videoDisplay.playing}"/>
<Playhead id="playhead" height="11"
mediaController="{videoDisplay}"/>
<Label width="31" height="20" vAlign="middle"
hAlign="left"
text="{format(videoDisplay.timeRemaining, MillisecondsTimecodeFormatter)}"/>
<VolumeControl id="volumeButton" showBack="false"
iconName="volume" mutedIconName="muted"
tooltip="mute tooltip" mutedTooltip="unmute tooltip"
width="22" height="17"
mediaController="{videoPlayer}"/>
</MediaControls>
Note that while the BEML DTD permits a VolumeControl component to be a child of any layout box, in fact it will only function if its parent layout box is a child of a MediaControls element.
A ToggleButton is a clickable graphic with a label. It can toggle between two states. You can define different graphics (icons), labels, tooltips, and click actions for its toggled and untoggled states.
For example, here is the standard Play button in a VideoPlayer:
<ToggleButton id="playButton" showBack="false" iconName="play" toggledIconName="pause"
label="controls play" toggledLabel="controls pause"
tooltip="controls play tooltip" toggledTooltip="controls pause tooltip"
height="19" autoSize="true" lockHeight="true"
iconAlignmentH="left" labelAlignmentH="left" labelOffsetX="20"
click="{videoPlayer.play()}" toggledClick="{videoPlayer.pause()}"
toggled="{videoPlayer.playing}"/>
The iconName attribute assigns a graphic to the ToggleButton for its untoggled state, while the toggledIconName attribute assigns a graphic for the toggled state. The possible values of iconName and toggledIconName are: menu, play, pause, volume, maximize, minimize, share, link, code. In the Play button example, the ToggleButton displays the play arrow icon in its untoggled state and the pause icon in its toggled state.
The click attribute defines the function that's invoked when the ToggleButton is clicked in its untoggled state, while the toggledClick attribute defines the function that's invoked when the ToggleButton is clicked in its toggled state. In the Play button example, clicking the ToggleButton when it is in its untoggled state invokes the play() function of the VideoPlayer, while clicking the ToggleButton when it is in its toggled state invokes the pause() function of the VideoPlayer.
Various attributes allow you to adjust the appearance of the button graphic: iconAlignmentH and iconAlignmentV control the alignment of the icon within the button, while using iconScale you can increase or decrease the size of the icon.
Note that while the BEML DTD permits a ToggleButton component to be a child of any layout box, in fact it will only function if its parent layout box is a child of a MediaControls element.
The Label is a simple text component that allows for any text to be added to a player. The text can be bound dynamically to any other component's property, for instance to display the name of the currently playing video.
<Label width="160" height="40"
text="{videoPlayer.video.displayName}" type="title"
hAlign="center" vAlign="middle" />
The TitleLabel is a Label component that can render a "selected" state. This is useful for lists where you need to distinguish the selected item. The text in a TitleLabel is displayed using a bold font.
<TitleLabel width="100" height="20" text="{data.displayName}" />
The Image allows for any JPG, GIF or SWF to be loaded into a player, scaled according to the scaleMode attribute of the component.
<Image width="200" height="120" scaleMode="exactFit"
source="http://myserver.com/logo.png" url="http://www.brightcove.com"
tooltip="Go to Brightcove." />
The Link component provides a means to display clickable text within a player to be used to navigate to another URL or call JavaScript.
<Link height="40"
text="{videoPlayer.selectedItem.linkText}"
url="{videoPlayer.selectedItem.linkURL}" />
The Button component provides a way to define a clickable graphic with a label that can broadcast events.
<Button width="80" height="20" text="See more..."
tooltip="Click to visit more videos." />
Various attributes allow you to adjust the appearance of the button graphic: iconAlignmentH and iconAlignmentV control the alignment of the icon within the button, while using iconScale you can increase or decrease the size of the icon.
The ThumbnailButton component displays an image; when the viewer moves the cursor over the image, the button displays a play icon. The click attribute specifies the function to execute when the image is clicked. The source attribute specifies the path to the image to display.
<ThumbnailButton width="80" height="60"
source="{data.thumbnailURL}" />
The List component provides a vertical scrolling list composed of ListItems. Each ListItem in turn specifies its contained elements and their layout. A ListItem can contain any of the supported UI control components, other than a VideoPlayer or a list component. The List component has a minimum size of 100x50.
<List id="playlist" rowHeight="60" automaticAdvance="true">
<ListItem id="videoItem" boxType="hbox" padding="5" gutter="10">
<ThumbnailButton width="67" height="50"
source="{currentItem.thumbnailURL}" click="{playlist.setSelectedIndex(index)}" />
<VBox gutter="5">
<TitleLabel width="225" height="25" vAlign="middle"
text="{currentItem.displayName}" size="18" truncate="true" />
<HBox gutter="10" height="20">
<Button autoSize="true" lockHeight="true"
label="PLAY" labelBuffer="5" click="{playVideo(currentItem)}" />
<Button autoSize="true" lockHeight="true"
label="SHARE" labelBuffer="5" click="{showEmailVideoMenu(currentItem)}" />
<Button autoSize="true" lockHeight="true"
label="GET LINK" labelBuffer="5" click="{showVideoLinkMenu(currentItem)}" />
</HBox>
</VBox>
</ListItem>
</List>
A TileList is a grid list with user-defined list items. A TileList contains ListItems, each of which can contain other components. A ListItem can contain any of the supported UI control components, other than a VideoPlayer or a list component. The TileList component has a minimum size of 100x50. For example:
<TileList id="playlist" rowHeight="60" columnWidth="200" automaticAdvance="true">
<ListItem id="videoItem" boxType="hbox" padding="5" gutter="10">
<ThumbnailButton width="67" height="50"
source="{currentItem.thumbnailURL}" click="{playlist.setSelectedIndex(index)}" />
<VBox gutter="5">
<TitleLabel height="25" vAlign="middle" text="{currentItem.displayName}"
size="18" truncate="true" />
<HBox gutter="10" height="20">
<Button autoSize="true" lockHeight="true"
label="PLAY" labelBuffer="5" click="{playVideo(currentItem)}" />
<Button autoSize="true" lockHeight="true"
label="SHARE" labelBuffer="5" click="{showEmailVideoMenu(currentItem)}" />
<Button autoSize="true" lockHeight="true"
label="GET LINK" labelBuffer="5" click="{showVideoLinkMenu(currentItem)}" />
</HBox>
</VBox>
</ListItem>
</List>
A ListItem must be defined within a List or TileList component. A ListItem can contain any supported component except a VideoPlayer or another list. For example:
<ListItem id="videoItem" boxType="hbox"
padding="5" gutter="10">
<ThumbnailButton width="67" height="50"
source="{currentItem.thumbnailURL}" click="{playlist.setSelectedIndex(index)}" />
<VBox gutter="5">
<TitleLabel width="225" height="25" vAlign="middle"
text="{currentItem.displayName}" size="18" truncate="true" />
<HBox gutter="10" height="20">
<Button autoSize="true" lockHeight="true"
label="PLAY" labelBuffer="5" click="{playVideo(currentItem)}" />
<Button autoSize="true" lockHeight="true"
label="SHARE" labelBuffer="5" click="{showEmailVideoMenu(currentItem)}" />
<Button autoSize="true" lockHeight="true"
label="GET LINK" labelBuffer="5" click="{showVideoLinkMenu(currentItem)}" />
</HBox>
</VBox>
</ListItem>
A ListItem element in a player template can refer to two special values: index and currentItem. The value of index is the integer index in the list of each particular ListItem. The value of currentItem is the data at the index of the List element's dataProvider for each ListItem. For instance, if a List is passed the VideoDTOs from a playlist, each ListItem and all of its subelements can reference its particular VideoDTO through the currentItem value. A ListItem can also use special global functions that enable components in a ListItem to make function calls. For more information, see Calling Functions from ListItems.
<ListItem>
<Image id="thumbnail" source="{currentItem.thumbnailURL}" />
</ListItem>
The TabBar component provides a horizontal paging series of tabs. The TabBar allows for a single selection in the collection. The TabBar displays left and right navigation when the number of tabs exceeds the component dimensions. Optionally, the TabBar can display a tab that produces a dropdown list on rollover. The TabBar component has a minimum size of 8x8.
<TabBar id="playlists" includeMenu="false"
selectedTabHeightOffset="0" />
The ComboBox component is a drop-down selection control that provides navigation similar to a TabBar. You can assign a group of playlists to a ComboBox, allowing selection of a single playlist from the group, or you can assign a single playlist, allowing selection of an individual video from the playlist. The ComboBox can be useful to create more compact player templates than the other selection control components like the TabBar or TileList.
The id attribute of a ComboBox determines whether the ComboBox displays a list of playlists, or a list of videos in a single playlist. To display a list of playlists, use id="playlistCombo"; to display a list of the videos in a single playlist, use id="videoCombo".
In this example, we specify that the ComboBox should display a list of playlists:
<ComboBox id="playlistCombo" height="40" width="40" />
Here is another example that illustrates how a ComboBox can be bound to a list.:
<ComboBox id="playlistCombo" height="25"/>
<List id="videoList" rowHeight="75" automaticAdvance="true"
data="{playlistCombo.selectedItem.videoDTOs}" itemLeading="2">
<ListItem boxType="hbox">
...
</ListItem>
</List>
A formatting component that creates space between other elements. For example:
<Spacer id="smallSpace" height="10" />
The Banner plugs into the advertising capabilities in a player. When a Banner element is included, a new format is allowed and are appended to all ad server calls, informing the ad server that a banner can be displayed. The size of the banner dictates the ad format supported, so a 468x60 banner element by default supports a 468x60 banner ad format. Additional ad formats can be specified as well, so that you can use a large banner area to support several smaller sizes of banner. How those banners are scaled and aligned within the larger area is controlled by the Banner's attributes.
<Banner width="468" height="60" />
The ExpandingBanner plugs into the advertising capabilities in a player. When an ExpandingBanner element is included, two new formats are allowed and are appended all ad server calls informing the ad server that a banner can be displayed. The size of the banner dictates the ad formats supported, so a 468x60 banner element by default supports a 468x60 banner ad format and a 468x60 synched banner unit. Additional ad formats can be specified as well, so that a large banner area can actually be made to support several smaller sizes of banner. How those banners are scaled and aligned within the larger area is controlled by the attributes.
This Developer Center article provides a detailed example of how to use an ExpandingBanner in an advertising context.
<ExpandingBanner width="468" height="60"
expandedHeight="360" expandedOffsetY="-50"
disableOnExpand="list" />
The SWFLoader component allows you to specify a custom-developed SWF to be loaded, positioned, and sized within a player. You can develop a custom component using ActionScript 3 and the Brightcove Player API. Note that an ActionScript 2 SWF will not be able to interact with the player. In order for the loaded SWF to be passed a handle to the runtime API, so that it can listen for events and interact with the rest of the player, it should implement the interface defined by the following method signature:
function setInterface(obj:Object):void;
For example:
function setInterface(player:Object):void {
mPlayer = player;
var experienceModule:Object = mPlayer.getModule("experience");
if (experienceModule) {
experienceModule.addEventListener("templateReady", onTemplateReady);
}
}
A SWFLoader element is similar to a Module element. Both load a custom SWF. However, since the SWFLoader can be placed in a layout component or a ListItem and has size and position attributes, it is suitable for custom components that are to be displayed in the player. The Module element cannot be a child of a layout component and can be used only for custom components that are not to be displayed in the player. For more information, see Creating Custom Player Components.
The SWFLoader element includes attributes that specify the the URL of the custom SWF (which must be hosted outside of Brightcove) and the size of the custom component when it is rendered within the player layout. For example:
<SWFLoader width="300" height="220" source="http://www.myserver/mySWF.swf" />
Learn more about the elements that make up a player template: