Warning: HTML preview using PygmentsRenderer failed (TypeError: function() takes at least 2 arguments (0 given))

source: trunk/fl5/doc/publishers/embedding.rst @ 1122

Revision 1122, 6.6 KB checked in by pablo, 3 years ago (diff)

Minor doc changes
Line 
1.. _embedding:
2
3Embedding the player
4====================
5
6Like every other Flash object, the JW Player has to be embedded into the HTML of a webpage using specific embed codes. Overall, there are two methods for embedding Flash:
7
8* Using a JavaScript (like `SWFObject <http://code.google.com/p/swfobject/>`_).
9* Using a HTML tag (like *<embed>*).
10
11We highly recommend the JavaScript method for Flash embedding. It can sniff if a browsers supports Flash, it ensures the player :ref:`javascriptapi` works and it avoids browser compatibility issues. Detailed instructions can be found below.
12
13
14Upload
15------
16
17First, a primer on uploading. This may sound obvious, but for the JW Player to work on your website, you must upload the *player.swf* file from the download (or SVN checkout) to your webserver. If you want to play Youtube videos, you must also upload the **yt.swf** file - this is the bridge between the player and Youtube. No other files are needed.
18
19Your :ref:`media files <mediaformats>` and :ref:`playlists <playlistformats>` can be hosted at any domain. Do note that :ref:`crossdomain` apply when loading these files from a different domain. In short, playing media files works, but loading playlists across domains will not work by default. Resolve this issue by hosting a :ref:`crossdomain.xml file <crossdomain>`.
20
21
22SWFObject
23---------
24
25The preferred way to embed the JW Player on a webpage is JavaScript. There's a wide array of good, open source libraries available for doing so. We recommend **SWFObject**, the most widely used one. It has `excellent documentation <http://code.google.com/p/swfobject/wiki/documentation>`_.
26
27Before embedding any players on the page, make sure to include the *swfobject.js* script in the *<head>* of your HTML. You can download the script and host it yourself, or leverage the copy `provided by Google <http://code.google.com/apis/ajaxlibs/documentation/>`_:
28
29.. code-block:: html
30
31   <script type="text/javascript"
32     src="http://ajax.googleapis.com/ajax/libs/swfobject/2.2/swfobject.js">
33   </script>
34
35With the library set up, you can start embedding players. Here's an example:
36
37.. code-block:: html
38
39   <p id="container1">Please install the Flash Plugin</p>
40
41   <script type="text/javascript">
42     var flashvars = { file:'/data/bbb.mp4',autostart:'true' };
43     var params = { allowfullscreen:'true', allowscriptaccess:'always' };
44     var attributes = { id:'player1', name:'player1' };
45
46     swfobject.embedSWF('player.swf','container1','480','270','9.0.115','false',
47       flashvars, params, attributes);
48   </script>
49
50It's a fairly sizeable chunk of code that contains the embed *container*, *flashvars*, *params*, *attributes* and *instantiation*. Let's walk through them one by one:
51
52* The *container* is the HTML element where the player will be placed into. It should be a block-level element, like a <p> or <div>. If a user has a sufficient version of Flash, the text inside the container is removed and replaced by the videoplayer. Otherwise, the contents of the container will remain visible.
53* The *flashvars* object lists your player :ref:`options`. One option that should always be there is *file*, which points to the file to play. You can insert as many options as you want.
54* The *params* object includes the `Flash plugin parameters <http://kb2.adobe.com/cps/127/tn_12701.html>`_. The two parameters in the example (our recommendation) enable both the *fullscreen* and *JavaScript* functionality of Flash.
55* The *attributes* object include the HTML attributes of the player. We recommend always (and only) setting an *id* and *name*, to the same value. This will be the *id* of the player instance if you use its :ref:`javascriptapi`.
56* The *instantiation* is where all things come together and the actual player embedding takes place. These are all parameters of the SWFObject call:
57
58   * The URL of the *player.swf*, relative to the page URL.
59   * The ID of the container you want to embed the player into.
60   * The width of the player, in pixels. Note the JW Player automatically stretches itself to fit.
61   * The height of the player, in pixels. Note the JW Player automatically stretches itself to fit.
62   * The required version of Flash. We highly recommend setting *9.0.115*. This is the first version that supports :ref:`MP4 <mediaformats>` and is currently installed at >95% of all computers. The only feature for which you might restricted to *10.0.0* is :ref:`RTMP dynamic streaming <rtmpstreaming>`.
63   * The location of a Flash auto-upgrade script. We recommend to **not** use it. People that do not have Flash 9.0.115 either do not want or are not able (no admin rights) to upgrade.
64   * Next, the *flashvars*, *params* and *attributes* are passed, in that order.
65
66
67It is no problem to embed multiple players on a page. However, make sure to give each player instance a different container **id** and a different attributess **id** and **name**.
68
69
70Embed tag
71---------
72
73In cases where a JavaScript embed method is not possible (e.g. if your CMS does not allow including JavaScripts), the player can be embedded using plain HTML. There are various combinations of tags for embedding a SWF player:
74
75* A single *<embed>* tag (for IE + other browsers).
76* An *<object>* tag with nested *<embed>* tag (the first one for IE, the second for other browsers).
77* An *<object>* tag with nested *<object>* tag (the first one for IE, the second for other browsers).
78
79We recommend using the single *<embed>* tag. This works in all current-day browsers (including IE6) and provides the shortest codes. Here is an example embed code that does exactly the same as the SWFObject example above:
80
81.. code-block:: html
82
83   <embed
84     flashvars="file=/data/bbb.mp4&autostart=true"
85     allowfullscreen="true"
86     allowscripaccess="always"
87     id="player1"
88     name="player1"
89     src="player.swf"
90     width="480"
91     height="270"
92   />
93
94As you can see, most of the data of the SWFObject embed is also in here:
95
96* The **container** is now the embed tag itself. The *fallback* text cannot be used anymore.
97* The **flashvars** are merged into a single string, and loaded as an attribute. You should always concatenate the flashvars using so-called querystring parameter encoding: *flashvar1=value1&flashvar2=value2&...*.
98* The **params** each are individual attributes of the embed tag.
99* The **attributes** also are individual attributes of the embed tag.
100* The **instantiation** options (source, width, height) are attributes of the embed tag.
101
102.. note::
103
104   As you can see, the Flash version reference is not in the embed tag: this is one of the drawbacks of this method: it's not possible to sniff for Flash and selectively hide it, e.g. if the flash version is not sufficient or if the device (iPad ...) doesn't support Flash.
Note: See TracBrowser for help on using the repository browser.