Back in the days when the DNN imagehandler was integrated in the core I wrote this documentation about the features. This documentation was attached to the JIRA support case but thats not a place where a developer or user will look after the options and possibilities so I decided to post it as a blog here on dnnsoftware.com. I'm not sure that all options are still working in the latest version but I think that not much has changed in the meantime. Hope you find it useful!
DnnImageHandler Documentation
Enabling the image handler functionality is done by an additional statement in the system.webServer/handlers section of web.config:
<add name="DnnImageHandler"
path="DnnImageHandler.ashx"
verb="*"
type="DotNetNuke.Services.GeneratedImage.DnnImageHandler, DotNetNuke"
preCondition="integratedMode" />
The image handler could be used if you enter the following image url:
http://mydomain.com/dnnimagehandler.ashx?mode=xyz¶m1=value1¶m2=value2...
There are a few modes defined:
- profilepic – shows the profile picture to a given userid (if allowed) or a generic “no avatar” image
- file – shows an image by given filename with path or url
- securefile – shows the image by a given fileid (if allowed). If no image format shows filetype icon instead
- placeholder – shows a rectangle with image dimensions or text on it
These “modes” are generating an image. The generated image could be modified by additional parameters. Available modifications are:
- Resize – defining the dimension of the resulting image with different resize modes, Adding borders and colored background
- Format – define the resulting format of the generated image (jpg, png…)
- Gamma – adjust the gamma value
- Brightness – adjust the brightness value
- Contrast – adjust the contrast value
- Greyscale – convert to greyscale image
- Invert – convert to negative image
- Rotate + Flip – rotate and / or flip the image
No Image
The query string parameter NoImage allow the user to specify a file path of an image file that we want to be served in case the image handling cannot be done (i.e.: try to display a securefile for that I do not have access as a specific user).
If the query string NoImage is not provided a 1x1 pixel transparent image will be served by the system. The file path is limited to the following folders (and its subfolders)
- DesktopModules
- Portals
- Images
Mode: Profilepic
The profilepic mode shows the profile picture to a given userid (if allowed) or a generic “no avatar” image. The functionality is the same as the old profilepic.ashx handler.
Parameters:
|
Name
|
Meaning
|
|
userid
|
ID of user whose profile image should be shown. If omitted, the profile pic of the current user is generated. If no user is logged in or the profile pic is not allowed to show, a generic avatar image is generated
|
<img src="/dnnimagehandler.ashx?mode=profilepic&w=120" />
<img src="/dnnimagehandler.ashx?mode=profilepic&userid=2&w=120" />
Mode: File
The file mode shows an image by given filename with path or url or filepath and index (alphabetical order)
Parameters:
|
Name
|
Meaning
|
|
file
|
Relative path to the file incl. filename, eg: /Portals/0/images/myimage.gif
|
Note: for security reason the file path provided in the query string is limited to the following folders (and its subfolders):
- DesktopModules
- Portals
- Images
or:
|
Name
|
Meaning
|
|
url
|
Url to image (url-encoded), eg: http%3A%2F%2Fwww.indisoftware.de%2FPortals%2F0%2Findilogo.png
|
<img src="/dnnimagehandler.ashx?mode=file&file=Portals/0/Images/icon-qa.png&size=xs" />
<img src="/dnnimagehandler.ashx?mode=file&url=http%3A%2F%2Fwww.indisoftware.de%2FPortals%2F0%2Findilogo.png" />
Mode: Securefile
The securefile mode shows the image by a given fileid (if allowed). If no image format shows filetype icon instead
Parameters:
|
Name
|
Meaning
|
|
fileid
|
Shows the image with the given fileid if the logged user has the view permission for this file. If the file is no image file, an icon is generated instead (from file _icons/Sigma/ext%EXTENSION%32x32_standard.png)
|
<img src="/dnnimagehandler.ashx?mode=securefile&fileid=100" /> (skin.css)
<img src="/dnnimagehandler.ashx?mode=securefile&fileid=101" /> (1-icn.png)
Mode: Placeholder
The placeholder mode shows a rectangle with image dimensions or text on it
Parameters:
|
Name
|
Meaning
|
|
w
|
Width in pixel
|
|
h
|
Height in pixel
|
|
color
|
Foreground color
|
|
backcolor
|
Background color
|
|
text
|
Text to display on image. If omitted, dimensions are shown
|
<img src="/dnnimagehandler.ashx?mode=placeholder&w=150&h=100&text=plugin-modul" />
<img src="/dnnimagehandler.ashx?mode=placeholder&w=150&h=100&color=yellow&backcolor=green" />
Additional Mode Extensions
The modes are extensible! If a developer writes a dll containing a class (for example: PercentTransform) derived from
DotNetNuke.Services.GeneratedImage.ImageTransform
with a public property named “value” where he creates a percentage circle like this:
and copy this dll to the DNN bin folder and also adds an entry to the AppSettings section of web.config like this:
<add key="DnnImageHandler.Percent" value="MyNamespace.PercentTransform, NameOfMyDll" />
(s)he is able to invoke the imagehandler with an URL syntax like this:
http://mydomain.com/DnnImagehandler.ashx?mode=percent&value=30
My github project BBImageHandler-8 includes a bunch of these extensions (e.g. Barcodes, Images from Database etc.), so if you are interested in creating your own imagehandler extension this would be a good starting point to look at!
Filter:Resize
Defining the dimension of the resulting image with different resize modes, Adding borders and colored background.
Parameters:
|
Name
|
Meaning
|
|
w
|
Width of Image
|
|
h
|
Height of Image
|
|
size
|
Predefined size of image: xxs: 16x16, xs:32x32, s:50x50, l:64x64, xl:128x128, xxl:256x256
|
|
maxwidth
|
Instead of Width this can be used to leave the picture as it is until the width reaches the max value.
|
|
maxheight
|
Instead of Height this can be used to leave the picture as it is until the height reaches the max value.
|
|
resizemode
|
- fit mode maintains the aspect ratio of the original image while ensuring that the dimensions of the result do not exceed the maximum values for the resize transformation. (Needs width or height parameter)
- fitsquare resizes the image with the given width as its longest side (depending on image direction) and maintains the aspect ratio. The image will be centered in a square area of the chosen background color (Needs width parameter, backcolor optional)
- crop resizes the image and removes parts of it to ensure that the dimensions of the result are exactly as specified by the transformation.(Needs width and height parameter)
- fill resizes the image with the given width or height without maintaing the aspect ratio.
|
|
backcolor
|
color of background or/and border when resizemode is fitsquare or fit
|
|
border
|
border width in pixels around the image (added to width / height) when resizemode is fitsquare or fit.
|
<img src="/dnnimagehandler.ashx?mode=profilepic&userid=2&size=xl&backcolor=%23F58719&border=10" />
<img src="/dnnimagehandler.ashx?mode=file&file=Portals/0/Images/icon-qa.png&h=128&w=40&resizemode=fill" />
Filter:Gamma
Adjusting the gamma value
Parameters:
|
Name
|
Meaning
|
|
gamma
|
Value for gamma adjustment between 0.2 and 5
|
<img src="/dnnimagehandler.ashx?mode=profilepic&userid=2&size=xl&gamma=4"/>
Filter:Brightness
Adjusting the brightness value
Parameters:
|
Name
|
Meaning
|
|
brightness
|
Value for brightness adjustment between -255 and +255
|
<img src="/dnnimagehandler.ashx?mode=profilepic&userid=2&size=xl&brightness=128" />
Filter: Contrast
Adjusting the contrast value
Parameters:
|
Name
|
Meaning
|
|
contrast
|
Value for contrast adjustment between -100 and +100
|
<img src="/dnnimagehandler.ashx?mode=profilepic&userid=2&size=xl&contrast=75" />
Filter: Greyscale
Convert image to greyscale
Parameters:
|
Name
|
Meaning
|
|
greyscale
|
If present, image is converted to greyscale (needs dummy value, e.g “1”)
|
<img src="/dnnimagehandler.ashx?mode=profilepic&userid=2&size=xl&greyscale=1" >
Filter: Invert
Converts an image to its negative representation
Parameters:
|
Name
|
Meaning
|
|
invert
|
If present, image is inverted (needs dummy value, e.g “1”)
|
<img src="/dnnimagehandler.ashx?mode=profilepic&userid=2&size=xl&invert=1" />
Filter: Rotateflip
Rotates and / or flips the image
Parameters:
|
Name
|
Meaning
|
|
rotateflip
|
RotateNoneFlipNone: Specifies no clockwise rotation and no flipping.
Rotate90FlipNone: Specifies a 90-degree clockwise rotation without flipping.
Rotate180FlipNone: Specifies a 180-degree clockwise rotation without flipping.
Rotate270FlipNone: Specifies a 270-degree clockwise rotation without flipping.
RotateNoneFlipX: Specifies no clockwise rotation followed by a horizontal flip.
Rotate90FlipX: Specifies a 90-degree clockwise rotation followed by a horizontal flip.
Rotate180FlipX: Specifies a 180-degree clockwise rotation followed by a horizontal flip.
Rotate270FlipX: Specifies a 270-degree clockwise rotation followed by a horizontal flip.
RotateNoneFlipY: Specifies no clockwise rotation followed by a vertical flip.
Rotate90FlipY: Specifies a 90-degree clockwise rotation followed by a vertical flip.
Rotate180FlipY: Specifies a 180-degree clockwise rotation followed by a vertical flip.
Rotate270FlipY: Specifies a 270-degree clockwise rotation followed by a vertical flip.
RotateNoneFlipXY: Specifies no clockwise rotation followed by a horizontal and vertical flip.
Rotate90FlipXY: Specifies a 90-degree clockwise rotation followed by a horizontal and vertical flip.
Rotate180FlipXY: Specifies a 180-degree clockwise rotation followed by a horizontal and vertical flip.
Rotate270FlipXY: Specifies a 270-degree clockwise rotation followed by a horizontal and vertical flip.
|
<img src="/dnnimagehandler.ashx?mode=profilepic&userid=2&size=xl&rotateflip=Rotate90FlipY" />
<img src="/dnnimagehandler.ashx?mode=profilepic&userid=2&size=xl&rotateflip=RotateNoneFlipY" />
<img src="/dnnimagehandler.ashx?mode=profilepic&userid=2&size=xl&rotateflip=RotateNoneFlipX" />
Configuration
There are a few options for the imagehandler that could be set up via configuration in web.config. You could set your options in appSettings-section:
<add key="DnnImageHandler" value="EnableIpCount=false;AllowStandalone=false;LogSecurity=true;AllowedDomains=mydomain.com,otherdomain.net;EnableServerCache=true;EnableClientCache=true;" />
The following options are available :
|
Name
|
Meaning
|
|
EnableIpCount
|
Default: true. If true, every generation of an image will be counted. If IPCountMax is hit no more images are generated until IPCountPurgeInterval is up. Physically there is a file in _App_Data/ipcount for every IP containing the number of hits. When IPCountPurgeInterval is over, this file is deleted.
|
|
IpCountMax
|
Default: 50. Max number of hits from an IP allowed in defined time span IPCountPurgeInterval
|
|
IPCountPurgeInterval
|
Default: 300. Seconds for measuring the hits from one IP.
|
|
EnableServerCache
|
Default: true. Enables the server side caching of images in folder _App_Data/images
|
|
ServerCacheExpiration
|
Default: 180. Seconds until the image is deleted from image cache folder and generated again.
|
|
EnableClientCache
|
Default: true. Enables the client side caching of images (answering with 304 http response until ClientCacheExpiration is reached)
|
|
ClientCacheExpiration
|
Default: 600. Seconds caching the image on client site.
|
|
AllowStandAlone
|
Default: false. If true, Images could be shown standalone via image url. If false, only images integrated in a web page (referrer is not null) are shown, others return 403 (forbidden) http status code.
|
|
LogSecurity
|
Default: false. If true, hitting IPCountMax or AllowStandalone bounderies produce an eventlog entry
|
|
AllowedDomains
|
Default: empty string. By default, all websites are allowed as referrer. Include here a comma-separated list of domains to restrict the embedding of your images to pages from these domains (e.g. mydomain.com,myotherdomain.net )
|
|
ImageCompression
|
Default: 95. Set the image generation quality. Range is from 0 to 100.
|