Tutorial 1: Image Popup Window

This tutorial shows how to use the Advanced Popup Window class library to assign a popup window behavior to a product thumbnail displayed on the Product Detail page using template #1. The popup window should display the large image of the product saved in the StoreFront database when the user clicks on the thumbnail.

The web page used to display the image is called "ShowImage.aspx" and is provided with the class library as an example. This file can be used directly in a production site, and you can easily customize it to match your site design if necessary.

Let's walk through the steps involved in providing this behavior. This tutorial includes the following sections:

Introduction

Because the add-on is a class library (it has no visible user interface), it must be used in the code-behind of your pages. In addition, the popup window behavior can only be registered with a control having an ID attribute and a runat="server" attribute.

Our first step will be to locate which control we will use to register the popup behavior. Open your ProductDetail1.ascx user control, located in the Controls folder under the root of your site. The product thumbnail is located toward the top of the file, normally on line 8 (StoreFront version 6.1.2). The code should read like the following:

The image tag (<IMG src='<%# DataBinder.Eval(Me,"ImageString") %>'>) seems at first to be the logical candidate to register our popup behavior. However, it does not have an ID attribute and a runat="server" attribute. Although we could add these attributes, we have an easier way which does not require modification to this file: the image tag is embedded in an asp:panel server control. This server control does have an ID attribute and a runat="server" attribute. It will be rendered by the server as a DIV tag on the client browser, which will have the exact same size as the image. So let's use it.

Assigning the Popup Behavior to the asp:panel Server Control

As mentionned above, you need to implement the add-on in the code-behind. So open the ProductDetail1.ascx.vb file. Locate the Page_Load event handler, and go to the end of the method. Just before the "End Sub" line, insert a new line and type the following code:

'Create an instance of the AdvancedPopupWindow class.
Dim myPopup As New GMS.Framework.Utilities.AdvancedPopupWindow.AdvancedPopupWindow
' Set the properties
myPopup.TriggerControl = ProductImage
myPopup.PopupUrl = "ShowImage.aspx"
myPopup.ImageQueryStringKeyName = "Image"
myPopup.ImagePath = Product.LargeImage
' Register the popup behavior
myPopup.RegisterImagePopup()

Note for Developers: an alternative coding style consists in importing the GMS.Framework.Utilities.AdvancedPopupWindow namespace in your code, allowing you to call the empty constructor without using the fully qualified name of the class.

Ignoring the comment lines (the lines starting with a single-quote character), the first line of code creates an instance of the AdvancedPopupWindow class. The following four lines assign values to properties of the class, as follows:

The TriggerControl property represents the control to which the popup behavior should be registered. In our case, we use the asp:panel control which has an ID equal to "ProductImage". Therefore, we assign the control's name (without quotes) to the TriggerControl property.
The PopupUrl property is the URL of the web page to be displayed in the popup window. In our case, we use the sample page provided with the add-on to display a product image. This page has a "Close Window" link at the top, followed by a horizontal ruler, and then the image itself.
The ImageQueryStringKeyName property represents the name of the value passed in the query string for the poup window. The sample page provided with the add-on to display a product image expects to read the path of the image in the query string under the "Image" key name.
The ImagePath property represents the value to be passed in the query string, corresponding to the ImageQueryStringKeyName property.

With these property values, the popup window will display the following URL: ShowImage.aspx?Image=xxxxxx, where "xxxxxx" represents the relative path to the image file, for example: myImage.jpg.

Finally, we register the behavior by calling the RegisterImagePopup() method of the AdvancedPopupWindow object. Try it on your site: compile the site, then navigate to a product detail page. When you click on the thumbnail image, you should see the popup window open, as per the following example:

Using the ImageWidthMargin and ImageHeightMargin Properties

Now, we have a small problem with this popup window: as you can notice, the picture is slighly cut-off because the height of the window is too small and there is a scrollbar which we would like not to be activated. By default, the AdvancedPopupWindow class has its AutoDetectImageSize property set to True, so it adjusts automatically to the actual size of the picture. However, our sample page adds a "Close Window" link and a horizontal ruler. This takes some space in addition to the picture size. For this reason, the AdvancedPopupWindow class provides two additional properties: ImageWidthMargin and ImageHeightMargin, which have a default value of 60 pixels. When you call the RegisterImagePopup method as in the prior example, these values were automatically added to the picture width and size. The additional 60 pixels was enough for the width, to accomodate for the white space around the picture and the width of the vertical scrollbar. But it was not enough for the height.

In order to take into account our additional content, besides the picture itself, let's increase the ImageHeightMargin to 125, like in the following code:

'Create an instance of the AdvancedPopupWindow class.
Dim myPopup As New GMS.Framework.Utilities.AdvancedPopupWindow.AdvancedPopupWindow
' Set the properties
myPopup.TriggerControl = ProductImage
myPopup.PopupUrl = "ShowImage.aspx"
myPopup.ImageQueryStringKeyName = "Image"
myPopup.ImagePath = Product.LargeImage
myPopup.ImageHeightMargin = 125
' Register the popup behavior
myPopup.RegisterImagePopup()

Compile your site again, refresh the product detail page that you were displaying before, so that the new settings are taken into account. Then click on the thumbnail again. The popup window should now be large enough so that no scrolling is required to see the entire picture and so that the scrollbar is displayed but not activaed, as in the following example:

Using the AdvancedPopupWindow Specialized Constructors

The example of opening a popup window displaying a product image and which adjusts its size automatically depending on the size of the image is so common that we provided a way for you to perform the same as our example by using a single line of code. The AdvancedPopupWindow class has several constructors ("New" methods). Two of these constructors faciliate the registration of a popup window displaying an image. The first of these constructors corresponds to our first example, while the second correspond to the second example. Let's examine how we can code this.

Replace the code you typed so far by the following:

' Register a popup window to display the large image of a product
Dim myPopup1 As New GMS.Framework.Utilities.AdvancedPopupWindow.AdvancedPopupWindow(ProductImage, "ShowImage.aspx", Product.LargeImage)

After writing a comment line explaining what we do (remember that it is good practice to comment your code, so that you will understand quickly, several months down the road, when you revisit the design and/or the programming of your site, what you were trying to accomplish), we add a single line of code, calling one of the specialized constructors of the AdvancedPopupWindow class. This constructor takes three parameters:

a control, which will be automatically saved in the TriggerControl property,
a URL, which will be saved in the PopupUrl property, and
a path to an image, which will be saved in the ImagePath property

Then, the constructor automatically calls the RegisterImagePopup() method for you.

If you try this constructor in your code, you will get again the popup window with a cut-off image which requires vertical scrolling. As mentionned, the ImageWidthMargin and ImageHeightMargin properties both have a default value of 60 pixels. Because of the "Close Window" link and the horizontal ruler, we need a height margin of 125 pixels instead of 60. To accomodate for this other common situation, we use the second specialized constructor as follows:

Compared to the prior one, this constructor adds the following two parameters:

a width margin value in pixels, which will be automatically saved in the ImageWidthMargin property, and
a height margin value in pixels, which will be automatically saved in the ImageHeightMargin property.

If you try this code on your site, you should now get a popup window which does not require any scrolling at all. All this with a single line of code.

You can now start experimenting with the other properties of the AdvancedPopupWindow class on your own site, or you can look at Tutorial 2, which will show you the use of some of the other properties. Tutorial 2 is an example of how to display a popup window displaying extra product information, using different methods.

Support: Contact and Purchase Information | Licensing the AdvancedPopupWindow Class Library