CPE Sample
Implementation
DRAFT
Ref :
TR-CPE-SIMPL
Version :
v0.8
Date: August 27, 2014
Cross Platform Extras
Sample Implementation
User’s Guide
Motion Picture Laboratories, Inc.
CONFIDENTIAL
1
CPE Sample
Implementation
DRAFT
Ref :
TR-CPE-SIMPL
Version :
v0.8
Date: August 27, 2014
CONTENTS
1
2
3
4
5
6
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
Demonstrating the CPE APIs ................................................................................................... 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
Sintel Intro................................................................................................................. 9
2.3.4
Sintel Main Menu Page ........................................................................................... 10
2.3.5
Creating an Account & Logging In ........................................................................... 11
2.3.6
‘Acquiring’ Content Rights ....................................................................................... 11
2.3.7
Playing a Movie ...................................................................................................... 11
2.3.8
Timed Events .......................................................................................................... 11
Learning and Using the Sample Implementation .................................................................... 13
3.1
Testbed Set-up and Configuration .................................................................................. 13
3.2
Package Integration ........................................................................................................ 14
3.2.1
Accessing the Framework API ................................................................................ 14
3.2.2
Making a Package Available for Selection............................................................... 16
3.2.3
Making a Package Runable .................................................................................... 17
3.2.4
Interactions with the Framework ............................................................................. 18
Developing and Customizing .................................................................................................. 19
4.1
Overview ........................................................................................................................ 19
4.2
Use of Source Code and Licensing................................................................................. 19
4.3
SI Framework Architecture ............................................................................................. 19
4.3.1
HTML ...................................................................................................................... 19
4.3.2
JavaScript for Framework ....................................................................................... 21
4.3.3
JavaScript for UI Construction................................................................................. 22
4.3.4
Stylesheets ............................................................................................................. 23
4.3.5
Accessing Back-End Services (BES) ...................................................................... 23
4.4
RI Package Architecture ................................................................................................. 25
4.4.1
Overview ................................................................................................................. 25
4.4.2
Interactions between Package and Base ................................................................ 26
Framework Development & Customization ............................................................................. 37
Package Development & Customization ................................................................................. 37
Motion Picture Laboratories, Inc.
CONFIDENTIAL
2
CPE Sample
Implementation
DRAFT
Ref :
TR-CPE-SIMPL
Version :
v0.8
Date: August 27, 2014
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.8
Date: August 27, 2014
REVISION HISTORY
Version
Date
Motion Picture Laboratories, Inc.
Description
CONFIDENTIAL
4
CPE Sample
Implementation
DRAFT
Ref :
TR-CPE-SIMPL
Version :
v0.8
Date: August 27, 2014
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 address a different use:

Section 2: Use of the SI web site to demonstrate the Cross Platforms Extra concept
Motion Picture Laboratories, Inc.
CONFIDENTIAL
5
CPE Sample
Implementation
DRAFT
Ref :
TR-CPE-SIMPL
Version :
v0.8
Date: August 27, 2014

