This project is read-only.

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-dark.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>
data-win-control: 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>
Note: Download the source zip and run the Samples application to view samples that demonstrate the available features of the player framework, custom player styling, and a variety of other use cases.

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>
Video element API: Another important thing to understand is that all properties, methods, and events available on the video element are also automatically available on the MediaPlayer control. This means that if you are familiar with the video element, then 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 element directly.

Plugins

The primary reason the player framework is considered a "framework" and not just a "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 and behavior of the MediaPlayer control. In fact, many of the player framework's features are implemented as plugins, such as playlists, captions, and advertising.

Plugins can have their own APIs, but via the dynamic nature of JavaScript, a plugin can also add a property for itself on the main MediaPlayer control. For example, you can set the playlistPlugin.autoAdvance property like this:

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>
Note: This applies to any property on the MediaPlayer, including properties that have been added by plugins.

Styling

The player framework exposes as much of its UI as possible via CSS. This means that you can easily extend and 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 includes a Custom User Experience sample that demonstrates how to style the MediaPlayer control very differently from the default look.
  • 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 which will help you determine how to extend and override the default styles.
  • Use the DOM Explorer in Visual Studio to view and modify the CSS at runtime to see what effect it has.

Last edited Jan 28, 2013 at 11:44 PM by timgreenfield, version 22