CPE Sample
Implementation
DRAFT
Ref :
TR-CPE-SIMPL
Version :
v0.10
Date: January 23, 2015
Cross Platform Extras
Sample Implementation
User’s Guide
Motion Picture Laboratories, Inc.
CONFIDENTIAL
1
CPE Sample
Implementation
DRAFT
Ref :
TR-CPE-SIMPL
Version :
v0.10
Date: January 23, 2015
CONTENTS
1
Introduction .............................................................................................................................. 5
1.1
Scope ............................................................................................................................... 5
1.1.1
Cross Platform Extras Sample Implementation ......................................................... 5
1.1.2
Intended Audience .................................................................................................... 5
1.2
Document Organization .................................................................................................... 5
1.3
References ....................................................................................................................... 6
1.4
Resources ........................................................................................................................ 6
1.5
Acknowledgements .......................................................................................................... 6
2
Demonstrating the CPE API ..................................................................................................... 7
2.1
Capabilities ....................................................................................................................... 7
2.2
Available Content ............................................................................................................. 7
2.3
Using ................................................................................................................................ 7
2.3.1
Accessing ................................................................................................................. 7
2.3.2
Package Selection .................................................................................................... 8
2.3.3
Package Intro............................................................................................................ 8
2.3.4
Package Main Menu Page ........................................................................................ 9
2.3.5
Creating an Account & Logging In ........................................................................... 10
2.3.6
Setting Preferences ................................................................................................ 10
2.3.7
‘Acquiring’ Content Rights ....................................................................................... 11
2.3.8
Playing a Movie ...................................................................................................... 11
2.3.9
Bookmarks .............................................................................................................. 13
2.3.10
Wishlists ................................................................................................................. 13
2.3.11
Timed Events .......................................................................................................... 14
2.3.12
Social Networking ................................................................................................... 14
3
Learning and Using the Sample Implementation .................................................................... 15
3.1
Testbed Set-up and Configuration .................................................................................. 15
3.2
Package Integration ........................................................................................................ 16
3.2.1
Accessing the Framework API ................................................................................ 16
3.2.2
Making a Package Available for Selection............................................................... 18
3.2.3
Making a Package Runable .................................................................................... 19
3.2.4
Interactions with the Framework ............................................................................. 20
4
Developing and Customizing .................................................................................................. 22
4.1
Overview ........................................................................................................................ 22
4.2
Use of Source Code and Licensing................................................................................. 22
4.3
SI Framework Architecture ............................................................................................. 22
4.3.1
HTML ...................................................................................................................... 22
4.3.2
JavaScript for Framework ....................................................................................... 24
4.3.3
JavaScript for UI Construction................................................................................. 25
4.3.4
Stylesheets ............................................................................................................. 26
4.3.5
Accessing Back-End Services (BES) ...................................................................... 26
4.4
SI Package Architecture ................................................................................................. 28
4.4.1
Overview ................................................................................................................. 29
Motion Picture Laboratories, Inc.
CONFIDENTIAL
2
CPE Sample
Implementation
DRAFT
5
6
Ref :
TR-CPE-SIMPL
Version :
v0.10
Date: January 23, 2015
4.4.2
Interactions between Package and Base ................................................................ 29
Framework Development & Customization ............................................................................. 40
Package Development & Customization ................................................................................. 41
NOTICES
This work is licensed under a Creative Commons Attribution 3.0 Unported License.
NOTE: No effort is being made by the Motion Picture Laboratories to in any way obligate any market
participant to adhere to this specification. Whether to adopt this specification in whole or in part is left entirely
to the individual discretion of individual market participants, using their own independent business judgment.
Moreover, Motion Picture Laboratories disclaims any warranty or representation as to the suitability of this
specification for any purpose, and any liability for any damages or other harm you may incur as a result of
subscribing to this specification.
Motion Picture Laboratories, Inc.
CONFIDENTIAL
3
CPE Sample
Implementation
DRAFT
Ref :
TR-CPE-SIMPL
Version :
v0.10
Date: January 23, 2015
REVISION HISTORY
Version
Date
Description
V0.8
2014-08-27
First preliminary draft circulated for comments.
V0.9
2014-12-03
Revised to reflect refactoring of framework, inclusion
of new functionality, and changes to the demonstration
package UX.
Motion Picture Laboratories, Inc.
CONFIDENTIAL
4
CPE Sample
Implementation
DRAFT
Ref :
TR-CPE-SIMPL
Version :
v0.10
Date: January 23, 2015
1 INTRODUCTION
1.1 Scope
1.1.1 Cross Platform Extras Sample Implementation
This guide provides both an overview and technical introduction to the Cross Platform
Extras Sample Implementation (CPE-SI). The Sample Implementation is itself intended to serve
multiple purposes. These include:
•
To provide a hands-on interactive demonstration of the concepts and capabilities of the CPE
API
•
To validate the Cross Platform Extras API.
•
To provide developers with a test environment that includes a sample implementation of the
API that may be used to test the compliance of their framework or package.
•
To provide open source code for developers to use as a starting point for their own
development efforts.
The structure and content of this document therefore reflects the variety of concerns and
goals that users of the Sample Implementation may have.
1.1.2 Intended Audience
It is assumed that readers of this document are familiar with the goals of the Cross Platform
Extras project. Information can be found at www.movielabs.com/cpe.
Developers must be familiar with the APIs document in Cross Platform Extras Interface
[CPE-API].
It is strongly recommended that developers read Sections 1 to 4 of [CPE-API] to familiarize
themselves with the concepts behind the API.
Developers are assumed to be proficient in both JavaScript and CSS.
1.2 Document Organization
The organization of this document reflects the intended uses of the Sample Implementation.
Section 1, this part, provides introductory material including references and links to additional
resources. Sections 2 through 4 each addresses a different use:

Section 2: Use of the SI web site to demonstrate the Cross Platforms Extra concept

Section 3: Use of the SI software as a testbed for validating package integration
Motion Picture Laboratories, Inc.
CONFIDENTIAL
5
CPE Sample
Implementation
DRAFT

Ref :
TR-CPE-SIMPL
Version :
v0.10
Date: January 23, 2015
Section 4: Use of SI code as basis for further development of custom framework or
packages.
Sections 5 and 6 are intended to cover in more detail the material presented in Section 4.
1.3 References
[CPE-API]
Cross Platform Extras, www.movielabs.com/cpe
1.4 Resources
The Sample Implementation is hosted online for those who wish to test or demonstrate its
capabilities using a standard web browser. Access to the demonstration implementation, as well as
supporting documentation and code is at http://test.movielabs.com/cpe/. The implementation may
be removed at any time
1.5 Acknowledgements
Our demonstration uses content made available under Creative Commons licensing. We
gratefully acknowledge the organizations and people whose willingness to share their fine work
makes our demonstration possible. Content providers include:
“Sintel” and “Big Buck Bunny” courtesy of The Blender Foundation: www.blender.org.
“Sita Sings the Blues” courtesy of Nina Paley: http://www.sitasingstheblues.com
Motion Picture Laboratories, Inc.
CONFIDENTIAL
6
CPE Sample
Implementation
DRAFT
Ref :
TR-CPE-SIMPL
Version :
v0.10
Date: January 23, 2015
2 DEMONSTRATING THE CPE API
The CPE-SI demonstration web site is intended to provide a hands-on interactive
demonstration of the concepts and capabilities provided by a CPE implementation and to validate
the Cross Platform Extras API. The demonstration site mimics an on-line retail distribution channel
that allows consumers to 'buy' or 'rent' content packages.
2.1 Capabilities
Current functionality provided by the demonstration site includes:

Access via any HTML5-compliant browser.

Creation of a user account. Each account is allocated 20 credits for 'buying' and 'renting'
content.

Selection of a package with immediate access to any 'free' content.

Logged-in users may use available credits to buy or rent content.

