Easy to use
- Takes care of all tasks needed to embed content from Ooyala onto a page
- Support for multiple players on pages
- Support for lazy loading of players on specified events
- Plethora of css hooks to use to style the player given its state
- Mechanisms for accessing the global
OOobject for a player, as well as the underlying Ooyala player itself
- Chainable, jquery-like interface for subscribing to player events
- Fine-grained control over the plugin's automatic initialization logic
- Built using jquery-boilerplate
- Full suite of jasmine unit tests
- 100% code coverage, verified by istanbul
- Heavily annotated source code, and a plethora of demos to get you up and running quickly!
Built by your friends on the Refinery29 Mobile Web Team
Table of Contents
generated with DocToc
- Basic Usage
- Advanced Usage
- Full List of Options
- Running Demos
You can install jquery-ooyala using either bower
$ bower install jquery-ooyala
$ component install refinery29/jquery-ooyala
$ npm install jquery-ooyala
Initializing the player
In your html, add an element with class "oo-player", as well as a script tag pointing to jquery and jquery-ooyala
<!-- .... --><!-- use dist/jquery.ooyala.min.js for a minified version -->
And that's all there is to it! jquery-ooyala will take care of all the plumbing around loading the Ooyala v3 player represented by the id specified in
data-player-id, as well as create the Player with the video specified by
<!-- .... --><!-- use dist/jquery.ooyala.min.js for a minified version -->
Then you can instantiate the plugin like so:
Note that in either case, playerId and contentId are required.
Often times, especially on mobile, you'll want to wait until a user interacts with an element on your page before you load all of the assets needed for the ooyala player. You can easily achieve this functionality using jquery-ooyala by specifying an event it should listen for before loading the player.
Tap me to load a video!
Now the ooyala player will not be loaded until a
touchend event is triggered on that element.
Using the Flash-based player
By default, jquery-ooyala opts for loading Ooyala's HTML5-based video player, rather than its flash version. If you'd like to disabled this functionality and only use the HTML5 player as a fallback by using
data-favor-html5="false" on an
.oo-player element, or by specifying
Customizing player placement within an element
jquery-ooyala allows you to control where exactly the player gets placed within its containing element via the
data-player-placement attribute (html) /
- "append" - The player will be appended to the element
- "prepend" - The player will be prepended to the element
- function( $videoContainer ) - A function can be used here to provide complete control over exactly where the player gets placed. It will be passed a jquery object representing the element containing all of the Ooyala DOM. This value of
thisin this function will be set to the jquery object representing the element the plugin was called on.
Here's how you could specify player placement using HTML
This text will appear below the ooyala player
jquery-ooyala provides the following css hooks for styling:
oo-playeris added to every element which the plugin is called on
oo-player-loadingis applied during initialization (before the player/content has loaded) as well as when different videos are being loaded
oo-player-readyis applied when content has been loaded and is ready to be played
oo-player-playingis applied when the player is current playing content
oo-player-pausedis applied when currently playing content is paused
oo-player-erroris applied if there is an error loading the player script, or if there is an error when loading content for a player
We use SMACCS-style naming conventions and don't apply any styling ourselves. Therefore you can apply universal styles using
oo-player, and then apply more specific styles using the
oo-player-* state specifiers.
Subscribing to player events
jquery-ooyala provides an interface to subscribe to Player events in the same way that you would subscribe to any other event on a jquery object. The format for subscribing to these events is
<EVENT_KEY> corresponds to a property name on the
OO.EVENTS object. All arguments sent by the player message bus will be passed onto the event handlers.
For more information on the events you can hook into, take a look at Ooyala's Player Message Bus Events
Using Additional Elements to Load / Seek Within Videos
A common use case with any video player is the ability to change the current video that is playing. This can be accomplished by using what we call "triggers". Triggers are elements that, when interacted with, will change the state of the player. A trigger looks something like this:
Play different video
data-oo-player-trigger param lets jquery-ooyala know that when the button is clicked, then the player within
<div id="player"/> should be load in the content
represented by id
"456". These triggers are registered when jquery-ooyala first initializes.
Triggers can also be used to seek within the same video. This is useful for longer videos, in which you may want something similar to "Chapters"
Chapter 1 (0:00)Chapter 2 (5:00)
The properties that can be specified within this object are as follows:
- domId: (Required) The id of an element which jquery-ooyala was initialized on.
- contentId: (Required) The id of the content that should be loaded.
- seek: (Default: 0) If the
contentIdis the same as the current
contentIdfor the content that's playing, this will cause the player to seek to the specified offset (in seconds) within that video. Note that this property will do nothing if the
- event: (Default: "click") String representing the event that will be listened to in order to active the trigger. Useful for mobile devices, or for more interactive video experiences where you want things to change on mouseovers, mousemoves, etc.
var $el =ooyala = $eldata "ooyala" ;;;
Custom script tag / player params
If you need to provide any query paramaters to the player script call, or need to provide any additional embedded parameters to the ooyala player, you can do so by using
Note that for url params,
namespace will be ignored, as we control that internally. Additionally,
onCreate is ignored in player params. See the next section for info on how to hook into
Directly accessing the Ooyala global object and player
When the ooyala script has completely loaded and the player has been created, the element containing the ooyala plugin will trigger an
"ooyala.ready" event on itself, and pass along both the instantiated player, as well as that player's global
OO object. You can hook into this event to perform low-level interactions with the player and the object.
The plugin instance itself can be retrieved by calling
.data( "ooyala" ) on the element. This will return an instance of
OoyalaWrapper, which is what we use to encapsulate all of the functionality of the plugin.
When jquery-ooyala initially loads, it automagically checks for all elements of class
oo-player and instantiates the plugin on all of them. It also wires up any trigger elements it finds. If you want to disable this functionality, add a
data-auto-init="false" attribute to the script tag that loads the player. Note that within the code we simply check for
script[data-auto-init], so that attribute can be attached to any script tag, such as a built
<!-- vendor.js contains jquery-ooyala bundled with it -->
You may also want to manually trigger this event, such as in a single-page application where elements are dynamically generated. You can do this by triggering a
document, which jquery-ooyala will listen to and perform that initialization logic when it's triggered.
Accessing the plugin constructor directly
You can access the
OoyalaWrapper constructor function by invoking
$.data( document.body, "_jquery.ooyala" ). Note however, that in most cases there are better ways to achieve what you are trying to do than this way. However, if you'd rather use a different pattern in your code than a traditional jquery plugin pattern, this will give you that flexibility.
This is the constructor that is used to instantiate the plugin on each element it's called on.
var ooyala = data "ooyala" ; // OoyalaWrapper instance
- el/$el: The element / jquery Object containing the element (respectively) that the plugin was called on.
- settings: An object representing the options the plugin was instantiated with, merged with its defaults.
- init( opts ): Called on instantiation to initialize the player. Takes an object
optscontaining plugin options (outlined below)
- getPlayer(): Makes a call for the ooyala player specified in
options.playerId. Returns a promise that is fulfilled when the player script loads and is executed
- loadContent( contentId ): Switches out the current content in the player for the one specified by
Ooyala Player method proxies.
OoyalaWrapper proxies the ooyala player's
skipAd() functions. See the ooyala docs for information on how to use those methods.
Full List of Options
||The id of the player to load|
||The id of the content for the player to load|
||When set to true, this will append
||When specified, the plugin will wait to load the player until the specified event is dispatched on the element. Note that this accepts any valid string that
||Options object that will be passed to
||Specifies how the player should be placed within its containing element. Can be either
||Object representing url params to be sent along with the player script tag url|
- cd into the plugin directory and run a static file server (such as Python's
SimpleHTTPServer)$ cd /path/to/jquery-ooyala$ python -m SimpleHTTPServer
- Navigate to
localhost:8000/demo/DEMO_FILE_NAME.htmlwhere you should see the demo. Note that we load bootstrap and jquery from a CDN on these pages, so you'll need a working internet connection.
I'm not seeing anything when I use the plugin on an empty element
Ensure that you set at least a
min-height and (if you're not using a block element) a
min-width on the element you're placing the plugin into. Ooyala sets styles on their html5 player by to
width:100%;height:100% so if your element has no width/height, it won't show. You can also use the
.oo-player css hook to apply global styles to all ooyala players on your page.
I'm trying to specify a certain namespace using
urlParams, but I'm not seeing the Ooyala object in that namespace
jquery-ooyala does not honor the url param if passed in. This is the only way we can reliably support having multiple players on one page. If you really need to assign a global
OO object for a player to a specific window property, you can accomplish this by using the
If you're experiencing other problems or have found a bug, please let us know by creating an issue
MIT License © Refinery29, Inc. 2014