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).

												$('div.media-player').jmeControl({
													addThemeRoller: false
												});
											

												<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-'
												});
											

												$('div.media-player').jmeControl({
													embed: {showFallback: true}
												});
											

List of media control elements/behavior-classes

												<div class="progressbar"></div>
											

												 <div class="jme-timeline-slider"></div>
											

												$('div.media-player').jmeControl({
												    classPrefix: 'jme-',
												    timeSlider: {
												        animate: true,
												        range: 'min'
												    }
												});
											

												 <div class="volume-slider"></div>
											

												$('div.media-player').jmeControl({
												    volumeSlider: {
												        orientation: 'vertical',
												        range: 'min'
												    }
												});
											

												$('div.media-player').jmeControl({
												    volumeSlider: {
												        mutestate: true
												    }
												});
											

												 <div class="volume-slider" data-mutestate="true"gt;</div>
											

												 <span class="duration"></span>
											

												 <span class="current-time"></span>
											

												 <span class="remaining-time"></span>
											

												<button class="play-pause"><span>play / pause</span></button>
											

												 <button class="mute-unmute">mute / unmute</button>
											

												$('div.media-player').jmeControl({
												    mediaState: {
												        click: 'play' // false || togglePlay || play || toggleMuted
												    }
												});
											

												 <div class="media-state"></div>
											

												 <span class="media-label">videoplayer: big buck bunny</span>
											

												 <span class="media-label">
												 	videoplayer: <span class="media-name">big buck bunny</span>
												</span>
											

												 <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).