Frontend Developer Manual / Version 2406.0
Table Of ContentsThis brick offers the following features:
CMPicture support with different image sizes for various viewport dimensions (responsive images). This means, that different crops of an image can be displayed on different devices.
CMVideo support to render a native HTML5 video element.
CMAudio support to render a native HTML5 audio element.
Note
To support the playback of videos from external sources like YouTube, Vimeo etc. the mediaelement brick is required. For more information visit Section 6.3.7, “MediaElement”
The image in its default size and shape
It can be fitted into different aspect ratios according to the parent container
And rendered with different resolutions for smaller use cases
Using the Brick
The brick provides a media view for content of type com.coremedia.blueprint.common.contentbeans.CMPicture,
com.coremedia.blueprint.common.contentbeans.CMVideo and com.coremedia.blueprint.common.contentbeans.CMAudio
so the first item in the media property of a com.coremedia.blueprint.common.contentbeans.CMTeasable could be rendered using:
<@cm.include self=self.firstMedia view="media" />Templates and Parameters
These templates can be included in your theme (for example, in a CMVideo.asHero.ftl template) as follows:
<@cm.include self=self view="media" params={"preload": true}/>Responsive Images
Images need to be available in various sizes and resolutions to fit different use cases. For example in a 4x3 aspect ratio for a teaser, 16x9 in a hero teaser and both scaled down for a mobile view as well. The media brick provides an efficient way to choose the best fitting image for any case.
At first the responsive image settings need to be configured in your sites content and linked to its settings. For more information
on how to do this, configuring all image croppings and the available settings see Section 5.4.14, “Images” in
Blueprint Developer Manual
.
The different image croppings you define here are then available in the frontend. When including a CMPicture
in a template using the media view, an object containing URLs for all defined variants will be added in a data-cm-responsive-media
attribute to the HTML img element.
The picture and its parent div element are essential units. The img has a CSS class consisting of the block class
and a __picture suffix. This positions the image absolute in its parent. The parent has the same block class with a __picture-box suffix.
This renders a before pseudo element responsible for the correct height ratio defined by its padding-top value. Therefore,
CoreMedia provides the SCSS mixin aspect-ratio-box to receive the wanted aspect ratio.
@include aspect-ratio-box(4, 3);
Note
The matching crop to the values for the aspect-ratio-box must be defined in the responsive image settings.
For every page load and viewport size change the responsive image JavaScript is triggered for every image with the cm-responsive-media data attribute.
It decides which is the best fitting image from the set of responsive images for the height and the width of the parent image-box div and puts its URL
into the src attribute of the image.
The view accepts the following parameters.
| Parameter | Type | Default | Description |
|---|---|---|---|
classBox
|
String
|
""
| CSS class for the outer div that contains the image and title. |
classMedia
|
String
|
""
| CSS class for the div containing the image. |
disableCropping
|
Boolean
|
false
| When set to true, in every case the highest available resolution of the image is used and responsive images is disabled. |
background
|
Boolean
|
false
|
When set to true, the image is linked as background-image in the style tag of the block div.
|
metadata
|
Array
|
[]
| Additional PDE Information to attach to the outer div of the image. |
metadataMedia
|
Array
|
[]
| Additional PDE Information to attach to the image itself. |
additionalAttr
|
Map
|
{}
|
This adds attributes to the img tag.
|
Table 6.11. Parameters of the media view for responsive images
Note
Correctly configured responsive image settings that are linked to the site are mandatory for the responsive images function to work! The fallback is one image with its highest resolution available.
Video and Audio
To configure the behavior of the video or audio elements you can add the following parameters to the
cm.include tag:
| Parameter | Type | Default | Description |
|---|---|---|---|
hideControls
|
Boolean
|
false
| Hide the control panel for audio and video playback |
autoplay
|
Boolean
|
false
| The media file starts playing automatically after it has been loaded |
loop
|
Boolean
|
false
| The audio or video plays in an infinite loop |
muted
|
Boolean
|
false
| The video is muted |
preload
|
Boolean
|
false
| The browser starts loading the first part of the media file |
Table 6.12. Parameters of the media brick
Note
Please note, that setting these parameters will overwrite the settings, defined in the content itself.
A Studio user can define the autoplay, loop, muted and hideControls
configuration of videos and audio files by changing them in the content form of the content.
Since the Studio configuration is only used as a fallback, the configuration by
template parameters will always finally decide the player's behavior.
Additional Resources
playicon.param.svgVideo_de.propertiesVideo_en.properties
