Export (0) Print
Expand All

How To: Create ASP.NET Web Server Control Templates Dynamically

When working with templated controls, you might not know until run time what templates you need or what text or controls the template should contain. In that case, you can create the templates dynamically in code.

NoteNote:

You can also create templates as user controls and bind them dynamically to controls on your page. For details, see How to: Create Templated ASP.NET User Controls.

You can create templates in code for all controls that use templates: the DataList, Repeater, GridView, FormView, DetailsView, and others. For the GridView control, you use templates to define columns instead of the row layout templates as for the other controls.

NoteNote:

There are a few differences when creating template columns for the GridView control as compared to other templated controls. For details, see Creating a Custom Column in a GridView Web Server Control.

To create dynamic templates, you create a template class, which you then instantiate when needed.

To create a template class

  1. Create a new class that implements the System.Web.UI.ITemplate interface.

  2. Optionally, pass into the class's constructor a value that the class can use to determine what type of template to create (ItemTemplate, AlternatingItemTemplate, and so on).

    NoteNote:

    A type-safe way to pass the template type to the constructor is to add a parameter to the constructor with the type ListItemType. The ListItemType enumeration defines the possible template types for the Repeater, DataList, and other list controls.

  3. In the class, implement the InstantiateIn method, which is the member of the ITemplate interface.

    This method provides a way to insert an instance of text and controls into the specified container.

  4. In the InstantiateIn method, create the controls for the template item, set their properties, and then add them to the parent's Controls collection.

    You can access the parent control via the reference passed to the InstantiateIn method.

    NoteNote:

    You cannot directly add static text to the Controls collection, but you can create controls like the Literal control or the LiteralControl control, set their Text properties, and then add those controls to the parent collection.

  5. For controls that require data binding, create and bind a method to handle the control's DataBinding event. This event is raised after the template item has been created with all its controls, and it provides you with an opportunity to fetch data and use it in a control.

    NoteNote:

    You cannot embed a data-binding expression as a string when creating controls in the template, as you do when defining templates at design time, because data-binding expressions are converted into code before your template is created.

    In the handler for the DataBinding event, you have an opportunity to manipulate the contents of the control. Typically (but not necessarily), you fetch data from somewhere and assign it to the control's Text property (or other property).

    NoteNote:

    For information on data binding in ASP.NET Web pages, see Accessing Data with ASP.NET.

    To add data binding to a dynamic template, you must do the following:

    • Add a data-binding event handler to the controls you create in the template.

    • Create the handler that you are binding to. In the handler, get the data that you want to bind to and assign it to the appropriate property of the control being bound.

      NoteNote:

      If you have multiple types of controls in your templates, you need to create a different data-binding event handler for each control type.

    The following code example illustrates a template class named MyTemplate that implements the ITemplate interface. The MyTemplate class defines a constructor that accepts a ListItemType enumeration value to indicate what type of template is being created. Depending on the template type, the code creates different types of controls and adds them to a PlaceHolder control which is then added to the Controls collection of the parent control. For the ListItemType of Item and AlternatingItem, an event handler named Item_DataBinding is created.

    The rendered Web page results in an HTML table with a different background color for the alternating item template.

    public class MyTemplate : System.Web.UI.ITemplate
    {
        System.Web.UI.WebControls.ListItemType templateType;
        public MyTemplate(System.Web.UI.WebControls.ListItemType type)
        {
            templateType = type;
        }
    
        public void InstantiateIn(System.Web.UI.Control container)
        {
            PlaceHolder ph = new PlaceHolder();
            Label item1 = new Label();
            Label item2 = new Label();
            item1.ID = "item1";
            item2.ID = "item2";
    
            switch (templateType)
            {
                case ListItemType.Header:
                    ph.Controls.Add(new LiteralControl("<table border=\"1\">" +
                        "<tr><td><b>Category ID</b></td>" + 
                        "<td><b>Category Name</b></td></tr>"));
                    break;
                case ListItemType.Item:
                    ph.Controls.Add(new LiteralControl("<tr><td>"));
                    ph.Controls.Add(item1);
                    ph.Controls.Add(new LiteralControl("</td><td>"));
                    ph.Controls.Add(item2);
                    ph.Controls.Add(new LiteralControl("</td></tr>"));
                    ph.DataBinding += new EventHandler(Item_DataBinding);
                    break;                    
                case ListItemType.AlternatingItem:
                    ph.Controls.Add(new LiteralControl("<tr bgcolor=\"lightblue\"><td>"));
                    ph.Controls.Add(item1);
                    ph.Controls.Add(new LiteralControl("</td><td>"));
                    ph.Controls.Add(item2);
                    ph.Controls.Add(new LiteralControl("</td></tr>"));
                    ph.DataBinding += new EventHandler(Item_DataBinding);
                    break;
                case ListItemType.Footer:
                    ph.Controls.Add(new LiteralControl("</table>"));
                    break;
            }
            container.Controls.Add(ph);
        }
    }
    

