Getting Started - jwplayer/jw-showcase GitHub Wiki

This page will help you get started with the basic configuration of your JW Showcase site. For a visual walkthrough of these steps, see this JW Player support article.

The basic steps are simple:

• Create a JW Player account.
• Upload your video files to JW Platform or register external video URLs using either JW Dashboard or our Platform API.
• Create a player and content playlists in JW Dashboard.
• Get the JW Showcase release code.
• Extract the files from the release Zip.
• Edit your config.json file to customize your site.
• Copy the Showcase files to your web server.

For instructions on creating players and playlists, see the "Getting Started" Support topics at support.jwplayer.com.

Go to the releases page and download the latest precompiled release file (precompiled-static-app.zip).

Extract the precompiled-static-app.zip file with Archiver (OS X), WinRAR (Windows) or command unzip precompiled-static-app.zip -d jw-showcase (Linux). The directory which contains index.html is the webroot of the JW Showcase application.

If you have advanced customization requirements (for example, integrating your main web site's navigation menus), you should follow the instructions in Building-from-the-Source-Code.

By default, JW Showcase assumes the site is in your top-level web document root (/). If you want to use a subdirectory (for example, /video/), edit the index.html file and replace the slash in <base href="/"> with your subdirectory (for example, "/video/").

In the JW Showcase root directory, you will find the main configuration file, config.json. This file contains multiple parameters such as the name, description and video playlists of your site.

The JW Showcase application requires you to fill in the following parameters in the config.json file:

• player

  Place the key of your custom created player from the JW Player Dashboard here. Note that this value is the eight-character identifier of the player, not your JW Player license key. To get the player key, in the JW Dashboard go to Publish > Tools. In the Cloud Hosted Player Libraries section at the top of the page, select the player you want to use from the Player Title drop down. Then, in the Cloud Player Library URL field, copy the eight-character value that appears just before .js. This value is the Player key.

• theme

  Choose from our available themes (light, dark or blue).

• siteName

  The title of your website.

• description

  A short description of your website. JW Showcase will automatically update the <meta name='description'> tag in your site to this value, which can help to improve your site's search engine performance.

• content

  Define which and how playlists should be listed on your Showcase. For optimal performance and user experience, we recommend a maximum of 10 playlists.

For more about the parameters, see Configuration Parameters below.

These are the available configuration parameters for the JW Showcase application's config.json file. This file can be found in the webroot of the application.

theme

Choose between the available themes light, dark or blue.

player

Player key of your custom created player in the JW Player dashboard.

siteName

Title of your website. JW Showcase will automatically update the <title> tag of your site to this value when the site loads.

description

Short description of your website. JW Showcase will automatically update the <meta name='description'> tag in your site to this value, which can help to improve your site's search engine performance.

footerText (optional)

Text that will be placed in the footer of the site.

assets.banner (optional, v3.3.0 and later)

Location of a JPG, PNG or GIF image to be used as the logo in the header (e.g. /images/logo.png).

content

Use the `content' array to define which and how content playlists should be displayed in "shelves" in your Showcase. For optimal performance and user experience, we recommend a maximum of 10 playlists. See the available options below to configure each shelf separately.

{
  content: [{
    "playlistId": "lrYLc95e",
    "featured": true
  }, {
    "playlistId": "continue-watching",
    "enableText": false
  }, {
    "playlistId": "WXu7kuaW",
    "backgroundColor": "#ff0000",
    "aspectratio": "9:16",
    "cols": 6
  }]  
}

content[].aspectratio (optional, v3.4.0 and later)

Changes the aspect ratio of the poster images in a playlist shelf on the home page. If aspectratio is not specified, the default aspect of 16:9 horizontal is used. Possible values are:

• 1:1 (square)
• 2:1 (horizontal orientation)
• 2:3 (vertical orientation)
• 4:3 (horizontal orientation)
• 5:3 (horizontal orientation)
• 9:16 (vertical orientation)

content[].backgroundColor (optional, v3.3.0 and later)

Set a custom shelf background color.

This setting can be overridden by creating a custom parameter in a playlist's metadata in the JW Dashboard. The custom parameter must be named "showcase.backgroundColor."

content[].cols (optional, v3.4.0 and later)

Change the rule of how many cards there should be visible in the shelve. This can either be a fixed number or an Object to change the value based on screen size.

When using an Object notation, you should define all sizes like below (this Object is used by default in Showcase):

{"xs": 1, "sm": 2, "md": 3, "lg": 4, "xl": 5}

The number after the size key defines how many cards should be visible when the screen size matches that key.

content[].enablePreview (optional, v3.3.0 and later)

Controls whether or not animated preview images are shown in the poster images when a user hovers over the image. It is "true" by default for the Featured and Continue Watching shelves. Images are not animated on mobile browsers.

This setting can be overridden by creating a custom parameter in a playlist's metadata in the JW Dashboard. The parameter must be named "showcase.enablePreview" and set to either "true" or "false."

content[].enableText (optional, v3.3.0 and later)

Controls whether or not title and description text overlays appear on the poster images. It is "true" by default. If your poster images contain a lot of text, we recommend setting this to "false."

This setting can be overridden by creating a custom parameter in a playlist's metadata in the JW Dashboard. The parameter must be named "showcase.enableText" and set to either "true" or "false."

content[].enableTitle (optional, v3.3.0 and later)

Controls whether or not the shelf title is shown. It is "true" by default.

This setting can be overridden by creating a custom parameter in a playlist's metadata in the JW Dashboard. The parameter must be named "showcase.enableTitle" and set to either "true" or "false."

content[].featured (optional, v3.3.0 and later)

Controls if the playlist should be used as a large "Featured" shelf on your Showcase home page.

content[].playlistId (v3.3.0 and later)

The eight-character Playlists IDs from the JW Player dashboard. These IDs populate the video "shelves" in your site.

It is also possible to use 'continue-watching' or 'saved-videos' as playlistId. With this, you can change the position and look of these shelves. Example:

{
  "playlistId": "continue-watching",
  "enableText": false
}

options.backgroundColor (optional)

Override the theme's background color without needing to change CSS (e.g. #ff0000).

options.enableContinueWatching (optional, v3.0.0 and later)

Controls whether or not users see the "Continue Watching" shelf in the app and top-level menu. To display Continue Watching, set to "true." To hide it, set to "false."

options.enableCookieNotice (optional)

Controls whether or not users see a pop-up notice about cookie the first time they visit the site. It is "false" by default.

options.enableHeader (optional)

Controls whether or not the site header (banner image, hamburger menu, search box, etc.) is shown. This option is useful if you are embedding Showcase within another web page that has its own header. The default is "true."

options.enableTags (optional)

Controls whether or not content tags are displayed with the description of the video in the watch page. Users can click the tags to display a page of similarly tagged videos in their Showcase. Tags are created and assigned to videos in your JW Dashboard. The default is "false."

options.highlightColor (optional, v3.4.0 and later)

Controls the color used for certain UI elements such as progress spinner, buttons, etc. The default is light red.

Specify the color in hexadecimal format. For example, if you want bright yellow, set it to "highlightColor": "#ffff00".

options.rightRail (optional, v3.4.0 and later)

Controls whether or not the current video's playlist items are displayed to the right of the video player as opposed to in a content "shelf" beneath the player.

The right rail is enabled by default. To disable it, set "enabled": false. For example:

  "rightRail" : {
    "enabled": false
   }

If you want the right rail to be populated with related videos from JW Recommendations instead of the video's playlist, see useRecommendationPlaylist below.

options.useRecommendationPlaylist (optional, v3.4.0 and later)

If the right rail playlist UI is enabled in your view pages (see options.rightRail above), controls whether the playlist items are populated from the currently playing video's master playlist (i.e., the playlist ID from JW Platform), or from the JW Recommendations engine. Note that Recommendations requires a JW Player Enterprise license. For more information about Search playlists, see this JW Player Support article. Default is "false."

options.videoTitlePosition (optional, v3.5.0 and later)

Choose the position of the video title. This can either be "below" the video player (default) or "above" the video player. When choosing the "above" position the social sharing buttons will display to the right of the title for desktop screen size.

options.displayAds (optional, v3.5.0 and later)

Enable display ads on your site with DoubleClick for Publishers (DFP). For more information about, see Adding-Display-Ads-To-Your-Showcase.

options.enableAddToHome (optional, v3.6.0 and later)

Enable showing the add-to-homescreen dialog. Note, the dialog will normally only be shown once.

options.enableInVideoSearch (optional, v3.6.0 and later)

Enable displaying alternative search results which display all search matches in a timeline.

recommendationsPlaylist (optional, v3.0.0 and later)

The eight-character Playlist ID of the Recommendations playlist that you want to use to populate the "Related Videos" shelf in your site. Note that Recommendations requires a JW Player Enterprise license. For more information about Recommendations playlists, see this JW Player Support article.

searchPlaylist (optional, v3.0.0 and later)

The eight-character Playlist ID of the Search playlist that you want to use to enable search on your site. Note that Search requires a JW Player Enterprise license. For more information about Search playlists, see this JW Player Support article.

Make sure you copy all the files and directories, including the .htaccess file, from the dist/ folder. Mac OS Finder and Windows File Explorer usually treat .htaccess as a system file and thus don't show it by default.