Supporting Templates with ASP.NET User Controls

ASP.NET User Controls (those files with the .ascx extensions) provide a really easy way to encapsulate functionality within an application, and allow it to be re-used across multiple pages and projects (note: for a tutorial on how to create re-usable user control libraries with the VS 2005 Web Application Project check out the C# one here, and the VB one here).

Most developers who create user-controls know that it is possible to easily expose public properties from them so that you can customize them from a page that is using them.  This allows a page developer to declare properties like so on the user-control tag (as well as access them from the code-behind):

   <MyLibrary:MyUserControl id="UC1" someproperty="somevalue" runat="server"/>

  

What is less well known is that in addition to exposing standard properties from user controls, you can also expose template properties.  This allows a page developer to pass templates to the user control like so:

 

 

   <MyLibrary:MyUserControl id="UC1" someproperty="somevalue" runat="server">

  

      <TitleTemplate>

           Some custom content I want rendered in the title...

      </TitleTemplate>

 

      <ItemTemplate>

           Here is a calendar: <asp:calendar id="cal1" runat="server" />

      </ItemTemplate>

 

   </MyLibrary:MyUserControl>

 

This allows you to provide much richer UI customization and further re-use.

Robert Seder has posted a nice blog post here that describes how to-do this.

Update: Kris also pointed me at some MSDN documentation that shows the syntax to support this with VB.  You can read it here.

Hope this helps,

Scott

 

Published Sunday, June 04, 2006 9:55 AM by ScottGu
Filed under:

Comments

# re: Supporting Templates with ASP.NET User Controls

Sunday, June 04, 2006 3:05 PM by Bilal Haidar [MVP]
What a great post!

Thanks Scott.

# Adding Templates to ASP.NET 2.0 User Controls

Sunday, June 04, 2006 3:11 PM by Brad Wilson - The .NET Guy

# re: Supporting Templates with ASP.NET User Controls

Sunday, June 04, 2006 3:54 PM by ScottGu
Kris - good pointer.  Thx!

# re: Supporting Templates with ASP.NET User Controls

Sunday, June 04, 2006 5:39 PM by David Taylor
Did you actually try his instructions Scott?

Yeah - it works, but it is pretty ugly when used from VS 2005.  The designer breaks with a "Error Creating User Control - User Control does not have public property names DescriptionTemplate" error.

# re: Supporting Templates with ASP.NET User Controls

Monday, June 05, 2006 9:21 AM by Vikram
I know I am asking something not related to this Topic.

But can u give us any update on when are the next set of Atlas control going to come and what are the new controls that are being added.

You also mentioned earlier that you would be blogging about whatever Microsoft is about to come up with in the month. I do not see anything like that.


Thanks
Vikram

# Interesting Finds: June 5, 2006 AM edition

Monday, June 05, 2006 10:48 AM by Jason Haley

# re: Supporting Templates with ASP.NET User Controls

Monday, June 05, 2006 11:42 AM by Dave Reed
Some of the new .NET controls like the Login Control use an even better kind of template. In this example the template can contain any controls the user of the control wants it to, but they don't interact with the user control itself. That is, unless the user control does a 'findcontrol' on the controls within the template and then uses the found control (if any) instead of its own internal version. The login control does that for the username, password, etc controls. That allows the template designer to make the UI of the control look like anything they want it to even if the structure is completely different -- for example, make the password box appear BEFORE the user name box. The template designer just has to name the controls with the correct ID so the parent control can find them. The whole idea is similar to the concept of user controls themselves -- except with user controls, the ascx file is the template, and the code behind for it is the control.

# re: Supporting Templates with ASP.NET User Controls

Monday, June 05, 2006 1:03 PM by Sergio Pereira
My wish is that in the future this experience can be similar to creating Master Pages.

# Supporting Templates with ASP.NET User Controls

Monday, June 05, 2006 1:54 PM by dotnetkicks.com
Trackback from dotnetkicks.com

# re: Supporting Templates with ASP.NET User Controls

Monday, June 05, 2006 2:05 PM by John S.
Excellent! Thanks!

# re: Supporting Templates with ASP.NET User Controls

Monday, June 05, 2006 3:29 PM by Liming
Brilliant! Much simpler than wip up a composite control.

# re: Supporting Templates with ASP.NET User Controls

Tuesday, June 06, 2006 8:44 AM by Koistya `Navin
Good point! Thanks.

# re: Supporting Templates with ASP.NET User Controls

Tuesday, June 06, 2006 12:57 PM by Rui Santos
Another important tip, to make the controls nested in the templates directly accessible on the Page that contains the user control, is to add an [TemplateInstance(TemplateInstance.Single)] attribute to the ITemplate properties of the User Control.

Scott, the designer error is really annoying.
The User Control designer doesn’t recognize any inner property of the User control and throws an error.

What can be done to correct it?

Cheers,
Rui

# re: Supporting Templates with ASP.NET User Controls

Saturday, June 10, 2006 11:20 AM by Manu
How can add design time support in VS2005?
I need to just expose one panle and allow people drag controls on it at design time but designer seems broken when using the code described.
Manu

# re: Supporting Templates with ASP.NET User Controls

Saturday, June 10, 2006 11:57 AM by ScottGu
Hi Manu,

For design-time support, you are best off using the new CompositeControl base class within ASP.NET.  This blog post points a few articles you can read about this: http://weblogs.asp.net/scottgu/archive/2006/02/14/438234.aspx

Hope this helps,

Scott

# re: Supporting Templates with ASP.NET User Controls

Saturday, June 10, 2006 12:32 PM by Manu
Thanks... I'm trying that way. Composite control support in 2.0 seems far better than in 1.1.
Manu

# Link Listing - June 10, 2006

Saturday, June 10, 2006 11:13 PM by Christopher Steen

 **NOW AVAILABLE** MOSS ECM Starter Kit for B2 (white
 papers, code samples, workflows, and VS...

# re: Supporting Templates with ASP.NET User Controls

Monday, June 12, 2006 2:57 AM by John Pequeno
Well I am having a problem.  I would like to have a templated user control, which I can use, let's say on a page, and then have the ability to access the controls within the template from the PAGE.  Example.

<uc:myTemplateUC runat="server">
 <asp:label id="myLabel" runat="server" />
</uc:myTemplateUC>

I would like to be able to access 'myLabel' from the page which uses 'myTemplateUC'.

The problem is here.  If I add the attribute to the user control:
[ParseChildren(false)]
It actually works, but then, I cannot use any code blocks in my usercontrol!  i get this fun error:
The Controls collection cannot be modified because the control contains code blocks (i.e. <% ... %>).

And if I use:
[ParseChildren(true)]
Intelisense shows the myLabel on the page, but If I try to do anything with it, I get a null reference exception.  Events also don't seem to fire in this case, as from an asp:button

Please help!  I have a very slick page template system, which is lacking only this fix.

# re: Supporting Templates with ASP.NET User Controls

Monday, June 12, 2006 12:09 PM by John Pequeno
Ok, in the end I found my mistake.  

I was trying to get access to my nested controls within the template of a templated user control, from the page instantiating that user control.

Do this:

Must use:
[ParseChildren(true)]   //on user control class

[PersistenceMod(PersistenceMode.InnerProperty),
TemplateContainer(typeof(TemplateControl)),
TemplateInstance(TemplateInstance.Single)
]   // on template property

And then must InstanceIn the template property on the override OnInit() in the user control.  

My problem the entire time was that I was using the user control PreRender instead of the OnInit to InstanceIn the controls, ugh...

# 通過 .NET 2.0 認證考試: 070-528(MCTS)

Tuesday, June 20, 2006 6:18 PM by Huan-Lin's Blog
考完 70-536 之後,接下來的 70-528 也順利通過了,也就是說,取得了 MCTS: .NET Framework 2.0 Web Applications 證照。
考完之後跟 Preparation...

# re: Supporting Templates with ASP.NET User Controls

Thursday, June 29, 2006 4:48 AM by Anonymous

A general advice to everybody:

Make sure you don't give your template property the name "Body", or the designer will break. I guess this applies to other reserved words also.

# re: Supporting Templates with ASP.NET User Controls

Tuesday, July 25, 2006 9:07 AM by Jaap Faber
In a previous post Dave Reed was talking about the templates of the Login Control. You can change the template, and have the same result, as long as you have the correct ID's for components on the template. Is it possible to switch the template of the Login Control runtime (say based on a value in Profile or database)? Thanks, Jaap.

# re: Supporting Templates with ASP.NET User Controls

Friday, September 29, 2006 10:45 AM by Kieran
Hi there, I'm currently developing an asp.net application. I have a usercontrol .ascx that is a datagrid bound to some data allowing the user to click the records and display the complete details for the chosen record. My dilemma is that I know have introduced a new admin.aspx page, on this I need to display the same grid of data but when clicking on records I will be loading the record for editing in a different interface, not loading it for viewing. The grid will also need to be a slightly different template layout in the admin.aspx page. So I want to use all the functionality of the datagrid usercontrol in both places but change a couple of pieces of functionality. What is the thought process that I should apply to these sort of problems? Do you create a new usercontrol and strip out/add in as required or do you use one usercontrol and adjust it for each scenario (which always seems to result in an 'if this', 'if that' type scenario) Would appreciate everyones thoughts on this?

# re: Supporting Templates with ASP.NET User Controls

Sunday, October 01, 2006 9:47 PM by ScottGu

Hi Kieran,

You can programmatically allow editing/deleting of values from a Grid column by retrieving its <asp:commandfield> column and then setting the ShowEditButton or ShowDeleteButton to true/false.  This would allow you to have one user control but customize it depending on the user role.

Hope this helps,

Scott

# Templating User Controls in ASP.NET And Inner Visibility

Thursday, June 28, 2007 5:13 AM by Mike Nichols - Son of Nun Technology

Templating User Controls in ASP.NET And Inner Visibility