Click here to Skip to main content
15,117,549 members
Articles / Web Development / ASP.NET
Posted 11 Feb 2007


202 bookmarked

Thumbnail Image Viewer Control for ASP.NET 2.0

Rate me:
Please Sign up or sign in to vote.
4.81/5 (50 votes)
24 May 20075 min read
A thumbnail image viewer control which downloads and displays the full size image in modal form using a floating div and javascript.

Screenshot - ThumbViewerControl1.jpg


Generating thumbnail images and building a user interface for viewing the full size images can be time consuming. Using an HttpHandler to generate thumbnail images at runtime is a well-documented topic in numerous articles. The ThumbViewer control uses this technique, but its main feature is that it has a UI for downloading and viewing fullsize images built into the control.


I originally developed the UI functionality of the ThumbViewer control for viewing photos on my personnal website using JavaScript and HTML. By using embedded resources and adding an HttpHandler, it was quite easy to wrap this up as an ASP.NET control.

Design Objectives

The design objectives of the control:

  • Display a thumbnail image on a web page with a means of requesting the full image.
  • When the user requests the full size image, stream it to the browser and display it.
  • While viewing the full image, the original web page is not closed or does not need to be reloaded when the full image is closed.
  • Display the full image without using a separate browser window.
  • Allow the user to choose which full size images to view without having to view all images in a slideshow type UI.
  • Maximize the size of the full image for the browser window size.

Using the ThumbViewer Control

In the Toolbox in Visual Studio 2005 right-click and select "Choose Items...". On the Choose Toolbox Items dialog click on Browse and select the Bright.Controls.dll assembly. This will add the ThumbViewer control to the toolbox.

Screenshot - ThumbViewerControl2.jpg

To register the ThumbViewer HttpHandler with your application, add the following to the <system.web> section of your web.config. (This step is not necessary if you plan to use your own thumbnail images)

<!-- Register the ThumbViewer HttpHandler -->
      <add verb="GET" path="ThumbHandler.ashx" 

Drag the ThumbViewer control onto a page like any other web control and set its properties.

Screenshot - ThumbViewerControl3.jpg


  • ImageUrl - The URL of the full size image
  • ThumbUrl - The URL of the thumbnail image
  • Title - The Title of the image, this is displayed when viewing the fullsize image
  • ModalDisplayMode - The mode of the modal display, Stretch, Fixed or Disabled
  • ModalImagePadding - The padding of the modal display if ModalDisplayMode is set to Stretch
  • ModalFixedWidth - The width of the modal display if ModalDisplayMode is set to Fixed
  • ModalFixedHeight - The height of the modal display if ModalDisplayMode is set to Fixed

There are several ways to use the ThumbViewer Control to display images.

Here are the options depending on the types of images you want to display

You already have thumbnail images:

  • Set the ImageUrl to the full size image location and set the ThumbUrl to the thumbnail image location.

You don't have thumbnail images:

  • Set the ImageUrl to the full size image location and leave the ThumbUrl property empty, the thumbnail image will be generated at runtime.

You have small images which and you want to display a larger version of the same image:

  • Set the ThumbUrl to the full size image location and leave the ImageUrl property empty.

Here are the ModalDisplayModes for the full size image

Stretch is the default display mode and will utilise the full size of the browser window while keeping the same aspect ratio as the thumbnail image.

The Fixed display mode will display the image to the size specified in the ModalFixedWidth and ModalFixedHeight properties.

The Disabled display mode will not allow the full size image to be viewed.

How it Works

C# Code

The Bright.WebControls assembly contains two classes, ThumbViewer.cs and ThumbHandler.cs. The ThumbViewer.cs class is derived from the System.Web.UI.WebControls.Image control.

Some of the Image properties are overidden:

public override string ImageUrl {}
public override Unit Width {}
public override Unit Height {}

and some custom properties and an enum are added:

public virtual string ThumbUrl {}
public virtual string Title {}
public virtual Unit ModalImagePadding {}
public virtual Unit ModalFixedWidth {}
public virtual Unit ModalFixedHeight {}
public ModalDisplayModeOptions ModalDisplayMode {}

// ModalDisplayModeOptions enum
public enum ModalDisplayModeOptions

The OnInit and some of the Render methods are overidden to setup various aspects of the contol.

protected override void OnInit(EventArgs e)
    // Register Javascript and CSS files as the control is initialised

protected override void Render(HtmlTextWriter writer)
    // Setup up the ImageUrl & ThumbUrl

public override void RenderBeginTag(HtmlTextWriter writer)
    if (!DesignMode)
        // Before the first control, write out the Modal Divs
protected override void AddAttributesToRender(HtmlTextWriter writer)
    if (!DesignMode)
        // Setup the image Attributes

  • OnInit calls SetupIncludes(); which registers the JavaScript and stylesheet resources with the page.
  • Render calls SetupUrls(); which modifies the src of the image as required.
  • RenderBeginTag calls SetupModal(writer); which adds the HTML for the modal. The modal is only added for the first control on the page and shared by all the others.
  • AddAttributesToRender calls SetupAttributes(writer); which adds the Onclick event handler to the images.

