BLOGS BY TOPIC
BLOGS BY AUTHOR
BLOGS BY YEAR
User controls are the key to using ASP.NET effectively - this blog explains how and why to create and use user controls, with code examples for VB and C#.
- User Controls in ASP.NET (this blog)
- How the User Controls will Work for our Case Study
- Raising Events for User Controls - Visual Basic
- Raising Events from User Controls in C#
- Problems with User Controls in ASP.NET
Posted by Andy Brown on 17 October 2012
You need a minimum screen resolution of about 700 pixels width to see our blogs. This is because they contain diagrams and tables which would not be viewable easily on a mobile phone or small laptop. Please use a larger tablet, notebook or desktop computer, or change your screen resolution settings.
User Controls in ASP.NET
I think there are two keys to writing effective websites in ASP.NET. The first is to understand data classes; and the second is to use user controls liberally.
There are a couple of things that you can do to make life with user controls easier. One is to use VB, not C# (although this blog shows both); and the other is to bear in mind the issues that Visual Studio has with user controls, as set out at the end of this blog series (they're not a problem if you know about them).
Simple User Controls
Consider the example I've used throughout this ASP.NET tutorial: creating a searchable to-do list. Here's what happens when a user does something wrong:
If you try to add a task without typing in text, you see an error message.
This error message may appear several different places. You want to make sure it has a consistent look, and is easy to use. The answer - as so often in ASP.NET - is to put it in a user control.
Creating the User Control
A user control is just part of a page, so one way to create it is to include it as part of a page, then extract the HTML lines of interest and copy them into the user control:
The error will show up in a div tag with a CSS class set.
The main difference between a user control and a page is the file extension (ascx, and not aspx).
Having worked out what your user control will include, start to create it:
Right-click on your project and choose to add a new item to it.
You can now give your user control a name, and choose a language:
The numbered steps are listed below.
The numbered steps to follow are:
- Choose a language (VB or C#).
- Choose to create a user control.
- Give your user control a name (Wise Owl have a convention that they should all begin wtih uc - I'm not sure how universal this is).
- Choose to add it (the master page option is greyed out because a user control can't have a master page).
You will now see something similar to the following (the C# version would look identical):
The only difference between this and a page directive is the highlighted word.
You can now either create the HTML for the user control, or copy it in from a page:
|Design view||Source (HTML) view|
Two things to note here are:
- The styles aren't applied in design view, because at this stage the user control can't know what style sheet the main page will be using.
- Don't be afraid to give controls on user controls the same name as those on the containing page. The two are managed independently.
Including the User Control on a Page
By far the easiest way to add a user control to a page is to drag it on in design view:
Click on the ucError.ascx user control and drag it to the correct position on the page.
This will give you the user control in design view:
The user control appears where you drag it (you can click to edit it separately).
In source view you can see what's happened:
The user control is registered at the top of the page, and used within it.
Here are the two lines of interest for our ucError user control. First the page registers that it will use our user control:
You can change the tag name and tag prefix to any sequence of characters you like.
We then include this user control somewhere on our page:
You must use the same tag name/prefix as when you registered the user control.
Giving User Controls Properties
Our achievement so far is underwhelming: all we've done is to get the same error message appearing at the top of every page:
The error message shows up at the top of the page.
As it happens, we've made the div tag in the user control invisible, so you wouldn't even see this!
We need some way to specify how the user control displays, and the easiest way to do this is to give it a property (usually best) or method. Let's call this property ErrorMessage. Here's how it will look inside our user control in VB:
Partial Class ucError
WriteOnly Property ErrorMessage As String
Set(value As String)
'tells the user control what to display
'(main page should have made it visible)
divError.InnerText = value
Here's the C# equivalent:
public partial class ucError : System.Web.UI.UserControl
public string ErrorMessage
// set how error message appears
divError.InnerText = value;
Here we're using a div tag running at the server to display the text; normally I would use an ASP.NET literal web server control to make life easier. They both do the same thing.
Changing User Controls from a Main Page
Now that we've given our user control a property, you can set this in either your HTML or in code. In HTML you would just specify the ErrorMessage property for the control:
The ErrorMessage property will appear in Intellisense when you start to type it in!
Although this looks impressive, you nearly always use code to change user control properties. Here's how we'd set an error message in VB:
'if error found, show it
ucError1.ErrorMessage = ThisErrorMessage
ucError1.Visible = TrueÂ
And here's the C# equivalent:
// if error found, show it
ucError1.ErrorMessage = ThisErrorMessage;
ucError1.Visible = true;
When the main page sets the ErrorMessage property of the user control, the user control will change the inner text for its divError tag to display the error!
Hiding the User Control on Page Load
We have one problem left: we need to make sure that the error message doesn't appear permanently, once set. To do this, just hide the user control whenever the page loads, whether in VB:
Protected Sub Page_Load(ByVal sender As Object,
ByVal e As System.EventArgs) Handles Me.Load
'hide error messages on every load
ucError1.Visible = False
Or in C#:
protected void Page_Load(object sender, EventArgs e)
// hide error on every load
ucError1.Visible = false;
Although initially the error message will be hidden for every page, subsequent events may display it.
A Footnote - Multiple User Controls and Nested User Controls
It's a common scenario to include multiple versions of a user control on the same page, and to put one user control within another. Consider a simple toolbar:
The humble Wise Owl intranet's main toolbar (don't ask what Wes Brown is doing there!).
This comprises a single user control called ucMenu, which itself contains 10 instances of a user control called ucMenuButton. If you look at the ucMenu control you'd see something like this:
The menu user control includes 10 menu buttons.
Of course, you've still got the problem of how to get the menu buttons to tell a webpage that they've been clicked, but I'll cover raising events later in this blog.