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.:
<img src='/Admin/Public/GetImage.ashx?Image=image.jpg&Crop=0&Format=jpg&Height=145&Compression=75'>
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.
Parameters
The following parameters can be used with the image handler service:
| Parameter | Value | Notes |
|---|---|---|
| Image | A path to an image file in the file manager – written or retrieved using a template tag. | Required |
| 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 |
| Width | 1-99999 | Required |
| Height | 1-99999 | Required |
| ColorSpace | RGB, CMYK or Grayscale | RGB is default |
| 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 | |
| Format | Jpg, gif, png, tiff, bmp, psd, pdf, webP | See section below for more information |
| Compression | 1-99 | Only for .jpg output. 1 is lowest quality, 99 best |
| Quality | 1-99 | Only for WebP images - default is 50, which is quite low, so please use a specific value -1 = lossless compression |
| Resolution | 72-300 | DPI |
| 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. |
| Background | Hex color code | Sets the background color for transparent png’s |
| DoNotUpscale | True/False | If cropmode 5 is used, DoNotUpscale is always set to true - this cannot be overridden. |
| Filename | A filename with an extension, e.g. MyFancyImage.jpg | |
| ForceDownload | True/False | |
| donotcache | True/False | Bypasses any image cache |
Converting images to other formats
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
- WEBP
The Format parameter is added to the getImage URL like any other parameter, e.g.:
<img src='/Admin/Public/GetImage.ashx?Image=yourimage.jpg&Crop=0&Height=145&Compression=75&Format=webP>
However, some of the formats come with additional parameters and settings:
- JPG adds an additional parameter – Compression – which defaults to 75
- GIF adds an additional parameter – Color – which controls the number of colors used in the generated gif (1-256)
- WebP adds an additional parameter – Quality – which controls the quality level of the generated webP image. The default quality is set to 50
Focal points
Focal points can be set on images using the standard image selector used in the backend. When set, focal point coordinates are available in frontend and can be passed to the image handler:
<img src='/Admin/Public/GetImage.ashx?Image=@Model.Image&Crop=0&Format=jpg&Height=145&Compression=75&x=@Model.ImageFocalX&y=@Model.ImageFocalY' alt="">
Focal points are used by all crop modes except crop mode 5 – Keep aspect ratio.