To create the handler for the DataBinding event

  1. Create a method that is either part of your template class and is a peer of the class's other methods (such as InstantiateIn) or a static (Shared in Visual Basic) method of the page. The handler's name must match the name you used when binding the event earlier.

  2. Get a reference to the DataItem object that contains the data by doing the following:

    1. Get a reference to the template item, which you can get from your control's NamingContainer property.

    2. Use that reference to get the naming container's (the template item's) DataItem property.

    3. Extract the individual data element from the DataItem object and use it to set a property of the control you are binding.

    The following code example illustrates one way to perform data binding within a dynamic template. It shows a complete data-binding event handler for the PlaceHolder control and for the Literal and Label controls created in the previous procedure. The event handler is implemented as a static method of the page.

    static void Item_DataBinding(object sender, System.EventArgs e)
    {
        PlaceHolder ph = (PlaceHolder)sender;
        RepeaterItem ri = (RepeaterItem)ph.NamingContainer;
        Int32 item1Value = (Int32)DataBinder.Eval(ri.DataItem, "CategoryID");
        String item2Value = (String)DataBinder.Eval(ri.DataItem, "CategoryName");
        ((Label)ph.FindControl("item1")).Text = item1Value.ToString();
        ((Label)ph.FindControl("item2")).Text = item2Value;
    }
    

When you have a dynamic template available, you can instantiate it in code.

To use a dynamic template

  1. Create an instance of your dynamic template, passing it an item type value if appropriate.

  2. Assign the instance to one of the template properties of the templated control, such as the ItemTemplate, AlternatingItemTemplate, or HeaderTemplate properties.

    The following code example shows how to use the dynamic template with a Repeater control. In this example, the templates are instantiated while the page is being loaded and before the control is bound to its data source.

    The example below assumes that you can connect to the Northwind sample database on Microsoft SQL Server 7.0 or later. It returns a list of records from the Categories table.

    protected void Page_Load(object sender, EventArgs e)
    {
        System.Data.SqlClient.SqlConnection conn =
            new System.Data.SqlClient.SqlConnection(
            ConfigurationManager.ConnectionStrings["Northwind"].ConnectionString);
    
        System.Data.SqlClient.SqlDataAdapter sqlDataAdapter1;
        System.Data.DataSet dsCategories1;
    
        sqlDataAdapter1 = new System.Data.SqlClient.SqlDataAdapter(
            "SELECT [CategoryID], [CategoryName] FROM [Categories]", conn);
        dsCategories1 = new System.Data.DataSet();
    
        Repeater1.HeaderTemplate = new MyTemplate(ListItemType.Header);
        Repeater1.ItemTemplate = new MyTemplate(ListItemType.Item);
        Repeater1.AlternatingItemTemplate =
           new MyTemplate(ListItemType.AlternatingItem);
        Repeater1.FooterTemplate = new MyTemplate(ListItemType.Footer);
        sqlDataAdapter1.Fill(dsCategories1, "Categories");
        Repeater1.DataSource = dsCategories1.Tables["Categories"];
        Repeater1.DataBind();
    }
    