The private methods are well commented in the source code download so I won't go into detail here.

The ThumbHandler.cs class implements the IHttpHandler interface.

public class ThumbHandler : IHttpHandler {}

The thumbnail image creation is handled in the ProcessRequest method.

public void ProcessRequest(HttpContext context)
    // Get the QueryString parameters passed
    string _imagePath = context.Request.QueryString["i"] == null ?
        string.Empty : context.Request.QueryString["i"].ToString();
    int _thumbWidth = context.Request.QueryString["w"] == null ?
        100 : int.Parse(context.Request.QueryString["w"].ToString());
    int _thumbHeight = context.Request.QueryString["h"] == null ?
        100 : int.Parse(context.Request.QueryString["h"].ToString());

    // Create a thumb image from the source image
    System.Drawing.Image _sourceImage = System.Drawing.Image.FromFile(
    System.Drawing.Image _thumbImage = this.CreateThumbnail(
        _sourceImage, _thumbWidth, _thumbHeight);

    // Save the thumb image to the OutputStream
    _thumbImage.Save(context.Response.OutputStream, ImageFormat.Jpeg);
private System.Drawing.Image CreateThumbnail(System.Drawing.Image image, 
    int thumbWidth, int thumbHeight)
    return image.GetThumbnailImage(
        delegate() { return false; }, 

The querystring parameters are retrieved and then the image is passed to CreateThumbnail to generate the thumbnail with the dimensions passed. The thumbnail image is then saved to the OutputStream.

Embedded Resources

The embedded resources are contained in the Resources folder:

  • ThumbViewer.js - Handles the modal display of the full size image.
  • ThumbViewer.css - Contains the styles for the modal display.
  • Progress.gif - Animated image which is displayed while the full size image is loading.

These resources are registered in the AssemblyInfo.cs class.

[assembly: WebResource("Bright.WebControls.Resources.ThumbViewer.css",
[assembly: WebResource("Bright.WebControls.Resources.ThumbViewer.js",
    "text/javascript", PerformSubstitution = true)]
[assembly: WebResource("Bright.WebControls.Resources.Progress.gif",


The control has been tested on the following browsers: IE 7.0, Firefox 2.0, Opera 9.1 and with the following image formats: JPG, GIF, PNG, BMP.



By extending the System.Web.UI.WebControls.Image control, adding some JavaScript and an HttpHandler you can create a nice solution for viewing thumbnails and fullsize images in a web application.


  • v1.0 - 11th Feb 2007
  • v1.1 - 18th Feb 2007
    The progress bar image is displayed correctly. The fullsize image modal is repositioned if page is resized or scrolled.


This article has no explicit license attached to it but may contain usage terms in the article text or the download files themselves. If in doubt please contact the author via the discussion board below.

A list of licenses authors might use can be found here


About the Author

Declan Bright
Ireland Ireland
I have been designing and developing business solutions for the aviation and telecommunications industries since 1999. My experience covers a wide range of technologies and I have delivered a variety of web and mobile based solutions.

Comments and Discussions

GeneralRe: Error Message for Thumbviewer control Pin
gem120410-May-07 16:31
Membergem120410-May-07 16:31 
GeneralRe: Error Message for Thumbviewer control Pin
Declan Bright15-May-07 22:54
MemberDeclan Bright15-May-07 22:54 
QuestionAdditional functionality query Pin
jimibt2-May-07 2:04
Memberjimibt2-May-07 2:04 
AnswerRe: Additional functionality query Pin
Declan Bright9-May-07 10:01
MemberDeclan Bright9-May-07 10:01 
GeneralModal window always showing in Landscape - won't show in portrait Pin
Amileigh1-May-07 14:11
MemberAmileigh1-May-07 14:11 
GeneralRe: Modal window always showing in Landscape - won't show in portrait Pin
jimibt3-May-07 9:50
Memberjimibt3-May-07 9:50 
GeneralRe: Modal window always showing in Landscape - won't show in portrait Pin
Declan Bright9-May-07 9:50
MemberDeclan Bright9-May-07 9:50 
GeneralRe: Modal window always showing in Landscape - won't show in portrait Pin
jimibt11-May-07 7:48
Memberjimibt11-May-07 7:48 
i've sorted this issue re the landscape/portrait problem. I basically had to change the code in two places:

ThumbViewer.cs and ThumbViewer.js.

the replacement code for the cs file is for the SetupAttributes method and is pasted below:

private void SetupAttributes(HtmlTextWriter writer)
// Check that the file exists
if (ImageUrl.Length > 0 && File.Exists(Context.Server.MapPath(_relativeImagePath)))
// Add the onclick event handler depending on the ModalDisplayModeOption
switch (_modalDisplayModeOption)
// If ModalDisplayMode is Stretch then write out the openModal
// javascript method to the Onclick event. The aspect ratio and
// padding are passed as parameters and the image is displayed
// to the full size of the browser window with the set padding.
case (ModalDisplayModeOptions.Stretch):
// get the image attributes to pass to the javascript function
System.Drawing.Image fullSizeImg;
fullSizeImg = System.Drawing.Image.FromFile(Context.Server.MapPath( _relativeImagePath));

+ _relativeImagePath + "', '"
+ Title + "', "
+ ModalImagePadding.Value.ToString() + ", "
+ _aspectRatio.ToString() + ", "
+ fullSizeImg.Width + ", "
+ fullSizeImg.Height
+ ");");
// If ModalDisplayMode is Fixed then write out the openModalDim
// javascript method to the Onclick event. ModalFixedWidth and
// ModalFixedHeight are passed as parameters.
case (ModalDisplayModeOptions.Fixed):
+ _relativeImagePath + "', '"
+ Title + "', "
+ ModalFixedWidth.Value.ToString() + ", "
+ ModalFixedHeight.Value.ToString() + ");");
// If ModalDisplayMode is Disabled then don't add an Onclick event.
case (ModalDisplayModeOptions.Disabled):
// Do nothing
// If the full size image does not exits then alert the user.
writer.AddAttribute(HtmlTextWriterAttribute.Onclick, "alert('Sorry, the full size image does not exist!')");

// Add the Title as the Alternate Text attribute.
writer.AddAttribute(HtmlTextWriterAttribute.Alt, Title);

and for the javascript file, it's the openModal function:

function openModal(imageUrl, imageTitle, padding, ratio, iwidth, iheight){
var width = 0;
var height = 0;

// Calculate size of modal
if(wh > ww || ((wh - padding) / ratio > ww)){
width = ww - padding;
height = width * ratio;
else {
height = wh - padding;
width = height / ratio;

if(iwidth > iheight)
iheight="(height/iheight)" *="" iheight;
="" }
="" else="" {
="" iwidth="width;
" else
="" iwidth;
="" if(width=""> 0 && height > 0){
openModalDim(imageUrl, imageTitle, iwidth, iheight);

hope this helps - it could of course still be improved but seems to reliably work on all sorts of file sizes and window sizes.

GeneralRe: Modal window always showing in Landscape - won't show in portrait Pin
jimibt12-May-07 3:08
Memberjimibt12-May-07 3:08 
GeneralRe: Modal window always showing in Landscape - won't show in portrait Pin
yannlh24-Dec-07 10:39
Memberyannlh24-Dec-07 10:39 
GeneralRe: Modal window always showing in Landscape - won't show in portrait Pin
yannlh24-Dec-07 11:25
Memberyannlh24-Dec-07 11:25 
GeneralRe: Modal window always showing in Landscape - won't show in portrait Pin
yannlh2-Jan-08 9:39
Memberyannlh2-Jan-08 9:39 
GeneralModified the demo to run with paging on repeater Pin
jimibt1-May-07 7:06
Memberjimibt1-May-07 7:06 
GeneralRe: Modified the demo to run with paging on repeater Pin
jimibt1-May-07 7:27
Memberjimibt1-May-07 7:27 
GeneralRe: Modified the demo to run with paging on repeater Pin
Declan Bright9-May-07 9:40
MemberDeclan Bright9-May-07 9:40 
GeneralFull Image does not appear when clicked Pin
sezhian_vertical30-Apr-07 1:23
Membersezhian_vertical30-Apr-07 1:23 
GeneralRe: Full Image does not appear when clicked Pin
Declan Bright30-Apr-07 3:51
MemberDeclan Bright30-Apr-07 3:51 
GeneralThanks Declan Pin
Elvisvr27-Apr-07 23:06
MemberElvisvr27-Apr-07 23:06 
GeneralRe: Thanks Declan Pin
Declan Bright29-Apr-07 7:24
MemberDeclan Bright29-Apr-07 7:24 
QuestionWhat about ModalDisplayMode to take the original Image size? Pin
Hasan Bazerbashi19-Mar-07 3:11
MemberHasan Bazerbashi19-Mar-07 3:11 
AnswerRe: What about ModalDisplayMode to take the original Image size? Pin
Declan Bright20-Mar-07 10:30
MemberDeclan Bright20-Mar-07 10:30 
GeneralRe: What about ModalDisplayMode to take the original Image size? Pin
yannlh19-Dec-07 16:36
Memberyannlh19-Dec-07 16:36 
GeneralRe: What about ModalDisplayMode to take the original Image size? Pin
yannlh24-Dec-07 11:22
Memberyannlh24-Dec-07 11:22 
Generalthanks Pin
dpobla4-Mar-07 5:34
Memberdpobla4-Mar-07 5:34 
GeneralRe: thanks Pin
dpobla4-Mar-07 5:54
Memberdpobla4-Mar-07 5:54 

General General    News News    Suggestion Suggestion    Question Question    Bug Bug    Answer Answer    Joke Joke    Praise Praise    Rant Rant    Admin Admin   

Use Ctrl+Left/Right to switch messages, Ctrl+Up/Down to switch threads, Ctrl+Shift+Left/Right to switch pages.