Product Images

Product images are images which are shown in a product list and/or on a product details page, hopefully inspiring website visitors to buy the product (Figure 1.1).

Figure 1.1 Product images in frontend

Of course, how exactly the images are rendered in frontend depends on the implementation and design; a subject out of scope for this article, where I will only deal with the different ways you can associate products with images in Dynamicweb.

In Dynamicweb, there are three ways to match an image with product images:

  1. Add images to three fields in the Product Images section on a product – Small, Medium, Large. This method is being deprecated.
  2. Add images in the Documents & Files section on a product – this method is used by Dynamicweb PIM
  3. Assign images to a product using image patterns. This can be done in several locations, some of which are also being deprecated.

The first method – the Product Images fields – is being deprecated and should not be used for new projects. It is described below for the sake of completeness, and because it is still used on many older solutions.

This method for adding images to a product is being deprecated – we do not recommend using it for new projects if you can avoid it, and you should consider converting older solutions to a more modern approach.

The Product Images section on a product card contains three standard fields – called Small, Medium, and Large – for adding images to a product (Figure 2.2). 

Figure 2.2 The Small/Medium/Large product image fields

The images added are then available in frontend via template tags in the relevant templates.

The Small, Medium, Large field can also be assigned images in the following manner:

  • Via the Small, Medium, and Large Image Patterns defined at the warehouse, shop, or product catalog app level
  • Via default images - a kind of fallback image set in Settings > Ecommerce > Advanced configuration > Images

As an alternative to the Small, Medium, Large product fields you can use the Details – Images/Links section to add as many images to a product as you want to, and to mark one of them as the Default image (Figure 3.1).

Figure 3.1 The Details - Images/Links section

As usual, the images added to a product are available in frontend using template tags, with a special tag available for the Default image.

This method is tightly integrated with image handling in Dynamicweb PIM, so all projects with a PIM component are advised to use this method in frontend.

The third option for matching products and images is using Images Patterns – also sometimes known as alt. images. Image patterns automatically assign images to a product based on one or more patterns – e.g. /{ProductNumber_Small.png) and a folder where the images must be located. As such, image patterns presuppose that images are named consistently and in a way which can be tied to the product, e.g. using the product number or an external ID.

There are two types of image patterns:

  • Small/Medium/Large Image patterns assign images to the Small, Medium, Large product image fields described above
  • Alternative image patterns assign images to no particular field, but create template tags in frontend when they are defined.

Image Patterns can be defined in several places, with the more specific pattern available being used:

  • If the Small, Medium, Large images are set, or if a Details – Images/Links image is set as the Default image, they will be used
  • If none are set, the image patterns defined on the product catalog app will be used
  • If none are set, the image patterns defined on the shop will be used
  • If none are set, the image pattern defined in Settings > Ecommerce > Advanced configuration > Images will be used

An image pattern can also be set on a warehouse in PIM, but there is no relation between this image pattern and the ones used for frontend.

To define image patterns:

  • Open the product catalog app or shop/warehouse settings
  • Check the Use alt. images checkbox (Figure 4.1)
  • Specify a folder in which the images are located – if relevant, check Search in subfolders
  • Define one or more file name patterns – if this is on a Shop, you can set one of the patterns to be the Default pattern. This will not take effect unless you deprecate the Small/Medium/Large fields & related features – see more below.
Figure 4.1 Image patterns

Patterns can be constructed from the following product fields:





















VariantOptionLevel {VariantOptionLevel1}.jpg

Retrieves the name of the variant option added to the product.

If you e.g have colors as 1. level variants (Orange, Green, Blue) they are OptionLevel1.

