From 9533391fc2adef4109286a4583ad5d7afba25def Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?B=C3=A1rbara=20Celi?= <112641072+barbara-celi@users.noreply.github.com> Date: Fri, 21 Feb 2025 13:49:33 -0300 Subject: [PATCH] Update ProductImages.md --- docs/ProductImages.md | 43 ++++++++++++++++++++++++++++--------------- 1 file changed, 28 insertions(+), 15 deletions(-) diff --git a/docs/ProductImages.md b/docs/ProductImages.md index 2e8a0f3d9..a125eaf72 100644 --- a/docs/ProductImages.md +++ b/docs/ProductImages.md @@ -6,6 +6,19 @@ The `product-images` block renders a product image or video. ![image](https://cdn.jsdelivr.net/gh/vtexdocs/dev-portal-content@main/images/vtex-store-components-productimages-0.png) +The accepted video formats are the following. Remember to replace `{VIDEO_ID}` according to your scenario. + +**Vimeo** + +- `https://vimeo.com/{VIDEO_ID}` + +**Youtube** + +- `https://youtu.be/{VIDEO_ID}` +- `https://www.youtube.com/watch?v={VIDEO_ID}` +- `https://www.youtube.com/embed/{VIDEO_ID}` +- `https://www.youtube.com/v/{VIDEO_ID}` + ## Configuration 1. Import the `vtex.store-components` app to your theme dependencies in the `manifest.json` file, as in the following example: @@ -31,7 +44,7 @@ The `product-images` block renders a product image or video. }, ``` -3. Then, declare the `product-images` block using the props stated in the [Props](#props) table. For example: +3. Declare the `product-images` block using the props stated in the [Props](#props) table. For example: ```json "product-images": { @@ -45,32 +58,32 @@ The `product-images` block renders a product image or video. | Prop name | Type | Description | Default value | | ------------------------- | ---------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------------- | -| `aspectRatio` | `string` | Sets the aspect ratio of the image; whether the image should be square, portrait, landscape, etc. The value should follow the [common aspect ratio notation](https://en.wikipedia.org/wiki/Aspect_ratio_(image)) i.e. two numbers separated by a colon, such as `1:1` for square, `3:4` for upright portrait, or `1920:1080` for even large values). | `"auto"` | +| `aspectRatio` | `string` | Sets the image's aspect ratio, determining whether it should be square, portrait, landscape, etc. Follow the [common aspect ratio notation](https://en.wikipedia.org/wiki/Aspect_ratio_(image)), represented by two numbers separated by a colon, such as `1:1` for square, `3:4` for portrait, or `1920:1080` for widescreen. | `"auto"` | | `blockClass` | `string` | Serves as the block's unique identifier for customization. | | `contentOrder` | `'videos-first'` | `'images-first'` | Controls the order in which the images and videos are displayed. | `'images-first'` | | `contentType` | `enum` | Controls the type of content that will be displayed in the block. Possible values are: `images`, `videos`, or `all`. | `all` | -| `displayMode` | `enum` | Defines how the product media should be displayed. Possible values are `carousel` (displays the product images and videos in a carousel), `list` (displays only the product images inline, with no extra markup), and `first-image` (displays only the first image available). *Caution*: The `list` and `first-image` values do not display product videos and are only compatible with the `maxHeight`, `hiddenImages`, `zoomFactor`, `aspectRatio`,`ModalZoomElement`, and `zoomMode` props. | `carousel` | +| `displayMode` | `enum` | Defines how the product media should be displayed. Possible values are `carousel` (displays the product images and videos in a carousel), `list` (displays only the product images inline, with no extra markup), and `first-image` (displays only the first image available). **The `list` and `first-image` values don't display product videos and are only compatible with the `maxHeight`, `hiddenImages`, `zoomFactor`, `aspectRatio`,`ModalZoomElement`, and `zoomMode` props**. | `carousel` | | `displayThumbnailsArrows` | `boolean` | Displays navigation arrows on the thumbnail media (if there are enough thumbnails for them to scroll). | `false` | -| `hiddenImages` | `string` | Hides images whose labels match the values listed in this prop. Intended to be used with the `product-summary-sku-selector` block. To learn more, please read the [SKU Selector](https://developers.vtex.com/docs/apps/vtex.store-components/skuselector) documentation. | `skuvariation` | +| `hiddenImages` | `string` | Hides images whose labels match the values listed in this prop. Intended to be used with the `product-summary-sku-selector` block. To learn more, see the [SKU Selector](https://developers.vtex.com/docs/apps/vtex.store-components/skuselector) documentation. | `skuvariation` | | `maxHeight` | `number` | Maximum height for individual product images (in pixels). | `600` | -| `ModalZoom` | `block` | Opens a modal for product image zooming. This prop value must match the name of the block responsible for triggering the modal containing the product image for zooming (e.g., `modal-layout` from [Modal layout](https://developers.vtex.com/apps/vtex.modal-layout) app). Please note that the `ModalZoom` prop will only work if the `zoomMode` prop is set as `open-modal`. To learn more, please see the [Advanced Configuration section](#Advanced-Configuration). | `undefined` | +| `ModalZoom` | `block` | Opens a modal for product image zooming. This prop value must match the name of the block responsible for triggering the modal containing the product image for zooming (for example, `modal-layout` from [Modal layout](https://developers.vtex.com/apps/vtex.modal-layout) app). The `ModalZoom` prop will only work if the `zoomMode` prop is set as `open-modal`. To learn more, see the [Advanced Configuration section](#Advanced-Configuration). | `undefined` | | `placeholder` | `string` | Sets the URL for a placeholder image to be used if there is no available image or video of the product. | `undefined` | -| `position` | `enum` | Sets the position of the thumbnails (`left` or `right`). Only used when `thumbnailsOrientation` is `vertical` | `left` | +| `position` | `enum` | Sets the position of the thumbnails (`left` or `right`). Only used when `thumbnailsOrientation` is `vertical`. | `left` | | `showNavigationArrows` | `boolean` | Defines if the navigation arrows should be displayed. | `true` | | `showPaginationDots` | `boolean` | Defines if the pagination dots should be displayed. -| `showImageLabel` | `boolean` | Controls if the image label text should be rendered above each image | `true` | +| `showImageLabel` | `boolean` | Controls if the image label text should be rendered above each image. | `true` | | `thumbnailVisibility` | `visible` or `hidden` | Defines if the thumbnails should be displayed in `carousel` displayMode. | `visible` | -| `thumbnailAspectRatio` | `string` | Sets the aspect ratio of the thumbnail image. For more information about aspect ratio, check out the `aspectRatio` prop | `"auto"` | +| `thumbnailAspectRatio` | `string` | Sets the aspect ratio of the thumbnail image. For more information about aspect ratio, check out the `aspectRatio` prop. | `"auto"` | | `thumbnailMaxHeight` | `number` | Maximum height of the thumbnail image (in pixels). | `150` | | `thumbnailsOrientation` | `enum` | Defines the orientation of the thumbnails. It can be `vertical` or `horizontal`. | `vertical` | -| `zoomFactor` | `number` | Sets how much the zoom increases the image size (e.g. `2` will make the zoomed-in image twice as large) | 2 | +| `zoomFactor` | `number` | Sets how much the zoom increases the image size (for example, `2` will make the zoomed-in image twice as large). | 2 | | `zoomMode` | `enum` | Defines the image zoom behavior. Possible values are: `disabled` (zoom is disabled), `in-place-click` (zoom is triggered when the image is clicked), `in-place-hover` (zoom is triggered when the image is hovered on), and `open-modal` (image is zoomed using a modal). | `in-place-click` | ### Advanced configuration -In this section, you will learn how to use modal zoom, a property for when you want to open a popup containing a product image for zooming. To use this feature, configure your `product-images` block using the `zoomMode` and `ModalZoom` props with `open-modal` and `modal-layout` set as its values, respectively. +In this section, you will learn how to use modal zoom, a property that allows you to open a popup displaying a product image for zooming purposes. To use this feature, configure your `product-images` block by setting the `zoomMode` and `ModalZoom` props to `open-modal` and `modal-layout` respectively. -When configured as explained, the `zoomMode` prop allows the trigger of a modal for image zooming. In addition to that, the `MozalZoom` prop will render the block defined as its value. In this case, the `modal-layout` is required. This way, **you will be able to configure a modal containing the product image for zooming**. +When configured as explained, the `zoomMode` prop allows the trigger of a modal for image zooming. Additionally, the `MozalZoom` prop will render the block defined as its value. In this case, the `modal-layout` is required. This allows you to configure a modal containing the product image for zooming. Once both props are correctly configured, you must declare the `modal-layout` block and the `product-images.high-quality-image` block as its child. @@ -108,17 +121,17 @@ For example: } ``` -Please note that the `product-images.high-quality-image` block must be declared as a child of `modal-layout`. You can also declare other blocks exported by the [Modal Layout app](https://developers.vtex.com/docs/apps/vtex.modal-layout) as children. +The `product-images.high-quality-image` block must be declared as a child of `modal-layout`. You can also declare other blocks exported by the [Modal Layout app](https://developers.vtex.com/docs/apps/vtex.modal-layout) as children. The following table shows the props allowed by `product-images.high-quality-image`: | Prop name | Type | Description | Default value | | ------------- | ---------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------- | -| `aspectRatio` | `string` | Defines the aspect ratio of the image; whether the image should be square, portrait, landscape, etc. The value should follow the \[common aspect ratio notation\](https://en.wikipedia.org/wiki/Aspect_ratio_(image) i.e., two numbers separated by a colon such as `1:1` for square, `3:4` for upright portrait, or `1920:1080` for even large values). | `auto` | +| `aspectRatio` | `string` | Sets the image's aspect ratio, determining whether it should be square, portrait, landscape, etc. Follow the [common aspect ratio notation](https://en.wikipedia.org/wiki/Aspect_ratio_(image)), represented by two numbers separated by a colon, such as `1:1` for square, `3:4` for portrait, or `1920:1080` for widescreen. | `auto` | | `defaultSize` | `number` | Image default size (in `px`). | `1200` | | `imageSizes` | `[number]` | Image size(s) (in `px`) to be used in the image [`srcset` HTML attribute](https://developer.mozilla.org/en-US/docs/Learn/HTML/Multimedia_and_embedding/Responsive_images). If no value is defined for this prop, the `srcset` will use the original image size. | `undefined` | -| `maxSize` | `number` | Image maximum size (in `px`) for rendering, regardless of the screen size. Please note that this prop only works if you also declare the `imageSizes` prop. | `4096` | -| `zoomFactor` | `number` | Defines how much the zoom increases the image size (e.g. `2` will make the zoomed-in image twice as large). | `2` | +| `maxSize` | `number` | Image maximum size (in `px`) for rendering, regardless of the screen size. This prop only works if you also declare the `imageSizes` prop. | `4096` | +| `zoomFactor` | `number` | Defines how much the zoom increases the image size (for example, `2` will make the zoomed-in image twice as large). | `2` | | `zoomMode` | `enum` | Defines the zoom behavior for the `product-images.high-quality-image` block. Possible values are: `disabled` (zoom is disabled), `in-place-click` (zoom is triggered when the image is clicked), and `in-place-hover` (zoom is triggered when the image is hovered on). Unlike the `store-images` prop, this one does not accept the `open-modal` value. | `disabled` | ## Customization