dcm.ImageWidget

The <dcm.ImageWidget> tag provides a CMS-ready approach to displaying an image.

Attributes

  • Path: path to the image folder, the /galleries is assumed, so / is the root gallery folder. Do not include the .v from the image folder, so if the folder is at /home/icon-1.v the Path would be /home/icon-1 .

  • Variant: which variant of the image to use, defaults to full ;

  • Extension: which file extension of the image to use, defaults to jpg ;

  • Display: set to “Banner” if displaying in banner mode

  • Centering: used with banner mode, set to “true” if you want the banner centered

  • CenterHint: used with banner mode, set to the centered width in the image - for example on a 2000 wide image, if the principle interest is at 300 then a browser at 320 width will show (approximately) the pixels from 140 to 460 with 300 at the center. This defaults to the image center.

  • Description: override the Description from the image's meta.json file (for alt text)

  • ExpandVariant: combined with the default template (or a proper custom template) this allows the user to click on an image and see a larger variant of the same image. Suggest use of large variant - CMS knows that large is bigger than full .

  • SEOPath: a Boolean attribute which determines how the image URL is finally rendered. Setting to True allows SEO to get a meaningful name assigned to the core image file.

    • example when set to True : root-domain/galleries/horizontal-paired-images/placeholder-1.jpg?dc-cache=20240430T160608239Z&dc-variant=full
    • example when set to False : root-domain/galleries/horizontal-paired-images/placeholder-1.v/full.jpg?dc-cache=20240430T160608239Z

  • Sizes: TODO explain - good for slow networks/mobile

  • ResponsiveVariants: TODO explain - good for slow networks/mobile

Usage Notes

When not in banner mode (see Display attribute) then an image automatically sizes to the space it is placed in and does not exceed the screen width nor the container it is placed in. When in banner mode the image will be centered around a hint and will have a minimal height - see examples below.

The image template is a very important, and significantly large, topic that it is handled separately. Please review the image templating page.

TODO how expand mode works with templates.

Examples

Be sure to also review how image templates work, see above.

<dcm.ImageWidget Path="/examples/one/rock" />

This example would display this image: /galleries/examples/one/rock.v/full.jpg because the Extension and the Variant have both defaulted. Those can be overridden though (see attributes). And note that /galleries is automatically added.

Here is that code output:

An image can be easily made into a banner as well, banners are designed so that they never get t0o short - always have a minimal height for readability. The result is that an image will be clipped on the left and right on a smaller screen. Minimally set the Display to Banner and add a CenterHint to work with this.

<dcm.ImageWidget Path="/examples/one/rock" Display="Banner" CenterHint="200" class="rock-pict" />

Each banner also needs some height information (current, min, max), like so:

.dcm-widget-banner.rock-pict { height: 400px; height: 33.33vw; max-height: 400px; min-height: 280px; overflow: hidden; }

The max-height would usually match the actual height of the image, the min would be the shortest you ever want it to go. The height needs to be set in vw units as a proportion to the width of the image. This image (gallery) is for 1200 x 400 images so the proportion is 1/3 or 33.33% - use at least two decimal places or the image may not fill in fully in mobile mode.

Here is the output for the banner, please review it at smaller screen widths and compare how it handles to the non-banner mode image above.

See Also