Media Component
Note: Spartacus 2.x is no longer maintained. Please upgrade to the latest version.
Note: This feature is introduced with version 2.0 of the Spartacus libraries.
The media component is a low-level component that is used to render a single media item. Although the back end could provide any type of media for a media item, the media component is currently limited to render images only. The type of image is not limited to a technical format, such as png or jpg. Every image format that can be rendered in an image element is supported, including svg. The media component renders specific images for different screen sizes and resolutions, so that each user has an optimized version of the image.
There are two main types of images that are rendered in Spartacus: product images and content images. Both types use the same technical implementation, but the semantics of the content is slightly different for each.
Note: Icons are a special type of image and are not rendered with the media component. For more information, see Icon Library.
Responsive Media
The image structure that is used in SAP Commerce Cloud consists of a media container that holds multiple media items. The media items inside a container are distinguished by a media format. The media format is used to provide the same media for various different screen sizes or placements.
The media formats for product images and for content images are different, and their use also differs.
Product Images
Product images are driven by product data. Product images are used in a large number of components, such as in the product listing and product details pages, as well as in components that are used for cart and order data, and also in components such as carousels, wish lists, interests, and so on. However, the product image data source is always the same, regardless of the component.
Different product images for different screen sizes are typically generated based on the same source image. This results in a media container that holds a number of media items that only differ in pixel size, but are equal in terms of content and proportions.
The media formats for product images can be configured in both the back end and the front end. The following list shows the (default) formats that are used in the sample data and in the Spartacus configuration:
- cartIcon
- thumbnail
- product
- zoom
Content Images
Content images are driven by CMS component data. Media items are used in different banner components. Unlike product images, banner images are often manually optimized for various screen sizes. This means that a content manager uploads alternative images to the banner for each media format. The technical structure is the same for product and banner media, but the formats are different. The following list shows the (default) formats that are used in the sample data and in the Spartacus configuration:
- mobile
- tablet
- desktop
- widescreen
For more information, see Banner Component.
Localized Media
SAP Commerce Cloud supports localized media, which means that different media items can be used for different languages. This is sometimes used for content images that contain localized text.
Localized media works transparently for the media component. Whenever the site context changes in Spartacus (including for languages), the CMS and product data are cleared from the state, which results in a reload of the data for the given context.
Implementation Details
The cx-media media component renders images with the native img HTML element. To support an optimized image for the given element, a container with multiple images is expected. The various images in the container are evaluated by their media format and compared to a media format configuration in Spartacus.
The native img element supports multiple images with the srcset attribute. This attribute takes various image sources and combines them with an associated width descriptor. The browser selects and downloads the correct image based on which dimensions of the img element are used. With this approach, you do not need to provide a specific format for the media component, although you can do this with the format input.
The srcset attribute also supports the pixel density descriptor, but it is (currently) not supported in Spartacus. The pixel density descriptor can be used to select different images for different devices. For example, an image width descriptor of 400 px might be rendered on retina devices at a maximum of 200 px, because these devices double the pixels to provide an optimized image resolution for their device screens.
The mapping from an image format to the srcset width descriptor is driven by the media configuration in Spartacus. The main image src and the various image descriptions for the srcset are collected by the MediaService. This services compares the images from the media container with a configuration set of media formats and their sizes. The matching sizes are collected and sorted, and written in the img srcset attribute, so that the browser can select and download the correct image.
Note: When you change the browser from a larger screen to a smaller screen, the browser does not download an additional image from the srcset, because it makes the assumption that the larger image can be decreased. This is acceptable for most images, but this might give unexpected results for banner images because the aspect ratio and the actual content of the banner image can be very different for each screen size.
You can provide a custom configuration using the MediaConfig typing. The following is an example of the default media configuration:
export const mediaConfig: MediaConfig = {
mediaFormats: {
// banner formats
mobile: { width: 400 },
tablet: { width: 1070 },
desktop: { width: 1140 },
widescreen: { width: 1400 },
// product formats
cartIcon: { width: 65 },
thumbnail: { width: 96 },
product: { width: 284 },
zoom: { width: 515 },
},
};
Missing Media
Whenever a media item is unavailable, the img element is not written in the DOM. The cx-media host element will get an is-missing class, so that the correct style can be applied by CSS. In this scenario, Spartacus provides an empty image through the background image.
If no matching image format is available in the media container, nor in the media configuration, Spartacus takes a random image from the container. This might not be an accurate format, but at least it helps to show content.
SEO
To ensure that crawlers get an optimized image from the img element, the main src of the img element is provided with the
largest image available. This is done in MediaService.resolveBestFormat(), and you can further customize this behavior if needed.
Note that the actual image for the page is not driven by the img element, because crawlers will use other sources to indicate the image. Spartacus supports both page meta tags (for example, 'og:image') and structural data (json-ld) to provide that data to crawlers. For more information, see Page Meta Resolvers and Structured Data.
Another important aspect for SEO is the usage of the alternative (alt) text for images. The alt text is automatically selected by the MediaService if it is available in the media container data. However, you can also input a custom alt text through the component input.