Playlist UI Plugin

Product(s)
Video Cloud
Brightcove Player
Role(s)
Player Developer
Task(s)
Create & Use Playlists
Topic(s)
Playlists
Plugins

In this topic, you will learn how to use the Playlist UI plugin to enhance the look and feel of default playlist functionality.

Overview

The Playlist UI Plugin contains the options you can use to customize playlist behavior. The numerous options provide changes to playlists, including their layout, behaviors and implementation strategies. The following examples show the two basic layouts for playlists, vertical and horizontal. For each example a small set of behaviors are listed for an introduction of what can be customized.

Vertical layout

This playlist example below demonstrates:

  • The vertical playlist located on the right side of the player has a show/hide button and the playlist is automatically sized and positioned. This is default behavior when using the Standard (iframe) player implementation.
  • The playlist is initially displayed. This can be altered by using the hideOnStart option.
  • Near the end of the video an overlay appears that displays the time to the next video and the next video's thumbnail. This is default behavior and controlled via the nextOverlay option.

Horizontal layout

This playlist example below demonstrates:

  • A horizontal playlist located below the video.
  • As well as the overlay being displayed near the end of the video, as is true in the example above, an endscreen shows the time before the next video begins playing. This is because the autoadvance option is non-zero and the endscreen displays for the pause between videos. The endscreen can be altered by using the nextEndscreen option.

Player/Playlist association

By default, the Playlist UI Plugin will handle finding the correct playlist container element for a given player. This means it will find the first empty .vjs-playlist element in the DOM and use that. However, the plugin offers more explicit associations that can be made between a player and playlist container when you are building complex workflows with multiple players.

data-for attribute

The data-for attribute can be applied to the playlist container to associate it with a player's id, for example:

<video-js id="myPlayerID"
  ...></video-js>

<div class="vjs-playlist" data-for="myPlayerID"></div>

This is the most specific method of explicit association available. It takes precedence over other method(s).

data-player and data-embed attributes

The data-player and data-embed attributes can be applied to the playlist container to associate it with a Brightcove Player. Note that both attributes must be used for the associate to function properly. In the following example, only the second <div> tag will hold the playlist for the player as a specific association is made. The first <div> will be empty.

<video-js data-playlist-id="5455901760001"
	data-account="1507807800001"
	data-player="SJLNAJye7"
	data-embed="default"...></video-js>
<script src="https://players.brightcove.net/1507807800001/SJLNAJye7_default/index.min.js"></script>

<div class="vjs-playlist"></div>

<div class="vjs-playlist" data-player="SJLNAJye7" data-embed="default"></div>

Options

You may pass in an options object to the plugin upon initialization. This object may contain any of the following options:

autoadvance

  • autoadvance:
    • Type: number
    • Default: undefined
    • Determines if, and for now long, a pause between videos in a playlist occurs. For complete details see the autoadvance section in the Playlist API Guide.

hideOnStart

  • hideOnStart:
    • Type: boolean
    • Default: false
    • Determines whether the playlist is initially hidden from view. This is only functional when using the iframe player implementation, which is logical since the show/hide playlist functionality is only available in the iframe. This option does NOT work with a horizontal playlist.
    • Requirements/dependencies:
      • playlistPicker: true
      • iframe embed
      • horizontal: false

horizontal

  • horizontal:
    • Type: boolean
    • Default: false
    • Displays the playlist horizontally below the player instead of vertically.
    • Requirements/dependencies:
      • playlistPicker: true

nextButton

  • nextButton:
    • Type: boolean
    • Default: true
    • If true, a button is added for moving to the next playlist item. The button can be disabled by setting the option to false. The button is added to the control bar to the right of the play button.
next button

nextEndscreen

  • nextEndscreen:
  • Type: boolean
  • Default: true
  • If true, the player will display a modal endscreen over the player after playback. The endscreen can be disabled by setting the option to false. This endscreen will preview the upcoming video in the playlist. Mode details on the option are:
    • The autoadvance option must be set to a value greater than zero (otherwise, there is no time to display the endscreen and it is skipped).
    • The displayed countdown represents the time remaining until the autoadvance trigger.
    • The player must not include an implementation of the custom endscreen plugin or the social plugin configured to display after a video. If either condition is detected, the endscreen will not be displayed.
next endscreen

nextOverlay

  • nextOverlay:
    • Type: boolean
    • Default: true
    • If true, the player will display a small overlay in the lower-right corner of the player. The overlay can be disabled by setting the option to false. This overlay will preview the upcoming video in the playlist. Mode details on the option are:
      • There must be a subsequent playlist item.
      • The autoadvance option must be set greater than or equal to zero.
      • The countdown represents the time remaining in the video plus any autoadvance wait time.
      • The overlay appears 10 seconds from the end of the video. However, if the video is less than 30 seconds long, it appears at the 2/3 point of the duration.
      • If the overlay is dismissed by the user, it will remain dismissed until the source is changed. It will re-appear for new sources.
      • If the Up Next endscreen is enabled, the overlay will hide when the video ends. Otherwise, it will stay open until the next video.
next overlay

playlist

  • playlist:
    • Type: array
    • Default: undefined
    • Used to pass the initial playlist data. For complete details see the playlist section in the Playlist API Guide.

