AdRotator Control

Article
09/14/2006

The AdRotator mobile control offers advertisement rotation functionality in the same way that the ASP.NET Web Forms AdRotator control does, but also provides adaptive rendering for mobile devices.

Note The AdRotator control itself is independent of the type of image file that you use for your advertisement. You can use any type of image file that is compatible with the targeted browser.

Alternate Image Capability

The AdRotator control can render alternate images for various devices. For example, if you want to be able to render the same image to two different types of devices, one that displays HTML and one that displays WML, you can use the <DeviceSpecific> element to specify a different ImageKey property for each targeted device. Within the DeviceSpecific/Choice construct, you specify the file format type that can be displayed on the targeted device. For more information about specifying different images, see the AdRotator class.

Mobile Controls Syntax

Required properties, defaults, and code-featured elements are noted in bold type.

<mobile:AdRotator
   runat="server"
   id="id"
   Font-Name="fontName"
   Font-Size="{NotSet|Normal|Small|Large}"
   Font-Bold="{NotSet|False|True}"
   Font-Italic=""{NotSet|False|True}"
   ForeColor="foregroundColor"
   BackColor="backgroundColor"
   Alignment="{NotSet|Left|Center|Right}"
   StyleReference="styleReference"
   Wrapping="{NotSet|Wrap|NoWrap}"

   AdvertisementFile="relativeURL"
   ImageKey="imageKey"
   KeywordFilter="keywordFilter"
   NavigateURLKey="navigateUrlKey"
   OnAdCreated="clickHandler">
Place DeviceSpecific/Choice construct here. (optional)
</mobile:AdRotator>

Advertisement File Format

<?xml version="1.0" ?>
<Advertisements>
   [<Ad>
     <ImageUrl>The URL of the image to display</ImageUrl>
     <NavigateURL>The URL of the page to display</NavigateURL>
     [<OptionalImageUrl>URL of monochrome image to display</OptionalImageUrl>]*
     [<OptionalNavigateURL>URL of page to display</OptionalNavigateURL>]*
     <AlternateText>The text to display as a ToolTip</AlternateText>
     <Keyword>The keyword used to filter</Keyword>
     <Impressions>
       The relative weighting of the advertisement
     </Impressions>
   </Ad>]*
</Advertisements>

The following points are important to remember when you are creating an advertisement file:

The XML must be well formed.
You can have multiple <Ad> elements, but only one <Advertisements> element in the file. Multiple <Advertisements> elements produce an error, and nested <Advertisements> elements are ignored.
The ImageUrl element contains an absolute or relative (to the Ads.xml file location) URL to the image file that is displayed for the advertisement when no ImageKey element matches an OptionalImageUrl element.
The OptionalImageUrl element contains an absolute or relative (to the Ads.xml file location) URL to the image file that is displayed for the advertisement for a matching ImageKey element (optional). You can have as many of these as your application requires.
The NavigateURL element contains the URL of the page to which the user is sent when they click the advertisement and no NavigateURLKey element matches an OptionalNavigateURL element (optional). If this is not set, the HREF property is not rendered on the anchor tag.
The OptionalNavigateURL element contains the URL of the page to which the user is sent when they click the advertisement for a matching NavigateURLKey element (optional). You can have as many of these as your application requires.
The AlternateText element contains the ALT attribute of the image (optional). In some browsers, this appears as a ToolTip for the advertisement. The text is also displayed if the image specified in the ImageUrl property cannot be found.
The Keyword element specifies a category for the advertisement (for example, "computers") by which you can filter advertisements (optional).
The Impressions element is a number that indicates the weight of the advertisement in the schedule of rotation relative to the other advertisements in the file (optional). The larger the number, the more often the advertisement is displayed. The total of all the numbers contained in the Impressions property cannot exceed 2,048,000,000–1. If it does, the AdRotator control throws a run-time exception.

Multiple Advertisement Images

The AdRotator control can be used with advertisements that render alternate images on different devices. To support such advertisements, take the following steps:

Declare a <DeviceSpecific> element in the AdRotator control.
For each special device class, declare a <Choice> element inside the <DeviceSpecific> element, set the filter property appropriately, and then set the ImageKey attribute to a unique name.
In addition to the normal ImageUrl property, each advertisement entry in the AdRotator configuration file must contain an element for each specified device class, with the same name as the corresponding ImageKey attribute, which contains the URL for the corresponding image.

At run time, with a device class chosen, the control uses the corresponding element in the advertisement entry to determine the URL of the image. Otherwise, the default image from the <ImgeUrl> element is chosen.

Containment Rules

The containment rules for all concrete classes derived from the AdRotator class are the same and are shown in the following table. The following controls can contain an AdRotator control.

Control	Comments
System.Web.UI.MobileControls.Form	Can contain any number of AdRotator controls.
System.Web.UI.MobileControls.Panel	Can contain any number of AdRotator controls.

The AdRotator control can contain the following controls.

Control	Comments
System.Web.UI.MobileControls.DeviceSpecific	Specifies per-device image alternatives. 0 or 1 DeviceSpecific controls can be contained in an AdRotator control.

Device Templates

None.

Device-Specific Behavior

For all targets, the AdRotator control chooses an advertisement from the advertisement file. Depending on the keyword in the Keyword element, the AdRotator control uses the information from the elements in the advertisement element to set the corresponding property for the control:

ImageKey. This property is set to the value in the ImageUrl element.
NavigateURLKey. This property is set to the value in the NavigateURL element.
KeywordFilter. This property is set to the value in the Keyword element.

Overriding the ImageKey property for specific devices provides functionality on a per-device basis. In the following example, the <DeviceSpecific> statement specifies that devices that render only monochrome images receive the link to the monochrome image file. When using device-specific information, you must follow the Device-Specific Rendering guidelines for adding device filters to the web.config file.

Example

The following example code creates an AdRotator control that processes an advertisement file and displays advertisements from it at random. To successfully run this control, you must supply the images and the XML code that calls the images and links them to the company's home page. An example XML file is shown after the AdRotator example.

[Visual Basic, C#]

<%@ Page Inherits="System.Web.UI.MobileControls.MobilePage" %>
<%@ Register TagPrefix="mobile"
    Namespace="System.Web.UI.MobileControls"
    Assembly="System.Web.Mobile" %>

<mobile:Form runat="server">
  <mobile:AdRotator runat="server" AdvertisementFile="Ads.xml"/>
   <DeviceSpecific>
    <Choice Filter="isMonochrome" ImageKey="monoImageUrl"/>
   </DeviceSpecific>
  <mobile:Label runat="server">
   The advertisement is refreshed every time you reload this page.
  </mobile:Label>
</mobile:Form>

The following code is a sample advertisement file, Ads.xml.

<?xml version="1.0"?>
<Advertisements>
  <Ad>
   <ImageUrl>Ads/Microsoft.gif</ImageUrl>
   <MonoImageUrl>Ads/Microsoft_bw.gif</MonoImageUrl>
   <NavigateURL>https://www.Microsoft.com</NavigateURL>
   <AlternateText>Software: Microsoft</AlternateText>
   <KeywordFilter>software</KeywordFilter>
   <Impressions>80</Impressions>
  </Ad>
  <Ad>
   <ImageUrl>Place second image here</ImageUrl>
   <NavigateURL>Place second URL here</NavigateURL>
   <AlternateText>Place alternate text here</AlternateText>
   <KeywordFilter>keyword</KeywordFilter>
   <Impressions>80</Impressions>
  </Ad>
</Advertisements>

Share via