Note
Access to this page requires authorization. You can try signing in or changing directories.
Access to this page requires authorization. You can try changing directories.
Note
The Retail Interest Group by Dynamics 365 Commerce has moved from Yammer to Viva Engage. If you don't have access to the new Viva Engage community, fill out this form (https://aka.ms/JoinD365commerceVivaEngageCommunity) to be added and stay engaged in the latest discussions.
This article describes how to use the Image component in the online software development kit (SDK) to embed images into a module in Microsoft Dynamics 365 Commerce.
The Image component uses the Dynamics 365 image resizer service to optimize image sizes, so that appropriately sized images load for the different viewport layouts that a module supports. The Image component also supports fallback and thumbnail images.
Use the Image component in a module
Use the Image component in a module by including a reference to @msdyn365-commerce/core, as shown in the following example.
import { IImageData, IImageSettings, Image } from '@msdyn365-commerce/core';
ImageSettings class
The Image component takes an ImageSettings class that defines the behavior of the image. The ImageSettings class enables the configuration of image dimensions for different viewport sizes. It also enables the configuration of lazy loading and image quality optimization. When you use an image configuration in a module, set the configuration values in Commerce site builder. The values are returned and used when the image renders, as shown in the following example interface.
export interface IImageSettings {
viewports: IViewPort;
lazyload?: boolean;
disableLazyLoad?: boolean;
quality?: number;
cropFocalRegion?: boolean;
mode?: number;
backgroundColor?: string;
}
export interface IViewPort {
xs: IImageDimension;
sm?: IImageDimension;
md?: IImageDimension;
lg?: IImageDimension;
xl?: IImageDimension;
}
export interface IImagePlaceholderConfig {
name: string;
svgConfig?: ISVGConfig;
imagePropertyName?: string;
moduleType?: string;
layout?: string;
moduleId?: string;
}
export interface ISVGConfig {
height: number;
width: number;
preserveAspectRatio?: string;
}
export interface IImageDimension {
w: number;
h: number;
q?: string;
}
ImageSettings viewport configuration
In general, the ImageSettings instance automatically fills in information from the image configuration in site builder. However, if you're manually constructing the object, it's useful to know the query string parameter values that the image resizer uses to render the images, in case you need to mock the data for testing purposes.
To ensure that the image resizer service handles an image correctly, set the appropriate "q" query string parameter on the ImageDimension instance. The format is w=WIDTH_NUMBER&h=HEIGHT_NUMBER&m=MODE_NUMBER, where WIDTH_NUMBER and HEIGHT_NUMBER specify the width and height values in pixels (0–3000), and MODE_NUMBER specifies the image resizer mode to use.
If you don't provide the "q" parameter, the service takes the width and height values from the "w" and "h" parameters of the viewports property. The service takes the image resizer mode from the mode property of the IImageSettings object.
Some image resizer modes might clip (crop) an image. If the aspect ratio of the cropped image doesn't match the aspect ratio of the original image, the background color fills in the remaining region.
The following table describes the image resizer modes that the service supports.
| Mode | Title | Description |
|---|---|---|
| 1 | letter-box | This mode scales an image from its original dimensions to the requested dimensions and maintains the aspect ratio of the original image. If the aspect ratio of the requested dimensions doesn't match the aspect ratio of the original image, a background color fills in the remaining region. |
| 2 | scale | This mode scales an image from its original dimensions to the requested dimensions and maintains the aspect ratio of the original image. This mode is the default mode if no mode is set. |
| 3 | stretch | This mode scales an image from its original dimensions to the requested dimensions but doesn't maintain the aspect ratio of the original image. |
| 4 | crop | This mode scales an image from its original dimensions to the requested dimensions and maintains the aspect ratio of the original image. If the aspect ratio of the requested dimensions doesn't match the aspect ratio of the original image, regions that fall inside the boundaries of the requested dimensions are cropped and retained. If the original image layout is landscape, the cropped region is centered both horizontally and vertically on the original image. However, if the image layout is portrait, the cropped region is centered horizontally and 30 percent from the top of the original image, to capture a face. |
| 5 | focal-crop | This mode is a variation of the standard crop mode. In this case, the region to crop is determined by a specified focal point. This mode scales an image from its original dimensions to the requested dimensions and maintains the aspect ratio of the original image. If the aspect ratio of the requested dimensions doesn't match the aspect ratio of the original image, regions that fall inside the boundaries of the requested dimensions are cropped and retained. If the original image layout is landscape, the cropped region is centered both horizontally and vertically on the original image. However, if the image layout is portrait, the cropped region is centered horizontally and one-sixth from the top of the original image, to capture a face. The location of the cropped region can be configured via the web.config file. In this case, the configuration affects all images. Alternatively, it can be configured via the URL. In this case, the configuration affects only the requested image. |
| 6 | facial crop | This mode is a variation of the focal-crop crop mode. In this case, the region to crop is determined by a focal region that is centered on automatically detected faces. This mode scales an image from its original dimensions to the requested dimensions and maintains the aspect ratio of the original image. If the aspect ratio of the requested dimensions doesn't match the aspect ratio of the original image, regions that fall inside the boundaries of the requested dimensions are cropped and retained. The cropped region is centered in an automatically detected collection of faces. |
| 8 | custom crop | This mode first crops the image to the region that the query string parameters specify. It then scales the cropped image to the requested dimensions. Depending on other settings that the query string parameters specify, scaling and letterboxing actions might also be performed. |
Example of Image component usage
The following example shows how you can use the Image component and the ImageSettings class in a module. The example declares a defaultImageSettings variable to set the width, height, scaling mode, and background color values if these values aren't provided in site builder. (Site builder might not provide these values if you're debugging in a development environment where the module mocks don't provide values.)
import * as React from 'react';
import { IImageSettings, Image } from '@msdyn365-commerce/core';
import { IProductFeatureData } from './product-feature.data';
import { IProductFeatureProps } from './product-feature.props.autogenerated';
export default (props: IProductFeatureProps<IProductFeatureData>) => {
const {} = props;
// Construct the default image settings if settings are not found in the theme settings file
const defaultImageSettings: IImageSettings = {
viewports: {
xs: { w: 100, h: 200 },
sm: { w: 200, h: 200 },
md: { w: 300, h: 300 },
lg: { w: 400, h: 400 }
},
lazyload: false,
mode: 8,
backgroundColor: 'FF0000'
};
return (
<div className='row align-items-center'>
<Image
requestContext={props.context.actionContext.requestContext}
className='product-image'
{...props.config.productImage}
gridSettings={props.context.request.gridSettings!}
imageSettings={props.config.productImage?.imageSettings || defaultImageSettings}
loadFailureBehavior='hide'
role='tabpanel'
id='productImageTage'
altText={props.config.productImage?.altText || ''}
/>
</div>
);
};
In the preceding example, the module uses a productImage module configuration that specifies "type": "image", as shown in the following example of a module definition file. This implementation lets the page author configure an image for the module in site builder. It also enables a focal point to be configured for each module image that the page author passes to the image resizer service.
{
"$type": "contentModule",
"friendlyName": "Product Feature",
"name": "product-feature",
"description": "Feature module used to highlight a product.",
"categories": [
"storytelling"
],
"tags": [
""
],
"dataActions": {
},
"config": {
"productImage": {
"type": "image",
"friendlyName": "Product Image",
"description": "Image representing the featured product"
}
}
}
Support module layouts in a theme
A site theme contains a THEME_NAME.theme.settings.json file that can define different module layouts, each of which has its own ImageSettings class. For more information, see Configure theme settings.
The following example shows a theme that defines a two-module layout (vertical and horizontal), where each viewport has different image sizes. All the defined layouts for a theme then appear in the module configuration in site builder, where the page author can select among them. When a module renders, the settings from the theme are passed to the image resizer service. The image resizer service can then serve the appropriately sized image, based on the browser viewport and the selected layout.
{
"modules": {
"product-feature": {
"properties": {
"vertical": {
"friendlyName": "Vertical",
"description": "Vertical",
"type": "layout",
"properties": {
"productImage": {
"friendlyName": "Image Settings",
"description": "Image settings for the main image",
"type": "imageSizes",
"properties": {
"xs": {
"width": 75,
"height": 75
},
"sm": {
"width": 250,
"height": 250
},
"md": {
"width": 350,
"height": 350
},
"lg": {
"width": 400,
"height": 400
},
"xl": {
"width": 500,
"height": 500
}
}
}
}
},
"horizontal": {
"friendlyName": "Horizontal",
"description": "Horizontal",
"type": "layout",
"properties": {
"productImage": {
"friendlyName": "Image Settings",
"description": "Image settings for the main image",
"type": "imageSizes",
"properties": {
"xs": {
"width": 155,
"height": 155
},
"sm": {
"width": 255,
"height": 255
},
"md": {
"width": 355,
"height": 355
},
"lg": {
"width": 455,
"height": 455
},
"xl": {
"width": 555,
"height": 555
}
}
}
}
}
}
}
},
"gridSettings": {
"xs": 768,
"sm": 991,
"md": 1199,
"lg": 1599,
"xl": 1600
}
}
Mock image data in a module mock
The following example shows a module mock file that sets the imageSettings mock data.
{
"id": "R1Module1",
"platform": {
"layout": "vertical"
},
"config": {
"msdyn365__moduleLayout": "vertical",
"imageAlignment": "left",
"productTitle": "Retro Horn Rimmed Keyhole Nose Bridge Round Sunglasses",
"productDetails": "High-quality and pioneered with the perfect blend of timeless classic and modern technology with hint of old school glamor.",
"productImage": {
"src": "https://images-us-ppe.cms.commerce.dynamics.com/cms/api/dbfztcmjrn/imageFileData/search?fileName=/Products%2F91005_000_001.png",
"altText": "Retro Horn Rimmed Keyhole Nose Bridge Round Sunglasses",
"quality": 80,
"imageSettings": {
"viewports": {
"xs": {
"q": "w=125&h=125&m=8",
"w": 0,
"h": 0
},
"sm": {
"q": "w=225&h=225&m=8",
"w": 0,
"h": 0
},
"md": {
"q": "w=325&h=325&m=8",
"w": 0,
"h": 0
},
"lg": {
"q": "w=425&h=425&m=8",
"w": 0,
"h": 0
}
},
"lazyload": false
}
},
"buttonText": "Buy Now"
},
"typeName": "product-feature"
}
Mock image data in a page mock
The following example shows a page mock file that sets the imageSettings mock data.
{
"exception": null,
"pageRoot": {
"id": "core-root_0",
"typeName": "core-root",
"modules": {
"body": [
{
"id": "default-page_0",
"typeName": "default-page",
"modules": {
"primary": [
{
"id": "ProductFeature__0",
"typeName": "product-feature",
"platform": {
"layout": "vertical"
},
"config": {
"msdyn365__moduleLayout": "vertical",
"imageAlignment": "left",
"productTitle": "Retro Horn Rimmed Keyhole Nose Bridge Round Sunglasses",
"productDetails": "High-quality and pioneered with the perfect blend of timeless classic and modern technology with hint of old school glamor.",
"productImage": {
"src": "https://images-us-ppe.cms.commerce.dynamics.com/cms/api/dbfztcmjrn/imageFileData/search?fileName=/Products%2F91005_000_001.png",
"altText": "Retro Horn Rimmed Keyhole Nose Bridge Round Sunglasses",
"quality": 80,
"imageSettings": {
"viewports": {
"xs": {
"q": "w=60&h=60&m=8",
"w": 0,
"h": 0
},
"sm": {
"q": "w=160&h=160&m=8",
"w": 0,
"h": 0
},
"md": {
"q": "w=260&h=260&m=8",
"w": 0,
"h": 0
},
"lg": {
"q": "w=360&h=360&m=8",
"w": 0,
"h": 0
}
},
"lazyload": false
}
},
"buttonText": "Buy Now"
}
},
{
"id": "ProductFeature__1",
"typeName": "product-feature",
"platform": {
"layout": "vertical"
},
"config": {
"msdyn365__moduleLayout": "vertical",
"imageAlignment": "right",
"productTitle": "Retro Horn Rimmed Keyhole Nose Bridge Round Sunglasses",
"productDetails": "High-quality and pioneered with the perfect blend of timeless classic and modern technology with hint of old school glamor.",
"productImage": {
"src": "https://images-us-ppe.cms.commerce.dynamics.com/cms/api/dbfztcmjrn/imageFileData/search?fileName=/Products%2F91005_000_001.png",
"altText": "Retro Horn Rimmed Keyhole Nose Bridge Round Sunglasses",
"quality": 80,
"imageSettings": {
"viewports": {
"xs": {
"q": "w=70&h=70&m=8",
"w": 0,
"h": 0
},
"sm": {
"q": "w=170&h=170&m=8",
"w": 0,
"h": 0
},
"md": {
"q": "w=270&h=270&m=8",
"w": 0,
"h": 0
},
"lg": {
"q": "w=370&h=370&m=8",
"w": 0,
"h": 0
}
},
"lazyload": false
}
},
"buttonText": "Buy Now"
}
}
]
},
"config": {
"pageTheme": "spring"
}
}
]
}
},
"renderingContext": {
"gridSettings": {
"xs": {
"w": 768
},
"sm": {
"w": 991
},
"md": {
"w": 1199
},
"lg": {
"w": 1599
},
"xl": {
"w": 1600
}
},
"staticContext": {
"staticCdnUrl": "/_scnr/"
},
"locale": "en-us",
"siteTheme": "spring"
},
"statusCode": 200
}