playlistPicker

  • playlistPicker:
    • Type: boolean
    • Default: true
    • Determines whether or not to include a visual list of videos in the playlist so the user can click on them. The hideOnStart and horizontal options modify its appearance and behavior. When playlistPicker is false, other UI elements can still be shown using the nextButton, nextEndscreen and nextOverlay options.

playOnSelect

  • playOnSelect:
    • Type: boolean
    • Default: false
    • The playOnSelect option is used to control if the video should begin playing when the user clicks a video in the playlist. When the option is set to true, selecting a new video from the playlist will start playing that video, even if the player was previously paused. By default, clicking a new video from the playlist will load the new video but keep the player paused if it was paused beforehand.
    • Requirements/dependencies:
      • playlistPicker: true

repeat

  • repeat:
    • Type: boolean
    • Default: false
    • Repeats a playlist after it has finished the last video in the playlist. This functionality plays the first video in the playlist once the last video in the playlist is finished.

shuffle

  • shuffle:
    • Type: boolean
    • Default: false
    • Shuffle the playlist items each time new data is loaded.

Using the options

You have two ways you can utilize the option:

  1. In Studio's PLAYERS > PLUGINS section.
  2. Using JavaScript with the player.

Using Studio

In Studio, if you have selected the player to use playlists in the player properties' Styling section you can set some of the above options in the UI. The following options are available in the Playback section for playlist players:

Playlist options in Studio

If you select Continuous play mode you can choose a Video Countdown option. The visual representation of the choices is shown here:

Up next card

Playlist card option

Up next endscreen

Playlist endscreen option

Using JavaScript

To implement the options in code, you create an object, assign desired options their respective values, then pass the options object when calling the plugin:

videojs.getPlayer('myPlayerID').ready(function() {
 var myPlayer = this,
   options = {};
  options.horizontal = true;
  options.nextButton = false;
  myPlayer.bcPlaylistUi(options);

Changelog

29 Oct 2018

v3.4.2

  • Added playlistPicker option, defaulting to true, to allow removal of the playlist picker (when passed as false)
  • Bug Fix: Make the horizontal playlist in iframe players have a static 20% height, instead of a variable height
  • Bug Fix: Fix an issue where a vertical scrollbar would appear on horizontal playlists
  • Bug Fix: Remove the playlist UI when the player is disposed

3 Oct 2018

v3.4.1

  • Fixed an issue where a vertical scrollbar would appear on horizontal playlists
  • Remove the playlist UI when the player is disposed

25 Sep 2018

v3.4.0

  • Added playlistPicker option, defaulting to true, to allow removal of the playlist picker.

17 Sep 2018

v3.3.2

  • Fixed an issue where a playlist player loaded at the wrong time could cause the UI not to render
  • Removed the postinstall script to prevent install issues
  • Silenced a play promise exception in playlists
  • Updated using plugin generator v7.2.0

13 Jun 2018

v3.3.1

  • Fixed an issue where the next item button did not have a pointer cursor

23 May 2018

v3.3.0

  • Support associating a playlist element explicitly with a player via attributes

9 May 2018

v3.2.1

  • Fixed an issue where an embed code which places a script before a playlist container on a page with multiple players with playlists could result in those playlists getting out of order

9 April 2018

v3.2.0

  • Added shuffle option to randomize playlist each time it's changed

29 Mar 2018

v3.1.1

  • Truncate longer video titles with ellipses when they overflow

25 Jan 2018

v3.1.0

  • Update to videojs-playlist 4.2.0, adding duringplaylistchange event and rest option for the shuffle() method

17 Jan 2018

v3.0.1

  • Addressed case where the playlist was empty, but the playlist sidebar in an iframe would still show
  • Fixed an issue where auto-advance would occur even if the user restarted playback after an ended event
  • Fixed clicking/tapping on icons in next overlay and endscreen on mobile

22 Dec 2017

v3.0.0

  • Features
    • Add optional Up Next closable overlay card
    • Add optional Up Next endscreen modal
    • Better support for multiple in-page players by more intelligently finding a player's associated playlist element
    • Bundle videojs-playlist as a direct dependency
    • Support horizontal playlists in iframe players
  • Code Refactoring
    • Move sidebar to component and refactor plugin to be class-based
    • Refactor new Up Next feature
    • Update tooling to plugin generator v5.1.1
  • BREAKING CHANGES
    • Removes support for IE8
    • No longer supports Video.js/Brightcove Player v5

21 Sep 2017

v2.1.2

  • No changes

25 Jul 2017

v2.1.1

  • No changes

26 Apr 2017

v2.1.0

  • Features
    • Add optional "Up Next" closable overlay card
    • Add optional "Up Next" endscreen modal
    • Better support for multiple in-page players by more intelligently finding a player's associated playlist element
    • Bundle videojs-playlist as a direct dependency
    • Support horizontal playlists in iframe players
  • Code Refactoring
    • Move sidebar to component and refactor plugin to be class-based
    • Refactor new 'Up Next' feature
    • Update tooling to plugin generator v5.1.1
  • BREAKING CHANGES
    • Removes support for IE8
    • No longer supports Video.js/Brightcove Player v5

8 Sep 2016

v2.0.0

  • Redesigned UI
    • Overall look and feel improvements
    • Bigger thumbnails
    • Room for longer video titles
    • Playlist drawer in iframe embeds
    • More responsive layout

6 Sep 2016

v1.0.1

  • Fix bug embedding playlist with in-page embed

16 Aug 2016

v1.0.0

  • Moved playlist UI into a new plugin