Developing Player Templates

A Video Cloud player is specified by an XML document called a player template. Video Cloud includes a number of standard player templates, but also gives you the ability to create custom player templates. This document describes the main elements of a custom player template.

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

This topic includes the following information:

Main elements in BEML

The XML that you use in a custom 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, 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 in your XML file 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 the topic, 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 Video Cloud 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 can 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 Video Cloud 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.

ChromelessVideoPlayer

The ChromelessVideoPlayer looks like a VideoDisplay component, with no player control "chrome." When the viewer places his mouse over the video display area, the player controls appear at the lower part of the video display.

MediaControls

A layout container that contains other components that control playback, including a Playhead and ToggleButtons.

Playhead

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.

VolumeControl

A vertical slider that controls audio volume during playback.

ToggleButton

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.

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 currently-selected item.

Image

An Image loads a scalable visual element (.jpg, .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. Custom modules for Flash players must be compiled into a SWF files, while modules for HTML5 players must be JavaScript files; both must be 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.

Requiring and Validating SWF Modules

You can require that a SWF plug-in be successfully loaded before the player is loaded by including the attribute required="true". You can also validate the checksum of the SWF file by including the attribute hash="[SHA1 hash code for the file]":

<Module file="http://ruggs.net/stuff/plugins/TestPlugin.swf" required="true" hash="d7bff4532be0fff524e4f2feb2d79c998f30031f" >
  <param name="currentVideo" value="{videoPlayer.video.displayName}"/>
</Module>

The required attribute indicates that a plugin is required for the player to function. If the plugin can not be loaded for any reason the player will abort loading and a template error event will be fired with a code 16, type PE_REQUIRED_COMPONENT.

When the hash attribute is used, if the module is loaded and the checksum does not match expectations one of two errors will be thrown. If the module is not required it will be code 18, type PE_COMPONENT_CORRUPTED. If the module is required it will be code 17, type PE_REQUIRED_COMPONENT_CORRUPTED. When the error is PE_COMPONENT_CORRUPTED the player is allowed to load but the plugin is not loaded.

Note: parameters added to the path for the SWF file are not supported for required plug-ins. Parameters must be added using the param element instead, as in the sample code above.

For further help

If you are having trouble styling your BEML player in the Publishing module, Brightcove Support is available to help. You can submit a case here. To make sure you get the fastest response possible, below is a list of what support will need to solve the problem.

  • Your Publisher ID / Publisher Name
  • Name of the player template that you are trying to customize in the Publishing module
  • A screenshot of the problem in the browser
  • The Player ID or the URL of the page you are testing

After your case is submitted, you will receive an email confirmation from Brightcove Support. To provide additional information on your case to Brightcove Support, reply to the confirmation email.

What's Next...

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

Post new comment

The content of this field is kept private and will not be shown publicly.
0

Comments