diff options
Diffstat (limited to 'controls.md')
| -rw-r--r-- | controls.md | 208 |
1 files changed, 123 insertions, 85 deletions
diff --git a/controls.md b/controls.md index 15f52e47..ce623907 100644 --- a/controls.md +++ b/controls.md @@ -1,27 +1,72 @@ # Controls -This is the markup that is rendered for the Plyr controls. You can use the default controls or provide a customized version of markup based on your needs. +This is the markup that is rendered for the Plyr controls. You can use the default controls or provide a customized version of markup based on your needs. You can pass the following to the `controls` option: -## Internationalization using default controls +* `Array` of options (this builds the default controls based on your choices) +* `String` containing the desired HTML +* `Function` that will be executed and should return one of the above + +## Using default controls + +If you want to use the standard controls as they are, you don't need to pass any options. If you want to turn on off controls, here's the full list: + +```javascript +controls: [ + 'play-large', // The large play button in the center + 'restart', // Restart playback + 'rewind', // Rewind by the seek time (default 10 seconds) + 'play', // Play/pause playback + 'fast-forward', // Fast forward by the seek time (default 10 seconds) + 'progress', // The progress bar and scrubber for playback and buffering + 'current-time', // The current time of playback + 'duration', // The full duration of the media + 'mute', // Toggle mute + 'volume', // Volume control + 'captions', // Toggle captions + 'settings', // Settings menu + 'pip', // Picture-in-picture (currently Safari only) + 'airplay', // Airplay (currently Safari only) + 'fullscreen', // Toggle fullscreen +]; +``` + +### Internationalization using default controls You can provide an `i18n` object as one of your options when initialising the plugin which we be used when rendering the controls. -### Example +#### Example ```javascript i18n: { - restart: "Restart", - rewind: "Rewind {seektime} secs", - play: "Play", - pause: "Pause", - forward: "Forward {seektime} secs", - buffered: "buffered", - currentTime: "Current time", - duration: "Duration", - volume: "Volume", - toggleMute: "Toggle Mute", - toggleCaptions: "Toggle Captions", - toggleFullscreen: "Toggle Fullscreen" + restart: 'Restart', + rewind: 'Rewind {seektime} secs', + play: 'Play', + pause: 'Pause', + fastForward: 'Forward {seektime} secs', + seek: 'Seek', + played: 'Played', + buffered: 'Buffered', + currentTime: 'Current time', + duration: 'Duration', + volume: 'Volume', + mute: 'Mute', + unmute: 'Unmute', + enableCaptions: 'Enable captions', + disableCaptions: 'Disable captions', + enterFullscreen: 'Enter fullscreen', + exitFullscreen: 'Exit fullscreen', + frameTitle: 'Player for {title}', + captions: 'Captions', + settings: 'Settings', + speed: 'Speed', + quality: 'Quality', + loop: 'Loop', + start: 'Start', + end: 'End', + all: 'All', + reset: 'Reset', + disabled: 'Disabled', + advertisement: 'Ad', } ``` @@ -29,85 +74,78 @@ Note: `{seektime}` will be replaced with your configured seek time or the defaul ## Using custom HTML -You can specify the HTML for the controls using the `html` option. +You can specify the HTML as a `String` or your `Function` return for the controls using the `controls` option. + +The classes and data attributes used in your template should match the `selectors` option if you change any. -The classes and data attributes used in your template should match the `selectors` option. +You need to add several placeholders to your HTML template that are replaced when rendering: -You need to add several placeholders to your html template that are replaced when rendering: +* `{id}` - the dynamically generated ID for the player (for form controls) +* `{seektime}` - the seek time specified in options for fast forward and rewind +* `{title}` - the title of your media, if specified -- `{id}` - the dynamically generated ID for the player (for form controls) -- `{seektime}` - the seek time specified in options for fast forward and rewind -- `{title}` - the title of your media, if specified +### Limitations -You can include only the controls you need when specifying custom html. +* Currently the settings menus are not supported with custom controls HTML +* AirPlay and PiP buttons can be added but you will have to manage feature detection ### Example -This is an example `html` option with all controls. +Here's an example of custom controls markup (this is just all default controls shown). ```javascript -var controls = ["<div class='plyr__controls'>", - "<button type='button' data-plyr='restart'>", - "<svg><use xlink:href='#plyr-restart'></use></svg>", - "<span class='plyr__sr-only'>Restart</span>", - "</button>", - "<button type='button' data-plyr='rewind'>", - "<svg><use xlink:href='#plyr-rewind'></use></svg>", - "<span class='plyr__sr-only'>Rewind {seektime} secs</span>", - "</button>", - "<button type='button' data-plyr='play'>", - "<svg><use xlink:href='#plyr-play'></use></svg>", - "<span class='plyr__sr-only'>Play</span>", - "</button>", - "<button type='button' data-plyr='pause'>", - "<svg><use xlink:href='#plyr-pause'></use></svg>", - "<span class='plyr__sr-only'>Pause</span>", - "</button>", - "<button type='button' data-plyr='fast-forward'>", - "<svg><use xlink:href='#plyr-fast-forward'></use></svg>", - "<span class='plyr__sr-only'>Forward {seektime} secs</span>", - "</button>", - "<span class='plyr__progress'>", - "<label for='seek{id}' class='plyr__sr-only'>Seek</label>", - "<input id='seek{id}' class='plyr__progress--seek' type='range' min='0' max='100' step='0.1' value='0' data-plyr='seek'>", - "<progress class='plyr__progress--played' max='100' value='0' role='presentation'></progress>", - "<progress class='plyr__progress--buffer' max='100' value='0'>", - "<span>0</span>% buffered", - "</progress>", - "<span class='plyr__tooltip'>00:00</span>", - "</span>", - "<span class='plyr__time'>", - "<span class='plyr__sr-only'>Current time</span>", - "<span class='plyr__time--current'>00:00</span>", - "</span>", - "<span class='plyr__time'>", - "<span class='plyr__sr-only'>Duration</span>", - "<span class='plyr__time--duration'>00:00</span>", - "</span>", - "<button type='button' data-plyr='mute'>", - "<svg class='icon--muted'><use xlink:href='#plyr-muted'></use></svg>", - "<svg><use xlink:href='#plyr-volume'></use></svg>", - "<span class='plyr__sr-only'>Toggle Mute</span>", - "</button>", - "<span class='plyr__volume'>", - "<label for='volume{id}' class='plyr__sr-only'>Volume</label>", - "<input id='volume{id}' class='plyr__volume--input' type='range' min='0' max='10' value='5' data-plyr='volume'>", - "<progress class='plyr__volume--display' max='10' value='0' role='presentation'></progress>", - "</span>", - "<button type='button' data-plyr='captions'>", - "<svg class='icon--captions-on'><use xlink:href='#plyr-captions-on'></use></svg>", - "<svg><use xlink:href='#plyr-captions-off'></use></svg>", - "<span class='plyr__sr-only'>Toggle Captions</span>", - "</button>", - "<button type='button' data-plyr='fullscreen'>", - "<svg class='icon--exit-fullscreen'><use xlink:href='#plyr-exit-fullscreen'></use></svg>", - "<svg><use xlink:href='#plyr-enter-fullscreen'></use></svg>", - "<span class='plyr__sr-only'>Toggle Fullscreen</span>", - "</button>", -"</div>"].join(""); +const controls = ` +<div class="plyr__controls"> + <button type="button" class="plyr__control" data-plyr="restart"> + <svg role="presentation"><use xlink:href="#plyr-restart"></use></svg> + <span class="plyr__tooltip" role="tooltip">Restart</span> + </button> + <button type="button" class="plyr__control" data-plyr="rewind"> + <svg role="presentation"><use xlink:href="#plyr-rewind"></use></svg> + <span class="plyr__tooltip" role="tooltip">Rewind {seektime} secs</span> + </button> + <button type="button" class="plyr__control" aria-pressed="false" aria-label="Play, {title}" data-plyr="play"> + <svg class="icon--pressed" role="presentation"><use xlink:href="#plyr-pause"></use></svg> + <svg class="icon--not-pressed" role="presentation"><use xlink:href="#plyr-play"></use></svg> + <span class="label--pressed plyr__tooltip" role="tooltip">Pause</span> + <span class="label--not-pressed plyr__tooltip" role="tooltip">Play</span> + </button> + <button type="button" class="plyr__control" data-plyr="fast-forward"> + <svg role="presentation"><use xlink:href="#plyr-fast-forward"></use></svg> + <span class="plyr__tooltip" role="tooltip">Forward {seektime} secs</span> + </button> + <div class="plyr__progress"> + <label for="plyr-seek-{id}" class="plyr__sr-only">Seek</label> + <input data-plyr="seek" type="range" min="0" max="100" step="0.01" value="0" id="plyr-seek-{id}"> + <progress class="plyr__progress--buffer" min="0" max="100" value="0">% buffered</progress> + <span role="tooltip" class="plyr__tooltip">00:00</span> + </div> + <div class="plyr__time">00:00</div> + <button type="button" class="plyr__control" aria-pressed="false" aria-label="Mute" data-plyr="mute"> + <svg class="icon--pressed" role="presentation"><use xlink:href="#plyr-muted"></use></svg> + <svg class="icon--not-pressed" role="presentation"><use xlink:href="#plyr-volume"></use></svg> + <span class="label--pressed plyr__tooltip" role="tooltip">Unmute</span> + <span class="label--not-pressed plyr__tooltip" role="tooltip">Mute</span> + </button> + <div class="plyr__volume"> + <label for="plyr-volume-{id}" class="plyr__sr-only">Volume</label> + <input data-plyr="volume" type="range" min="0" max="1" step="0.05" value="1" autocomplete="off" id="plyr-volume-{id}"> + </div> + <button type="button" class="plyr__control" aria-pressed="true" aria-label="Enable captions" data-plyr="captions"> + <svg class="icon--pressed" role="presentation"><use xlink:href="#plyr-captions-on"></use></svg> + <svg class="icon--not-pressed" role="presentation"><use xlink:href="#plyr-captions-off"></use></svg> + <span class="label--pressed plyr__tooltip" role="tooltip">Disable captions</span> + <span class="label--not-pressed plyr__tooltip" role="tooltip">Enable captions</span> + </button> + <button type="button" class="plyr__control" aria-pressed="false" aria-label="Enter fullscreen" data-plyr="fullscreen"> + <svg class="icon--pressed" role="presentation"><use xlink:href="#plyr-exit-fullscreen"></use></svg> + <svg class="icon--not-pressed" role="presentation"><use xlink:href="#plyr-enter-fullscreen"></use></svg> + <span class="label--pressed plyr__tooltip" role="tooltip">Exit fullscreen</span> + <span class="label--not-pressed plyr__tooltip" role="tooltip">Enter fullscreen</span> + </button> +</div> +`; // Setup the player -plyr.setup('.js-player', { - html: controls -}); +const player = new Plyr('#player', { controls }); ``` |