Access rights that have been purchased are available when logging in from any device
or platform.
2.2 Available Content
All content is open-source and freely available on the Internet (see Acknowledgements in
1.5). The use of credits for 'buying' and 'renting' content is strictly for the purpose of emulating
actual transactions. No ownership or actual rights are obtained or transferred via the use of this
software.
2.3 Using
2.3.1 Accessing
The demonstration is accessed via a HTML5-compliant browser. Use of Chrome is
recommend. Internet Explorer is not supported at this time. See Resources in Section 1.4 for
information on how to access the online demo.
Figure 1 shows the initial view, referred to as the storefront. Graphics for all known packages are
shown in a scrollable display. There are six packages displayed. Currently only three of these are
active and available.
The header bar across the top of the page provides access to social media as well as the ability to
log-in or establish an ‘account’. The user may log in or out at any time. Any attempt to access a
feature not yet supported will result in a “Work in Progress” message (Figure 2).
Motion Picture Laboratories, Inc.
CONFIDENTIAL
7
CPE Sample
Implementation
DRAFT
Ref :
TR-CPE-SIMPL
Version :
v0.10
Date: January 23, 2015
Fig. 1: Storefront view
2.3.2 Package Selection
Packages are selected by a LEFT-click on the
associated graphic. Selection of any movie that is not
yet implemented in the demo will result in a “work in
progress” pop-up message. To dismiss the pop-up,
LEFT-click anywhere outside of the pop-up or click on
the “X” in the upper right corner.
2.3.3 Package Intro
When a package is selected, control of the main pane of the browser window is handed over
to the package. Note that while the package has control of the page's central panel, the framework
(i.e., retailer) retains control of the Retailer's menu bar which is always displayed at the top of the
page:
Fig. 3: Retailer Menu Bar
It is up to the implementer of a package what will be shown to a user at any point, what
the available options are, and how users will navigate through the package's display modes.
The SI demo packages will initially display a Main Menu page with an overlay describing what
features of the CPEx API are highlighted by that package. It will also acknowledge the content
provider appropriate to that package (e.g., the Blender Foundation)
Motion Picture Laboratories, Inc.
CONFIDENTIAL
8
CPE Sample
Implementation
DRAFT
Ref :
TR-CPE-SIMPL
Version :
v0.10
Date: January 23, 2015
Fig. 4: Initial Display
2.3.4 Package Main Menu Page
The SI demo package uses a Main Menu page with overlaid icons acting as buttons:
Fig. 5: Package Main Menu (example)
The icons that will initiate playing of content will have a colored border. A green border
indicates the content is accessible to the user while a magenta border indicates content they must
first “purchase” or “rent”.
In the example shown in Figure 5, selecting the Trailer icon will allow the user to view the
Sintel trailer. Note that this icon is enabled because the trailer has been designated as free content.
The movie itself, however, has not. The Play icon, therefore, will remain disabled until the logged-in
Motion Picture Laboratories, Inc.
CONFIDENTIAL
9
CPE Sample
Implementation
DRAFT
Ref :
TR-CPE-SIMPL
Version :
v0.10
Date: January 23, 2015
user has acquired the rights to view it. Before the rights may be acquired (i.e., the move purchased
or rented) the user must, however, log in.
2.3.5 Creating an Account & Logging In
To either log in or to create a new account use the log-in button in the Retailer's menu bar.
When a new account has been successfully created a welcome message will be displayed:
Once a user has logged in, the Retailer's menu bar will display the user's name and the
Login button will be with two drop-down menus:
2.3.6 Setting Preferences
.Access to the Preference menu is via the Account menu. This means that you must be
logged in to set a preference.
The SI Demo currently provides the ability to set only one preference: language. The
available languages will be displayed in a drop-down menu:
Motion Picture Laboratories, Inc.
CONFIDENTIAL
10
CPE Sample
Implementation
DRAFT
Ref :
TR-CPE-SIMPL
Version :
v0.10
Date: January 23, 2015
The framework header menus will adjust automatically to a change in language preference:
The ability of a package to change language will be a package-specific capability. Currently,
only the Sita Sings The Blues package implements this feature.
2.3.7 ‘Acquiring’ Content Rights
Clicking on the Acquire icon will activate the Retailer's Purchase Dialog. The one used by
the demo site is as follows:
Once rights are acquired the Acquire icon will be replaced with an activated Play icon.
2.3.8 Playing a Movie
All video content is played using a standard HTML5 Video element. Users may enter and
exit full-screen mode, adjust volume, pause, or resume using the standard control bar. If the
package provides access to the advanced control mode, the user may slow or speed-up the
Motion Picture Laboratories, Inc.
CONFIDENTIAL
11
CPE Sample
Implementation
DRAFT
Ref :
TR-CPE-SIMPL
Version :
v0.10
Date: January 23, 2015
playback, repeat the last 5 seconds, or reverse the direction of playback. The control bar for the
advanced mode is shown in Figure 10.
NOTE: the advanced controls are not available when in full-screen mode. The control
interface will change to the basic player controls when entering full-screen mode and then revert
Fig. 10: Advanced Control Bar
back to the advanced controls when the user returns to the normal display mode.
Playback control is also accessible via a pop-up menu that is activated by a RIGHT click
anywhere on the video. The pop-up menu is also the mechanism for accessing the Bookmark
functions.
The video screen will have two overlaid icons:

A “return” button in the lower left corner signals the package to terminate playback
and return to the package main menu.

The Movie Labs icon in the lower-right corner may be used to terminate playback,
exit the package, and return the user to the Retailer’s Storefront display.
Fig. 11: Video Screen with Overlays
Motion Picture Laboratories, Inc.
CONFIDENTIAL
12
CPE Sample
Implementation
DRAFT
Ref :
TR-CPE-SIMPL
Version :
v0.10
Date: January 23, 2015
2.3.9 Bookmarks
When logged in a user may access the bookmark functions.
Bookmarks may be added, deleted, or used by means of the pop-up
menu previously described. The following functions are provided:

Previous Bookmark: shift the current media location to that
of the closest bookmark to the current location but
occurring earlier in the playback sequence. The meaning
of “earlier” will be dependent on the current direction of
playback (e.g., when playback is reversed a location 20
minutes into the stream is considered “earlier” than a
location 10 minutes into the stream).
Fig 12: Pop-up Menu

Next Bookmark: shift the current media location to that of
the closest bookmark to the current location but occurring later in the playback
sequence.

Avail Bookmarks: displays a list of bookmarks sorted chronologically

Add Bookmark: allows user to set a bookmark at the current location. Play is paused
while the bookmark is being set. NOTE: this function is currently not usable when in
full-screen mode.

Delete Bookmark: allows user to delete any previously set. NOTE: this function is
currently not usable when in full-screen mode
2.3.10 Wishlists
A drop-down menu supporting wishlists is included in the Retailer header bar. This
function is a work-in-progress and is not accessible in the current SI release.
Motion Picture Laboratories, Inc.
CONFIDENTIAL
13
CPE Sample
Implementation
DRAFT
Ref :
TR-CPE-SIMPL
Version :
v0.10
Date: January 23, 2015
2.3.11 Timed Events
Fig. 13: Example of Timed Event Overlay
At several points during the playing of Sintel, simulated social commentary will be displayed
in red text at the bottom center of the player area:
Currently the demo software only allows the display of these simulated Notices. Future
releases will also support social networking functions accessing this part of the API.
2.3.12 Social Networking
Access to social networks is available via the drop-down menus in the upper-left of the
window. Note that this functionality is only partially supported at this time. Current level of support
is:

Twitter: fully supported

Facebook: not available

