Image Handler

The Dynamicweb Image Handler – GetImage.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

Pdf is for generating pdfs from text files, not for handling images.

 

Using GIF adds a Colors parameter which controls the number of colors used in the gif – value can be 1-256

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

 

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.

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 2.1).

Figure 2.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.