How to build a simple List to List Composite Web Control
By Guy Sofer

Visual Studio .NET 2003 (1.1)

Summary: List2List custom composite web control enables a developer to bind two Tables in a DataSet into two list boxes and enables the end user to move items from the source list box to the destination list box (Add). The end user will also be able as you can see in the screen capture to remove items from the destination list box and to order the destination list box items using the arrows – move up, move down.

We also implement in the level of the control a ListChange event for the developer who uses the control. There, the developer can get all the latest changes in the destination list box items (Added, Deleted, Un changed).

Last but not least – the control should eliminate conflicts when using more then one instance in the same ASPX (conflict on JS level or other)

What this article will cover

·                     Steps for building custom web control

·                     Keeping state of the control properties we are using during postback/s

·                     Define an Event in our control and subscribe to it from the application

·                     Adding JavaScript capabilities to our web controls

Downloads

·                     Demo / Source Code 

Introduction

ASP.NET enables us to re-use its out of the box web controls. ASP.NET also gives us a very rich infrastructure to build our own custom controls. We can do it when we need a functionality which does not exist in the out of the box web controls pool.

The different ways we can implement our custom controls are -

·                     User Control (ascx file) – – A way that enable us to create a new control functionality using VS.NET designer by dragging one or more existing server control to the designer and attach to this control our custom functionality . Because the user control compound from HTML and controls that contained in VS.NET designer the control compiled as part of the project it’s located in. This option will not enable us to compile the result code as stand alone assembly and locate the compile dll file in the GAC for re-using in all the web applications which located on the server

·                     Composite custom web control – A way that enables us to create a new control from one or more existing server control but instead of using the VS.NET designer we add the composite controls in our code where we also add the code for the functionality and behavior. The new control is stand alone and can be compile and deploy in the GAC for re-using at the server level. This is exactly what we need.

·                     Rendered custom control –  Instead of using composition of existing web controls and HTML controls like the previous methods we should construct the control entirely from HTML elements, attributes etc step by step. This gives us the most flexibility to things we can do while constructing the control but this is also the most complex way to build your own controls

Solution

In order to build our own composite custom web control we need a class that inherits from WebControl Class. This will gives our custom control the methods and properties of a web control. Part of the functionality can be overridden and extend. We also need to declare that our custom control support INamingContainer interface in order to get the ASP.NET plumbing to composite control IDs unique names (TODO: sample for IDs names - list2listctrl0:ourName, ctrl1:).

In order to create a project template in VS.NET 2003        for web control we need to open a new project from the template – Web Control Library.

The template created a basic control – which does not do much. I added to the project another new web control called List2List.

This is what we get from VS.NET:

We need to omit the method Render (don’t do it right a way – we would like to run it as it is) as its name applied, rendered HTML elements while stream it to the client as output. We will not use it directly.

Before you omit the Render method and the Text Property test the default web control by doing the following –

Add to the Web Control, Text property a constant return value – “Hello World”

Compile the control

Add another web application project to the solution

Add as Reference in the web application to the web control

Add the Web Control dll to the Control Tool Box menu (you can add to the Toolbox your own tab that will contain your controls). It will look like that –

Drag the control from the Toolbox and run the testing web application page

As expected – we will see the Hello World the control return from its Text property

Few words on ViewState – ViewState is a collection type instance that is available for us in each ASP.NET page. There we can hold key/value pairs. The ViewState mechanism is responsible to keep these values between round trips to the client and back to the server. The values are kept in a hidden input element called __ViewState when the page rendered on the server side and stream to the client. The data encrypted and restore when the client posts the page to the server.

ViewState is in a way similar to keep values in HTML form hidden elements. Hidden elements (not like the view state) available on the client directly using DOM (Html document Object Model)

There is no support to the VS.NET Designer but in order to get the minimum support we had to add at the control class level attribute declaration the following statement which state what is the class that handle the design

      DefaultProperty ( "Text" ),

      Designer ( "CustomControls.Design.TemplatedListDesigner, CustomControls.Design", typeof ( IDesigner ) )

      ,

      ToolboxData("<{0}:List2List runat=server></{0}:List2List>")]

The Properties List2List control supports are

List of Methods/Events we are using -

Controls Naming Conventions

OK – controls unique names handled by the ASP.NET framework the moment we declare that our custom web control support the INamingContainer

When a developer use two list to list custom control on the same page the controls name will be in this structure – namePrefix:nameSuffix

namePrefix – the name the developer gave to our control

nameSuffix – the name we gave to one of the composite controls

In grids control the principle is very similar but the namePrefix will contain a unique addition (ctl1, ctrl2 etc). I will get into it in a future article on Grids 

Example of grid naming prefix/suffix

Using ViewState

