Creating a Templated User Control

Article
10/17/2014

You can create user controls that implement templates (an ASP.NET feature that allows the separation of control data from its presentation). A templated control does not provide a user interface (UI). The UI for the control is supplied by a page developer through inline templates that allow a page developer to customize the UI for the control. Creating templated user controls affords you the ease of adding user controls to pages in your application without compiling a custom control into a .dll file.

For more information about creating custom templated controls, see Developing a Templated Control.

To create a templated user control

In the .ascx file, declaratively create an ASP.NET Placeholder Web server control where you want the template to appear.
In the user control's code-declaration block or code-behind class, implement a property of type ITemplate.
In the same code block, define a server control that implements INamingContainer as a container in which to create an instance of the template. This is called the template's naming container.

Note This control essentially becomes a nested class of the user control, though this is not required.
Apply the TemplateContainerAttribute to the ITemplate property and pass the type of the template's naming container as the argument to the constructor or the attribute.
In the Page_Init method, repeat the following steps one or more times:
- Create an instance of the naming container class.
- Create an instance of the template in the naming container.
- Add the naming container instance to the Controls property of the PlaceHolder server control.
  
  Note From the point of view of the page using the user control, the syntax for the templated user control is identical to what it would be with a custom templated control.

The following example demonstrates a templated user control and a page that contains it.

Note This example exposes only one template property, but you can expose as many template properties as you need for your application to work properly.

The templated user control:

<%@ Control language="VB" debug="True" %>
<script runat="server" >
Private messageTemplate As ITemplate = Nothing
<TemplateContainer(GetType(MessageContainer))>Public Property MessageTemplate() As ITemplate
    Get
        Return messageTemplate
    End Get
    Set
        messageTemplate = value
    End Set
End Property
    
Sub Page_Init()
    If Not (messageTemplate Is Nothing) Then
        Dim i As Integer
        For i = 0 To 4
            Dim container As New MessageContainer(i)
            messageTemplate.InstantiateIn(container)
            msgholder.Controls.Add(container)
        Next i
    End If
End Sub 'Page_Init


Public Class MessageContainer
    Inherits Control
    Implements INamingContainer 

    Private index As Integer
    
    Friend Sub New(index As Integer)
        Me.index = index
    End Sub 'New
    
    Public ReadOnly Property Index() As Integer
        Get
            Return index
        End Get
    End Property 
End Class 'MessageContainer
</script>

<hr>
<asp:placeholder runat=server id=msgholder/>
<hr>
[C#]
<%@ Control language=c# debug=true %>
<script runat=server>
private ITemplate messageTemplate = null;      

[ TemplateContainer(typeof(MessageContainer)) ]
public ITemplate MessageTemplate {
    get { return messageTemplate; }
    set { messageTemplate = value; }
}

void Page_Init() {
    if (messageTemplate != null) {
        for (int i=0; i<5; i++) {
            MessageContainer container = new MessageContainer(i);
            messageTemplate.InstantiateIn(container);
            msgholder.Controls.Add(container);
        }
    }
}

public class MessageContainer: Control, INamingContainer {
    private int index;
    internal MessageContainer(int index) { this.index = index; }
    public int Index { get { return index; } }
}

</script>

<hr>
<asp:placeholder runat=server id=msgholder/>
<hr>

The ASP.NET page that contains the templated user control:

<%@ language=vb debug=true %>
<%@ Register TagPrefix="acme" tagname="test" src=TemplatedUserControl.ascx %>
<html>
<script runat=server>
    Sub Page_Load()
        DataBind()
    End Sub 'Page_Load
</script>
<body>
' The Container in the data-binding syntax will automatically be of type
' MessageContainer, since the TemplateContainer attribute was applied 
' to the ITemplate class in the .ascx file.
<form runat=server>
<acme:test runat=server>
    <MessageTemplate>
        Hello #<%# Container.Index %>.<br>
    </MessageTemplate>
</acme:test>
</form>
</body>
</html>
[C#]
<%@ language=c# debug=true %>
<%@ Register TagPrefix="acme" tagname="test" src=TemplatedUserControl.ascx %>
<html>
<script runat=server>
    void Page_Load() {
        DataBind();
    }
</script>
<body>
// The Container in the data-binding syntax will automatically be of type
// MessageContainer, since the TemplateContainer attribute was applied 
// to the ITemplate class in the .ascx file.
<form runat=server>
<acme:test runat=server>
    <MessageTemplate>
        Hello #<%# Container.Index %>.<br>
    </MessageTemplate>
</acme:test>
</form>
</body>
</html>

Creating a Templated User Control

See Also

Additional resources