This section provides details about the Content Player which is what is loaded for launched content (except for
tincan.xml based packages1). 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).
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=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.
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.
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.
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".
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:
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.
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.
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.
We've been implementing learning standards for more than a decade. So we know where the specifications are vague, incomplete, and/or frustrating. And we've worked hard to design Engine to work around those moments as much as possible. This is why player settings (previously called package properties) exist.
Player Settings are settings associated with each course imported into Engine that give you fine-grained control over specific conformance-related and interface behaviors.
Caution for Upgrading Customers: It's best not to mix the "Package Property Editor" (PPE) with the new configuration system settings mentioned above. Setting the associated configuration setting, even at the system level, will override any such value set in the PPE.
Here are a few of the most commonly used player settings:
If you are launching the player into a new window, then there are a number of settings that can be used to set the size of the player.
PlayerDesiredHeight- The number of pixels in height the course would like to have available, if possible, during delivery.
PlayerDesiredWidth- The number of pixels in width the course would like to have available, if possible, during delivery.
PlayerDesiredFullScreen- Specifies that the course is best experienced when it occupies the full screen.
PlayerDesired* settings are used to set the preferred dimensions of Engine's player. If the values configured for these settings are for some reason not possible, then the player will silently concede and allow for the size to be set to the nearest possible value. These settings are usually best used when the player size is a matter of user experience more than course functionality.
PlayerRequiredHeight- The number of pixels in height the course must occupy to function correctly.
PlayerRequiredWidth- The number of pixels in width the course must occupy to function correctly.
PlayerRequiredFullScreen- Specifies that the course must be experienced in full screen mode to function correctly.
PlayerRequired* settings are to be used when the specified dimension are non-negotiable. If the player cannot be sized according to the configured values, then an error will be displayed in a browser alert to inform the learner that the course will likely not function as designed. Use these settings if you have courses that require browsers be a certain size or if you have outside requirements informing player size.
PlayerLaunchType- Specifies how the player should be launched for this course.
PlayerScoLaunchType- Specifies how the individual learning objects of a course should be launched for this course.
PlayerLaunchType is used to configure if Engine's player should be launched in a new window or within an
iframe on the launch page. The most common values for this setting are
FRAMESET, but we do also support
NEW_WINDOW_AFTER_CLICK, which can be used to help get around some pop-up blockers.
PlayerScoLaunchType is a setting used to guide the behavior of the player when opening a new learning object. The name refers to a piece of the SCORM spec called SCOs, but the setting applies to every learning standard that has a similar idea. The AICC, SCORM, and cmi5 specifications each define a minimum piece of launchable content that every course is built out of at least one of. While each spec has their own nomenclature for these building blocks, we will generalize them into a concept we call "learning objects".
PlayerScoLaunchType has the same possible values as
PlayerLaunchType and follows the same behavior. If set to
NEW_WINDOW, then each learning object will be launched out of the player into a new window, and if the value is set to
FRAMESET, each learning object will be launched within an iframe in the player window.
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.
1. Packages with a
tincan.xmlfile (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. ↩