JavaScript usage guide
The Windows 8 JavaScript version of the player framework works much like
other WinJS controls. This is a high level guide to help show you how to add, initialize, and style the player framework.
Adding the player framework to your HTML
First, make sure the player framework project reference is added to your application. Next, add the necessary player framework CSS and script references to your HTML. Finally, add a div tag for your MediaPlayer control. See the
Getting Started Guide for step-by-step instructions. Once you're done, your HTML should look something like this:
<!-- PlayerFramework references -->
<link href="/Microsoft.PlayerFramework.Js/css/PlayerFramework.css" rel="stylesheet">
<script src="/Microsoft.PlayerFramework.Js/js/PlayerFramework.js"></script>
<div data-win-control="PlayerFramework.MediaPlayer" data-win-options="{ width: 640, height: 360, src: 'http://smf.blob.core.windows.net/samples/videos/wildlife.mp4' }"></div>
By default, the JS file associated with your HTML page should already include a call to WinJS.UI.processAll(). This function tells WinJS to find all elements with data-win-control attributes and initialize the appropriate controls. In this case, the PlayerFramework.MediaPlayer control is defined in PlayerFramework.js (loaded via the script tag you added). Internally, the player framework expects to find a video tag as a child of the main div tag, otherwise it will add one for you by default.
data-win-options: You can set options on the MediaPlayer control either via the data-win-options attribute (as shown above), by declaring attributes on the child video tag (if you added one), or by setting properties directly on the control in code.
data-win-bind: Like other WinJS controls, writable properties of the MediaPlayer control can also be set via declarative bindings. The following example shows how to bind to the src property:
<div data-win-control="PlayerFramework.MediaPlayer" data-win-options="{ width: 640, height: 360 }" data-win-bind="winControl.src: source;"></div>
Initializing the player framework in your HTML
Like other WinJS controls, initialization of the player framework can be done in HTML via the
data-win-options attribute. This attribute takes a JSON object that contains property values to help define how the control should look and behave. Note: You could also set these properties in code.
The player framework allows you to specify any option defined as a writable property on the PlayerFramework.MediaPlayer control. See a list of properties in the
Player Framework's JavaScript API reference. For example, there are two properties on MediaPlayer called isRewindVisible and isFastForwardVisible which specify whether to show rewind and fast forward buttons in the MediaPlayer's control panel. By default these properties are both false, but you can set them to true in your JSON options as shown below:
<div data-win-control="PlayerFramework.MediaPlayer" data-win-options="{ width: 640, height: 360, src: 'http://smf.blob.core.windows.net/samples/videos/wildlife.mp4', isRewindVisible: true, isFastForwardVisible: true }"></div>
Another important thing to understand is that all
properties, methods, and events available on the video tag are also automatically available on the MediaPlayer control. This means that if you are familiar with the video tag, you already know a large part of the player framework's API. This also means that there is rarely a reason to access the control's internal video tag directly.
Plugins
The primary reason the player framework is considered a "framework" vs. "control" is because it supports an extensible plugin architecture that allows other components to be created and connected to the player framework in order to add new features or to change the default look or behavior of the control. In fact, many of the player framework's features are implemented as plugins.
Plugins can have their own APIs, but via the dynamic nature of JavaScript, a plugin can extend the MediaPlayer's API by adding a property for itself on the main MediaPlayer control. For example, you can set the autoAdvance property of the PlaylistPlugin as follows:
mediaPlayer.playlistPlugin.autoAdvance = true;
This also make it possible to set properties on a plugin through the JSON options just like any other property found on the MediaPlayer control. For example:
<div data-win-control="PlayerFramework.MediaPlayer" data-win-options="{
width: 600,
height: 400,
playlistPlugin: {
autoAdvance: true,
playlist: [
{
src: 'http://smf.blob.core.windows.net/samples/videos/bigbuck.mp4'
}, {
src: 'http://smf.blob.core.windows.net/samples/videos/wildlife.mp4'
}
]
}
}"></div>
Playlists
One special plugin shipped with the player framework is the PlaylistPlugin. This plugin allows you to create a media playlist that the user can either play continuously or skip through. Additionally, you may want to set certain properties on the MediaPlayer depending on the current playlist item. To support this, any property that you can normally set through the MediaPlayer's JSON options can also be set via a special playlist option. The example below shows the skip next and skip previous buttons, and includes a playlist where the src property will be set depending on the current playlist item:
<div data-win-control="PlayerFramework.MediaPlayer" data-win-options="{
width: 600,
height: 400,
isSkipPreviousVisible: true,
isSkipNextVisible: true,
playlistPlugin: {
playlist: [
{
src: 'http://smf.blob.core.windows.net/samples/videos/bigbuck.mp4'
}, {
src: 'http://smf.blob.core.windows.net/samples/videos/wildlife.mp4'
}
]
}
}"></div>
But what if you wanted to hide the skip previous button for the first playlist item and show it for the last one? In this example, you could simply move any property into the JSON options for a particular playlist item:
<div data-win-control="PlayerFramework.MediaPlayer" data-win-options="{
width: 600,
height: 400,
playlistPlugin: {
playlist: [
{
isSkipPreviousVisible: false,
isSkipNextVisible: true,
src: 'http://smf.blob.core.windows.net/samples/videos/bigbuck.mp4'
}, {
isSkipPreviousVisible: true,
isSkipNextVisible: false,
src: 'http://smf.blob.core.windows.net/samples/videos/wildlife.mp4'
}
]
}
}"></div>
Styling
The player framework exposes as much of its UI as possible via CSS. This means that you can easily override the default styles. To find out more about styling via custom CSS, we recommend a few different resources:
- Download the source zip. The source solution contains many samples, including a Custom UX sample that demonstrates how to build a heavily customized player with a very unique look from the default look of the player framework.
- Look at the CSS shipped with the player framework. You can expand your project reference and double-click the PlayerFramework.css file in Visual Studio to view the source CSS.
- Use the DOM Explorer in Visual Studio to view and modify the CSS at runtime to see what effect it has.