| 1 | <html> |
|---|
| 2 | <head> |
|---|
| 3 | <title>Related Plugin Reference</title> |
|---|
| 4 | <style> |
|---|
| 5 | body { padding: 50px 100px; width: 660px; font: 13px/20px Arial; background: #FFF; } |
|---|
| 6 | a , h1, h2{ color: #369; } |
|---|
| 7 | h1 { font-size: 32px; } |
|---|
| 8 | h2 { margin-top: 50px; } |
|---|
| 9 | h3 { margin-top: 25px; } |
|---|
| 10 | img, #player { -webkit-box-shadow: 0 0 5px #999; margin: 0 10px; } |
|---|
| 11 | pre { font-size: 12px; background: #E5F3C8; padding:5px 10px; border: 1px solid #D3EAA4; } |
|---|
| 12 | dd { color: #333; font-style: italic; } |
|---|
| 13 | </style> |
|---|
| 14 | </head><body> |
|---|
| 15 | |
|---|
| 16 | <h1>Related Plugin Reference</h1> |
|---|
| 17 | |
|---|
| 18 | |
|---|
| 19 | |
|---|
| 20 | <h2>Purpose</h2> |
|---|
| 21 | |
|---|
| 22 | <p>The purpose of this guide is to give you a feature overview of the <a href="http://www.longtailvideo.com/addons/plugins/">Related plugin for JW Player</a>.</p> |
|---|
| 23 | |
|---|
| 24 | |
|---|
| 25 | |
|---|
| 26 | <h2>Introduction</h2> |
|---|
| 27 | |
|---|
| 28 | <p>The Related plugin for the JW Player presents a screen with related videos to your viewers. This screen is shown when a video is completed or when a viewer presses the <em>related</em> button. Upon clicking a related video, the viewer is redirected to the page with that video, improving user engagement and advertising opportunities.</p> |
|---|
| 29 | |
|---|
| 30 | <p><img alt="Related Example Player" src="assets/related_example.png" style="margin-left: 10px" /></p> |
|---|
| 31 | |
|---|
| 32 | <p>The list of related videos is loaded using an mRSS feed. The plugin automatically renders up t0 2 rows of up to 5 related videos, depending upon how many fit the screen. Buttons for re-playing the video and for closing the overlay are shown in the top corners.</p> |
|---|
| 33 | |
|---|
| 34 | <p>The plugin works in both Flash and HTML5, including touch devices like the iPad/iPhone and Android. When using a playlist, every entry can have its own related videos.</p> |
|---|
| 35 | |
|---|
| 36 | |
|---|
| 37 | |
|---|
| 38 | <h2>Configuration Options</h2> |
|---|
| 39 | |
|---|
| 40 | <p>The Related plugin supports the following configuration options:</p> |
|---|
| 41 | |
|---|
| 42 | <dl> |
|---|
| 43 | <dt><strong>related.file</strong> ( <em>undefined</em> )</dt> |
|---|
| 44 | <dd>Location of the mRSS file with related videos, e.g. <strong>http://example.com/related.xml</strong>.</dd> |
|---|
| 45 | <dt><strong>related.oncomplete</strong> ( <em>true</em> )</dt> |
|---|
| 46 | <dd>Whether to display the related videos screen when the video is completed. When set <strong>false</strong>, the screen does not automatically pop up.</dd> |
|---|
| 47 | <dt><strong>related.usedock</strong> ( <em>true</em> )</dt> |
|---|
| 48 | <dd>Whether to add a button to the player to pop up the related videos screen manually. When set <strong>false</strong>, this button is omitted.</dd> |
|---|
| 49 | <dt><strong>related.heading</strong> ( <em>Watch related videos</em> )</dt> |
|---|
| 50 | <dd>Single line heading displayed above the grid with related videos. Generally contains a short call-to-action.</dd> |
|---|
| 51 | </dl> |
|---|
| 52 | |
|---|
| 53 | <h3>Example</h3> |
|---|
| 54 | |
|---|
| 55 | <p>Here is a basic example of the plugin, setting just a <em>related.file</em>:</p> |
|---|
| 56 | |
|---|
| 57 | <pre> |
|---|
| 58 | <div id='player'>Get Flash to see the video</div> |
|---|
| 59 | <script type="text/javascript> |
|---|
| 60 | jwplayer('player').setup({ |
|---|
| 61 | file: '/assets/bbb.mp4', |
|---|
| 62 | flashplayer: '/assets/player.swf', |
|---|
| 63 | plugins: { |
|---|
| 64 | 'related-1': { |
|---|
| 65 | file: '/assets/bbb-related.xml' |
|---|
| 66 | } |
|---|
| 67 | } |
|---|
| 68 | }); |
|---|
| 69 | </script> |
|---|
| 70 | </pre> |
|---|
| 71 | |
|---|
| 72 | <p>This example uses the - preferred - <a href="http://www.longtailvideo.com/support/jw-player/jw-player-for-flash-v5/15995/jw-embedder-reference-guide">JW Embedder method</a>. Please see our <a href="http://www.longtailvideo.com/support/jw-player/jw-player-for-flash-v5/12538/supported-player-embed-methods">Supported Embed Methods</a> guide for other options like SWFObject.</p> |
|---|
| 73 | |
|---|
| 74 | |
|---|
| 75 | <h2>The mRSS File</h2> |
|---|
| 76 | |
|---|
| 77 | <p>The mRSS feed is loaded into the <strong>file</strong> option of the plugin is can be any standard feed, just like for the <a href="http://www.longtailvideo.com/support/jw-player/jw-player-for-flash-v5/19824/playlist-support-in-the-jw-player">JW Player playlist</a>. The <em>title</em>, <em>link</em> and <em>media:thumbnail</em> options are required and used by the plugin. All other data in the mRSS feed is ignored. Here's an example feed with three related videos:</p> |
|---|
| 78 | |
|---|
| 79 | <pre> |
|---|
| 80 | <rss version="2.0" xmlns:media="http://search.yahoo.com/mrss/"> |
|---|
| 81 | <channel> |
|---|
| 82 | <item> |
|---|
| 83 | <title>Big Buck Bunny</title> |
|---|
| 84 | <link>http://example.com/watch/28839</link> |
|---|
| 85 | <media:thumbnail>http://example.com/thumbs/28839.jpg</media:thumbnail> |
|---|
| 86 | </item> |
|---|
| 87 | |
|---|
| 88 | <item> |
|---|
| 89 | <title>Sintel</title> |
|---|
| 90 | <link>http://example.com/watch/21987</link> |
|---|
| 91 | <media:thumbnail>http://example.com/thumbs/21987.jpg</media:thumbnail> |
|---|
| 92 | </item> |
|---|
| 93 | |
|---|
| 94 | <item> |
|---|
| 95 | <title>Elephant's Dream</title> |
|---|
| 96 | <link>http://example.com/watch/8791</link> |
|---|
| 97 | <media:thumbnail>http://example.com/thumbs/8791.jpg</media:thumbnail> |
|---|
| 98 | </item> |
|---|
| 99 | </channel> |
|---|
| 100 | </rss> |
|---|
| 101 | </pre> |
|---|
| 102 | |
|---|
| 103 | <p>Entries in the mRSS feed that do not contain a title, link and thumbnail are ignored. If the mRSS feed has 0 valid entries, or if the mRSS feed fails loading or parsing:</p> |
|---|
| 104 | |
|---|
| 105 | <ul> |
|---|
| 106 | <li>The button in the <em>dock</em> is greyed out.</li> |
|---|
| 107 | <li>The <em>related videos</em> screen is not displayed.</li> |
|---|
| 108 | </ul> |
|---|
| 109 | |
|---|
| 110 | |
|---|
| 111 | |
|---|
| 112 | |
|---|
| 113 | <h2>Playlist Support</h2> |
|---|
| 114 | |
|---|
| 115 | <p>Related videos can be assigned to one or more videos in a playlist. The functionality is available for both inline and mRSS playlists. Instead of setting the related file URL in the plugin configuration, they are set in the playlist.</p> |
|---|
| 116 | |
|---|
| 117 | <p>Since the mRSS playlist format defines no elements for linking to related files, it should be set using the <a href="http://www.longtailvideo.com/support/jw-player/jw-player-for-flash-v5/12537/xml-playlist-support">JWPlayer XML namespace</a>. In practice, the namespace is enabled by:</p> |
|---|
| 118 | |
|---|
| 119 | <ul> |
|---|
| 120 | <li>Setting an <b>xmlns:jwplayer</b> attribute in the main RSS tag.</li> |
|---|
| 121 | <li>Prefixing the XML elements with <strong>jwplayer:</strong> (<i><jwplayer:related.file></i>).</li> |
|---|
| 122 | </ul> |
|---|
| 123 | |
|---|
| 124 | <h3> Example</h3> |
|---|
| 125 | |
|---|
| 126 | <p> The config solely needs a reference to the plugin:</p> |
|---|
| 127 | |
|---|
| 128 | <pre> |
|---|
| 129 | <div id='player'>Get Flash to see the video</div> |
|---|
| 130 | <script type="text/javascript> |
|---|
| 131 | jwplayer('player').setup({ |
|---|
| 132 | flashplayer: '/assets/player.swf', |
|---|
| 133 | playlistfile: '/assets/playlist.xml', |
|---|
| 134 | plugins: { |
|---|
| 135 | 'related-1': {} |
|---|
| 136 | } |
|---|
| 137 | }); |
|---|
| 138 | </script> |
|---|
| 139 | </pre> |
|---|
| 140 | |
|---|
| 141 | <p>In the <strong>playlist.xml</strong>, the <em>jwplayer:related.file</em> element defines the related videos feed for each entry:</p> |
|---|
| 142 | |
|---|
| 143 | <pre> |
|---|
| 144 | <rss version="2.0" xmlns:jwplayer="http://developer.longtailvideo.com/"> |
|---|
| 145 | <channel> |
|---|
| 146 | <item> |
|---|
| 147 | <title>My first video</title> |
|---|
| 148 | <description>This one starts the playlist.</description> |
|---|
| 149 | <jwplayer:file>video.mp4</jwplayer:file> |
|---|
| 150 | <jwplayer:related.file>video-related.xml</jwplayer:related.file> |
|---|
| 151 | </item> |
|---|
| 152 | |
|---|
| 153 | <item> |
|---|
| 154 | <title>My second video</title> |
|---|
| 155 | <description>This one concludes it all.</description> |
|---|
| 156 | <jwplayer:file>video-2.mp4</jwplayer:file> |
|---|
| 157 | <jwplayer:related.file>video-2-related.xml</jwplayer:related.file> |
|---|
| 158 | </item> |
|---|
| 159 | </channel> |
|---|
| 160 | </rss> |
|---|
| 161 | </pre> |
|---|
| 162 | |
|---|
| 163 | <p>Note the <i>xmlns:jwplayer</i> at the top! It is needed to validate the <i>jwplayer:related.file</i> elements.</p> |
|---|
| 164 | |
|---|
| 165 | |
|---|
| 166 | |
|---|
| 167 | <h2>Device Support</h2> |
|---|
| 168 | |
|---|
| 169 | <p>On touch devices (iPhone, iPad, Android), the related plugin fully functions, with one exception: the Related dock button is not available when the video is playing. This because no custom controls can be shown when a video plays in fullscreen.</p> |
|---|
| 170 | |
|---|
| 171 | <p>Before and after playback, the player is displayed inline in the page and the related videos screen is available:</p> |
|---|
| 172 | |
|---|
| 173 | <p><img alt="Related on iPhone" src="assets/related_iphone.png" style="margin-left: 10px" /></p> |
|---|
| 174 | |
|---|
| 175 | |
|---|
| 176 | |
|---|
| 177 | <h2>Changelog</h2> |
|---|
| 178 | |
|---|
| 179 | <h3>Version 1.0</h3> |
|---|
| 180 | <ul> |
|---|
| 181 | <li>Load related videos using an mRSS feed.</li> |
|---|
| 182 | <li>Enter related screen through dock button or upon complete.</li> |
|---|
| 183 | <li>Support for Flash and HTML5 modes (including touch devices).</li> |
|---|
| 184 | <li>Support for related videos per playlist entry.</li> |
|---|
| 185 | </ul> |
|---|
| 186 | |
|---|
| 187 | |
|---|
| 188 | |
|---|
| 189 | </body> |
|---|
| 190 | </html> |
|---|
