ZK Component Reference/Multimedia and Miscellaneous/Video

Video

• Java API: Video
• JavaScript API: Video

[ ZK EE ]
[ since 8.6.0 ]

Employment/Purpose

A video component is used to play the video in the browser. Like audio, you can use the src property to specify an URL of the video resource, or use the setContent method to specify a dynamically generated video. Developers can control the video by play, stop and pause.

Example

 <video src="zk.mp4" controls="true" autoplay="true" loop="true" />

Supports HTML5

The video component is based on HTML 5's <video> tag, and supports the following properties: autoplay, controls, loop, muted, preload, poster and crossorigin.

Multiple Sources

Most browsers do not support all the video formats, so we can specify multiple source files in different formats for different browsers. If the first format is not supported by the browser, it will fallback to the 2nd format. For example:

 <video src="zk.mp4, zk.webm, zk.ogg" />

enableFullScreen

For security reason, fullScreen API can only be initiated by an user gesture, therefore the video component only provides a client-side method enableFullScreen() for enabling the full screen mode.

 <video id="player" src="zk.mp4" />
 <button xmlns:w="client" w:onClick="zk.$('$player').enableFullScreen()" />

dimBackground

The video component provides a theater mode, If dimBackground="true", the whole page will be covered by translucent black by default except for the Video.

When the theater mode is enabled, user can click anywhere on the page outside the Video to disable theater mode and return to the normal view.

 <video src="zk.mp4" dimBackground="true" />

By default, css of dimBackground has two properties like following css code.

You can also customize what background you like, just override .z-video-dim-background in css.

<style>
.z-video-dim-background {
    background: black;
    opacity: 0.8;
}
</style>

playbackRate

The video provides setPlaybackRate(double) to control the video playing speed, the valid value is depending on browser.

Default: 1.0

 <video src="zk.mp4" playbackRate="0.5" />

currentTime

The video provides setCurrentTime(double) to jump to the specified time-point (in seconds) of the playback video.

 <video src="zk.mp4" currentTime="60" />

playing

The video provides setPlaying(boolean) to play or pause the video.

playing="true" is same as invoking play(), playing="false" is same as invoking pause().

 <video src="zk.mp4" playing="false" />

volume

The video component provides setVolume(double) to change the volume, the value should range between 0.0 and 1.0.

Default: 1.0

 <video src="zk.mp4" volume="0.5" />

muted

The video component provides setMuted(boolean) to mute the video.

Default: false

 <video src="zk.mp4" muted="true" />

clipToFit

The video component provides setClipToFit(boolean) to clip video when the source size doesn't fit the tag size setting.

For example:

The source below is 450 * 320, when I set width="300px", height="320px", there will be blank up and down in the video to preserve the aspect ratio, like first image, when I set clipToFit="true", it will cut off the sides and filling in the space, like second image.

  <video width="300px" height="320px" src="zk.mp4" style="border: 1px solid red;"/>
  <video width="300px" height="320px" src="zk.mp4" style="border: 1px solid red;" clipToFit="true" />

StateChangeEvent

When calling play(), stop() or pause() StateChangeEvent will be triggered. You can check the current state by calling event.getState(). Video has three states, you can access them by using Video.PLAY, Video.STOP and Video.PAUSE.

For example:

If you want to do something after start playing the video, you can write codes as shown below (MVVM style).

  <video onStateChange="@command('stateChange', event=event)" />

  @Command
  public void stateChange(@BindingParam("event") StateChangeEvent event) {
    if (event.getState() == Video.PLAY) {
      // do something...
    }
  }

Supported Events

Name	Event Type
onStateChange	Event: StateChangeEvent Notifies when invoking play(), stop() or pause().

• Inherited Supported Events: XulElement

Supported Children

*NONE