Event listeners
This commit is contained in:
Sam Potts
144
readme.md
144
readme.md
@ -305,12 +305,6 @@ Options must be passed as an object to the `setup()` method as above.
|
||||
<td>—</td>
|
||||
<td>Two properties; <code>enabled</code> which toggles if local storage should be enabled (if the browser supports it). The default value is `true`. This enables storing user settings, currently it only stores volume but more will be added later. The second property <code>key</code> is the key used for the local storage. The default is <code>plyr_volume</code> until more settings are stored.</td>
|
||||
</tr>
|
||||
<tr>
|
||||
<td><code>onSetup</code></td>
|
||||
<td>Function</td>
|
||||
<td>—</td>
|
||||
<td>This callback function is called on every new plyr instance created. The context (<code>this</code>) is the plyr instance itself.</td>
|
||||
</tr>
|
||||
</tbody>
|
||||
</table>
|
||||
|
||||
@ -370,7 +364,7 @@ Or you can use the returned object from your call to the setup method:
|
||||
var player = plyr.setup('.js-plyr')[0];
|
||||
```
|
||||
|
||||
This will return an array of plyr instances setup, so you need to specify the index of the instance you want. This is less useful if you are setting up mutliple instances. You can also use the `onSetup` callback documented below which will return each instance one by one, as they are setup.
|
||||
This will return an array of plyr instances setup, so you need to specify the index of the instance you want. This is less useful if you are setting up mutliple instances. You can listen for the `setup` [event](#events) documented below which will return each instance one by one, as they are setup (in the `plyr` key of the event object).
|
||||
|
||||
Once you have your instance, you can use the API methods below on it. For example to pause it:
|
||||
|
||||
@ -605,19 +599,139 @@ Some more details on the object parameters
|
||||
</table>
|
||||
|
||||
|
||||
## Events/Callbacks
|
||||
## Events
|
||||
|
||||
The `plyr` object on the player element also contains a `media` property which is a reference to the `<audio>` or `<video>` element within the player which you can use to listen for events. Here's an example:
|
||||
You can listen for events on the element you setup Plyr on. Some events only apply to HTML5 audio and video.
|
||||
|
||||
<table class="table" width="100%">
|
||||
<thead>
|
||||
<tr>
|
||||
<th width="20%">Event name</th>
|
||||
<th width="20%">HTML5 only</th>
|
||||
<th width="60%">Description</th>
|
||||
</tr>
|
||||
</thead>
|
||||
<tbody>
|
||||
<tr>
|
||||
<td><code><a href="/en-US/docs/Web/Events/canplay" title="/en-US/docs/Web/Events/canplay">canplay</a></code></td>
|
||||
<td>✔</td>
|
||||
<td>Sent when enough data is available that the media can be played, at least for a couple of frames. This corresponds to the <code>HAVE_ENOUGH_DATA</code> <code>readyState</code>.</td>
|
||||
</tr>
|
||||
<tr>
|
||||
<td><code><a href="/en-US/docs/Web/Events/canplaythrough" title="/en-US/docs/Web/Events/canplaythrough">canplaythrough</a></code></td>
|
||||
<td></td>
|
||||
<td>Sent when the ready state changes to <code>CAN_PLAY_THROUGH</code>, indicating that the entire media can be played without interruption, assuming the download rate remains at least at the current level. <strong>Note</strong>: Manually setting the <code>currentTime</code> will eventually fire a <code>canplaythrough</code> event in firefox. Other browsers might not fire this event.</td>
|
||||
</tr>
|
||||
<tr>
|
||||
<td><code><a href="/en-US/docs/Web/Events/emptied" title="/en-US/docs/Web/Events/emptied">emptied</a></code></td>
|
||||
<td>✔</td>
|
||||
<td>The media has become empty; for example, this event is sent if the media has already been loaded (or partially loaded), and the <a href="/En/XPCOM_Interface_Reference/NsIDOMHTMLMediaElement" class="internal" title="en/nsIDOMHTMLMediaElement"><code>load()</code></a> method is called to reload it.</td>
|
||||
</tr>
|
||||
<tr>
|
||||
<td><code>ended</code></td>
|
||||
<td></td>
|
||||
<td>Sent when playback completes.</td>
|
||||
</tr>
|
||||
<tr>
|
||||
<td><code>error</code></td>
|
||||
<td>✔</td>
|
||||
<td>Sent when an error occurs. The element's <code>error</code> attribute contains more information. See <a href="/en-US/docs/Web/Guide/HTML/Using_HTML5_audio_and_video#Error_handling">Error handling</a> for details.</td>
|
||||
</tr>
|
||||
<tr>
|
||||
<td><code><a href="/en-US/docs/Web/Events/loadeddata" title="/en-US/docs/Web/Events/loadeddata">loadeddata</a></code></td>
|
||||
<td>✔</td>
|
||||
<td>The first frame of the media has finished loading.</td>
|
||||
</tr>
|
||||
<tr>
|
||||
<td><code><a href="/en-US/docs/Web/Events/loadedmetadata" title="/en-US/docs/Web/Events/loadedmetadata">loadedmetadata</a></code></td>
|
||||
<td>✔</td>
|
||||
<td>The media's metadata has finished loading; all attributes now contain as much useful information as they're going to.</td>
|
||||
</tr>
|
||||
<tr>
|
||||
<td><code><a href="/en-US/docs/Web/Events/loadstart" title="/en-US/docs/Web/Events/loadstart">loadstart</a></code></td>
|
||||
<td>✔</td>
|
||||
<td>Sent when loading of the media begins.</td>
|
||||
</tr>
|
||||
<tr>
|
||||
<td><code><a href="/en-US/docs/Web/Events/pause" title="/en-US/docs/Web/Events/pause">pause</a></code></td>
|
||||
<td></td>
|
||||
<td>Sent when playback is paused.</td>
|
||||
</tr>
|
||||
<tr>
|
||||
<td><code><a href="/en-US/docs/Web/Events/play" title="/en-US/docs/Web/Events/play">play</a></code></td>
|
||||
<td></td>
|
||||
<td>Sent when playback of the media starts after having been paused; that is, when playback is resumed after a prior <code>pause</code> event.</td>
|
||||
</tr>
|
||||
<tr>
|
||||
<td><code><a href="/en-US/docs/Web/Events/playing" title="/en-US/docs/Web/Events/playing">playing</a></code></td>
|
||||
<td></td>
|
||||
<td>Sent when the media begins to play (either for the first time, after having been paused, or after ending and then restarting).</td>
|
||||
</tr>
|
||||
<tr>
|
||||
<td><code><a href="/en-US/docs/Web/Events/progress" title="/en-US/docs/Web/Events/progress">progress</a></code></td>
|
||||
<td></td>
|
||||
<td>Sent periodically to inform interested parties of progress downloading the media. Information about the current amount of the media that has been downloaded is available in the media element's <code>buffered</code> attribute.</td>
|
||||
</tr>
|
||||
<tr>
|
||||
<td><code><a href="/en-US/docs/Web/Events/seeked" title="/en-US/docs/Web/Events/seeked">seeked</a></code></td>
|
||||
<td>✔</td>
|
||||
<td>Sent when a seek operation completes.</td>
|
||||
</tr>
|
||||
<tr>
|
||||
<td><code><a href="/en-US/docs/Web/Events/seeking" title="/en-US/docs/Web/Events/seeking">seeking</a></code></td>
|
||||
<td>✔</td>
|
||||
<td>Sent when a seek operation begins.</td>
|
||||
</tr>
|
||||
<tr>
|
||||
<td><code><a href="/en-US/docs/Web/Events/stalled" title="/en-US/docs/Web/Events/stalled">stalled</a></code></td>
|
||||
<td>✔</td>
|
||||
<td>Sent when the user agent is trying to fetch media data, but data is unexpectedly not forthcoming.</td>
|
||||
</tr>
|
||||
<tr>
|
||||
<td><code><a href="/en-US/docs/Web/Events/timeupdate" title="/en-US/docs/Web/Events/timeupdate">timeupdate</a></code></td>
|
||||
<td></td>
|
||||
<td>The time indicated by the element's <code>currentTime</code> attribute has changed.</td>
|
||||
</tr>
|
||||
<tr>
|
||||
<td><code><a href="/en-US/docs/Web/Events/volumechange" title="/en-US/docs/Web/Events/volumechange">volumechange</a></code></td>
|
||||
<td></td>
|
||||
<td>Sent when the audio volume changes (both when the volume is set and when the <code>muted</code> attribute is changed).</td>
|
||||
</tr>
|
||||
<tr>
|
||||
<td><code><a href="/en-US/docs/Web/Events/waiting" title="/en-US/docs/Web/Events/waiting">waiting</a></code></td>
|
||||
<td>✔</td>
|
||||
<td>Sent when the requested operation (such as playback) is delayed pending the completion of another operation (such as a seek).</td>
|
||||
</tr>
|
||||
<tr>
|
||||
<td><code>enterfullscreen</code></td>
|
||||
<td></td>
|
||||
<td>User enters fullscreen (either the proper fullscreen or full-window fallback for older browsers)</td>
|
||||
</tr>
|
||||
<tr>
|
||||
<td><code>exitfullscreen</code></td>
|
||||
<td></td>
|
||||
<td>User exits fullscreen</td>
|
||||
</tr>
|
||||
<tr>
|
||||
<td><code>captionsenabled</code></td>
|
||||
<td></td>
|
||||
<td>Captions toggled on</td>
|
||||
</tr>
|
||||
<tr>
|
||||
<td><code>captionsdisabled</code></td>
|
||||
<td></td>
|
||||
<td>Captions toggled off</td>
|
||||
</tr>
|
||||
</tbody>
|
||||
</table>
|
||||
|
||||
Here's an example of binding an event listener:
|
||||
|
||||
```javascript
|
||||
var media = document.querySelector(".js-plyr").plyr.media;
|
||||
|
||||
media.addEventListener("playing", function() {
|
||||
console.log("playing");
|
||||
document.querySelector(".js-plyr").addEventListener("playing", function() {
|
||||
/* Magic happens */
|
||||
});
|
||||
```
|
||||
A complete list of events can be found here:
|
||||
[Media Events - W3.org](http://www.w3.org/2010/05/video/mediaevents.html)
|
||||
|
||||
## Embeds
|
||||
|
||||
|
||||
Reference in New Issue
Block a user