Section 5.4. AdRotator Control

5.4. AdRotator Control

This control is called an AdRotator because it is most often used to display advertisements on web pages. It displays an image randomly selected from a list stored either in a separate XML file or a data-bound data source. In either case, the list contains image attributes, including the path to the image and a URL to link to when the image is clicked. The image changes every time the page is loaded.

In addition to the properties inherited from WebControl , the AdRotator control has the properties and events listed in Table 5-10.

Table 5-10. Properties and events of the AdRotator control

Name	Type	Get	Set	Description
AdvertisementFile	String			The path to an XML file that contains the list of advertisements and their attributes. This file is described in detail below.
AlternateTextField	String			Element name from the Advertisement file or data field from which the alternate text is stored. Default is AlternateText .
DataMember	String			The name of the specific list of data the control will bind to.
DataSource	Object			An object from which the control can retrieve data.
DataSourceID	String			The ID of the control from which the AdRotator can retrieve data.
ImageUrlField	String			Element name from the Advertisement file or data field from which the URL for the image is stored. Default is ImageUrl .
KeywordFilter	String			Filters ads displayed to include only those with the specified keyword in the AdvertisementFile .
NavigateUrlField	String			Element name from the Advertisement file or data field in which the URL to navigate to is stored. Default is NavigateUrl .
Target	String			The browser window or frame that displays the contents of the page linked to when the AdRotator is clicked.
AdCreated	Event			Occurs once per round trip to the server after creation of the control, but before the page is rendered.

The Target property is used to specify which browser window or frame is used to display the results of clicking on the AdRotator control. It dictates if the resulting page displaces the current contents in the current browser window or frame, opens a new browser window, or does something else. The values of the Target property must begin with any letter in the range of a to z, case insensitive, except for the special values shown in Table 5-11, which begin with an underscore . These are the same special values recognized by the Target property of the HyperLink control.

Table 5-11. Special values of the Target property

Value	Description
_blank	Renders the content in a new, unnamed window without frames .
_new	Not documented. Behaves the same as _blank the first time the control is clicked, but subsequent clicks will render to that same window, rather than open another blank window.
_parent	Renders the content in the parent window or frameset of the window or frame with the hyperlink. If the child container is a window or top-level frame, it behaves the same as _self .
_self	Renders the content in the current frame or window with focus. This is the default behavior.
_top	Renders the content in the current full window without frames.

5.4.1. Advertisement File

The advertisement file is an XML file that contains information about the advertisements to be displayed by the AdRotator control. Its location and filename is specified by the AdvertisementFile property of the control.

The location of the advertisement file can be relative to the web site root directory or can be absolute. If its location is other than the web root, you will need to ensure that the application has sufficient rights to access the file, especially after deployment. For this and other security reasons, it is usually best to locate the file directly in the web root.

The AdvertisementFile property cannot be set simultaneously with the DataSource , DataMember , or DataSourceID properties. In other words, if the data is coming from an advertisement file, then it cannot simultaneously come from a data source, and vice versa.

The advertisement file and the AdvertisementFile property are optional. If you want to create an advertisement programmatically, without the use of an advertisement file, put the code to display the desired elements in the AdCreated event.

As an XML file, the advertisement file is a structured text file with well-defined tags delineating the data. Table 5-12 lists the standard tags, which are enclosed in angle brackets ( < > ) and require matching closing tags.

Table 5-12. XML tags used in the advertisement file

Tag	Description
Advertisements	Encloses the entire advertisement file.
Ad	Delineates each separate ad.
ImageUrl	The URL of the image to display. Required.
NavigateUrl	The URL of the page to navigate to when the control is clicked.
AlternateText	The text displayed in the control if the image is unavailable. In browsers that support the ToolTips feature, this text is also displayed as a ToolTip.
Keyword	The advertisement category. The keyword can be used to filter the advertisements displayed by the control by setting the AdRotator KeywordFilter property.
Impressions	A value indicating how often the ad is displayed relative to the other ads in the file.

Since this is XML and not HTML, it is much less forgiving of files that are not well- formed . These tags are case-sensitive: ImageUrl will work; ImageURL will not.

For a complete description of well-formed XML, see the sidebar, "Well-Formed XHTML," in Chapter 3.

In addition to the tags listed in Table 5-12, you can include your own custom tags to have custom attributes. The sample advertisement file in Example 5-13, contains a custom attribute called Animal , which will hold the animal pictured on the cover of each book. (No, the authors have no say in selecting the animal that goes on our books.)

