jMediaelement control-element documentation
jMediaelement uses a flexible technique, to create custom stylable, WAI-Aria enhanced control elements without dictating a specific markup. To achieve this, the script has to detect, which control-behavior it has to add to your markup and which of possible multiple media elements is controlled by this markup.
This is achieved by behavior-classes and a common wrapper element/a data-controls attribute.
The method to add control-behavior to your markup, is called jmeControl.
Example: The behavior-class for a play-/pause button is called play-pause. In our example the video-element and our play-pause button are wrapped by a div-container with the class .media-player
<div class="media-player"> <video src="my-video.mp4"></video> <button class="play-pause">play / pause</button> </div>
Then we have to call jmeControl on this wrapper-element:
$('div.media-player').jmeControl();
If you want to add other controls, for example a mute-unmute button, we only have to add another element with the class mute-unmute:
<div class="media-player"> <video src="my-video.mp4"></video> <button class="play-pause">play / pause</button> <button class="mute-unmute">mute / unmute</button> </div>
This let's you write your markup, how you want, but helps you to add the right control-behavior for your jMediaelement
You can compare this technique to a possible upcomming HTML5.1 / HTML6 feature for creating custom stylable media control elements. An example:
<player> <video src="my-video.webm" poster="my-poster.jpg"></video> <button type="play-pause">play / pause</button> <label for="time-range">play position</label> <input type="time-range" id="time-range" /> <output type="current-position" /> <!-- more "HTML6" media control elements --> </player>
The example above isn't valid HTML5, so jMediaelement uses Classes and the data-* attribute to add valid and custom stylable control elements:
<div class="player"> <video src="my-video.webm" poster="my-poster.jpg"></video> <button class="play-pause">play / pause</button> <div class="timeline-slider"> <span class="handle-label">video position</span> </div> <span class="current-position">00:00</span> <!-- more jme control elements --> </div>
$('div.player').jmeControl();
general options of .jmeControl()
jmeControl has three main-options (every control-element/behavior-class can add additional options).
addThemeRoller defauls to true
This option decides wether the script should add jQuery UI Themeroller classes like ‘ui-state-default’ or ‘ui-corner-all’ to your control elements.
$('div.media-player').jmeControl({ addThemeRoller: false });
classPrefix defauls to "" (empty string)
To minimize conflicts with your existing classes, you can specify a prefix for all behavior classes.
<div class="media-player"> <video src="my-video.mp4"></video> <a class="jme-play-pause" href="#">play / pause</a> <a class="jme-mute-unmute" href="#">mute / unmute</a> </div>
$('div.media-player').jmeControl({ classPrefix: 'jme-' });
embed embed options
Options to configure the jmeEmbed-method. jmeControl changes the default embed option 'removeControls' to true.
If you use jmeControl you won't have to additionally use the embed-method (jmeEmbed). To be able to configure your embed-behavior you can use this property. All configuration-options are explained on the embedding-site.
$('div.media-player').jmeControl({ embed: {showFallback: true} });
List of media control elements/behavior-classes
progressbar
The behavior-class progressbar adds jQuery UI Progressbar behavior to the markup, showing the current buffer-progress of your j mediaelement.
<div class="progressbar"></div>
timeline-slider slider-options
The behavior-class timeline-slider adds jQuery UI Slider behavior to your markup, showing and changing the current time position of your jMediaelement.
<div class="jme-timeline-slider"></div>
All jQuery UI-Options can be configured due to the timeSlider-property.
$('div.media-player').jmeControl({ classPrefix: 'jme-', timeSlider: { animate: true, range: 'min' } });
volume-slider slider-options
The behavior-class volume-slider adds jQuery UI Slider behavior to your markup, showing and changing the current volume of your jMediaelement.
<div class="volume-slider"></div>
All jQuery UI-Options can be configured due to the volumeSlider-property.
$('div.media-player').jmeControl({ volumeSlider: { orientation: 'vertical', range: 'min' } });
Additional you can use the "mutestate" property (defaults to false). If mutestate is true, the volumeslider is also bound to the mute-state.
$('div.media-player').jmeControl({ volumeSlider: { mutestate: true } });
or using the markup-API:
<div class="volume-slider" data-mutestate="true"gt;</div>
duration
The behavior-class duration adds duration-display behavior to your element. It shows the duration of your jMediaelement in the mm:ss format.
<span class="duration"></span>
current-time
The behavior-class current-time adds current-time-display behavior to your element. It shows the current time of your jMediaelement in the mm:ss format.
<span class="current-time"></span>
remaining-time
The behavior-class remaining-time adds remaining-time-display behavior to your element. It shows the remaining time of your jMediaelement in the mm:ss format.
<span class="remaining-time"></span>
play-pause
The play-pause class adds behavior for toggeling the play/pause-state of your jMediaelement. It also toggles between the classes ui-icon-pause and ui-icon-play.
<button class="play-pause"><span>play / pause</span></button>
mute-unmute
The mute-unmute class adds behavior for toggeling the mute-state of your jMediaelement. It also toggles between the classes ui-icon-volume-off and ui-icon-volume-on.
<button class="mute-unmute">mute / unmute</button>
media-controlsmediaControls-options
Grouping element for a set of other control elements
This control adds some jQuery UI Themeroller classes and WAI-Aria attributes to your markup.
The media-controls element provides two options
-
dynamicTimeslider (defaults to false)
Setting this to true, the media-control will calculate the available inner width not consumed by his children and will automatically set the width of the timeline-slider to the availabel width.
This makes it a lot easier to style controls over different sized columns.
-
timeSliderAdjust (defaults to 0)
Only effects if dynamicTimeslider is set to true. Adjustes the calculated width by the provided number.
$('div.media-player').jmeControl({ mediaControls: { dynamicTimeslider: true, //deal with different subpixel rendering: timeSliderAdjust: -3 } });
media-state click-behavior
A visual element representing the current state of the media element.
This control switches between different state- and api-classes which represent the current state or used api of the media element.
State Classes:
- idle: media element is in paused or ended state
- totalerror: media element can not play the current source
- playing: media element is currently playing
- waiting: media element has not enough data to play or seek
API Classes:
- nativ: media element uses the native HTML5 element to play
- jwPlayer: media element uses JW-Player (Flash-Plugin) to play
Due to the fact, that the media-state control is commonly used as an video-overlay, you can specify a default click behavior, which defaults to 'togglePlay'.
$('div.media-player').jmeControl({ mediaState: { click: 'play' // false || togglePlay || play || toggleMuted } });
<div class="media-state"></div>
media-label
The name of your media player. Good for accessibility.
This media-label element will label the common wrapper element.
We suggest that you use both a "role"-name (i.e. audioplayer/videoplayer) and a media-name.
<span class="media-label">videoplayer: big buck bunny</span>
If you use the loadSrc-method with the mediaName-parameter and only want to change the media-name and not the role-name. Wrap your media-name into an element with the class 'media-name'.
<span class="media-label"> videoplayer: <span class="media-name">big buck bunny</span> </span>
fallback
A element that serves as a fallback message. The fallback element is always a descendant-element of your media element.
Using this markup will override the showFallback-option by the jmeEmbed-method.
<video src="my-video.mp4"> <p class="fallback"> Please, install flash </p> </video>
general Informations about some controls
Toggle Buttons (play-pause, mute-unmute)
Toggle buttons always toggle the state of the jMediaelement and reflect this state with toggleing between two classes. Additionally, if you provide a text or a title wich is seperated with / or | it will also toggle this text.
If you want to generate UI Themeroller conform markup, you have to use the class 'ui-icon' and the jme-specific class 'button-text'.
<button class="mute-unmute"><span class="ui-icon"></span> <span class="button-text">mute / unmute</span></button>
Some accessibility information: If you don't use a button element for your toggle buttons (for better cross-browser-styling). jmeControl will automatically add WAI-Aria attributes to make your buttons more accessible.
The follwoing code for example:
<span class="mute-unmute">mute / unmute</span>
will be automatically transformed to the following markup
<span role="button" tabindex="0" class="mute-unmute">mute / unmute</span>
creating accessible WAI-Aria enhanced sliders
jQuery UI does not provide WAI-Aria conform sliders yet. By using the a11y-slider extension for jQuery UI you can easily add accessiblity to your sliders.
To use the a11y-slider extension simply include the JavaScript file. You will find this file in our utils-folder.
To be accessible you have to label the slider-control yourself, to let the user know what he can achieve with the slider.
<div class="timeline-slider"> <span class="handle-label">volume control</span> </div>
/* yes display: none is not only accessible in conjunction with 'aria-labelledby elements', it is recommended */ .handle-label {display: none;}
Note: We have successfully testet the a11y-slider extension with Jaws 11 using IE8+ and FF 3.5+ and with NVDA 2009.1+ using FF 3.5+. But there are some known unfixable issues with Jaws 10 using IE8.
creating a relationship between a control and the controled media element
There are two possibilities to create a control-relationship, between a control element and his media element.
common wrapper
To create a control media element relationship simply call jmeControl on a common wrapper:
<div class="my-common-wrapper"> <video src="my-video.mp4" controls="controls"></video> <div class="media-controls"> <button class="play-pause">play / pause</button> <!-- a bunch of additional controls --> </div> </div>
$('div.my-common-wrapper').jmeControl();
The common wrapper serves also as a media-state-control with shortcut-support, but without a click behavior.
data-controls attribute
Another way to create a control-relationship is to use the data-controls-attribute. The value of this attribute references the id of the media element.
The data-controls attribute can be used directly on the control-element:
<video id="video-ref" src="my-video.mp4" controls="controls"></video> <button data-controls="video-ref" class="play-pause">play / pause</button>
$('button[data-controls]').jmeControl();
... or on a wrapper element:
<div data-controls="video-ref"> <button class="play-pause">play / pause</button> <button class="mute-unmute">mute / unmute</button> <!-- a bunch of additional controls --> </div>
$('div[data-controls]').jmeControl();
Tips for rapid development: UI markup helpers & UI behavior helpers
The freedom to let you write your own control-markup and your own UI behavior gives you a great flexibility, but it comes with a downside:
You have to define your controls your own and you have to add extra UI behavior, if you need.
To reduce this downside, jme comes with some demos as a starting point and some markup and UI helpers.
- use the HTML, CSS and JS from a demo-site included in the project/bundeled download as starting point.
- instead of writing the same control-markup again and again, be dry and use the jmeEmbedControls-utility as a starting point (create your own version of this extremly simple plugin).