Developing Player Templates

Applies to Roles
Developer
Version
Brightcove 4
Modules
BEML
Edition
Pro, Enterprise

Custom player templates are available only for Brightcove Pro and Enterprise customers. If you are interested in upgrading your Brightcove account, please contact Brightcove for more information.

A Brightcove player is specified by an XML document called a player template. Brightcove includes a number of standard player templates, but also gives you the ability to create custom player templates. This document describes how to write the XML document that specifies your custom player template.

Main Elements in BEML

The XML you use in a player template is defined by the document type definition (DTD) for the Brightcove Experience Markup Language (BEML). The BEML DTD Reference describes all of the XML elements and attributes that you can use in a BEML document. The standard player templates may be a useful starting point for your custom player template development. You can download the BEML for each of the standard player templates as a .zip file.

Each element in a player template defines some visual or non-visual aspect of a player. An element can define a UI element, like a text label, a banner, or a video player, or a layout element, that defines how the UI elements are arranged in relation to each other and the overall player layout. The attributes of player elements define such things as the elements' location (in terms of x, y coordinates), the style, and the source of the data to display (video name, image location, etc.) The main elements in a player template include:

BEML and XML

Because a BEML player template is an XML document, you need to understand the basics of XML to be able to develop a custom player template using BEML. If you need a primer on XML, here are a few basic resources:

The single problem you are most likely to encounter is with special characters. In XML markup, be sure to escape the following five special characters:

Character
Escaped form
<
&lt;
>
&gt;
&
&amp;
'
&apos;
"
&quot;

In addition, be sure not to include extra white space in XML attributes. For example, do this:

<element id="foo" />

and not this:

<element id = "foo" />

The extra white space before and after the equals sign in this example prevents the player template from being styled in the Publishing module.

Labels element: Customize and localize text

Using the Labels element in a player template, you can customize the text of every label in your player. This enables you to create a player with labels in most languages, as well as customize the text for style, branding, promotion, or other purposes. For more information, see Localizing players.

Theme element: Customize look and feel

Using the Theme element in a player template, you can customize the look and feel of your custom Brightcove players. Depending on the degree of customization you require, you can use the Theme element and Style elements to:

Note that if a player template does not include a Theme element, then you will not be able to use the Publishing module to modify the styles of a player that is based on that player template. For more detail, see Themes and styles in player templates.

Layout element: Customize positioning

The Layout element controls which UI elements are included in a player and where they are positioned within the player. A Layout element can contain two types of child elements: layout boxes and components. Layout boxes are containers for other elements, which can be either additional layout boxes or components. The containing layout box defines how the child elements are laid out and sized. Components are the UI elements themselves, like a VideoPlayer, Label, or Image.

In general, layout boxes are non-rendering, though you an assign a background color and a background image to a layout box that will be rendered behind all of its child elements. You can use the following standard layout boxes:

Canvas
The simplest of the layout boxes. Child elements in a Canvas are positioned absolutely within the canvas box at the (x, y) position specified in the child element.
HBox
A horizontal box that lays out all its child elements horizontally. Child elements in an HBox are positioned sequentially from left to right, with each child element being placed directly to the right of the preceding child element, with an optional gutter between.
VBox
A vertical box that lays out all its child elements vertically. Child elements in a VBox are positioned sequentially from top to bottom, with each child element being placed directly below the preceding child element, with an optional gutter between.
Grid
A layout box that allows for a more complex layout, with child elements laid out in columns and rows.
TextRegion
A TextRegion allows you to group together text components (like labels, links, etc.) and express the group as a more unified component in the Publishing module styling mode. This includes new functionality to specify the background and border colors of the region.

For more information about the Layout element and layout boxes, see Layout elements in player templates.

Components: UI elements

Components include several different classes of objects that you can include in the layout of a player. A component can be visual, like a VideoPlayer or an Image, or non-visual. Here's how some of these elements appear in a player:

Brightcove includes the following standard components, each of which is described in more detail in Components in player templates and the BEML DTD Reference:

VideoPlayer
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.
VideoDisplay
A video window without the standard media control bar.
Label
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.
TitleLabel
A Label component that can render a "selected" state. This is useful for lists where you need to distinguish the selected item.
Image
An Image loads a scalable visual element (JPEG, GIF or SWF) into a player.
Button
A clickable graphic with a label that can broadcast events.
ThumbnailButton
Displays an image; when the viewer moves the cursor over the image, the button displays a play icon.
Link
Provides a means to display clickable text within a player to be used to navigate to another URL or to call JavaScript.
List
A vertical scrolling list with user-defined list items. A List contains ListItems, each of which can contain other components.
TileList
A grid list with user-defined list items. A TileList contains ListItems, each of which can contain other components.
ListItem
A ListItem must be defined within a List or TileList component. This serves as the visual definition of all list items rendered within that list. The definition of a ListItem uses the same BEML as a Layout element. Its subcomponents can be any supported component except a VideoPlayer or another List.
Banner
The Banner plugs into the advertising capabilities in a player. When a banner node 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.
ExpandingBanner
The ExpandingBanner plugs into the advertising capabilities in a player. When a expanding banner node is included, two new formats are 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 formats supported, so a 468x60 banner element by default supports a 468x60 banner ad format and a 468x60 synched banner unit.
Spacer
A formatting component that creates space between other elements.
TabBar
A series of tabs that page horizontally. 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.
SWFLoader
The SWFLoader component enables loading custom components that can be positioned and sized within a player. The loaded SWF is passed a handle to the runtime API so that it may listen for events and interact with the rest of the player. For more information about custom components, see Creating custom player components and Adding a custom component to a player template.

Modules element: Custom components

You can use the Modules element to load non-rendering custom components into your players. A custom module must be compiled into a SWF file and hosted outside of Brightcove. In order to specify a custom module, include as a child of the Modules element a Module element that contains a file attribute with the path to the SWF to be loaded. For example:

<Modules>
  <Module file="http://myserver/customReporting.swf" />
</Modules>

The Module element can optionally include any number of parameters, which will be passed through to the SWF when it loads:

<Module file="http://server/file.swf">
  <param name="foo" value="bar" />
  <param name="food" value="grill" />
</Module>

The values of the parameters can also be bound to other elements in the player template. For instance, if a module needed a flashvar param set in the HTML as well as the name of the video every time it changed, the following BEML would allow for that:

<Module file="http://server/file.swf">
  <param name="customParam" value="{player.parameters.customParam}" />
  <param name="videoName" value="{videoPlayer.video.displayName}" />
</Module>

A Modules element can include more than one Module child element, if you have more than one SWF you want to load in the player. For custom components that need to be rendered in the player, use the SWFLoader component instead. For more information about custom components, see Creating custom player components and Adding a custom component to a player template.

What's Next...

Learn more about the elements that make up a player template:

Tags