dcm.GalleryWidget

The <dcm.GalleryWidget> tag provides a CMS ready approach to displaying one or more images in a grid like layout.

Attributes

ExpandVariant: if specified, is the variant to use when displaying a larger version of the image in the grid. See usage notes below.
Extension: defaults to jpg can be set to png or gif as appropriate
Max: max images to show from the image list or show.
Path: path to the gallery folder, the /galleries is assumed, so / is the root gallery folder.
PropertyEditor: the path to a custom property editor, used in CMS mode to edit the properties of an Image child.
Show: name of the show (found in the meta.json file, in the gallery folder - see Path above) to use as the source of the image list. See usage notes to compare Show use vs Image use. Show is not recommended for most usages.
Size: the grid size to use for each image, based on the grid system which would typically be “1-2”, “1-3”, “1-4”, etc. See a list of the supported and custom sizes.
Variant: which variant of the image to use, defaults to full ;

Special Children

Template: template for the image, the code contained within is repeated for each image in the list or in the the show. Template may contain advanced instructions, including conditional logic.
Image: each Image child has an Alias attribute connecting it to an image name in the gallery folder. An Image child may have other attributes that contain data specific to that show, those attributes are determined by the developer when they add the control to the page. Common examples would be Title, Name, and Description.

Usage Notes

Template

In the simplest usage a template contains an img pointing to the path contained in $_Image.Path and wrapped in a div that links to the image alias (folder name) from $_Image.Alias .

<Template>
    <div data-dcm-alias="{$_Image.Alias}">
        <img src="{$_Image.Path}" class="pure-img" />
    </div>
</Template>

The template is cloned for each image in the gallery and the variables are replaced with the current $_Image values.

Alternative options including using the either an ImageWidget instead of an img tag:

<Template>
    <div data-dcm-alias="{$_Image.Alias}">
            <dcm.ImageWidget Path="{$Image.BasePath}" Description="{$Image.Element.attributes.Description}" class="pure-img" />
    </div>
</Template>

or using a special dc.ImgCache tag that has built in references to path

<Template>
    <div data-dcm-alias="{$_Image.Alias}">
            <dc.ImgCache class="pure-img" />
    </div>
</Template>

Learn more about templates and variables can be used when building a gallery.

Shows vs Inline (Standard)

The inline approach is compatible with the preview feature of the CMS and is simpler to code, it is strongly preferred over the shows approach. The latter loads the list of images to display from a meta.json file in the CMS Gallery. The former lists the images right in the code as child elements of the widget. Details of these approaches are given below.

Slider

This widget pairs well with the dcm.SliderWidget if you are looking for a way to pair a list of thumbs with a single larger image that is connected to that thumbs list (and with left/right controls to cycle through that list).

Inline Approach

In this approach the widget contains Image children as a way to indicate which images to display in the gallery. Images are displayed in the order that the Image tags appear. It does not matter where the Image tag appears relative to the Template child, but it must be a peer to the Template (not inside).

A basic example:

<dcm.GalleryWidget Path="/examples/simple/board" Size="1-4">
    <Template>
        <div data-dcm-alias="{$_Image.Alias}">
            <dc.ImgCache class="pure-img" />
        </div>
    </Template>

    <Image Alias="mac" />
    <Image Alias="lance" />
    <Image Alias="tom" />
    <Image Alias="carrie" />
</dcm.GalleryWidget>

Output:

If 1/4 sizing doesn't work, consult the list of the supported and custom sizes. . For example if you need each image to always display at 450px wide, which is a custom size, and for there to be automatic spacing between the images, then create a rule like so:

.pure-u-Custom450 {
    width: 450px;
}

.even-content {
    justify-content: space-evenly;
}

And then switch the size attribute and add a class:

<dcm.GalleryWidget Path="/examples/simple/board" Size="Custom450" class="even-content">

Output:

It is common to assign a link and title to images in a gallery.

<dcm.GalleryWidget Path="/examples/simple/board" Size="1-4" class="board-gallery">
    <Template>
        <div data-dcm-alias="{$_Image.Alias}" class="board-item">
            <dc.Link Page="/board/{$_Image.Alias}" class="board-link">
                <dc.ImgCache class="pure-img board-image" />
                <div class="board-name">
                    {$_Image.Element.@Title}
                </div>
            </dc.Link>
        </div>
    </Template>

    <Image Alias="mac" Title="Mac" />
    <Image Alias="lance" Title="Lance" />
    <Image Alias="tom" Title="Tom" />
    <Image Alias="carrie" Title="Carrie" />
</dcm.GalleryWidget>

The additions above are:

each Image tag now has a Title. Title and Description attributes are supported by default, please use these when reasonable to do so.
many classes where added in the form of “board-NNNNN” which are not necessary for the example but demonstrates good practice, it is now easier for someone to add styling to any of these layers.
the Title from the image now displays under the image because $_Image.Element points to the Image element (tag).

Output:

Learn more about template and variable usage.

Property Editor

TODO how to use this

Show Usage

Instead of using Image Children in the gallery, the gallery gets its list of images from a Gallery Show instead. Some information can be found on Shows in the dcm.CarouselWidget and some in the examples further below. We recommend the CMS Oriented approach above, so no further information will be provided about the Shows usage beyond the example.

TODO link to deeper resources on Shows

Examples

<dcm.GalleryWidget Path="/about/doctors" Show="main" Size="1-3" class="dc-layout-row-pad-large dc-layout-collapse-medium">
    <Template>
        <div class="dc-layout-pad-large">
            <div class="dc-widget dc-widget-image dc-media-box dc-media-image">
                <dc.ImgCache class="pure-img-inline" alt="{$_Image.Data.Title}" />
            </div>

            <div class="doctorName white">
                <p>
                    <dc.Link Label="{$_Image.Data.Title}" Page="/about-us/doctors/{$_Image.Data.Slug}" />
                </p>
            </div>
        </div>
    </Template>
</dcm.GalleryWidget>

Property Editor

TODO how to use this with shows