Image Handler

The Dynamicweb Image HandlerGetImage.ashx – is a tool for generating images dynamically based on a source file located in the file archive. This eliminates the need for generating thumbnails or resizing images manually or automatically from the file manager.

The image handler is used by calling GetImage.ashx directly in a template with a set of relevant parameters, e.g.:

HTML
<img src='/Admin/Public/GetImage.ashx?Image=@product.GetString("Ecom:Product.ImageDefault")&Crop=0&Format=jpg&Height=145&Compression=75' alt="">

Based on these parameters, an image is generated and stored in the /Files/Cache/Images folder, from where it is served until the cache is invalidated and a new image is generated.

To help you familiarize yourself with the Image handler a graphical tool – the Image Handler tool – is available from Settings > Developer > Image Handler (Figure 1.2).

Figure 1.2 The Image Handler tool

Using this tool, you can try out different parameter combinations and generate an URL and a preview image. 

The following parameters can be set – please note that the parameter name may not match the Image Handler UI name:

#

Parameter

Value

Notes

1

Image

A path to an image file in the file manager – written or retrieved using a template tag.

Required

2

AlternativeImage

A path to an image file

If the primary image does not exist, the image specified here will be shown instead.

 

Can also be specified using the &altFmImage_path= parameter – this is the old parameter

3

Width

1-99999

Required

4

Height

1-99999

Required

5

ColorSpace

RGB, CMYK or Grayscale

RGB is default

6

Crop

Center: 0
From upper left: 1
From lower left: 2
From lower right: 3
From upper right: 4
Keep aspect ratio: 5
Fit image: 6
CenterOrFocal: 7

 

7

Format

Jpg, gif, png, tiff, bmp, psd, pdf, webP

See section below for more information

8

Compression

1-99

Only for .jpg output. 1 is lowest quality, 99 best

9

Resolution

72-300

DPI

10

fillcanvas

True/False

If width and height is specified and the crop mode is set to Keep aspect ratio, the image will be resized to fit in the defined box.

 

If this flag is set, the remainder of the specified view box will be filled with the color specified via the Background parameter.

11

Background

Hex color code

Sets the background color for transparent png’s

12

DoNotUpscale

True/False

If cropmode 5 is used, DoNotUpscale is always set to true - this cannot be overridden.

13

Filename

A filename with an extension, e.g. MyFancyImage.jpg

 

14

ForceDownload

True/False

 

-

donotcache

True/False

Bypasses any image cache – can’t be set from the Image Handler tool

You can also visit www.yoursolution.com/admin/examples/getimagetest.html and examine the testsite we use internally to test the image handler functionality.

The Format parameter is a deceptively simple parameter which allows you to a very cool thing; convert images to other formats on the fly. Currently the following formats are supported:

  • JPEG
  • GIF
  • PNG
  • TIFF
  • BMP
  • PSD
  • PDF
  • WEBP

The Format parameter is added to the getImage URL like any other parameter, e.g.:

HTML
<img src='/Admin/Public/GetImage.ashx?Image=yourimage.jpg&Crop=0&Format=jpg&Height=145&Compression=75&Format=webP>

However, some of the formats come with additional parameters and settings:

  • Using JPG adds an additional parameter – Compression – which defaults to 75
  • Using GIF adds an additional parameter – Color – which controls the number of colors used in the generated gif (1-256)
  • Using WebP adds an additional parameter – Quality – which controls the quality level of the generated webP image. The default quality is set to 50
  • The PDF format is for generating pdf files from text files, not for handling images.

Since support for the WebP format is not yet universal, we check the accept header for an image/webp value before serving a WebP image – if the header is not found, we instead generate and serve a .jpg.

Focal points is an advanced image feature used to crop responsive images intelligently, making sure that the selected focal point is always included in the image shown in frontend.

Focal points can be activated on:

  • All item fields of the type File when used as image selectors
  • All image fields on a standard paragraph – if toggled in the interface settings

When focal points are enabled, you will be able to set a focal point on an image using the curser (Figure 3.1).

Figure 3.1 Setting a focal point

When a focal point has been set, the focal point coordinates are made available in frontend via template tags and ViewModel properties, can can be passed to GetImage:

HTML
<img src='/Admin/Public/GetImage.ashx?Image=@product.GetString("Ecom:Product.ImageDefault")&Crop=0&Format=jpg&Height=145&Compression=75&x=40&y=54' alt="">

Focal points are used by all crop modes except crop mode 5 – Keep aspect ratio.

You can visit www.yoursolution.com/admin/examples/getimagefocaltest.html and examine a couple of examples we use to test focal points internally.

GetImage.ashx supports embedded ICC profiles when files are downloaded, which is essential when working with images for e.g. print media.

Embedding ICC profiles is supported for TIFF and JPEG images only.

To embed an ICC profile in an image generated by the Image Handler, you simply use a set of query string parameters which detail whether to include ICC information, and which profile to use.

Parameter

Function

ICC=true/false

If true, this embeds an ICC profile – defaults to auto

ICCprofile=auto

This profile preserves original color profiles where possible, and is generally faster than using standard because less conversion is done.

ICCprofile=standard

The built-in default color profile will be used – sRGB

ICCprofile=device

The device ColorSpace will be used

ICCprofile=[icm file]

Uses the color profile in a particular ICM file – e.g. AdobeRGB1998.icc – provided that the default color profile folder on the server (\Windows\System32\spool\drivers\color) contains a file of that name

Database

There is no database specific information for this subject.