Tumblr: partial support
Motion Picture Laboratories, Inc.
CONFIDENTIAL
14
CPE Sample
Implementation
DRAFT
Ref :
TR-CPE-SIMPL
Version :
v0.10
Date: January 23, 2015
3 LEARNING AND USING THE SAMPLE IMPLEMENTATION
Following are key design points for the Sample Implementation
•
Implemented in JavaScript
•
The API is instantiated via one set of JavaScript files that define all the constants that are
included in the API. The implementation of the packages and framework is in another set of
JavaScript files.
•
All interactions of a package with the framework are via a globally accessible variable:
CpxFramework. This variable is also passed to the package as an argument of the
initialize() function.
•
The modular design of the framework is closely matched to the groups and subgroups
defined by the API (e.g., CpxFramework.PackageMgmt implements the Package
Management group). See Section 3.2.1 for details.
Additional modules that are used by the Framework are covered in the sections discussing
Developing and Customizing.
•
To deploy a package the developer must provide:
1. one or more JavaScript files
2. a single image file that will act as the 'storefront icon' for the package.
3. A JSON-formatted file with metadata regarding any content accessible via the
package. This metadata includes the specification of access rights that a consumer
may acquire and a URL from which to stream or download the content.
•
There is also the option to provide a CSS file.
3.1 Testbed Set-up and Configuration
A CPE testbed may be set-up using any available web server.
1. Download the latest version of the CPE_RefImplementation zip file into a sub-directory
of your web server's directory tree. This will be the {Install_dir}
2. Unzip into the {Install_dir}. The following sub-directories will be created:
•
{Install_dir}/html
•
{Install_dir}/resources
•
{Install_dir}/scripts
Motion Picture Laboratories, Inc.
CONFIDENTIAL
15
CPE Sample
Implementation
DRAFT
•
Ref :
TR-CPE-SIMPL
Version :
v0.10
Date: January 23, 2015
{Install_dir}/styles
3. The testbed requires the use of a back-end service to support various functions relating to
social networking, account access, and cross-platform preferences. The testbed is currently
configured to use Firebase. Free accounts are available at www.firebase.com to support up
to fifty users. Once an account has been created, the URL that has been assigned to it must
be entered into the testbed. This is done by editing the file
{Install_dir}/scripts/demo/framework/BES/FireBase.js.
The value of the variable accntRoot should be changed to that associated with your
account, e.g.,
var accntRoot = 'https://furious-flame-21234.firebaseio.com/';
4. You may now run the Demo Retailer to verify proper installation. Using a suitable browser1,
access the URL mapping to {Install_dir}/html/DemoRetailer.html
The downloaded zip file includes all of the files required to access the packages described
in Section 2. If you are unable to create a new user account and/or login it is probably due to not
having configured the Firebase accntRoot correctly.
3.2 Package Integration
This section describes the procedure for integrating a CPE package with the Sample
Implementation (SI) framework. It is strongly recommended that readers be familiar with the
material covered in the Cross Platform Extras Interface document. A working knowledge of
JavaScript is also highly advantageous.
3.2.1 Accessing the Framework API
The CPE API is defined in terms of six groups:
1
•
Package Management API Group
•
Content Access API Group
•
Account Access API Group
•
Player Interaction API Group
•
Social Networking API Group
•
Enhancements API Group
Chrome is recommended. Firefox should also work. Use of IE is not yet supported.
Motion Picture Laboratories, Inc.
CONFIDENTIAL
16
CPE Sample
Implementation
Ref :
TR-CPE-SIMPL
Version :
v0.10
Date: January 23, 2015
DRAFT
Each group is further divided into sub-groups. A sub-group may be designated as
OPTIONAL or MANDATORY. The table below indicates which sub-groups are currently supported
by the Sample Implementation framework and, if supported, the method for invoking.
For most sub-groups, access to a function is via a global variable defined for the group. For
example, the Content Access API Group is supported by var CPX_ContentMgmt. Thus, to invoke
the 'getAvailability' function, a package could use the code
var accessCodes = CPX_ContentMgmt.getAvailability(contentId);
The exception to this design pattern is the Player Interaction group. The functionality of the
Lifecycle sub-group is accessed via a global CPX variable. This may be used to create media
players which, in the Sample Implementation framework, are represented by an instance of the
PlayerWrapper class. Access to all other player-related sub-groups is via a PlayerWrapper.
Group
Package Mgmt.
Table 1: API Compliance
Subgroup
Status
Access Mechanism
var CpxFramework.PackageMgmt
Lifecycle
M - Supported
Connectivity
Environment
O
O
Availability
M - Supported
var CpxFramework.ContentMgmt
Access Event
Download
M - Supported
O
var CpxFramework.ContentMgmt
Account Access
Basic
Account Event
M - Supported
M - Supported
var CpxFramework.AccountMgmt
Player Interaction
Lifecycle
M - Supported
var CpxFramework.PlayerMgmt
Basic
Trickplay
M - Supported
O- Supported
instance of PlayerWrapper
Controls
O- Supported
instance of PlayerWrapper
Sound
Player Event
O (partial support)
M - Supported
instance of PlayerWrapper
Geometry
M - Supported
instance of PlayerWrapper
Sharing
O- Supported
var CpxFramework.SNetMgmt
Social Event
M
Wishlists
Bookmarks
O- (partial support)
O- Supported
var CpxFramework.WishlistMgmt
Package History
O - Supported
var CpxFramework.HistoryMgmt
Content Access
Social Networking
Enhancements
instance of PlayerWrapper
instance of PlayerWrapper
var CpxFramework.BookmarkMgmt
The following example shows how to create a new player with support for the advanced
(i.e., Trickplay) features and then add an event listener:
var statusDesc = CpxFramework.PlayerMgmt.createPlayer(contentId, playerId, true);
// get the PlayerWrapper instance
Motion Picture Laboratories, Inc.
CONFIDENTIAL
17
CPE Sample
Implementation
DRAFT
Ref :
TR-CPE-SIMPL
Version :
v0.10
Date: January 23, 2015
var mainPlayer = statusDesc.context;
// add an event listener
playerListener = new DemoPlayerListener();
mainPlayer.addListener(playerListener);
3.2.2 Making a Package Available for Selection
When a consumer first accesses the application they are presented with the storefront
display showing all available packages:
Fig. 14: Storefront
The packages to be displayed to consumers are specified in a JSON file. The file,
{Install_dir}/resources/framework/StorefrontDb.json, contains one entry for each
package:
{
"packages":[
{
"id":"sintel01",
"title":"Sintel",
"display":"../resources/framework/images/PackageLogos/sintel.jpg",
"status":"AVAILABLE",
"display":"../resources/framework/images/PackageLogos/sintel.jpg",
“tagline” : “A girl on a quest”
},
{
"id":"bbb",
"title":"Big Buck Bunny",
"display":"../resources/framework/images/PackageLogos/bbb.jpg",
"status":"PENDING",
“tagline” : “Don’t mess with the bunny!”
},
:
:
Motion Picture Laboratories, Inc.
CONFIDENTIAL
18
CPE Sample
Implementation
DRAFT
Ref :
TR-CPE-SIMPL
Version :
v0.10
Date: January 23, 2015
When adding a package entry to the JSON, the following requirements must be met:
•
The “id” will be used to identify the package JavaScript file. For example, the package for
the movie “Tears of Steal” is implemented in the JavaScript file “tos.js”.
•
The “display” attribute is the relative path to the graphic that will be shown in the storefront
display. By convention, these are placed in the
../resources/framework/images/PackageLogo directory. That is not, however, a
requirement.
•
The storefront's display graphics will be sized to a uniform size. Currently, this is specified
as 260px x 110px. Image sizes not consistent with this aspect may appear distorted when
displayed to users.
•
The “status” may be set to either AVAILABLE or PENDING.
3.2.3 Making a Package Runable
Package implementers must follow exactly all instructions in this section. Failure to do
so will prevent the package from being displayed to users.
When a user selects a package the framework will add the supporting javascript file to the
DOM tree and then invoke the package's initialization and start-up functions. The “id” field in the
JSON file is used to identify the appropriate JavaScript file. For example, a package with id :
yoyodyne/fooBar01 will be expected to have its JavaScript file named fooBar01.js. The framework
will expect to find the file in directory {Install_dir}/scripts/packages/yoyodyne
The selection of a package by the user will only initiate a load of the package's JavaScript
file. It is the responsibility of the package to single to the framework when it has completed its
loading process and is ready to be initialized and displayed to the user. The complete sequence of
events, which must be followed exactly as described, is:
1. the framework's PackageMgmt module loads the package by appending the appropriate
JavaScript to the DOM
2. the package will assign to the global variable CPX_Package a function that implements it's
side of the Cross-Platform Extras interface.
3. at the completion of the loading, the package sets its state to P_STATE_LOADED
4. the package signals to the framework a state change:
var statusDesc = new StatusDescriptor(LEVEL_INFO, CC_STATE_CHANGE);
// Notify framework:
CpxFramework.PackageMgmt.status(statusDesc);
Motion Picture Laboratories, Inc.
CONFIDENTIAL
19
CPE Sample
Implementation
DRAFT
Ref :
TR-CPE-SIMPL
Version :
v0.10
Date: January 23, 2015
5. the framework will query the package for its current state, which is now P_STATE_LOADED:
var curPState = CPX_Package.getState();
6.
the framework then invokes the package's initialization function:
CPX_Package.initialize("FooBar", this, packageDiv);
7. The package initialization code will first change the package state to P_STATE_INIT. It will
then proceed with the initialization process. At the completion will set the state to
P_STATE_AVAILABLE and the notify the framework:
packState = P_STATE_AVAILABLE;
// Notify framework:
statusDesc = new StatusDescriptor(LEVEL_INFO, CC_STATE_CHANGE);
CpxFramework.PackageMgmt.status(statusDesc);
8. the framework will make the package visible to the consumer.
Each package must have a primary JavaScript file that follows the naming convention and
sequence of events described in the previous paragraphs. It must also provide the functions defined
in Section 4.3.1 of the API document. There is, however, the option of having the primary
JavaScript add additional js and css files to the DOM. The Sintel package uses this approach. See
Section 4.4 of this document for details and code snippets. Note that this design pattern is optional.
If a package does append additional styles or JavaScript to the DOM, it is also responsible for
cleaning up upon termination.
3.2.4 Interactions with the Framework
The API defines a number of codes that may be passed between the framework and
package. For example, Section 5.1 of the API documentation defines Content Access Codes, such
as ACC_AVAIL_2BUY. Where codes are defined as integer or other non-string types, a global
variable with the appropriate value assignment is defined by the JavaScript in the directory
{Install_dir}/scripts/API. The javascript file indicates which version of the API it is
compliant with. As an example, the file CPX-API-v0.90.js contains the following:
var
var
var
var
var
var
var
var
var
ACC_AVAIL_2BUY = 5001;
ACC_AVAIL_2RENT = 5002;
ACC_AVAIL_FREE = 5003;
ACC_AVAIL_BOUGHT = 5004;
ACC_AVAIL_RENTED = 5005;
ACC_AVAIL_PENDING = 5006;
ACC_AVAIL_UNAVAIL = 5007;
ACC_AVAIL_UNK = 5008;
ACC_CONTENT_UNK = 5009;
Motion Picture Laboratories, Inc.
CONFIDENTIAL
20
CPE Sample
Implementation
DRAFT
Ref :
TR-CPE-SIMPL
Version :
v0.10
Date: January 23, 2015
The API specifies the names but not the values. Framework implementers are free to
change the values but may not change the names. Packages must reference any codes by the
correct name.
Motion Picture Laboratories, Inc.
CONFIDENTIAL
21
CPE Sample
Implementation
DRAFT
Ref :
TR-CPE-SIMPL
Version :
v0.10
Date: January 23, 2015
4 DEVELOPING AND CUSTOMIZING
4.1 Overview
The JavaScript and style sheets used in the Cross Platform Extras Sample Implementation
are available to developers wishing to create their own framework and/or package implementations.
Since the entire purpose of the Cross Platform Extras API is to decouple the framework
implementation from that of the package, a developer is free to implement
•
only a Framework,
•
only a Package, or
•
both Framework and Package.
Each topic is, therefore, covered separately. The overview material regarding framework
development and customization are covered in Section 4.3 while Section 4.4 addresses the
package side of the API. Detailed information for each area is presented in Sections 0 and 0
respectively.
4.2 Use of Source Code and Licensing
All code and supporting constructs (e.g., CSS) developed by Movie Labs and used in the
Cross Platform Extras Sample Implementation is licensed under a Creative Commons Attribution
(CC BY) 3.0 Unported license.
4.3 SI Framework Architecture
The CPE Sample Implementation (SI) is built using HTML5 technologies. This means that,
with exception of any back-end (i.e., cloud-based) services, all functionality is implemented using
HTML, JavaScript, and CSS. The following subsections provide an overview how each of these
technologies is used. Refer to Section 5 for detailed information.
4.3.1 HTML
The SI uses a single HTML page: {Install_dir}/html/DemoRetailer.html. The
only HTML constructs explicitly defined in the body section of this page are the three buttons that
make up the header bar. All remaining elements DOM nodes that are presented to the consumer
are created by the JavaScript. A pair of nested <div> elements acts as the container for this
dynamic content.
The menu bar is defined by the following HTML:
<ul id="cpx_header_bar">
Motion Picture Laboratories, Inc.
CONFIDENTIAL
22
CPE Sample
Implementation
DRAFT
Ref :
TR-CPE-SIMPL
Version :
v0.10
Date: January 23, 2015
<img id="cpx_hdrBtn_logInOut" class="cpx_hdrBtn"
src="../resources/framework/images/LoginBtn.jpg"
onclick="CpxFramework.AccountMgmt.logInOut( )"
onmouseover="this.src='../resources/framework/images/LoginBtn2.jpg';"
onmouseout="this.src='../resources/framework/images/LoginBtn.jpg';"></img>
<img id="cpx_hdrBtn_about" class="cpx_hdrBtn"
src="../resources/framework/images/AboutBtn.jpg"
onclick="CpxFramework.showAbout()"
onmouseover="this.src='../resources/framework/images/AboutBtn2.jpg';"
onmouseout="this.src='../resources/framework/images/AboutBtn.jpg';"></img>
<img id="cpx_hdrBtn_contact" class="cpx_hdrBtn"
src="../resources/framework/images/ContactBtn.jpg"
onclick='CpxFramework.contact()'
onmouseover="this.src='../resources/framework/images/ContactBtn2.jpg';"
onmouseout="this.src='../resources/framework/images/ContactBtn.jpg';"></img>
</ul>
Note that the 'onclick' parameters for these buttons refer to specific variables defined
within the javascript Main.js.
The HTML defines an 'onLoad' argument that points to the javascript that will dynamically
build the remaining HTML:
<body onLoad="$(document).ready(CpxFramework.initialize);">
The CpxFramework object is defined in the file Main.js.
There are four categories of JavaScript that the HTML page loads:
•
API definition: this is a version-specific file defining any constants used by one of the groups
defined by the Cross Platform Extras interface and discussed previously in Section 3.2.4.
The API files are located in the directory {Install_dir}/scripts/API.
•
Framework implementation: This set of files is located in the directory
{Install_dir}/scripts/demo/framework. A minified version will be included with
future releases.
•
Sample Implementation utilities: these files provide support for GUI-building and include
widgets (e.g., expandable/collapsible menus) and layout managers and are intended to act
as the foundation for what will eventually evolve into a Common Extras Menu Metadata
capability. This is intended to allow the creation of a simple interactive experience directly
from XML. See http://www.movielabs.com/md/extras/#current for current status.
•
3rd party libraries: this includes libraries such as jQuery and jssor.
The HTML page also loads two CSS style sheets, both discussed further in Section 4.3.4.
Motion Picture Laboratories, Inc.
CONFIDENTIAL
23
CPE Sample
Implementation
DRAFT
Ref :
TR-CPE-SIMPL
Version :
v0.10
Date: January 23, 2015
The JavaScript and CSS files used to implement packages are not loaded by the
HTML. It is, instead, loaded on an 'as-needed' basis. See Section 3.2.3 for further details.
4.3.2 JavaScript for Framework
The JavaScript used to create the framework for the CPE Sample Implementation is highly
modular. The architecture is shown below in Figure 15. At the core is the CpxFramework, which is
defined in the file Main.js. The CpxFramework module is responsible for configuring the
framework by loading and initializing the modules that will provide the functionality specified in the
Cross Platform Extras Interface.
Fig. 15: SI Framework Architecture
As noted in the previous section, the HTML page identifies CpxFramework.initialize()
as the 'onLoad' function. The primary task of this function is to initialize instances of modules that
implement one of the API sub-groups. For example,
CpxFramework.AccountMgmt = new AccountMgmt();
enables the software that will support account management functions such as signing in.
That software itself is contained in the file AccountMgmt.js. There are equivalent files and
initialization code for all supported API subgroups listed in Table 1 on page 16.
Motion Picture Laboratories, Inc.
CONFIDENTIAL
24
CPE Sample
Implementation
DRAFT
Ref :
TR-CPE-SIMPL
Version :
v0.10
Date: January 23, 2015
The framework also includes modules that provide functionality not covered by the CPE API
specification. One of these is CpxFramework.BackEndSvc. The term “back-end services” (or
“BES”) refers to the JavaScript that is used to access any cloud-based (i.e., off-platform)
capabilities. Authentication of a consumer's login credentials is one example of a capability that
requires access to a back-end service. As noted in Section 3.1, the Sample Implementation is
currently configured to use Firebase as its BES provider. It is recognized, however, that each
retailer and distribution channel will wish to use its own preferred BES provider, whether 3rd party or
in-house. To facilitate this, the Sample Implementation defines a BES Interface and API. This is
entirely independent of the Cross Platform Extras Interface, is informative (i.e., not normative), and
has no official standing. Its sole purpose is to make it easier for developers to adapt the Sample
Implementation to their own environment and needs. Refer to Section 4.3.5 for additional
information on the customization and use of back-end services.
The last major component configured as part of the Retailer’s framework initialization
process is the Storefront. The Storefront module is responsible for the visual and interactive
aspects of package selection. The Storefront is, therefore, instantiating the 'view' aspect of a MVC
approach. The Storefront determines which packages to display to a consumer by retrieving the
JSON file previously discussed in Section 3.2.2. It also determines the appropriate response to any
user interaction with the display (e.g., clicking on a package icon). If the appropriate response is to
activate the package, the Storefront will inform the PackageMgmt module.
In terms of user interaction, the key modules are therefore:
•
Storefront: handles presentation of available packages, including browsing, search, and
selection.
•
Player: media playback with controls for pause, rewind, etc.
•
Package: responsible for all other aspects of an experience.
4.3.3 JavaScript for UI Construction
As noted previously in Section 4.3.1, the Sample Implementation makes use of a set of
utilities that provide support for GUI-building. The JavaScript files are located in directory
{Install_dir}/scripts/util. The functionality is provided by three separate files, each with
a different focus:
•
CPE-UI-Widgets.js: provides component widgets (e.g., buttons, expandable/collapsible
menus). These widgets are 'active' in that they respond to either user interactions,
background events, or both.
•
CPE-UI-Layouts.js: provides layouts and layout managers. It also provides support for
video overlays in a 'safe' area.
•
CPE-UI-FX.js: provides effects such as transitions (fade in/out) and slide shows.
Motion Picture Laboratories, Inc.
CONFIDENTIAL
25
CPE Sample
Implementation
DRAFT
Ref :
TR-CPE-SIMPL
Version :
v0.10
Date: January 23, 2015
These are all 1st generation capabilities and are intended to act as the foundation for what
will eventually evolve into a Common Extras Menu Metadata capability. The ultimate goal is to allow
the creation of a simple interactive experience directly from XML. They may, however, also be used
to facilitate the creation of packages when implementing directly via JavaScript. The Sintel package
provides several examples of this approach.
4.3.4 Stylesheets
The HTML page for the Sample Implementation links several CSS files, each with a different
focus:

../styles/CPE-UI-Widgets.js: provides component widgets (e.g., buttons,
expandable/collapsible menus). These widgets are 'active' in that they respond to either user
interactions, background events, or both.

../styles/CPE-UI-Layouts.js: provides layouts and layout managers. It also
provides support for video overlays in a 'safe' area.

../styles/CPE-UI-FX.js: provides effects such as transitions (fade in/out) and slide
shows.
These are all 1st generation capabilities and are intended to act as the foundation for what will
eventually evolve into a Common Extras Menu Metadata capability. The ultimate goal is to allow the
creation of a simple interactive experience directly from XML. They may, however, also be used to
facilitate the creation of packages when implementing directly via JavaScript.
Any CSS files used by a specific package should be added and removed by the
JavaScript implementing the package's initialize() and terminate() functions.
4.3.5 Accessing Back-End Services (BES)
The term “back-end services” refers to any service that requires interaction with a remote
server, whether cloud-based or organic to the retailer's infrastructure. A primary use of back-end
services is to provide a mechanism for persisting and retrieving information specific to an individual
consumer. Examples include user preferences, content access rights, and viewing history. Backend services are also used to authenticate login credentials.
It is recognized, however, that each retailer and distribution channel will wish to use its own
preferred BES provider, whether 3rd party or in-house. To facilitate this, the Sample Implementation
defines a BES Interface and API. This is entirely independent of the Cross Platform Extras
Interface, is informative (i.e., not normative), and has no official standing. Its sole purpose is to
make it easier for developers to adapt the Sample Implementation to their own environment and
needs.
Motion Picture Laboratories, Inc.
CONFIDENTIAL
26
CPE Sample
Implementation
DRAFT
Ref :
TR-CPE-SIMPL
Version :
v0.10
Date: January 23, 2015
The BES Interface is depicted in Figure 15 as the vertical rectangle on the left side of the
diagram. It is defined by the JavaScript in
{Install_dir}/scripts/demo/framework/BES_Interface.js. This file is located in the demo,
rather than API, directory tree because, as noted above, it is not specified as part of the Cross
Platform Extras Interface and, therefore, has no official status. It may be freely modified and
adapted by developers or may be ignored entirely.
The BES Interface contains two sets of information. The first is a set of constants specifying
event codes passed across the interface. The current set is:
var
var
var
var
var
BES_SVC_LOGIN = "logIn";
BES_SVC_LOGOUT = "logOut";
BES_SVC_ADDACCNT = "addAccnt";
BES_SVC_CAR_SET = "setCAR";
BES_SVC_CAR_GET = "getCAR";
var
var
var
var
var
BES_STATUS_SUCCESS = 100;
BES_STATUS_FAILURE = 200;
BES_STATUS_UNK_USER = 201;
BES_STATUS_BAD_PWD = 202;
BES_STATUS_DUP_USER = 203;
The remainder of the file contains a template for implementing a back-end service. This
specifies all the functions that are used by the Framework's modules. The current set, as grouped
by the module that access it, includes:
return {
// Account Mgmt capabilities:
login : login,
logout : logout,
addAccount : addAccount,
// Content Mgmt capabilities:
getContentRecord : getContentRecord,
loadUserRights : loadUserRights,
getDefaultRights : getDefaultRights,
getUserRights : getUserRights,
updateUserRights : updateUserRights
// capabilities used by Bookmarks, History, and Wishlist:
getDataBlob : getDataBlob,
setDataBlob : setDataBlob
};
The BES Interface is a work-in-progress as is expected to expand significantly in
future versions of the Sample Implementation. In particular, note that the SI does not at this time
support the functions in the optional groups and sub-groups of Cross Platform Extras Interface.
Several these, such as the Enhancements Group, will require additions to the BES Interface. Refer
to Section 3.2.1 to identify which groups and sub-groups are currently supported.
Motion Picture Laboratories, Inc.
CONFIDENTIAL
27
CPE Sample
Implementation
DRAFT
Ref :
TR-CPE-SIMPL
Version :
v0.10
Date: January 23, 2015
The Sample Implementation currently provides two different BES implementations:
•
BES_Pseudo: Implements a fake back-end cloud-based service. This is DEMO code used
to validate the API and as a proof-of-concept. Actual accounts are NOT supported. Instead
a pseudo-capability is implemented using cookies and no actual ready-for-prime-time
account DB or back-end-service provided.
•
BES_FireBase: This module provides access to a true cloud-based BES capability. The
underlying provider is Firebase.
The demo is currently configured to use Firebase. Developers who wish to use Firebase as their BES
will first need to establish an account. Free accounts are available to support up to fifty users. Once
an account has been created, the URL that has been assigned to it must be entered into the testbed.
This is done by editing the value of the variable accntRoot.
Please do not use the same account as the demonstration implementation.
Developers may also choose to use a different BES provider. To do so in a manner
transparent to the other framework components, the developer will need to:
1. implement a module that is compatible with the BES Interface definition
2. edit the CpxFramework.initialize() code in Main.js to assign the new module as the
CpxFramework.BackEndSvc
4.4 SI Package Architecture
The material in this section deals with a preliminary capability that is an incomplete
work-in-progress. Documentation of changes may lag changes to the software due to
the rapid development cycle.
This section provides an overview of the architecture used by the Sample Implementation to
implement a package. This is only one of the many possible ways to design a Cross-Platform
Extras package. The material in this section is provided as guidance for any developers who wish to
understand or adapt the SI package code.
Developers are expected to be familiar with the material covered in Section 3.2.3 of
this document prior to reading the material in this section. In particular, they should understand the
sequence of events that takes place during the package activation process.
Motion Picture Laboratories, Inc.
CONFIDENTIAL
28
CPE Sample
Implementation
DRAFT
Ref :
TR-CPE-SIMPL
Version :
v0.10
Date: January 23, 2015
4.4.1 Overview
The SI approach to package implementation is based on the following design patterns:
(a) all HTML is built as-needed by the JavaScript. No predefined HTML files are used.
(b) A package is structured as a finite state machine (FSM) with state transitions triggered by
the user's actions.
(c) The functionality is divided between two JavaScript files:
•
a base file contains a set of functions intended to provide a common look-n-feel across all
packages developed by a content provider (e.g., a movie studio). A second purpose is to
provide utility functions that are generic to this content provider but not provided at the
framework level (e.g., event listeners).
•
A content-specific file acts as the primary interface between the framework and the
package. It also contains all the functionality and properties specific to a single package.
In the case of the Sample Implementation's demonstration packages, the “content provider”
is, for most of the material, the Blender Foundation so there is a file named blenderBase.js. The
content-specific code for Sintel is in the file sintel01.js. Both are located in
{Install_dir}/scripts/packages
The design patterns identified above result in the following code structure:
•
The base file has responsibility for implementing a common look-and-feel across packages.
Since a large part of the visual appearance is determined by the HTML, which is generated
on-demand by JavaScript, the code to carry out this type of function is located in the base
files.
•
The content-specific file controls the state transitions. It therefore assumes much of the
responsibility for event handling.
•
When entering a new state, the content-specific file determines the specific media (i.e.,
images, video, and audio) files to show or link to. The base file will insert these into the
presentation template it uses for the requested state.
4.4.2 Interactions between Package and Base
4.4.2.1 Loading of JavaScript
The framework will load the content-specific js file (e.g. sintel01.js). This file is responsible, in
turn, for loading the base file (i.e., blenderBase.js). Once the base file has completed loading, it
invokes the content-specific file's _Base_completedLoad() function. The content-specific file is
then responsible for notifying the framework that the load process has completed.
The following example code is from the Sintel file:
Motion Picture Laboratories, Inc.
CONFIDENTIAL
29
CPE Sample
Implementation
DRAFT
Ref :
TR-CPE-SIMPL
Version :
v0.10
Date: January 23, 2015
/*
* Invoked by the 'base' script when it has completed loading and is available
*/
_Base_completedLoad = function() {
console.log("Package " + packID + ": loading completed");
var statusDesc = new StatusDescriptor(LEVEL_INFO, CC_STATE_CHANGE);
// Notify framework:
CPX_PackageMgmt.status(statusDesc);
};
var loadBase = function() {
var bodyEl = document.body;
var pscriptEl = document.createElement('script');
pscriptEl.type = 'text/javascript';
pscriptEl.async = false;
var envDesc = CPX_PackageMgmt.getEnvironmentDesc();
var packageUrl = envDesc['packageDir'] + 'blenderBase.js';
pscriptEl.src = packageUrl;
if (typeof pscriptEl != "undefined") {
console.log("Adding package BASE script " + packageUrl);
document.getElementsByTagName("head")[0].appendChild(pscriptEl);
} else {
alert("Unable to add package script " + packageUrl);
}
};
/*
* This code will execute when the js file completes loading. It will trigger
* the loading of the abstract 'base' package that is generic across all
* packages provided by this content provider.
*/
loadBase();
The base side of the interaction is a single line of code at the end of the file:
_Base_completedLoad();
4.4.2.2 Initialization
Initialization is completed when the package is in a state allowing the control of the UI to be
passed to it (i.e., it is in the Available state). The nature of the operations that are carried out during
initialization may vary from package to package and may take some time if remote resources are
required. The package is, therefore, allowed to complete the initialization process asynchronously.
The package should verify before returning that it can access the framework, that it recognizes the
context, and that it is compatible with the viewing environment. Any additional initialization may take
place asynchronously.
Motion Picture Laboratories, Inc.
CONFIDENTIAL
30
CPE Sample
Implementation
DRAFT
Ref :
TR-CPE-SIMPL
Version :
v0.10
Date: January 23, 2015
As with all interactions in which the framework invokes a function provided by a package,
the SI design has the initial point-of-invocation being provided by the content-specific file. The first
step it takes is to change its state to P_STATE_INIT and notify the framework of the change:
function initialize(_context, _framework, _container) {
packState = P_STATE_INIT;
// Notify framework:
var statusDesc = new StatusDescriptor(LEVEL_INFO, CC_STATE_CHANGE);
CPX_PackageMgmt.status(statusDesc);
The next step is to save the arguments passed by the framework and then to invoke the
base initialization process:
context = _context;
framework = _framework;
container = _container;
BlenderBase.initialize("sintel", context, framework, container,
"style01");
The base code initialization is focused on two requirements: loading the content provider's
own style sheets (i.e., CSS files) and initializing any variables used to retrieve media files:
function initialize(_packageId, context, framework, _container, _styleId) {
container = _container;
packageId = _packageId;
pkgStyleId = _styleId;
debug("Initializing for package '" + packageId + "'");
/*
* Style is added ...
*/
style = document.createElement('link');
style.rel = 'stylesheet';
style.type = 'text/css';
style.href = rsrcPathBase + 'package.css';
document.getElementsByTagName('head')[0].appendChild(style);
debug("added CSS " + rsrcPathBase + 'package.css');
var envDesc = CPX_PackageMgmt.getEnvironmentDesc();
rsrcPathBase = envDesc['rsrcDir'] + 'blender/';
pkgRsrcPath = rsrcPathBase + packageId + '/';
pkgRsrcPathImg = pkgRsrcPath + "images/";
pkgRsrcPathAudio = pkgRsrcPath + "audio/";
/*
* let player mgmt know default path to find media
*/
CPX_PlayerMgmt.setMediaPath(pkgRsrcPath);
Motion Picture Laboratories, Inc.
CONFIDENTIAL
31
CPE Sample
Implementation
DRAFT
Ref :
TR-CPE-SIMPL
Version :
v0.10
Date: January 23, 2015
Another aspect of look-and-feel is the use of animation. In the SI code the Blender base
code uses the CPE-UI library to set up a fade-out/fade-in effect to transition between states:
/*
* Instantiate a transition effect for top-level UI screens
*/
uiSwapper = DivSwapFadding(container, swapSpeed);
The last step in the base initialization is to register as a listener with the CPE-UI's layout
manager:
var ll = new LayoutListener();
Package_Layout_Mgr.addListener(ll);
}
At this point the initialization process reverts to the control of the content-specific code.
Since this is the module responsible for the management of state transitions, its primary concern is
registering to receive event notifications:
/* add an event listener to the BODY */
var bodyEl = document.body.addEventListener("click", evtHandlerClicks, false);
/*
* we want to be informed of changes to the user's access rights to the
* content. That includes changes in log-in state
*/
carEvtListener = new AccessEventListener();
CPX_ContentMgmt.addListener(carEvtListener);
accntEvtListener = new AccountEventListener();
CPX_AccountMgmt.addListener(accntEvtListener);
The last step of initialization is to build the UI structure that will be displayed to the consumer
when the package is first enabled. This consists of an HTML <div> that is inserted into the DOM
whenever the state is entered and then removed when the state is exited. State transitions are
described in more detail in Section 0. In terms of the initialization process a single line of code is all
that is required:
enterState01();
The specifics of what this function does are covered in next in Section 4.4.2.3. For now all
that needs to be understood is that this function results in the construction of the required <div>
element which is then saved as var rootElState01.
The last step is to update the package's state and then notify the framework that the
initialization process has completed:
packState = P_STATE_AVAILABLE;
// Notify framework:
statusDesc = new StatusDescriptor(LEVEL_INFO, CC_STATE_CHANGE);
CPX_PackageMgmt.status(statusDesc);
Motion Picture Laboratories, Inc.
CONFIDENTIAL
32
CPE Sample
Implementation
DRAFT
Ref :
TR-CPE-SIMPL
Version :
v0.10
Date: January 23, 2015
}
4.4.2.3 UI Construction
The Sample Implementation is a work-in-progress as is expected to expand significantly
in future versions. In particular, note that the SI does not at this time support the functions in the
optional groups and sub-groups of Cross Platform Extras Interface. Several these will result in new
states and UI screens being added to the demo packages. This, in turn, will require additions to the
code described in this section.
The Blender base code used for the demonstration packages provides several functions that
implement various template screens. The current capabilities include:
•
addSlideCarousel: creates a slide show with background soundtrack and (optional)
poster
•
buildState02: In this state the user is shown the top-level menu for a package. This
includes a menu with icons to access main content and (possibly) a free 'teaser' clip and any
extras.
•
buildPlaybackState: This is applicable to any state in which video is being made
available to the consumer. This includes, but is not limited to, the main (i.e., feature) content,
trailers and previews of coming attractions, interviews with cast, or behind-the-scenes
documentaries.
The role of the content-specific code is to invoke these template patterns with arguments
pointing to the appropriate media. For example, in the SI demo the Blender “look and feel” for a
package is to open with a slide show, before continuing to the main navigation menu. The following
code snippet from the Sintel file shows how to create the slide show display shown in Section 2.3.3:
rootElState01 = document.createElement('div');
var imgSeq = new Array();
imgSeq.push("01a_comp_000197-1100x600.jpg");
imgSeq.push("01a_comp_000559-1100x600.jpg");
imgSeq.push("02.b_comp_000296-1100x600.jpg");
imgSeq.push("02.d_comp_000411-1100x600.jpg");
imgSeq.push("02.g_comp_000106-1100x600.jpg");
var audioSrc = "3-The_Ziggurat.mp3";
var poster = "sintel_poster.jpg";
slideShow01 = BlenderBase.addSlideCarousel(rootElState01, imgSeq,
audioSrc, poster);
Creation of the “main-menu”, shown in Figure XX in Section 2.3.4, is even simpler:
var teaser = "blender:sintel:trailer:v01:720p";
var poster = "sintel_cover.jpg";
rootElState02 = BlenderBase.buildState02(primaryContentId, teaser,
poster, "style01");
Motion Picture Laboratories, Inc.
CONFIDENTIAL
33
CPE Sample
Implementation
DRAFT
Ref :
TR-CPE-SIMPL
Version :
v0.10
Date: January 23, 2015
The main menu gives the consumer the ability to view either a free teaser clip or, if they
have acquired the rights, the actual movie. Both of these UI states are easily constructed using the
buildPlaybackState function. The UI for playing the teaser is built using a single line of code:
rootElState04 = BlenderBase.buildPlaybackState(contentId, enabledState,
false, "EntryScreen01.png", popupEvents);
Building the UI for playback of the movie is virtually identical. The only change is the
Boolean argument indicating if the UI is to be used for showing the main feature of for showing
some supplementary content:
rootElState03 = BlenderBase.buildPlaybackState(contentId, enabledState,
true, "EntryScreen01.png", popupEvents);
The next section will cover how the package software implements the transition from one
state (e.g., display of an introductory slide show) to another (e.g., display of a main menu).
4.4.2.4 UI State Transitions
The states referred to in this section are UI states as opposed to package states. The
latter are defined by Section 4.1.1 of the Cross Platforms Experience Interface. The UI states are
an artifact of the SI demonstration package code and are not defined in any controlled API or
interface document. Any reference to the package states (e.g., P_STATE_RUNNING) will explicit
indicate that a package, rather than UI, state is being referred to.
The package base code provides three functions that the content-specific code uses to
initiate FSM transitions:

launch: used to load the initial display into the UI

transitionTo: implements the visual aspects of transition from one state to another

terminate: clean-up and garbage collection.
The termination process is covered in more detail in Section 4.4.2.6. The remainder of this
section will discuss the launch and transition processes.
4.4.2.4.1 Launching
The base-code launch function takes a single argument: the root <div> for the initial display.
In the previous section it was explained how the Sintel package creates an initial slide show to be
used as the first screen shown to a consumer. This code snippet begins with the instruction
rootElState01 = document.createElement('div');
This <div> is what will be passed by the content-specific code to the base code when it is
ready to take control of the user interface and be displayed to the consumer. The entire initialization
process is described in Section 3.2.3. The change to the P_STATE_AVAILABLE, at the end of the
Motion Picture Laboratories, Inc.
CONFIDENTIAL
34
CPE Sample
Implementation
DRAFT
Ref :
TR-CPE-SIMPL
Version :
v0.10
Date: January 23, 2015
7th step in that process, is the trigger for the UI launch. The exact sequence of interactions between
the modules is:
1. the package changes the package state to P_STATE_AVAILABLE and then signals
the framework that there has been a state change.
2. The framework will respond by querying the package for its current pckage state.
When it determines that the package is now P_STATE_AVAILABLE, the framework
will invoke CPX_Package.enable().
3. The enable() function will invoke the launch mechanism, as well as handling and
changes to the state variables:
function enable() {
BlenderBase.launch(rootElState01);
packState = P_STATE_RUNNING;
// Notify framework:
statusDesc = new StatusDescriptor(LEVEL_INFO, CC_STATE_CHANGE);
CPX_PackageMgmt.status(statusDesc);
}
4.4.2.4.2 Transition To
The transition process is an event-driven procedure. The package contains several event
listeners, which are described in detail in Section 4.4.2.5. For now it suffices to know that the
package may receive events that are generated due to a variety of causes including, but not limited
to:

A user action (e.g., mouse click),

A change in the user’s login status,

A player-related event (e.g., the end of the movie was reached), or

A change to the user’s rights to content (e.g., a rental period has expired).
The design pattern used in the SI demo packages is that when an event handler determines that a
state transition is required, it invokes the transition() function in the content-specific package
module. This takes two mandatory arguments, both of which are functions. The first function is the
exit handler for the current state and the second the entry handler for the new state. A third optional
argument is used to pass any context information associated with the triggering event.
The following code traces the sequence of actions that occur when the user clicks anywhere
on the screen during the initial introductory slide show described in Section 2.3.3. This is intended
to terminate the slide show and transition to a display of the package’s main menu. The starting
point is, therefore, the event handler for mouse clicks. This will kick-off the process:
transition(exitState01, enterState02);
The transition() function is fairly simple:
Motion Picture Laboratories, Inc.
CONFIDENTIAL
35
CPE Sample
Implementation
DRAFT
Ref :
TR-CPE-SIMPL
Version :
v0.10
Date: January 23, 2015
function transition(exitFunc, enterFunc, context) {
var curGuiRoot = exitFunc();
var nextGuiRoot = enterFunc(context);
BlenderBase.transitionTo(curGuiRoot, nextGuiRoot);
}
The exit and enter functions both return the root <div> for their respective UI states. These
will be passed to the base module’s transitionTo() function. This is, for the SI demo packages,
a very simple function. If you refer back to the description of the initialization process in Section
4.4.2.2, you will note that the 2nd from last step of the base initialization process was the use of the
CPE-UI library to set up a fade-out/fade-in effect to transition between UI states:
/*
* Instantiate a transition effect for top-level UI screens
*/
uiSwapper = DivSwapFadding(container, swapSpeed);
The transitionTo() function simply applies that effect:
function transitionTo(currentEl, nextEl) {
uiSwapper.changeTo(currentEl, nextEl);
}
In the above discussion, the details of the exit and enter functions was skipped over. The
enter functions have already been introduced in the previous section as part of the UI construction
process. Recall the description on page 34 of how the GUI for movie playback is created. This is
associated with UI state 3. Hence the enterState03 function is:
/*
* STATE 3: Player state, used for actually playing a movie
*/
function enterState03(contentId) {
var enabledState = "UI03";
if (rootElState03 != null) {
// IMPORTANT: Indicate the state transition
uiState = enabledState;
return rootElState03;
}
rootElState03 = BlenderBase.buildPlaybackState(contentId, enabledState,
true, "EntryScreen01.png", popupEvents);
// IMPORTANT: Indicate the state transition
uiState = enabledState;
return rootElState03;
}
The exit functions are primarily dealing with graceful shutdown and exit. For UI state 3 that
means stopping the player:
function exitState03() {
// make sure player is stopped
var curPlayer = BlenderBase.getPlayer(BlenderBase.playerId);
Motion Picture Laboratories, Inc.
CONFIDENTIAL
36
CPE Sample
Implementation
DRAFT
Ref :
TR-CPE-SIMPL
Version :
v0.10
Date: January 23, 2015
curPlayer.stop();
// IMPORTANT: Indicate the state transition
uiState = null;
return rootElState03;
}
Also note that the last step in the exit function is to set the uiState to null. This indicates
that there is at this point no package-specific component in the DOM being displayed to the user.
4.4.2.5 Event Handling
As noted in the preceding section, the package may receive events that are generated due
to a variety of causes including, but not limited to a user action (e.g., mouse click), a change in the
user’s login status, a player-related event (e.g., the end of the movie was reached), or a change to
the user’s rights to content (e.g., a rental period has expired).
The design pattern used by the SI demo package to deal with these types of events is
1. The base module provides the code for establishing a variety of event listeners
2. Depending on the type of event, the listener will either:

Pass the event to a handler function in the base module,

Pass the event to a handler in the content-specific module,

Handle the event itself, or

Ignore the event.
Mouse-click events are the exception to this design pattern. Refer to Section 4.4.2.5.5 for
further details.
The following are the event listeners used and the response mode of each
4.4.2.5.1 Player Events
The base module provides a sub-class (i.e., extension) of the PlayerEventListener
called DemoPlayerListener. The event processing is as follows:

READY, VISIBILITY, or STOPPED: Pass the event to a handler in the
content-specific module. The reasoning is that auto-play, restart, or automatic
state-transitions upon completion may all be appropriate actions to take but only the
package will be in a position to decide.

PLAYING or RESUMED: handled in-line. The response is to expand or collapse any
menus.

GEOMETRY_CHANGE: handled in-line.
Motion Picture Laboratories, Inc.
CONFIDENTIAL
37
CPE Sample
Implementation
DRAFT

Ref :
TR-CPE-SIMPL
Version :
v0.10
Date: January 23, 2015
TIME_EVT_R: handled in-line. The response is to display a text message in a pop-up
overlay for 3 seconds. Note that this is a temporary demo-only feature used to
demonstrate several capabilities of the CP Extras API.
All other player-related events are currently ignored.
4.4.2.5.2 Content Access Events
The base module provides a sub-class (i.e., extension) of the CAEventListener prototype
called AccessEventListener. The listener response to all events is to pass the event to a
handler in the content-specific module by invoking CPX_Package.updateAccessRts().
4.4.2.5.3 Account Events
The base module provides a sub-class (i.e., extension) of the Listener prototype called
AccountEventListener. The listener response to either a log-in or log-out event is to invoke the
content-specific module CPX_Package.updateAccessRts().
4.4.2.5.4 Layout Events
Layout events are generated by the CPEx-UI Layout Manager when the browser window
changes shape, size, or orientation. Since this is primarily a look-n-feel issue the response is to
handle it within the base module by invoking the function BlenderBase.respondToLayout().
4.4.2.5.5 Mouse Click Events
This category of events is primarily dealing with the user clicking on menu items or icons.
The current code deviates from the normal design pattern in that neither the base module nor the
framework provide a listener prototype. Instead, the content-specific module provides a listener
function that is added to the DOM body as part of the initialization process:
var bodyEl = document.body;
bodyEl.addEventListener("click", evtHandlerClicks, false);
The function evtHandlerClicks() determines whether or not a UI state change is
warranted and, if so, invokes the state transition process described in Section 4.4.2.4.2
4.4.2.6 Termination and Shutdown
In the SI demonstration the starting point for the termination and shutdown of a package is
the user clicking on an EXIT icon within one of the menus. This will result in an event delivery to the
mouse-click listener described in the previous section. The listener will, in this situation, call the
package’s exit() function. The exit handler will immediately change the package state to
P_STATE_EXITING and then notify the framework of the change in status:
packState = P_STATE_EXITING;
var statusDesc = new StatusDescriptor(LEVEL_INFO, CC_STATE_CHANGE);
CPX_PackageMgmt.status(statusDesc);
Motion Picture Laboratories, Inc.
CONFIDENTIAL
38
CPE Sample
Implementation
DRAFT
Ref :
TR-CPE-SIMPL
Version :
v0.10
Date: January 23, 2015
The framework will perform any required preliminary steps and then, when ready, call
CPX_Package.terminate(). The content-specific module contains the terminate function.
This immediately changes the package state and then calls the base module’s terminate
function, removes any listeners, and then finally notifies the framework it has completed all
shutdown operations:
function terminate() {
packState = P_STATE_TERMINATED;
BlenderBase.terminate();
var bodyEl = document.body;
bodyEl.removeEventListener("click", evtHandlerClicks, false);
CPX_ContentMgmt.removeListener(carEvtListener);
CPX_AccountMgmt.removeListener(accntEvtListener);
var statusDesc = new StatusDescriptor(LEVEL_INFO, CC_STATE_CHANGE);
CPX_PackageMgmt.status(statusDesc);
}
The base module’s termination actions are for the most part fairly simple garbage collection
and clean-up activities. One key point, however, is that it is responsible for removing any CSS style
sheets that it has added to the DOM:
function terminate() {
debug("termination initiated");
rsrcPathBase = null;
packageId = null;
pkgRsrcPath = null;
pkgRsrcPathImg = null;
pkgRsrcPathAudio = null;
container = null;
uiSwapper = null;
requiredNotices = false;
requiredNoticesDiv = null;
if (style != null) {
$(style).remove();
style = null;
}
}
Motion Picture Laboratories, Inc.
CONFIDENTIAL
39
CPE Sample
Implementation
DRAFT
Ref :
TR-CPE-SIMPL
Version :
v0.10
Date: January 23, 2015
5 FRAMEWORK DEVELOPMENT & CUSTOMIZATION
Motion Picture Laboratories, Inc.
CONFIDENTIAL
40
CPE Sample
Implementation
DRAFT
Ref :
TR-CPE-SIMPL
Version :
v0.10
Date: January 23, 2015
6 PACKAGE DEVELOPMENT & CUSTOMIZATION
Motion Picture Laboratories, Inc.
CONFIDENTIAL
41