Click here to Skip to main content
Click here to Skip to main content

User controls in ASP .NET

, 15 Jan 2002
Rate this:
Please Sign up or sign in to vote.
An introduction to writing User Controls in ASP .NET

Introduction

In traditional ASP code reuse and encapulation was traditionally done using a combination of include files and web classes. While this worked reasonably well for business logic, it was always a little fiddly for visual components. For example, if you wanted to display a grid of data in many different places and have the grid have the same general look and feel, but be customisable for a particular page, then you either cut and pasted the HTML, used style sheets, used an include file, wrote some VBScript to generate the HTML on the fly, or used a combination of all these methods.

It was messy. It could also be difficult to move these components between projects because there was the ever present problem of ensuring that variable names didn't conflict, that you had the include file included only once (and in the correct order). Then there was the whole issue of tying the new control into existing code.

ASP .NET solves many of these issues with the introduction of User Controls. These are self contained visual elements that can be placed on a web page in the same way as a tradition intrinsic HTML control, and can have their attributes set in a similar fashion.

In this article I'll present a Title bar that has 6 properties (border width and colour, Title text and colour, background and padding. The control is embedded in a page using the following simple syntax:

<CP:TitleBar Title="User Control Test" TextColor="green" Padding=10 runat="server" />

This produces the following output:

Sample Image - MyUserControl.gif

So how do we write a user control?

The easiest way is using Visual Studio .NET. Start a new web project and right click on the project's name in the Server Explorer. Select 'Add...' then 'Add Web User Control...' Rename the control and hit Open. The wizard produces two files: a .ascx file containing the visual layout, and a .ascx.cs (assuming you are working in C#) that has the business logic.

The Visual Layout

First we design the visual layout of the Title bar. We'll use the new asp:XXX controls so that we get simple access to their attributes at runtime.

The entire .ascx file looks like:

<%@ Control Language="c#" AutoEventWireup="false" 
    Codebehind="MyUserControl.ascx.cs" 
    Inherits="CodeProject.MyUserControl" 
    TargetSchema="http://schemas.microsoft.com/intellisense/ie3-2nav3-0"%>

<asp:table id=OuterTable BackColor=#c0c0c0c BorderWidth=0 cellPadding=0 
           cellSpacing=1 width='100%' Runat="server">
<asp:tableRow><asp:tableCell width="100%">

<asp:table id=InnerTable BackColor=#cccccc BorderWidth=0 cellPadding=0 
           cellSpacing=1 width="100%" Runat="server">
<asp:tableRow<asp:tablecell HorizontalAlign=Center>

<asp:Label ID=TitleLabel Runat="server" />

</asp:tablecell></asp:tableRow>
</asp:table>

</asp:tablecell></asp:tableRow>
</asp:table>

A fairly traditional way of creating a table with a thin border - except that we are using ASP .NET controls instead of traditional HTML.

Note that if you were restricting your viewers to using IE then you could use the border-width style to set the border style and stick with one table. However, if you have Netscape 4.X viewers then this won't work. ASP .NET controls will output HTML 3.2 for downspec browsers like Netscape, so while ASP .NET's promise of 'write-once, view anywhere' sounds good, it doesn't actually happen in practice.

I'm not going to go into the in's and out's of ASP .NET controls. They are fairly self explanatory. Just make sure you include the 'runat=server' bit. They help.

The backend logic

Note the bit up the top of the file: Codebehind="MyUserControl.ascx.cs". This is where the visual layout (.ascx file) is hooked up with the backend logic (.ascx.cs). We will barely scrape the surface of what this separation of logic and display can do.

Our C# code looks like the following:

namespace CodeProject
{
    using System;
    ...

    public abstract class MyUserControl : System.Web.UI.UserControl
    {
        public string Title       = null;
        public string TextColor   = Color.Black.Name;
        public string BackColor   = Color.Wheat.Name;
        public int    Padding     = 2;
        public string BorderColor = Color.Gray.Name;
        public int    BorderWidth = 1;
        
        protected Table OuterTable;
        protected Table InnerTable;
        protected Label TitleLabel;

