Introduction

The web control we are about to build is considered a container control, just like the ASP.NET Panel control. Actually if you set the GroupingText property of the Panel control you'll end up with what we are going to implement in few seconds, however with some limitations.

Html element that represent a GroupBox like shape

The <fieldset></fieldset> element with the <legend></legend> element embedded inside will give you the shape of a GroupBox. It's worth mentioning that the fieldset element is a block element just like the div element. Our web control will render a fieldset html tag, and if the caption is defined, a legend html will be rendered inside the fieldset element.

Overriding the WebControl Class

Before we go through this, I'd like to mention that the WebControl class is a good example to show how Template design patterns are implemented. The WebControl class defines an overridable method called Render(HtmlTextWriter writer) which is inherited from the Control class. This method acts as Template Method. The typical implementation of this method looks like this:

As you can see above, the method invokes three other methods in sequence RenderBeginTag(writer), RenderContents(writer) and RenderEndTag(writer). In our GroupBox control, we will override the 1^st and 3^rd methods, and let the base Render method do its job as a Template and invoke our overridden methods.

Overriding the rendering related methods of WebControl Class

In this section, we will go through the implementation of the following methods:

1. AddAttributesToRender(HtmlTextWriter writer)
2. RenderBeginTag(HtmlTextWriter writer)
3. RenderEndTag(HtmlTextWriter writer)

AddAttributesToRender Method

This method adds the necessary HTML attributes and styles that need to be rendered to the specified HtmlTextWriterTag method. The simplest implementation of this method just makes a call to the base.AddAttributesToRender(writer), and this is what most of us will do, in addition to any extra attributes you might wish to render, e.g. specifying content's direction or horizontal alignment. Although these properties are specified and handled by the GroupBoxStyle as we will see later, I thought it is worth mentioning how to use the AddAttributesToRender method incase they are not specified in the control style class.

RenderBeginTag Method

This method renders the HTML opening tag of the control to the specified writer. Our GroupBox control specifies the <fieldset> tag as the TagKey in the constructor as seen in the following code statement:

The GroupBox implementation of the RenderBeginTag invokes the AddAttributesToRender method at the beginning and checks if the Caption is specified. If it is, it will render the Caption using the <legend> tag.

As you might notice in the above code, the RenderCaption method is used to render the <legend> tag to display the Caption; it will also render the CaptionStyle if the Style is specified. The CaptionStyle is an instance of Style. In the Panel control you cannot specify the style for the GroupingText. The CaptionStyle is stored in the ViewState. Later in this article we will see how to manage the ViewState to track the CaptionStyle property.

RenderEndTag Method

This method renders the HTML closing tag of the control into the specified writer. As long as our control is very simple and does not include complex rendering mechanism; this method can simply call the base.RenderEndTag(writer), of course this will render the closing tag for fieldset tag.

Render Method

You might ask yourself, whether we shall implement the Render method or not? The answer was mentioned earlier in this article. The WebControl class already implements this method in a way that we can use it as shown in the first code snippet. We will also not implement RenderContents method as there is no need for that.

Maintaining ViewState

Earlier we mentioned something about the CaptionStyle property; this property is a Style object stored in the ViewState and used to render GroupBox's Caption style. The code below shows how the CaptionStyle property is flagged for the ViewState for the tracking purpose.

To complete the ViewState tracking and maintaining, we'll have to override the following three methods

1. TrackViewState()
2. SaveViewState()
3. LoadViewState(object savedState)

It is worth mentioning that the style object can maintain its own ViewState by itself, so this will simplify our job; as we will just make calls to the related ViewState tracking methods, TrackViewState, SaveViewState and LoadViewState.

TrackViewState Method

The TrackViewState method causes the control to track changes to its ViewState so that they can be stored in the object's ViewState property. Again here we will invoke the TrackViewState method for our _captionStyle instance.

SaveViewState Method

This method saves any state that was modified after the TrackViewState method was invoked. We will invoke the base.SaveViewState(), this should return what is saved by the base class. Then we will call the SaveViewState method of our _captionStyle instance.

LoadViewState Method

This method restores the ViewState information from the previous request that was saved with the SaveViewState method. Here we are loading the saved information from the ViewState.

Building the GroupBox typed style, GroupBoxStyle

I thought of building a custom typed style class for the GroupBox control, the GroupBoxStyle. It will contain two properties to specify the horizontal alignment as well as the direction (right to left or left to right). As a beginning we will override the CreateControlStyle method of the GroupBox control to return a new instance of GroupBoxStyle.

GroupBoxStyle

The GroupBoxStyle typed style class will be used to delegate the style functionality. It exposes 2 style properties, HorizontalAlign and Direction. Of course you might suggest more properties like Wrap or Display. For simplicity will only focus on our 2 properties. These two properties are also defined in the GroupBoxStyle class. Before we go further, here are the basic steps to write the typed style class:

1. Create a class they derives from System.Web.UI.WebControls.Style
2. Define style properties that your control will offer and store them in your style's ViewState. In our case they are HorizontalAlign and Direction
3. Override Style.CopyFrom and Style.MergeWith methods to copy from or to merge the properties you defined with properties for a given style
4. Override Style.Reset method to remove the properties you added to the ViewState
5. Override the Style.AddAttributesToRender method to generate HTML and CSS attributes as part of the rendering process.

Important note: The above list is taken from "Developing Microsoft ASP.NET Server Controls and Components" book written by Nikhil Kothari and Vandana Datye.

The GroupBoxStyle Derives from Style class

The GroupBoxStyle class derives directly from the Style class and defines two properties HorizontalAlign and Direction. These properties support the corresponding style properties in our control.

Overriding the Style.AddAttributesToRender

The GroupBoxStyle class calls the base class method and then performs its own logic, just as the following:

Overriding the Style.CopyFrom and Style.MergeWith methods

The CopyFrom method will replace the existing property values with those properties that have been set in the Style instance that are passed to the method. This method invokes its base class method and then performs its own logic.

The MergeWith method will preserve the values of the properties that are already set and copies other properties that are set in the Style instance passed to the method. This method invokes its base class method and then performs its own logic as well.

Overriding the Style.Reset method

The Reset method will remove the properties that were added to the ViewState. Again this method invokes the base class method and performs its own logic.

Style ViewState

I'm sure you have noticed that we used Style ViewState to store our properties as the Style class already maintains the ViewState by default.

Conclusion

In this article we discussed how to build a simple container control similar to the ASP.NET Panel control. We have seen how to give our control additional style features by supporting the style for the caption and building custom typed styles for the control.

The attached code supports design time features for the GroupBox control. As this article got long enough, I thought I might discuss the design time support by building a simple custom control designer on another article referencing this article. Just for a hint, if you wished to build a custom control designer for container control like this one, you'll need to derive from the ContainerControlDesigner class.

You also could also easily add additional style properties like support for the background image and scrolling contents. You might also add a caption image etc... All these are sample practices to put your hand on first steps to develop custom controls.

Download

GroupBox source code and demo (57KB)

References

Developing Microsoft ASP.NET Server Controls and Components

About Muhammad Mosa

Sorry, no bio is available This author has published 8 articles on DotNetSlackers. View other articles or the complete profile here.

---

Discussion

Subject	Author	Date
Very Nice	Chandler Smith	5/5/2007 8:29 PM
Waiting to read about design time support! I'll try to figure it out myself from the code anyway. Thanks for the hint Reply | Permanent link
Very good start for beginners	Cadmus K	5/12/2007 5:37 AM
I liked the idea! A very good startup point to get started with custome server controls. cool! Reply | Permanent link

---

Please login to rate or to leave a comment.