After creating all the components listed previously, add a Repeater control named Repeater1 to the page markup and run the page. The complete code and markup for the Web page (using the single-file code model) is shown below.

<%@ Page Language="C#" %>

<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">

<script runat="server">

    public class MyTemplate : System.Web.UI.ITemplate
    {
        System.Web.UI.WebControls.ListItemType templateType;
        public MyTemplate(System.Web.UI.WebControls.ListItemType type)
        {
            templateType = type;
        }

        public void InstantiateIn(System.Web.UI.Control container)
        {
            PlaceHolder ph = new PlaceHolder();
            Label item1 = new Label();
            Label item2 = new Label();
            item1.ID = "item1";
            item2.ID = "item2";

            switch (templateType)
            {
                case ListItemType.Header:
                    ph.Controls.Add(new LiteralControl("<table border=\"1\">" +
                        "<tr><td><b>Category ID</b></td>" + 
                        "<td><b>Category Name</b></td></tr>"));
                    break;
                case ListItemType.Item:
                    ph.Controls.Add(new LiteralControl("<tr><td>"));
                    ph.Controls.Add(item1);
                    ph.Controls.Add(new LiteralControl("</td><td>"));
                    ph.Controls.Add(item2);
                    ph.Controls.Add(new LiteralControl("</td></tr>"));
                    ph.DataBinding += new EventHandler(Item_DataBinding);
                    break;                    
                case ListItemType.AlternatingItem:
                    ph.Controls.Add(new LiteralControl("<tr bgcolor=\"lightblue\"><td>"));
                    ph.Controls.Add(item1);
                    ph.Controls.Add(new LiteralControl("</td><td>"));
                    ph.Controls.Add(item2);
                    ph.Controls.Add(new LiteralControl("</td></tr>"));
                    ph.DataBinding += new EventHandler(Item_DataBinding);
                    break;
                case ListItemType.Footer:
                    ph.Controls.Add(new LiteralControl("</table>"));
                    break;
            }
            container.Controls.Add(ph);
        }
    }

    static void Item_DataBinding(object sender, System.EventArgs e)
    {
        PlaceHolder ph = (PlaceHolder)sender;
        RepeaterItem ri = (RepeaterItem)ph.NamingContainer;
        Int32 item1Value = (Int32)DataBinder.Eval(ri.DataItem, "CategoryID");
        String item2Value = (String)DataBinder.Eval(ri.DataItem, "CategoryName");
        ((Label)ph.FindControl("item1")).Text = item1Value.ToString();
        ((Label)ph.FindControl("item2")).Text = item2Value;
    }

    protected void Page_Load(object sender, EventArgs e)
    {
        System.Data.SqlClient.SqlConnection conn =
            new System.Data.SqlClient.SqlConnection(
            ConfigurationManager.ConnectionStrings["Northwind"].ConnectionString);

        System.Data.SqlClient.SqlDataAdapter sqlDataAdapter1;
        System.Data.DataSet dsCategories1;

        sqlDataAdapter1 = new System.Data.SqlClient.SqlDataAdapter(
            "SELECT [CategoryID], [CategoryName] FROM [Categories]", conn);
        dsCategories1 = new System.Data.DataSet();

        Repeater1.HeaderTemplate = new MyTemplate(ListItemType.Header);
        Repeater1.ItemTemplate = new MyTemplate(ListItemType.Item);
        Repeater1.AlternatingItemTemplate =
           new MyTemplate(ListItemType.AlternatingItem);
        Repeater1.FooterTemplate = new MyTemplate(ListItemType.Footer);
        sqlDataAdapter1.Fill(dsCategories1, "Categories");
        Repeater1.DataSource = dsCategories1.Tables["Categories"];
        Repeater1.DataBind();
    }


</script>
<html xmlns="http://www.w3.org/1999/xhtml" >
<head runat="server">
    <title>Dynamically Creating Templates</title>
</head>
<body>
    <form id="form1" runat="server">
    <div>
      <asp:Repeater id="Repeater1" runat="server"></asp:Repeater>
    </div>
    </form>
</body>
</html>

Community Additions

ADD
Show:
© 2014 Microsoft