        private void Page_Load(object sender, System.EventArgs e)
        {
            if (Title==null || Title=="") 
                Visible = false;
            else
            {

                OuterTable.BackColor   = Color.FromName(BorderColor);
                OuterTable.CellSpacing = BorderWidth;
                InnerTable.CellPadding = Padding;
                InnerTable.BackColor   = Color.FromName(BackColor);
                
                TitleLabel.Text        = Title;
                TitleLabel.ForeColor   = Color.FromName(TextColor);
                TitleLabel.Font.Name   = "Verdana";
                TitleLabel.Font.Bold   = true;
                TitleLabel.Font.Size   = FontUnit.Parse("13");
            }
        }

        #region Web Form Designer generated code
        ...
        #endregion
    }
}

The entire purpose of this backend is to define a set of properties that the user can access when instantiating the control, and to then set the attributes of the ASP .NET controls in our .ascx file based on these properites.

We could just as easily open a connection to a database and bind a dataset to a control, or we could access the page that this control resides in (using the Page property) and adjust the look and feel of the control from what we find there. We could also provide user input mechanisms in our display and provide handlers for click events in the control here as well. These controls really are quite powerful.

Unfortunately we'll be staying a lot closer to Earth and will only provide the mediocrity of colour and border width changes.

Properties

Note the block of variable declarations at the top:

        public string Title       = null;
        public string TextColor   = Color.Black.Name;
        public string BackColor   = Color.Wheat.Name;
        public int    Padding     = 2;
        public string BorderColor = Color.Gray.Name;
        public int    BorderWidth = 1;

These publicly accessible variables form the attributes that are available to the user when he or she instantiates the control in a web page:

<CP:TitleBar Title="User Control Test" TextColor="green" Padding=10 runat="server" />

The user can set all, some or none of these properties.

The link between the visual elements and the code

The other half of the story is the link between the ASP .NET controls and the C# code. Note the block of variables underneath these:

        protected Table OuterTable;
        protected Table InnerTable;
        protected Label TitleLabel;

The names of these variables are the same as the ID's of the ASP .NET controls in our .ascx page. This causes the variable in our C# class to be linked up to the ASP .NET control in the .ascx page. We can now manipulate the controls on the page however we like:

            if (Title==null || Title=="") 
                Visible = false;
            else
            {

                OuterTable.BackColor   = Color.FromName(BorderColor);
                OuterTable.CellSpacing = BorderWidth;
                InnerTable.CellPadding = Padding;
                InnerTable.BackColor   = Color.FromName(BackColor);
                
                TitleLabel.Text        = Title;
                TitleLabel.ForeColor   = Color.FromName(TextColor);
                TitleLabel.Font.Name   = "Verdana";
                TitleLabel.Font.Bold   = true;
                TitleLabel.Font.Size   = FontUnit.Parse("13");
            }

