JW6: WordPress Plugin Reference
The JW Player WordPress Plugin enables you to configure and embed audio and video content through your WordPress website. This is the official JW Player plugin, developed by the JW Player team itself.
Table Of Contents
This guide explains all functionality available in the plugin. For those eager to get started, there's a separate Getting Started guide, which explains the installation and basic embed process.
The JW Player WordPress Plugin is compatible with WordPress 3.0 and up.
The JW Player Plugin for WordPress extends the existing media management capabilities of WordPress. This allows you to embed the player into your post through the Add Media interface.
To insert a JW Player, simply click on the Add Media button while editing your post. This will cause the WordPress media manager popup to appear. Now, go to the Media Library section to select an audio/video file (or upload a new one). The metadata of this item appear to the right:
In addition to the default WordPress meta data, the JW Player Plugin for WordPress provides several fields related to the configuration of the JW Player. These include the following:
- This allows you to specify a poster image for the audio/video file from your Media Library. GIF, JPG and PNG images are supported. Alternatively, you can configure an image from outside WordPress by clicking the Thumbnail URL link.
- JW Player
- This allows you to embed the selected audio/video file into your post with JW Player. You can choose to select a specific Player Template or stick with the default one.
Clicking the button Embed JW Player button will insert its Short Code into your post and close the Media Manager.
The JW Player plugin adds two new screens to the Media Manager. The first, Add External URL, allows you to add an external media URL to the Media Library. Here's what the screen looks like:
As the help text says, several types of external media can be inserted. The Media Formats Reference has a full overview.
After inserting external URLs, they can then be managed and embedded just like videos you uploaded to the Media Library. You can also group external URLs together with uploaded media into playlists.
The second screen added to the media manager is the one to Embed a Playlist. It allows you to embed a playlist you created with JW Player:
To build a playlist, navigate to the Playlists page located in the Media section of the WordPress dashboard. There, you will see two table headers. The table on the right displays all audio/video files in your Media Library. The table on the left, initially empty, lists which videos are in your playlist:
To begin creating a playlist, enter the name of the playlist in the New Playlist field and click the Create Playlist button. Next, simply drag items from the right to the left column. To remove an item simply drag it back to the media column on the right. Once you are satisfied click the Save button to save the playlist. If you wish to remove a playlist, simply click the Delete button.
Note JW Player has the ability to display the playlist in a sidebar next to the video screen (here's an example). You can enable this through the listbar options in your Player Templates. The specific options are:
- listbar position
- Whether the playlist sidebar should be displayed to the right or bottom of the video screen. The default is none.
- listbar size
- The width (position=right) or height (position=bottom) of the playlist sidebar in pixels. The default is 180 pixels.
Note the listbar steals pixels from the video screen. If, for example, the player is 560 pixels high and a bottom listbar has a size of 200 pixels, that leaves 360 pixels for the video screen.
The JW Player WordPress plugin is very flexible in its management of the JW Player. You can begin embedding JW Players immediately after installing the plugin. However, you will be using the default JW Player template, which may not fit with the theme of your site. Therefore, there's the ability to design your own JW Player templates, under JW Player » Templates:
In this section, there's the ability to create new player templates or to edit, copy and delete existing ones. Clicking an Edit button will display the player template options.
The available player options depend upon which edition of JW Player you licensed. See our JW Player Introduction for an overview of the editions. See the Plugin Settings for directions on how to set your player edition and license key.
The actual embedding of a JW Player into an article body is controlled by the shortcode system. The shortcode system is quite flexible and allows for varying levels of complexity in your embedding. The basic syntax for the shortcode system is as follows:
[jwplayer param1="value1" param2="value2" ...]
When clicking an Embed JW Player button in the WordPress interface, a basic shortcode is always inserted. Here are a few examples:
[jwplayer mediaid="22" player="3"] [jwplayer playlistid="1" player="3"] [jwplayer mediaid="22"]
The first above shortcode embeds item 22 from your media library, using JW Player template number 3. The second shortcode embeds not a single media, but playlist number 1. The third shortcode contains no player, so the default Player Template is used.
In addition to these basic parameters, you can specify one or more Configuration Option to tweak your embeds. This gives you the flexibility to setup specific players without creating a new Player Template. Here are a few examples:
[jwplayer mediaid="22" player="3" width="320" height="180"] [jwplayer playlistid="1" player="3" autostart="true"] [jwplayer mediaid="22" primary="html5"]
In the first shortcode, the dimensions of the player are set to 320x180, overriding those set in player number 3. In the second shortcode, the player is set to automatically start playback on page load. In the third shortcode, the player is set to prefer the HTML5 rendering mode over Flash.
The JW Player WordPress Plugin provides settings for inserting your license edition/key, for customising the shortcode behaviour on overview pages and for some other features.
If you own a commercial JW Player license, you must set your Player Edition and License Key in the JW Player » Settings screen:
Setting these options will un-lock the edition's additional Player Template options, as well as hide the JW Player logo from the player video screen. Note a license key is not required for the Free edition, but inserting one will enable the video analytics in your JW Player account.
Unfortunately, the JW Player plugin does not use the official WordPress Shortcode API due to incompatibility with options that contain a ".". Therefore, there's unexpected behaviour on overview pages (home, categories, search, tags) in combination with certain WordPress themes. This can be overridden by these shortcode settings:
The last section of the settings contains three items:
- Player Version
- This informs you which version of JW Player is currently active with the WordPress plugin. New versions of JW Player will automatically get pushed along with new versions of the WordPress plugin. There's no need for any manual upgrades.
- Anonymous Tracking
- This informs us which JW Player plugin features you are using for your site (templates, external media, playlists, shortcodes, etc). It allows us to prioritize development and bug fixing. Un-check the box if you don't want to share this info.
- Purge Settings
- Checking this option will delete all JW Player plugin data (templates, playlists) the next time you de-activate the plugin. Use this if you intend to stop using the JW Player plugin altogether.