If you also have sizes as variants (Large, Medium, Small, they are OptionLevel2.

ProductEAN {ProductEAN}.jpg  
Custom product fields {ProductFieldSystemName}.jpg Please note that only product fields are supported, not product category fields or product group fields.

Please note:

  • Fields can be combined in any way you like, e.g. {ProductNumber}-{ProductManufacturer}.png
  • Wildcards are not supported - this is for performance reasons
  • In image pattern field can contain 2 patterns separated by semicolon, e.g. /{ProductNumber}{VariantOptionIdLevel1}.jpg;/{ProductNumber}jpg
  • If more than one image matches a pattern the first one in alphabetical order till be used
  • Image patterns may be extended by implementing a class inheriting from ImagePatternExtenderBase

Improved image patterns

Dynamicweb 9.7 introduced a new and faster version of the Image Pattern feature, with new template tags and explicit fallback logic. Like their counterparts, improved image patterns can be built on all standard product fields – but also custom product fields, which makes the new implementation much more flexible.

This implementation is not backwards compatible with older versions of Dynamicweb – specifically because it changes the tags used to retrieve images in templates. You can, of course, easily convert your templates to use the new tags.

To toggle improved image patterns:

  • Go to Settings > Ecommerce > Advanced Configuration > Images
  • Check Improved image patters (Figure 5.1)

So, what happens when you toggle improved image patterns? Well…

  • The Deprecate Small, Medium and Large image features checkbox is checked – read more about the effects below
  • The Default property is removed from all image patterns – not related to the Default property on details images used by PIM
  • Two new image patterns – Main product and Variant product – are made available. New tags for these are added, including a new tag MasterOrVariant which renders the image from the Master product image pattern when a main product is shown, the Variant product image if a variant is being shows, unless there is no variant product in which case the Master product image is used.
  • A number of old image tags are deprecated – specifically Ecom:Product.ImageLarge.Clean, Ecom:Product.ImageDefault, Ecom:Product.ImageDefault.Default.Clean, and Ecom:Product.Image{PatternName}.Clean

While we strongly recommend converting your templates to use the new tags, a compatibility mode is available until this process has been finalized. This mode fills the old deprecated image tags with values from the new image patterns.

The Enable caching checkbox is checked by default – this should only be changed temporarily for debugging purposes, as it has a significant impact on performance.

Figure 5.1 Toggling improved image patterns

In an effort to consolidate how images are handled, Dynamicweb 9.6 introduced the option of permanently converting your existing solution to use the image features which will continue to be developed in the future.

The essence is very simple:

  • The Small/Medium/Large fields on products are being deprecated, alongside all related feaures, e.g. the Small/Medium/Large image patterns
  • Image Patterns will only be defined at the shop/warehouse level in the future, and not from the product catalog or elsewhere, and the Width and Height properties are removed

Converting a solution is a multi-step process:

  1. Ensure that the solution is not dependent on different image patterns at the product catalog level – if it is, stop and reevaluate
  2. Transfer any image patterns which are in use at the product catalog level to the shop level
  3. If the Small/Medium/Large image patterns are in use at the shop level, open the shop settings and convert them to alternative image patterns (Figure 6.1) – if Large has a value it will be marked as the Default pattern, if not Medium will be set as the Default, else Small.
Figure 6.1 Converting from old image features

After moving and/or converting existing patterns, go to Settings > Ecommerce > Advanced configuration > Images and check Deprecate Small, Medium and Large image features then save (Figure 6.2).

Figure 6.2 Deprecating old image features

The following happens when you deprecate Small/Medium/Large and related features:

  • At the shop/warehouse level, the Small/Medium/Large image patterns are removed alongside the Convert button
  • In the product catalog settings the alt. images section is removed completely
  • Width & Height are removed as properties for alternative image patterns everywhere
  • The Small/Medium/Large image fields are removed from both Ecommerce and PIM
  • On the Settings > Ecommerce > Advanced configuration > Images page:
    • The Small/Medium/Large default image fields are removed
    • The fallback image pattern is removed
    • The auto-scale settings are removed
  • All template tags related to Small/Medium/Large will stop rendering in frontend