Share via


Walkthrough: Making Controls Located in Web User Controls Easier to Access from JavaScript

In this walkthrough, you will create a Web user control that displays a DropDownList control and a Label control. When you select one of four seasons in the drop-down list, client script sets the label text to the name of a sport that is typically played during that season.

The Label control renders as a span element in HTML, and the client script obtains a reference to the span element by using its id attribute. You will set the ClientIDMode of the Label control to Static so that the ID will remain the same and the client script will work regardless of where on a page you position the user control.

Prerequisites

Creating a user control

To create a Web user control with a Label control that generates predictable HTML id attributes, set the ClientIDMode property of the Label control to Static.

To create a user control

  1. In Visual Studio, create a new Web user control named Seasons.ascx.

  2. Add a DropDownList control to the user control.

  3. Switch to Design View if you are not already in it.

  4. Open the DropDownList Tasks menu and click Edit Items.

  5. Add items with the following values:

    • Select a season

    • Spring

    • Summer

    • Autumn

    • Winter.

  6. Add a Label control to the user control after the DropDownList control.

  7. In the Label control's Properties window, set ID to SelectedSport, set ClientIDMode to Static, and clear the Text field.

  8. Switch to Source View.

  9. Insert a break (<br />) between the two controls.

  10. Add the following client script before the asp:DropDownList element

    <script type="text/javascript">
      var seasonalSports = new Array("None selected",
                                     "Tennis",
                                     "Volleyball",
                                     "Baseball",
                                     "Skiing");
    
      function DisplaySport(x) {
          document.getElementById("SelectedSport").innerHTML
          = seasonalSports[x];
      }    
    </script>
    

    This script uses the selectedIndex property of the HTML select element that is rendered for the DropDownList server control to select a sport name corresponding to the selected season name. It sets the innerHTML property of the span element that is rendered for the Label control to that name.

  11. Add an onChange attribute to the asp:DropDownList element that will cause the DisplaySport function to be run whenever the DropDownList selection is changed. The DropDownList will be rendered as an HTML select element, and you will pass to the DisplaySport function the value of the selectedIndex property of the select element.

    <asp:DropDownList ID="DropDownList1" runat="server" 
                      onchange="DisplaySport(this.selectedIndex);">
    

    The markup for the completed server control now resembles the following.

    <%@ Control AutoEventWireup="true" %>
    
    <script type="text/javascript">
      var seasonalSports = new Array("None selected",
                                     "Tennis",
                                     "Volleyball",
                                     "Baseball",
                                     "Skiing");
    
      function DisplaySport(x) {
          document.getElementById("SelectedSport").innerHTML
          = seasonalSports[x];
      }    
    </script>
    
    <asp:DropDownList ID="DropDownList1" runat="server" 
                      onchange="DisplaySport(this.selectedIndex);">
      <asp:ListItem Value="Select a season"></asp:ListItem>
      <asp:ListItem Value="Spring"></asp:ListItem>
      <asp:ListItem Value="Summer"></asp:ListItem>
      <asp:ListItem Value="Autumn"></asp:ListItem>
      <asp:ListItem Value="Winter"></asp:ListItem>
    </asp:DropDownList>
    <br />
    <asp:Label ID="SelectedSport" runat="server" ClientIDMode="Static">
    </asp:Label>
    

Adding the user control to a content page

To locate the user control inside a hierarchy of naming containers you create a master page and a content page, and locate the user control on the content page.

To add the user control to a content page

  1. Create a new master page named Seasons.master.

  2. Create a new Web form named Seasons.aspx, selecting Seasons.master as its master page.

  3. With Seasons.aspx still open, switch to Design view.

  4. Drag the user control Seasons.ascx from Solution Explorer to the design surface.

    The markup for the master page Seasons.master now resembles the following.

    <%@ Master AutoEventWireup="true" %>
    
    <!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "https://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
    
    <html xmlns="https://www.w3.org/1999/xhtml">
    <head runat="server">
        <title></title>
        <asp:ContentPlaceHolder id="head" runat="server">
        </asp:ContentPlaceHolder>
    </head>
    <body>
        <form id="form1" runat="server">
        <div>
            <asp:ContentPlaceHolder id="ContentPlaceHolder1" runat="server">
    
            </asp:ContentPlaceHolder>
        </div>
        </form>
    </body>
    </html>
    

    And the markup for the content page Seasons.aspx now resembles the following.

    <%@ Page Title="" MasterPageFile="~/Seasons.master" AutoEventWireup="true" %>
    
    <%@ Register Src="Seasons.ascx" TagName="Seasons" TagPrefix="uc1" %>
    <asp:Content ID="Content1" ContentPlaceHolderID="head" runat="Server">
    </asp:Content>
    <asp:Content ID="Content2" ContentPlaceHolderID="ContentPlaceHolder1" runat="Server">
      <uc1:Seasons ID="Seasons1" runat="server" />
    </asp:Content>
    
  5. Right-click Seasons.aspx in Solution Explorer and select View in Browser.

    You see a drop-down box with Select a season displayed.

    The Seasons.ascx drop-down box

  6. Select Spring.

    You see Tennis displayed under the drop-down box.

  7. View the page source in your browser.

    You see that the Label control is rendered as a span element:

    <span id="SelectedSport"></span>
    

    If you had not set the ClientIDMode property of the Label control, the id attribute would have been rendered as ctl00_ContentPlaceHolder1_Seasons1_SelectedSport. Since the id would change if the user control were put in a different naming container - a different master page or content page or a container control on a page - it would be more difficult to write client script that would continue to work regardless of how and where the user control is used.

Next Steps

This walkthrough has shown you how to use client script to access controls that are located on a Web user control. From here, you might want to learn more about how ASP.NET generates ClientID values or about special considerations that relate to data-bound controls. The following list suggests topics for additional learning.

See Also

Reference

Control.ClientID

Control.ClientIDMode

System.Web.UI.ClientIDMode

Concepts

ASP.NET Web Server Control Identification