AdRotator Control Syntax

ASP.NET Syntax ASP.NET Syntax for Web Controls

Displays an advertisement banner on a Web Forms page.

<asp:AdRotator
   AccessKey = "string"
   AdvertisementFile = "uri"
   AlternateTextField = "string"
   BackColor = "color name | #dddddd"
   BorderColor = "color name | #dddddd"
   BorderStyle = "NotSet | None | Dotted | Dashed | Solid | Double | Groove |
      Ridge | Inset | Outset"
   BorderWidth = size
   CssClass = "string"
   DataMember = "string"
   DataSource = "string"
   DataSourceID = "string"
   Enabled = "True | False"
   EnableTheming = "True | False"
   EnableViewState = "True | False"
   ForeColor = "color name | #dddddd"
   Height = size
   ID = "string"
   ImageUrlField = "string"
   KeywordFilter = "string"
   NavigateUrlField = "string"
   OnAdCreated = "AdCreated event handler"
   OnDataBinding = "DataBinding event handler"
   OnDataBound = "DataBound event handler"
   OnDisposed = "Disposed event handler"
   OnInit = "Init event handler"
   OnLoad = "Load event handler"
   OnPreRender = "PreRender event handler"
   OnUnload = "Unload event handler"
   runat = "server"
   SkinID = "string"
   Style = "string"
   TabIndex = integer
   Target = "string | _blank | _parent | _search | _self | _top"
   ToolTip = "string"
   Visible = "True | False"
   Width = size
 />

For information on the individual members of this class, see AdRotator in the class library.

The AdRotator control uses a separate XML advertisement file to store the advertisement information, such as the location of the image to display and the URL of the page to link to. The AdvertisementFile property of the AdRotator control specifies the path to this file.

When creating the advertisement file, opening and closing <Advertisements> tags mark the beginning and the end of the file, respectively. Opening and closing <Ad> tags delimit each advertisement. All advertisements are nested between the opening and closing <Advertisements> tags. If the file contains multiple <Advertisements> tags, only the first set of <Advertisements> tags in the file will be parsed by the AdRotator control. All other <Advertisements> tags will be ignored.

The data elements for each advertisement are nested between the opening and closing <Ad> tags. Although certain data elements are predefined ( such as ImageUrl and NavigateUrl ), you can place custom elements between the <Ad> tags. These elements will be read by the AdRotator control when it parses the file. The information is then passed to the AdCreated event in the AdProperties dictionary property.

The following table lists the data elements that are predefined for the XML advertisement file.

Element	Description
<ImageUrl>	The absolute or relative URL to an image file ( optional ).
<NavigateUrl>	The URL of a page to link to if the user clicks the ad ( optional ). NOTE: If this element is not set, the HRef property is not rendered on the anchor tag.
<AlternateText>	The text display in place of the image when the image is not available ( optional ). This text is displayed if the image specified in ImageUrl is not accessible. In some browsers, this text also appears as a ToolTip for the advertisement.
<Keyword>	A category for the advertisement ( for example, "computers" ) that you can filter by ( optional ).
<Impressions>	A number that indicates the importance of the ad in the schedule of rotation relative to the other ads in the file ( optional ). The larger the number, the more often the ad is displayed. The total of all Impressions values in the XML file cannot exceed 2,047,999,999. If it does, the AdRotator throws a run-time exception.

The following shows the format for the XML advertisement file.

<Advertisements>
   <Ad>
      <ImageUrl>
         URL of image to display for Advertisement #1
      </ImageUrl>
      <NavigateUrl>
         URL of page to link to for Advertisement #1
      </NavigateUrl>
      <AlternateText>
         Text to show as a ToolTip for Advertisement #1
      </AlternateText>
      <Keyword>
         Keyword used to filter for Advertisement #1
      </Keyword>
      <Impressions>
         Relative importance of Advertisement #1
      </Impressions>
      <CustomInformation>
         Custom Data about Advertisement #1
      </CustomInformation>
   </Ad>
</Advertisements>

The AdRotator control displays an advertisement banner on a Web Forms page. It displays the image specified by the ImageUrl element within an anchor control. At run time, the AdRotator control uses <asp:HyperLink> and <asp:Image> controls to render the control on the Web Forms page. The source image is sized by the browser to the dimensions of the AdRotator control, regardless of its actual size.

If the AdvertisementFile property is set, an advertisement is selected based on the value of the Impressions property from the file. The event arguments are then set and the AdCreated event is raised. If the AdvertisementFile property is not set, the event arguments are empty when the AdCreated event is raised. The event arguments are used to render the AdRotator control, so you can modify the values passed to the event from the advertisement file, or set them with values you generate yourself. A common scenario is to populate the event arguments with values pulled from a database.

When you create an advertisement file, the following points are important to remember:

The XML in the advertisement file must be well formed.

Only the first <Advertisements> element in the file is parsed by the AdRotator control. All other <Advertisements> elements within the file are ignored.

You can add custom elements to the XML description of an advertisement. These values are passed to the AdCreated event in the AdProperties dictionary property.

You can use the AdCreated event to select the advertisements directly in your code or to modify the rendering of an ad selected from the advertisement file. If an advertisement file is set, the arguments to the AdCreated event are already set to the selected ad when the event is called. Whether or not the values are already set, you can modify the values in the ImageUrl, NavigateUrl, and AlternateText properties to modify the rendering of the AdRotator control. Custom elements added to the XML description of the advertisement are available in the AdCreatedEventArgs.AdProperties dictionary property.

The below code snippet shows a sample declaration for an AdRotator control in an .aspx file.

<asp:adrotator advertisementfile = "ads.xml" 
   bordercolor = "silver" borderwidth=1 runat="server" />

AdRotator Example

Run Sample View Source

The following example shows how you can dynamically retrieve and display ad properties when an ad is created at run time.

void AdCreatedHandler ( Object sender, AdCreatedEventArgs e ) {
   string props = "Selected ad properties<br>";
   props += "Alternate Text: " + e.AlternateText + "<br>";
   props += "URL: " + e.NavigateUrl + "<br>";
   adProps.Text = props;
}

Sub AdCreatedHandler ( sender As Object, e As AdCreatedEventArgs )
   Dim props As String = "Selected ad properties<br>"
   props = props & "Alternate Text: " & e.AlternateText & "<br>"
   props = props & "URL: " & e.NavigateUrl & "<br>"
   adProps.Text = props
End Sub

AdCreated Event Handler Example

Run Sample View Source

AdRotator Class AdRotator Web Server Control

Home Getting Started Web Forms Web Applications ADO.NET ASP/ADO Back to Basics

AdRotator Control Syntax

Advertisement File Format

Remarks

Syntax Example

See Also