Reader Level:

Building the ListBoxesFT_C ASP.NET Web User Control in Visual Studio 2005: Part I

By Michael Livshitz on Nov 07, 2006
In multi-part article, I share how you can build your own ASP.NET web user control.

I am sure , that if you are a developer who works for a ASP.NET "big project" (I mean a project that includes at least more than ten web forms),  from time to time you need to create some Web server control that has functionality and interface not provided by the standard ASP.NET Web Server Control. In this article I share how you can build your own ASP.NET web user control ( custom control, usually, is more complex  and used for more "global" tasks; this is a special theme). As example, I use control which includes at least two built-in ASP.NET Web server controls (ListBox controls) and allows "to make data exchange" between them :

  1. By using server side process (PostBack );
  2. By using only your own client script  (without using PostBack).

Saying "client script" I don't mean "something without a full PostBack to the server" (XmlHttp object, ICallbackEventHandler method, etc. This is very interesting but for another discussion). The examples are written using C# and JavaScript.

We define the task as follows.

To build Web User Control, named ListBoxesFT_C, that allows to select from input data (as "input DataTable") needed items and then to get selected data (as "output DataTable") on the parent web page. The control should include the following basic built-in ASP.NET Web server controls : two ListBox controls, named ListBoxFrom and ListBoxTo (to display and select "input" and "output" items); two Button controls to manipulate data ("to transfer" items from one ListBox into another); two Label control to specify ListBox controls (with the text "List" and "Select").  The control should look as follows (fig 1.).


Figure 1.

The ListBoxesFT_C control should have the following properties:

  • C_DataIn , type of "DataTable", that allows to set item list  for the control;
  • C_DataOut, type of "DataTable", that allows to get selected items on the parent page;
  • C_LabelFrom , type of "string", that allows to set and get the text  of  the button, "transfering" items from "List" into "Select"; default text is ">>";
  • C_LabelTo , type of "string", that allows to set and get the text  of  the button, "transfering" items from "Select" into "List"; default text is "<<";
  • C_WidthLB , type of "int", that allows to set and get the width of the ListBoxes controls; default value is 60;
  • C_HeightLB , type of "int", that allows to set and get the height of the ListBoxes controls; default value is 120;
  • C_SortBy , type of  "int", that allows to set and get number of the column for sorting the "input" DataTable; default value is 1;
  • C_SortByText, type of "bool" , that allows to set and get  value for sorting items of the ListBoxes on client side; when "true" - items are sorted by DataTextField, when "false" - by "DataValueField"; default value is "true";
  • C_Client , type of "bool" , that allows to set and get value , which defines type of "data exchange" between ListBoxes (client or server); default value is "true".

OK! First of all we have to have the Web site project to which we will add our web user control. We create the project named "WebSites_Test". The way, that I recommend to work, is to add to your project the special folder named "UserControls". Into this folder you "can put" all user controls which you need for your project. Now, right click on the folder and then left click on "Add New Items.....". From "Visual studio installed templates" select "Web User Control". Type the name "ListBoxesFT_C" and click "Add" button. Of course, when building and after building the control we have to test the control. Do you remember ? we have decided that you are one of developers of a big team working for a "big project". This is : the control cannot been tested on any "working" form (may be your friend, exactly in this time  works with the form, or just the form already "works" in some process, etc. )  but only on the special testing form for this control. This form should have additional controls to model real situation. The other web user control can have any different "real situation". From this point of view it is better for every web user control of our project to have some special test form (of course, each project "dictates" its own situations and for some project there is no need for any test form). OK! We add to the project the folder named "WebForms_Test" and to this folder we add the web form named "WF_ListBoxes". Of course, we need some data base (or its simulation). With this purpose we add reference to GetData.dll. One more point. Imagine you build some user control, your friend of your team builds some control too, etc. From time to time your team leader just have to check up any (or may be - all !) user control. The best way to help him is to create some web page from which there is possibility "to get" (to link) any web user control of your project.  For this purpose we just use Default form with the Menu control (of course, you can use some other form and, for example, the Button control ). Well ! now our solution looks so (fig.2) :


Figure 2.

OK ! We can begin to build our web user control. According to the task from the Toolbox  drag and drop on "Design" of the ListBoxesFT_C such Standard control as: two ListBoxes, two Labels, two Buttons. Add such HTML control as: two Input(Button), four Input(Hidden). These control we will use for "client side" process (more detailed purpose of these controls will be clear further). Change "runat" attributes of HTML controls to "server". All our controls we place inside of two tables (fig 3.) :


Figure 3.

The source of the design is the following:  

<div style="text-align: center">

    <table id="TableBorder" runat=server border="1">


            <td align="center" style="width: 100px" valign="top">

                <div style="text-align: center">

                    <table id="TableListBoxes"

                            style="width: 100%; height: 100%" >

                        <tr align =center >

                            <td style="width: 100%; height: 100%">

                                <asp:Label ID="LabelFrom" runat="server" Text="List"></asp:Label>


                            <td style="width: 100%; height: 100%">&nbsp;


                            <td style="width: 100%; height: 100%"  >

                               <asp:Label ID="LabelTo" runat="server" Text="Select"></asp:Label>


                        <tr align =center >

                            <td style="width: 100%; height: 100%">

                                <asp:ListBox ID="ListBoxFrom" runat="server"></asp:ListBox></td>

                            <td style="width: 100%; height: 100%">

                                <p ><asp:Button ID="ButtonFrom" runat="server" Text=">>"

                                     OnClick="ButtonFrom_Click" CausesValidation="False" />  

                                <input id="ButtonHTMLFrom" type="button" value=">>"  runat=server/></p>

                                <p><asp:Button ID="ButtonTo" runat="server" Text="<<" OnClick="ButtonTo_Click"
="False" />

                                <input id="ButtonHTMLTo" type="button" value="<<" runat=server /></p></td>

                            <td style="width: 100%; height: 100%">

                                <asp:ListBox ID="ListBoxTo" runat="server"></asp:ListBox></td>




<input id="HiddenFromValue" style="width: 23px"

        type="hidden" runat=server/>

<input id="HiddenFromText" style="width: 23px"

        type="hidden" runat=server/>

<input id="HiddenToValue" style="width: 23px"

        type="hidden" runat=server/>&nbsp;

<input id="HiddenToText" style="width: 23px"

        type="hidden" runat=server/></td>




OK! Now we are ready to write code for the class UserControls_ListBoxesFT_C. As usual, let's drink a cup of coffee before we shall pass to the second part .

Good luck in programming !

Michael Livshitz
Michael Livshitz

Michael is a lead programmer for a large technological firm. He has experience working with .NET projects (ASP.NET and Windows) since 2002. Currently used languages are C#, VB.NET, T-SQL and JavaScript. He also has exper... Read more