Section 3: Use of the SI software as a testbed for validating package integration

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. The implementation currently exists here, although it
may be removed at any time. Please contact MovieLabs for the latest version.
http://www.criticalarchitectures.com/projects/MovieLab/CPE/Demo03/html/DemoRetailer.html
Code and supporting resources used in the Sample Implementation will ultimately be hosted
online. In the meantime, please contact MovieLabs.
1.5 Acknowledgements
Our demonstration uses work associated with the Blender Foundation. We gratefully
acknowledge the organization and the people behind it, and the fine work that makes our
demonstration possible. Please visit www.blender.org.
Motion Picture Laboratories, Inc.
CONFIDENTIAL
6
CPE Sample
Implementation
DRAFT
Ref :
TR-CPE-SIMPL
Version :
v0.8
Date: August 27, 2014
2 DEMONSTRATING THE CPE APIS
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 any HTML5-compliant browser. See Resources in
Section 1.4 for information where to obtain the demo.
Figure 1 shows the initial view, referred to as the storefront. Graphics for all known packages are
shown. In this case there are three, although currently only the first one is active. The user may log
in or out at any time.
Motion Picture Laboratories, Inc.
CONFIDENTIAL
7
CPE Sample
Implementation
DRAFT
Ref :
TR-CPE-SIMPL
Version :
v0.8
Date: August 27, 2014
Figure 1: Storefront view
2.3.2 Package Selection
Packages are selected by a LEFT-click on the associated graphic. Three packages are
currently displayed. From left to right these are Sintel, Big Buck Bunny, and Tears of Steel. This is,
however, a scrollable display and two additional packages may be displayed: Sita Sings the Blues
and Elephant Dreams.
Currently, only the first package, Sintel, is accessible. Selection of any of the others will
result in a “work in progress” pop-up message. To dismiss the pop-up, LEFT-click anywhere outside
of the pop-up.
Motion Picture Laboratories, Inc.
CONFIDENTIAL
8
CPE Sample
Implementation
DRAFT
Ref :
TR-CPE-SIMPL
Version :
v0.8
Date: August 27, 2014
2.3.3 Sintel Intro
If the Sintel 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:
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 Sintel
demo package will initially display an introduction consisting of the movie poster on one side and a
slide-show that continually loops on the other:
To exit the intro and access the package's main-menu, LEFT click anywhere on the page.
Motion Picture Laboratories, Inc.
CONFIDENTIAL
9
CPE Sample
Implementation
DRAFT
Ref :
TR-CPE-SIMPL
Version :
v0.8
Date: August 27, 2014
2.3.4 Sintel Main Menu Page
The demo package uses a Main Menu page with a collapsible menu bar on the right side of
the page and a poster graphic in the center:
The menu may be collapsed or expanded using the button at the top:
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 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.
Motion Picture Laboratories, Inc.
CONFIDENTIAL
10
CPE Sample
Implementation
DRAFT
Ref :
TR-CPE-SIMPL
Version :
v0.8
Date: August 27, 2014
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 changed to a Logout button:
2.3.6 ‘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 Play icon will be activated.
2.3.7 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.
2.3.8 Timed Events
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:
Motion Picture Laboratories, Inc.
CONFIDENTIAL
11
CPE Sample
Implementation
DRAFT
Ref :
TR-CPE-SIMPL
Version :
v0.8
Date: August 27, 2014
Currently the demo software only allows the display of these Notices. Future releases will
also support social networking functions supported by the API.
Motion Picture Laboratories, Inc.
CONFIDENTIAL
12
CPE Sample
Implementation
DRAFT
Ref :
TR-CPE-SIMPL
Version :
v0.8
Date: August 27, 2014
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 handled by globally accessible
modules.
•
The modular design of the framework is closely matched to the groups and subgroups
defined by the API (e.g., CPX_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
13
CPE Sample
Implementation
DRAFT
•
Ref :
TR-CPE-SIMPL
Version :
v0.8
Date: August 27, 2014
{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. Use any browser to 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:
•
Package Management API Group
•
Content Access API Group
•
Account Access API Group
•
Player Interaction API Group
•
Social Networking API Group
•
Enhancements API Group
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.
Motion Picture Laboratories, Inc.
CONFIDENTIAL
14
CPE Sample
Implementation
Ref :
TR-CPE-SIMPL
Version :
v0.8
Date: August 27, 2014
DRAFT
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.
Subgroup
Lifecycle
Status
M - Supported
Connectivity
Environment
O
O
Availability
Access Event
M - Supported
M - Supported
Download
O
Account Access
Basic
Account Event
M - Supported
M - Supported
var CPX_AccountMgmt
Player Interaction
Lifecycle
M - Supported
var CPX_PlayerMgmt
Basic
M - Supported
instance of PlayerWrapper
Trickplay
O
Controls
Sound
O
O
Player Event
M - Supported
instance of PlayerWrapper
M - Supported
O
instance of PlayerWrapper
Social Networking
Geometry
Sharing
Enhancements
Social Event
Wishlists
M
O
Bookmarks
O
Package History
O
Content Access
Access Mechanism
var CPX_PackageMgmt
var CPX_ContentMgmt
var CPX_ContentMgmt
The following example shows how to create a new player and then add an event listener:
var statusDesc = CPX_PlayerMgmt.createPlayer(contentId, playerId);
// aget the PlayerWrapper instance
var mainPlayer = statusDesc.context;
// add an event listener
playerListener = new DemoPlayerListener();
mainPlayer.addListener(playerListener);
Motion Picture Laboratories, Inc.
CONFIDENTIAL
15
CPE Sample
Implementation
DRAFT
Ref :
TR-CPE-SIMPL
Version :
v0.8
Date: August 27, 2014
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:
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"
},
{
"id":"bbb",
"title":"Big Buck Bunny",
"display":"../resources/framework/images/PackageLogos/bbb.jpg",
"status":"PENDING"
},
{
"id":"tos",
"title":"Tears of Steal",
"display":"../resources/framework/images/PackageLogos/tos.jpg",
"status":"PENDING"
}
}
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”.
Motion Picture Laboratories, Inc.
CONFIDENTIAL
16
CPE Sample
Implementation
DRAFT
Ref :
TR-CPE-SIMPL
Version :
v0.8
Date: August 27, 2014
•
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
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 :
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
The framework 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 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:
CPX_PackageMgmt.status(statusDesc);
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:
Motion Picture Laboratories, Inc.
CONFIDENTIAL
17
CPE Sample
Implementation
DRAFT
Ref :
TR-CPE-SIMPL
Version :
v0.8
Date: August 27, 2014
packState = P_STATE_AVAILABLE;
// Notify framework:
statusDesc = new StatusDescriptor(LEVEL_INFO, CC_STATE_CHANGE);
CPX_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 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.
The file sintel01.js includes a function, loadBase(), that will execute when the js file
completes loading. It will trigger the loading of the 'base' file blenderBase.js. This second file
provides a set of functions intended to provide a common look-n-feel across all packages
developed by this content provider (i.e., blender.org). 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).
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. As an example, the file ContentAccess.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;
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
18
CPE Sample
Implementation
DRAFT
Ref :
TR-CPE-SIMPL
Version :
v0.8
Date: August 27, 2014
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
•
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:
Motion Picture Laboratories, Inc.
CONFIDENTIAL
19
CPE Sample
Implementation
DRAFT
Ref :
TR-CPE-SIMPL
Version :
v0.8
Date: August 27, 2014
<ul id="cpx_header_bar">
<img id="cpx_hdrBtn_logInOut" class="cpx_hdrBtn"
src="../resources/framework/images/LoginBtn.jpg"
onclick="CPX_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="Retailer.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='Retailer.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' parameter that points to the javascript that will dynamically
build the remaining HTML: <body onLoad="Retailer.initialize( )"> The Retailer object
is defined in the file Main.js.
There are four categories of JavaScript that the HTML page loads:
•
API definition: this currently consists of five files, each of which is specific to one of the
groups defined by the Cross Platform Extras interface and discussed previously in Section
3.2. The files are all located in the directory {Install_dir}/scripts/API. Future
releases of the Sample Implementation will include a single-file minified version.
•
Framework implementation: This set of files is located in the directory
{Install_dir}/scripts/demo/framework. As in the case of the API files, 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
20
CPE Sample
Implementation
DRAFT
Ref :
TR-CPE-SIMPL
Version :
v0.8
Date: August 27, 2014
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 1. At the core is the Retailer, which is defined
in the file Main.js. The Retailer 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.
As noted in the previous section, the HTML page identifies Retailer.initialize() as the
'onLoad' function. The primary task of this function is to initialize five global singleton variables:
var
var
var
var
var
CPX_PlayerMgmt = null;
CPX_AccountMgmt = null;
CPX_PackageMgmt = null;
CPX_ContentMgmt = null;
CPX_BackEndSvc = null;
The first four of these all are mapped to instances of modules that implement one of the API
sub-groups. For example,
CPX_AccountMgmt = 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 PackageMgmt, ContentMgmt, and PlayerMgmt.
The last of the CPX_ globals is CPX_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.
Motion Picture Laboratories, Inc.
CONFIDENTIAL
21
CPE Sample
Implementation
DRAFT
Ref :
TR-CPE-SIMPL
Version :
v0.8
Date: August 27, 2014
Figure 1 SI Architecture
The last major component configured as part of the Retailer initialization process is the
Storefront. The Storefront class 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 component.
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:
Motion Picture Laboratories, Inc.
CONFIDENTIAL
22
CPE Sample
Implementation
DRAFT
Ref :
TR-CPE-SIMPL
Version :
v0.8
Date: August 27, 2014
•
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.
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 two CSS files. These are:
•
../styles/CPE-UI.css – this contains styles used by one or more of the CPE-UI
JavaScript files. Changes may impact proper operation of layouts or component widgets.
•
../styles/MLabsRI.css – contains styles used only in the context of the Sample
Implementation framework (e.g., background color of the menu header bar)
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.
The BES Interface is depicted in Figure 1 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
Motion Picture Laboratories, Inc.
CONFIDENTIAL
23
CPE Sample
Implementation
DRAFT
Ref :
TR-CPE-SIMPL
Version :
v0.8
Date: August 27, 2014
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
};
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.
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.
Motion Picture Laboratories, Inc.
CONFIDENTIAL
24
CPE Sample
Implementation
DRAFT
•
Ref :
TR-CPE-SIMPL
Version :
v0.8
Date: August 27, 2014
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 Retailer.initialize() code in Main.js to assign the new module as the
CPX_BackEndSvc
4.4 RI Package Architecture
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.
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).
Motion Picture Laboratories, Inc.
CONFIDENTIAL
25
CPE Sample
Implementation
DRAFT
•
Ref :
TR-CPE-SIMPL
Version :
v0.8
Date: August 27, 2014
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:
/*
* 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';
Motion Picture Laboratories, Inc.
CONFIDENTIAL
26
CPE Sample
Implementation
DRAFT
Ref :
TR-CPE-SIMPL
Version :
v0.8
Date: August 27, 2014
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.
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;
Motion Picture Laboratories, Inc.
CONFIDENTIAL
27
CPE Sample
Implementation
DRAFT
Ref :
TR-CPE-SIMPL
Version :
v0.8
Date: August 27, 2014
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);
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);
}
Motion Picture Laboratories, Inc.
CONFIDENTIAL
28
CPE Sample
Implementation
DRAFT
Ref :
TR-CPE-SIMPL
Version :
v0.8
Date: August 27, 2014
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);
}
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:
Motion Picture Laboratories, Inc.
CONFIDENTIAL
29
CPE Sample
Implementation
DRAFT
Ref :
TR-CPE-SIMPL
Version :
v0.8
Date: August 27, 2014
•
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");
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);
Motion Picture Laboratories, Inc.
CONFIDENTIAL
30
CPE Sample
Implementation
DRAFT
Ref :
TR-CPE-SIMPL
Version :
v0.8
Date: August 27, 2014
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
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:
Motion Picture Laboratories, Inc.
CONFIDENTIAL
31
CPE Sample
Implementation
DRAFT
Ref :
TR-CPE-SIMPL
Version :
v0.8
Date: August 27, 2014
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:
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:
Motion Picture Laboratories, Inc.
CONFIDENTIAL
32
CPE Sample
Implementation
DRAFT
Ref :
TR-CPE-SIMPL
Version :
v0.8
Date: August 27, 2014
/*
* 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 30 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);
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.
Motion Picture Laboratories, Inc.
CONFIDENTIAL
33
CPE Sample
Implementation
DRAFT
Ref :
TR-CPE-SIMPL
Version :
v0.8
Date: August 27, 2014
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.

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.
Motion Picture Laboratories, Inc.
CONFIDENTIAL
34
CPE Sample
Implementation
DRAFT
Ref :
TR-CPE-SIMPL
Version :
v0.8
Date: August 27, 2014
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);
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:
Motion Picture Laboratories, Inc.
CONFIDENTIAL
35
CPE Sample
Implementation
DRAFT
Ref :
TR-CPE-SIMPL
Version :
v0.8
Date: August 27, 2014
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
36
CPE Sample
Implementation
DRAFT
Ref :
TR-CPE-SIMPL
Version :
v0.8
Date: August 27, 2014
5 FRAMEWORK DEVELOPMENT & CUSTOMIZATION
TBS
6 PACKAGE DEVELOPMENT & CUSTOMIZATION
TBS
Motion Picture Laboratories, Inc.
CONFIDENTIAL
37