Custom Application Renderering

Our Player 2.0 framework was designed to be extensible for other developers to easily build on top of it. Create your own design for rendering the player, playlist (thumbs), or playlist tabs (UI for switching playlists) using JavaScript. Keep in mind that these three components are all rendered separately, therefore making it possible to mix renderers. We can, for example, have a custom renderer for the player with our standard playlist (thumbs) renderer or vice versa.

Please keep in mind that this type of custom rendering requires intermediate to advanced knowledge of JavaScript. Before you get started please take the time to understand how our rendering framework is structured, keep in mind the following libraries that are used by our framework, and review the code snippets on how to structure your JavaScript file. Below are also instructions on how to configure your application to call your JavaScript file and a brief overview of configuration properties.

Rendering Framework

Our framework was designed to be flexible and scalable. Our JS rendering framework is broken down into three separate components (player, thumbs, and tabs) as depicted in the image below:

  • Player Renderer - shown in blue
    • handles display (control bar, overlays etc.) and playback functionality
  • Thumbs Renderer - shown in green
    • handles how thumbnails are displayed
  • Tabs Renderer - shown in red
    • handles the UI of playlist switching
  • Playback stage - shown in black
    • handles logic of which playback adapter to load (flash, HTML5)

This breakdown allows for the flexibility to toggle components on or off (e.g. use a player renderer with no thumbnails) OR to mix and match your custom renderers. With each renderer, there are core properties you can leverage and you can create your own custom configuration properties. See the "Configurations Properties" section below for more information. Behind the scenes the Player and Playlist objects broadcasts beacons that send messages for other objects to listen to and fire events that can be wired up to perform some action at that event.

Develop Your Own Renderer

Libraries

Our framework (referred to as Apps JS) is bundled with the runtime version of HandlebarsJS, jQuery 1.9.1, and uses a namespaced version of RequireJS to prevent clashes with other scripts. RequireJS is used to manage dependencies both in our core and in our renderers and is accessible through com.onescreen.require and com.onescreen.define.

On loading our framework our version of jQuery will NOT fill the global variables: $ or jQuery. Instead, it is namespaced and available through com.onescreen.jq or as the 'jquery' module, so as not to interact with other versions of jQuery or other scripts that may be on the page. Please note that custom event handlers bound using another instance of jQuery may not interact properly with our Apps JS.

Keep in mind that, when building your own modules using our version of RequireJS, the base url is always the directory in which _onescreen.js is located. To reference your own modules you will have to do something like:

com.onescreen.define(['util', 'new/module/script.js', 'handlebars'], function(util, newModule, hb) { ... });

Accessing the Player and Playlist Object

Inside your player or thumbs/tabs renderer, you will receive either a player or playlist object, respectively. You will need to add some boiler-plate code to your modules since the require & define globals are placed in the com.onescreen namespace to prevent clashes with other scripts.

Inside your com.onescreen.define function, return a function with the first parameter being the config object, and the second parameter being either the player or playlist object. Note the use of css! in our define function. This is due to using require-css in our build script to optimize css. Not all of the modules in the below snippet are required in your define function.

Player Renderer Example
Thumbs or Tab Renderer Example

Configuration Properties

Our framework contains two types of properties:

  1. Core properties. Core properties are available across ALL renderers and include properties such as autoPlay, width and height of the player, startIndex, showThumbs, volume, mute, etc. For a full list of core properties please refer to our configuration properties page.
  2. Render specific properties. Render specific properties are properties that only apply to specific renderers. It is up to the renderer to respect these properties. Any non-core properties found on our configuration properties page apply to the standard/default player, thumbs and tabs renderer. In your custom renderers, you can create your own render specific properties.

Referencing Your Renderer

There are a couple of steps to take to set up your application to reference your JS file and apply any custom settings. In the properties bag of your application, you will need to set the appropriate property and provide a reference to your JS file as the value of the property. Depending on what type of renderer you are writing, will determine which property to use. For example, if you are writing a renderer for the player, you will use the playerRenderer property and provide a reference to your JS file as the value of that property. Use the thumbsRenderer property for thumbnail rendering and tabsRenderer for multiple playlists rendering.

You can reference your JavaScript file in the appropriate property in one of three ways:

  1. Provide the absolute path to your JS file
  2. Provide a relative path from the root of your JS file (path must reference the same domain)
  3. Provide the name of the renderer, if JS file is hosted by Adaptive Media (path will be constructed internally)

NOTE: A path relative to the current HTML document such as ../../renderers/player/main.js will break local require paths, as well as relative CSS using require.toUrl.

After properly referencing your JS file in the appropriate property, you can then add in any custom properties of your renderer.