Content Player

This section provides details about the Content Player which is what is loaded for launched content (except for tincan.xml based packages¹). As of 2017.1 the player and supporting files are static assets that can be served with the Engine server application or may be hosted remotely along with content (on a CDN for instance).

Variants

When launching content in Engine there are two "players" that can be used, specifically the "modern" player and the "legacy" player. The modern player is the default, but that default may be changed using the UseModernPlayer configuration setting. You can also specify the player to use on a per-launch basis by adding player=modern or player=legacy to the launch URL.

The legacy player is really only intended to be used by Engine customers upgrading from version 2015 or before. Customers starting with 2016.1 or after should only use the modern player.

Modern (responsive)

The modern player is designed to be responsive to differing screen sizes and uses a more modern HTML DOM structure. The content container is an <iframe> element and all supporting structure (when available and displayed) such as the course menu, title bar, navigation controls, etc. are contained within the page around the iframe container.

The responsiveness automatically adjusts the display, size, and position of the title, progress bar, and navigation controls (word vs. icon only) as well as the position of the course menu. In general,

• on larger screens: the course menu is along the left of the content container, the title is larger (for very long titles may still split onto multiple lines), the navigation control buttons include both a title and an icon and are right aligned, and the progress bar is displayed
• on medium screens: the course menu shifts to be vertically between the title bar and the content container, the title is more likely to break onto multiple lines, the navigation control buttons switch to be icon only, and the progress bar may be hidden
• on smaller screens: the title and navigation control buttons shrink
• on very small screens (i.e. phone in portait mode): the title shifts up and the navigation control buttons move down and become left aligned

Additional specific work has been done on the modern player to make it more accessible for keyboard navigation and screenreader use.

Additionally the modern player supports inclusion of a customized logo image that will be displayed in the upper left corner of the header when configured. See the ModernPlayerCustomizationLogo configuration setting. The logo has a set height of 46 pixels so that it will appropriately fit in the header container. The width is dynamically scaled by the browser allowing for logos of different shapes to be handled in the same player space. The width will effect the display of responsive components, so it should be taken into account and tested with courses of varying title length. Because the browser landscape isn't well adapted to high DPI images yet, to support such devices we suggest that larger image files are used despite the performance overhead. Ultimately these logos are displayed relatively small (46 pixels high) so even at larger physical dimensions the resulting image size should be manageable compared to typical course content. To scale as cleanly as possible images should be created with a vertical dimension that is a multiple of 46 pixels.

Legacy (original)

The legacy player is the original Engine player and uses an older HTML DOM structure from before iframes were well supported in browsers. The legacy player uses a nested <frameset> with one frame acting as the content container and supporting structures getting their own independent frames.

Customizing

Player Settings / Package Properties

Both players support the vast majority of the configuration settings in the "Player Settings" section of the documentation as they generally pertain more to the content and the player's structural items (navigation controls, title bar, etc.). See below for customization of the player's skin and/or customization of the player's logic using the "DeliverCustomization Settings".

Skinning

The two players have to be customized independently because of the significant differences in their DOM structures. Each player has a configuration setting to load a CSS file for customization during player load. This CSS file will be appended to the DOM's <head> element and allows for sufficient specificity to override any other style property. The configuration settings are: ModernPlayerCustomizationStylesheetUrl and LegacyPlayerCustomizationStylesheetUrl. The value set for each must be a URL to the stylesheet and may be absolute or relative to the player/ directory. Note: failure to load the customization stylesheet URL WILL NOT cause the player to stop execution as it is assumed to be used for display purposes only.

Execution

Generally before customizing the execution of the player we suggest you discuss the proposed adjustments with the Engine support team. Engine is intended to be very flexible and may already have a customization setting for the behavior you want. If it doesn't, it's possible we could add it as a core feature of Engine rather than requiring you to add customization code.

As with skinning above, each player has a configuration setting for loading a JavaScript file from a URL. The configuration settings are ModernPlayerCustomizationScriptUrl and LegacyPlayerCustomizationScriptUrl. The value set for each must be a URL to a JavaScript script file and may be absolute or relative to the player/ directory. Note: failure to load the customization script URL (including invalid JavaScript) WILL cause the player to stop execution and display an error message as it is assumed the functionality is required for proper player execution.

The client customization script is loaded near the end of the player initialization process. It is loaded after the runtime configuration from the server has been made available via an rscpCfg object as well as other player core objects such as the IntegrationImplementation object specific to the player and which exposes the translated strings. The rscpCfg object exposes values such as the learning standard, learner items, external config/registration id, and the registration object being delivered.

If a client customization script is used, it must call the rscpCustomizationCompleted function (in the global namespace). The client customization script is intended to be executed on load, but stalls initialization of the player until the function is called. If this function is never called the player will appear to hang, but will place a warning in the console after 5 seconds.

Remotely Hosted Deliver Page

For legacy reasons the player HTML page(s) is referred to as the "Deliver Page". The content player and all necessary assets are now static and can be served outside of the web application package. This makes it possible to serve the player at a different location from the rest of the Engine server application. At launch time the launch page handler will redirect to the deliver page and the loading of that page will make an AJAX request to the Engine server to get all other necessary runtime configuration information.

To implement this setup it is necessary to copy the defaultui/player/ directory (and files) to a location at the same domain as the content and then provide the location as the value for the RemoteDeliverPageUrl configuration setting.

If you have imported content prior to switching to a remotely hosted player, please take steps to ensure that the content is accessible from the same domain as the new remote player. Since the web path of a course's content is stored during the import process, the web path may no longer be valid after the switch, especially if you used a fully-qualified url with a different domain than the remote player. Once you have made the old content accessible under the domain of the remote player, you can use the WebPathToContentRootHistory setting to have Engine replace old content web paths with the new one at runtime, if necessary.

Note: when using this feature, you will probably need to specify fully-qualified urls for your RedirectOnExitUrl and RedirectOnRefreshUrl, as otherwise they will be relative to the domain of the remote player and not the Engine application.

¹. Packages with a tincan.xml file (or Tin Can packages) bypass the deliver page by being launched to the content's URL directly and are expected to handle their own "player" like requirements and communicate solely via the xAPI LRS. ↩