Easing in to user controls
Denise Wynn
November 30, 2004
Download the example code for this article. BeginningUserControlsCode.zip
We're going to start with 2 extremely simple controls that set the banner and footer of all web pages on a site. The idea is to isolate those areas of a page that are shared and put that code in a user control. That way when you need to update a link or some text or even just swap out your banner image you only have to modify and upload one file instead of every file in your site.
Template.aspx
We'll start with a simple template web page. In Notepad or any other text editor create a file called template.aspx in your test directory and enter the following code.
<%@ Page runat="server" language="c#"%>
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Strict//EN"
"http://www.w3.org/TR/xhtml1/DTD/xhtml1-strict.dtd">
<html>
<head>
<title>User Control Template</title>
</head>
<body>
</body>
</html>
There isn't really much to it and the only thing that makes it look different from any static html page is the @ Page declaration at the top.
You can view your new page by opening a browser and going to http://localhost/test/template.aspx.
The Banner Control
Now we will create the first user control. Create a text file named banner.ascx in the test directory and enter the following code.
<%@ Control runat="server" language="c#" %> <img src="banner.jpg" alt="My Banner" />
The @ Control directive lets ASP.NET know that this file is a user control. Beneath the directive is the actual html that we want to use for our banner that will be inserted into any page that implements the banner control. This is really the simplest implementation of a user control since it contains only static html and no other code.
Since the banner control has an image tag we'll need an image in our test directory or we'll just display a broken image on the page. The sample download includes a banner image you can use or you can reference any other image that you have available.
Now we want to add our banner to our template page. Go back to the template.aspx file and add the following bold lines.
<%@ Page runat="server" language="c#"%>
<%@ Register TagPrefix="nbs" TagName="banner" Src="banner.ascx" %>
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Strict//EN"
"http://www.w3.org/TR/xhtml1/DTD/xhtml1-strict.dtd">
<html>
<head>
<title>User Control Template</title>
</head>
<body>
<nbs:banner runat="server" />
</body>
</html>
The @ Register directive allows the page to register a custom user control. It lets the page know where to find the control as well as what tag prefix and name will be used within the page to instantiate the control. The TagPrefix attributes value is set to "nbs" and the TagName attributes value to "banner". So in the page we've created a tag using nbs:banner exactly where you want the banner code to be displayed. We added a runat="server" to the nbs:banner tag so the page knows to render this on the server side before sending it to the client. If we didn't add the runat="server" then the banner code would not be written into the page and nothing would be displayed in that space on the client. Doing a view source would just show an <nbs:banner /> tag.
The Src attributes value has been set to the banner.ascx file that is located in the same directory. We could also put all of the controls in a directory called controls or templates and set the Src accordingly. The path in the Src attribute can be either relative or absolute.
If you were to view the template.aspx page in a browser you will see the banner image displayed across the top of the page. Viewing the source would show the following:
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Strict//EN"
"http://www.w3.org/TR/xhtml1/DTD/xhtml1-strict.dtd">
<html>
<head>
<title>User Control Template</title>
</head>
<body>
<img src="banner.jpg" alt="My Banner" />
</body>
</html>
The Footer Control
We also want to add a footer to our page. Create a text file named footer.ascx in the test direcroty and add the following code to it.
<%@ Control runat="server" language="c#" %> <div> Copyright © 2004 No Box Solutions, Inc. </div>Go back to the template.aspx file and add the following bold lines.
<%@ Page runat="server" language="c#"%>
<%@ Register TagPrefix="nbs" TagName="banner" Src="banner.ascx" %>
<%@ Register TagPrefix="nbs" TagName="footer" Src="footer.ascx" %>
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Strict//EN"
"http://www.w3.org/TR/xhtml1/DTD/xhtml1-strict.dtd">
<html>
<head>
<title>User Control Template</title>
</head>
<body>
<nbs:banner runat="server" />
<nbs:footer runat="server" />
</body>
</html>
Notice how the TagPrefix is the same but the TagName is different as is the Src. I've used nbs to signify that these are No Box Solutions custom controls.
Viewing the template page now in your browser will display the banner and directly beneath it will appear the footer. Viewing the page source will show the following:
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Strict//EN"
"http://www.w3.org/TR/xhtml1/DTD/xhtml1-strict.dtd">
<html>
<head>
<title>User Control Template</title>
</head>
<body>
<img src="banner.jpg" alt="My Banner" />
<div>
Copyright © 2004 No Box Solutions, Inc.
</div>
</body>
</html>
Putting it to work
Now that we have our template we can start to do something useful with it.
Save a copy of your template.aspx file as firstpage.aspx in your test directory. Open firstpage.aspx in a text editor and add the following bold line.
<%@ Page runat="server" language="c#"%>
<%@ Register TagPrefix="nbs" TagName="banner" Src="banner.ascx" %>
<%@ Register TagPrefix="nbs" TagName="footer" Src="footer.ascx" %>
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Strict//EN"
"http://www.w3.org/TR/xhtml1/DTD/xhtml1-strict.dtd">
<html>
<head>
<title>User Control Template</title>
</head>
<body>
<nbs:banner runat="server" />
<p>This is the first page made from my new template.</p>
<nbs:footer runat="server" />
</body>
</html>
Save firstpage.aspx and in your browser go to http://localhost/test/firstpage.aspx.
You have just created a page using your template file and all you had to enter was the static text/html for that page. You can create additional pages from the same template in the same way.
The advantage is that no matter how many pages you create from the same template, if you want to change your banner or footer you only have to change one file that you have to upload to your site instead of changing all of the pages.
In Conclusion
You now have a template file that you can use as a base for creating numerous web pages. If you need to make a change to either the banner or the footer you only have to change a single file.