Example 5-13. ads.XML, sample advertisement file

 <Advertisements>    <Ad>       <ImageUrl>ProgAspNet.gif</ImageUrl>       <NavigateUrl>          http://www.oreilly.com/catalog/progaspdotnet2/index.html       </NavigateUrl>       <AlternateText>Programming ASP.NET</AlternateText>       <Keyword>Web</Keyword>       <Impressions>50</Impressions>       <Animal>stingray</Animal>    </Ad>    <Ad>       <ImageUrl>WinApps.gif</ImageUrl>       <NavigateUrl>          http://www.oreilly.com/catalog/pnetwinaps/index.html       </NavigateUrl>       <AlternateText>Programming .NET Windows Applications</AlternateText>       <Keyword>Windows</Keyword>       <Impressions>40</Impressions>       <Animal>darter</Animal>    </Ad>    <Ad>       <ImageUrl>ProgCSharp.gif</ImageUrl>       <NavigateUrl>          http://www.oreilly.com/catalog/progcsharp4/       </NavigateUrl>       <AlternateText>Programming C#</AlternateText>       <Keyword>Language</Keyword>       <Impressions>40</Impressions>       <Animal>African Crowned Crane</Animal>    </Ad>    <Ad>       <ImageUrl>ProgVB.gif</ImageUrl>       <NavigateUrl>          http://www.oreilly.com/catalog/progvb2005/       </NavigateUrl>       <AlternateText>Programming Visual Basic 2005</AlternateText>       <Keyword>Language</Keyword>       <Impressions>30</Impressions>       <Animal>catfish</Animal>    </Ad> </Advertisements> 

All the attribute tags in the advertisement file are parsed and placed in the adProperties dictionary. This dictionary can be used programmatically to access attributes, either standard or custom, by placing code in the AdCreated event handler.

Example 5-13 shows a sample advertisement file that contains references to books and web sites for several excellent programming books.

5.4.2. Using AdRotator

Now all you need is a web page with an AdRotator control to use this advertisement file, as shown in the next example, AdRotatorDemo . After creating a new web site by that name, drag an AdRotator control onto the page, along with a Label control to display the animal. The content file should look something like Example 5-14.

Example 5-14. Default.aspx for AdRotatoDemo

 <%@ Page Language="C#" AutoEventWireup="true"  CodeFile="Default.aspx.cs"    Inherits="_Default" %> <!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.1//EN"    "http://www.w3.org/TR/xhtml11/DTD/xhtml11.dtd"> <html xmlns="http://www.w3.org/1999/xhtml" > <head runat="server">     <title>AdRotator</title> </head> <body>     <form id="form1" runat="server">     <div>       <h1>AdRotator Control</h1>  <asp:AdRotator ID="ad" runat="server"             Target="_blank"             AdvertisementFile="ads.xml"             OnAdCreated="ad_AdCreated" />  <br />        Animal:        <asp:Label id="lblAnimal" runat="server"/>     </div>     </form> </body> </html> 

The event handler, ad_AdCreated , is highlighted in the code-behind file listed in Example 5-15.

Example 5-15. Default.aspx.cs for AdRotatorDemo

 using System; using System.Data; using System.Configuration; using System.Web; using System.Web.Security; using System.Web.UI; using System.Web.UI.WebControls; using System.Web.UI.WebControls.WebParts; using System.Web.UI.HtmlControls; public partial class _Default : System.Web.UI.Page {     protected void Page_Load(object sender, EventArgs e)     {     }  protected void ad_AdCreated(object sender, AdCreatedEventArgs e)     {        if ((string)e.AdProperties["Animal"] != "")           lblAnimal.Text = (string)e.AdProperties["Animal"];        else           lblAnimal.Text = "n.a.";     }  } 

Make certain that the advertisement file called ads.xml , listed in Example 5-13, is located in the web site root directory, along with the image files specified within that file: ProgAspNet.gif, ProgCSharp.gif, ProgVB.gif, and WinApps.gif .

The results of running AdRotatorDemo are shown in Figure 5-13. To see the images cycle through, refresh the view on your browser.

Figure 5-13. AdRotatorDemo

This control raises an AdCreated event, which occurs on every round trip to the server after the control is created but before the page is rendered. An attribute in the control declaration called OnAdCreated specifies the event handler to execute whenever the event fires. The event handler is passed an argument of type AdCreatedEventArgs , which has the properties listed in Table 5-13.

Table 5-13. Properties of the AdCreateEventArgs class

Property	Description
AdProperties	Gets a dictionary object that contains all the advertisement properties contained in the advertisement file.
AlternateText	The alternate text displayed by the browser when the advertisement image is unavailable . If the browser supports ToolTips, then this text will be displayed as a ToolTip.
ImageUrl	The URL of an image to display.
NavigateUrl	URL of the web page to display when the control is clicked.

Every time the ad is changed (i.e., every time the page is reloaded), the event handler, ad_AdCreated , fires and updates lblAnimal contained on the page. ad_AdCreated first tests to be certain a value is in the Animal attribute. If not, then "n.a." (for "not available") is displayed.

AdProperties returns a Dictionary object. When the AdProperties property is invoked, it implicitly calls the Item method of the Dictionary object, which returns the value corresponding to the dictionary entry whose key is Animal . This value is then cast, or converted, to a string. In C#, this is done with the following syntax:

 (string)e.AdProperties["Animal"]