As specified in the previous section - ViewState enable us to keep truck on properties values during round trips from the server to the client and vice versa.

In the ViewState we keep the Control properties initial values. We will need the DataSet, where the source Table data located and the destination Table Data. In the Destination table we will maintain the Destination ListBox list of items.

In order to maintain the DataSet we need to override the build in base web control event – LoadViewState

Before we start any manipulations on the DataSource Property we have to call the base.LoadViewState with the event given argument. Afterward we can be sure the ViewState restored and ready for use

 View State Load Event Header

In the event as already mentioned we want to re-construct the Destination Items within the DataSource Destination Table

In this custom control all changes to the Destination ListBox been done on the client before a post occurred on the form. These are the available operations -

Add Item to Destination ListBox

Remove Item from Destination ListBox

On the client side we maintain a hidden input box that holds all the IDs of the Destination ListBox Items. We could not use the Destination ListBox for that – because in order to gets its items values on the server within the Request.Params collection we would need to select them before the Post occurred. This is how ListBox is working. 

List2List ListBoxes accessible internally using properties

The benefits to do so are the benefits of properties. In the property block (get/set) we centralize the code we need before accessing the property contained object and control the access to the data/object itself.

In our custom control within the ListBoxes get properties we check the existing of the ListBox, we create it if it’s the first access to it and we set its ID

Our DataSource Property

Here we create & define our DataSource using the given DataSet.

We define for each Table in the DataSet the relevant primary column to gain performance when accessing its rows

Building our Controls Display

Our Custom List2List control display created in this method. Here we construct the HTML table with all the other HTML elements in it that will transfer to our client. The using of a table enables us a better control of the HTML final result.

The controls we are using in order to accomplish all the functionality of the List2List custom control we are –

Two List boxes – Source List Box, Destination List Box

Hidden Input Box – to keep all the items IDs we have in our Destination ListBox.  On round trip to the server we will use its values (between each value we use comma delimiter) to update the internal DataSource destination Table

Add Button – enable the user to add the selected item from the source list box to the destination list box

Remove Button – to remove the selected item from the Destination List Box

Move Up Link Button – enable to move one step up the selected item in the destination ListBox

Move Down Link Button - enable to move one step up the selected item in the destination ListBox

On this stage we also add the JavaScript functions calls. We attach it to the different buttons.

Overriding LoadViewState Method

In this build in event we override from the base control we update the DataSource destination Table.

Before accessing to the Destination table we ensure that ViewState mechanism did his work and restore the ViewState properties by calling the base.LoadViewState

After we have the destination table we remove from it all the items that don’t exist in the Hidden field where we have the user selected items IDs. Afterward – we add all the items that the user selected and exists in the Hidden field values but still does not exists in the Destination Table.

If we discover a change during the process mention above we raise the OnChange flag

According the OnChange flag we know if we should raise the ListChange Event

Declare the OnChange Event

We first define the delegate type method signature that we will use to define our OnChange event. A developer should subscribe to our ListChange Event by pointing his delegate implementation to our event

This been done as follow -

Then we need to define our internal ListChange Handler. The principle is the same with why we are using properties – we don’t raise the external events directly – we do it from our internal event handler. This centralizes our code, enable us more control on what will be done before and after the external event will be raised

The last thing to do is to raise the above internal event the moment a change been done in the Destination Items.

This will be done in the LoadViewState event that was describe in the previous section

Binding our ListBoxes – DataBind Method

There is nothing much to explain here. The ListBoxes been bounded to their equivalents Tables

Overriding the PreRander Event

Here we usually add the JS client functionality

We concatenate a string that holds the JS function and we attach it to our page using the following code –

Client JavaScript functionality

The functions we use are –

function list2list_Add(rootName)

function list2list_Remove(rootName)

function list2list_SetNewValues(rootName)

function list2list_MoveUp(rootName)

function list2list_MoveDn(rootName)

We always send the rootName which is our custom control Client unique ID which will be use as prefix for any element we used in our composite control. The moment we have it we can access to our Lists object by using the following syntax and base on the prefix we have

How to use the Control –

In order to use the control we need to create a DataSet with two tables. The first Table should contain the Source ListBox items and the other will be use for the Destination ListBox items.

One limitation when we supply the input DataSource DataSet is that we have to supply the Destination Table & its schema definition – even if it’s empty. You cannot supply only a Source Items

This is something that should be improved in the future.

We can drag the Control from the ToolBox

Then add to it the declarations in the HTML layout:

<cc1:list2List id, runat, HeaderText,

child element for the

<TableSource with the attributes – TableName, DataTextField, DataValueField,  

<TableDestination with the attributes – TableName, DataTextField, DataValueField, 

We should subscribe to the List2List event to get the changed items in the Destination List Box

And define the event handler

That’s all fox :-)