Here we simply check if there is any title text, and if not then we set the control as invisible (meaning the HTML for the control simply won't be rendered and will not be sent down to the client). If there is text then we go ahead and set the properties of the controls.

And we're done!

Using the control

To use the control you will first need to compile the project with your files, and then create a page to host the control. The code for the control will be compiled into an assembly and placed in the /bin directory. If you make any changes to the C# code you'll need to recompile. You do not have to recompile if you make changes to the visual layout (.ascx) file.

To use the control you must make a page aware of the control. We do this by using a Register directive that specified the tag prefix we'll use, the tag name and the location of the user control's page:

<%@ Register TagPrefix="CP" TagName="TitleBar" Src="MyUserControl.ascx" %>
         
<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.0 Transitional//EN" > 
<html>
  <head>
    <title>MyPage</title>
  </head>
  <body>
  <basefont face=verdana>
  
  <CP:TitleBar Title="User Control Test" TextColor="green" Padding=10 runat="server" />
    
  </body>
</html>

The tag prefix in this case is CP, and the tag TitleBar They can be anything you want as long as there are no conflicts. Open the page in your browser and be amazed at your cleverness.

License

This article, along with any associated source code and files, is licensed under The Code Project Open License (CPOL)

Share

About the Author

Chris Maunder
Founder CodeProject
Canada Canada
Chris is the Co-founder, Administrator, Architect, Chief Editor and Shameless Hack who wrote and runs The Code Project. He's been programming since 1988 while pretending to be, in various guises, an astrophysicist, mathematician, physicist, hydrologist, geomorphologist, defence intelligence researcher and then, when all that got a bit rough on the nerves, a web developer. He is a Microsoft Visual C++ MVP both globally and for Canada locally.
 
His programming experience includes C/C++, C#, SQL, MFC, ASP, ASP.NET, and far, far too much FORTRAN. He has worked on PocketPCs, AIX mainframes, Sun workstations, and a CRAY YMP C90 behemoth but finds notebooks take up less desk space.
 
He dodges, he weaves, and he never gets enough sleep. He is kind to small animals.
 
Chris was born and bred in Australia but splits his time between Toronto and Melbourne, depending on the weather. For relaxation he is into road cycling, snowboarding, rock climbing, and storm chasing.
Follow on   Twitter   Google+   LinkedIn

Comments and Discussions

 
GeneralMy vote of 1 PinmemberBalasubramanian T23-Sep-13 19:52 
GeneralMy vote of 2 PinmemberMember 95240117-Mar-13 0:04 
GeneralMy vote of 3 PinmemberAbhisheik yk1-Jan-13 22:07 
QuestionExcellent post! PinmemberMember 868963822-Sep-12 7:04 
GeneralMy vote of 5 Pinmemberbajwa0135-Jul-12 1:48 
GeneralIt give build Error ! PinmemberMr Ashish Anand3-Jun-11 2:01 
GeneralMy vote of 2 PinmemberMember 323281315-Feb-11 22:07 
GeneralUser Control PinmemberMathewPV3-Nov-10 19:58 
GeneralMy vote of 2 Pinmembertmslvn13-Oct-10 16:50 
GeneralMessage Automatically Removed Pinmemberharsh07346-Aug-10 2:02 
GeneralMy vote of 5 PinmemberMember 33082472-Jul-10 9:47 
GeneralThanks PinmemberTom Klein13-Jul-09 22:32 
QuestionHelp register user control PinmemberNitin Kr Jain15-May-08 2:33 
GeneralSweet Pinmemberextremeg21-Feb-08 21:49 
QuestionIs there a VB version of this code? PinmemberVeeves23-Feb-06 4:30 
AnswerRe: Is there a VB version of this code? PinmemberTom Klein13-Jul-09 22:33 
GeneralDisplaying User Control without overlapping Pinmemberrajabunny13-Jul-05 17:53 
GeneralRe: Displaying User Control without overlapping PinmemberTicTac2Kcal2-Aug-05 21:39 
GeneralI know I'm making this harder than it needs to be. PinmemberChuck Lane8-Jul-04 10:39 
GeneralUserControl prop from code-behind of parent page Pinmembercolinhodges26-Apr-04 18:43 
QuestionHow to make it visible in FrontPage ? Pinmemberqt13-Mar-04 13:37 
GeneralCustumizing the checkboxlist control PinsussAnonymous22-Feb-04 4:39 
GeneralWeb Loader ASCX control Pinmemberitsmark4223-Dec-03 3:18 
Questionhow to pass value of a variable from one UC1 to another Pinmemberkkiran26-Aug-03 7:32 
GeneralCaching User Controls PinmemberMajid Shahabfar1-Apr-03 7:58 

General General    News News    Suggestion Suggestion    Question Question    Bug Bug    Answer Answer    Joke Joke    Rant Rant    Admin Admin   

Use Ctrl+Left/Right to switch messages, Ctrl+Up/Down to switch threads, Ctrl+Shift+Left/Right to switch pages.

| Advertise | Privacy | Mobile
Web01 | 2.8.140827.1 | Last Updated 16 Jan 2002
Article Copyright 2002 by Chris Maunder
Everything else Copyright © CodeProject, 1999-2014
Terms of Service
Layout: fixed | fluid