,

etc) -->

Introduction

Have you ever wanted to build a custom web control, but lost confidence once you started to navigate the MSDN information ocean? Ever wanted to build a web control only to find out that you don't know where to start and worse yet there are no comprehensive examples available on the internet? If you have faced any or all of these situations, sit back and relax! Throughout this article I will detail the major "gotchas" relating to building a custom web control and deploy it to your web application.

About Web Controls

Web Controls should be designed with the following considerations in mind; alleviate repetitive, complex tasks and add new functionality to your web pages (web forms). After wading through numerous resources, I discovered that .NET controls for the web can come in many different varieties! In short, web controls can be broken down into 6 logical types (classes):

HTML Server Control

Web Server Control

Web Validation Control

Web User Control

Composite Control

Custom Control

Since we are going to focus on custom controls, I will limit discussion on all other types to a basic definition.

Web Server Control: Web Server Controls are designed to provide a quick, easy way to add functionality to your web pages. These controls provide for up and down level browser support. The core requirements for Up-level Browsers are; ECMAScript (JScript, JavaScript) support, HTML version 4.0 compliance, Supports Microsoft Document Object Model (MSDOM) and Cascading style sheets (CSS) support. Additionally, these controls can be used to build more complex server controls.

Web Validation Control: Validation controls provide you with a way to check user input in Web or HTML server controls. Attach validation controls to input controls to test what the user enters for that input control.

Web User Control: Web User Controls are created like Web Forms pages. These controls can be embedded into other Web Forms pages and are an easy way to create menus, toolbars, and other reusable elements. These types of controls always end with the extension of .ascx and must be included separately in each project that uses the control. Web User Controls are dynamically compiled at run time.

Composite Control: Composite Controls combine the functionality of two or more existing controls and can expose custom properties and events. Basic requirements for implementation: must override the CreateChildControls method inherited from Control and must implement System.Web.UI.INamingContainer interface for unique naming convention.

Custom Control: Custom Controls are fully authored, pre-compiled code (.dll) and are a good choice for dynamic web page layout. The major advantage of Custom Controls is full design-time support, to include: Toolbox Integration, Visual Designers support and interfacing with the Property Grid. These controls can be installed to the Global Assembly Cache (GAC) which will allow multiple applications to share a single control.

Classy Choices - enter System.Web.UI

The System.Web.UI namespace provides classes and interfaces that allow you to create ASP.NET server controls and pages that will appear in your Web applications as user interface elements. This namespace includes the Control class, which provides all server controls, whether HTML server controls, Web server controls, or user controls, with a common set of functionality. It also includes the Page class, which is generated automatically whenever a request is made for an .aspx file contained in your Web application. You can inherit from both of these classes. Also provided are classes which provide the server controls with data binding functionality, the ability to save the view state of a given control or page, and parsing functionality for both programmable and literal controls."

The two classes that we will focus on for the purpose of this article are UserControl and WebControls. User controls are contained in ASP.NET Web Forms pages, and offer Web developers an easy way to capture commonly used Web UI. They are instantiated and cached in ways similar to Page objects. Unlike pages, however, user controls cannot be called independently. They can only be called from the page or other user control that contains them.

The WebControl class provides the properties, methods, and events that are common to all Web server controls. You can control the appearance and behavior of a Web server control by setting properties defined in this class. For example, the background color and font color of a control are controlled by using the BackColor and ForeColor properties, respectively. On controls that can display a border, you can control the border width, the border style, and the border color by setting the BorderWidth, BorderStyle, and BorderColor properties. The size of a Web server control can be specified by using the Height and Width properties.

The behavior of the control can be specified by setting certain properties. You can enable and disable a control by setting the Enabled property. The place of the control in the tab order is controlled by setting the TabIndex property. You can specify a ToolTip for the control by setting the ToolTip property.

Enough Already! How does it work?

Now that all the basics are out of the way, lets examine the class I implemented for WebChart. The WebChart control is inherited from System.Web.UI.WebControls.WebControl. By inheriting this class I have achieved "free functionality" such as Height, Width, BackColor and ForeColor. Not bad considering this is one line of code! Additionally, I will override the Render method of MyBase to display my user drawn GDI+ chart. The following code example shows how to inherit from System.Web.UI.WebControls.WebControl:

The above code block is relatively easy to understand, but what's all the stuff above the class statement? These are known as attributes. When you compile your code for the runtime, it is converted into Microsoft intermediate language (MSIL) and placed inside a portable executable (PE) file along with metadata generated by the compiler. Attributes allow you to place extra descriptive information into metadata that can be extracted using runtime reflection services. The compiler creates attributes when you declare instances of special classes that derive from System.Attribute. The ToolBoxData Attribute specifies how the control will be named when placed on an ASP.NET web form. The ParseChildren Attribute must identify the indexed property you will hold your collection within. The ToolboxBitmap Attribute is used to supply a custom icon for your control. The icon must be 16 x 16 and be restricted to 16 colors. The bottom left corner of the bitmap is used as the transparency color. Lastly, the icon for this project is set as an embedded resource and is named the same as the Root Namespace.

Delving deeper into the WebChart Class, we will look at enumerations and properties:

Scalar Property (above): Notice that the public property Type is declared as the type ChartType. This will allow the Property Type to contain a drop down box populated with the 'English' values to be displayed in the property grid. Also, by initializing the mChartType property to ChartType = ChartType.Bar you are effectively assigning a default value to your property! The Attribute DefaultValue is set to get the type ChartType via Reflection and set the value to "Bar". In the property grid default values are not bolded, values which have changed from their default property will be displayed as bold text. The Category Attribute determines which category this property will be associated with on the PropertyGrid. Last, the Description Attribute is used to give the developer an idea of what the property does.

Indexed Property: Our indexed property WebChartItems is ReadOnly because it only controls the return of our collection object. Keep in mind that a WebChartItem is added to the WebChartCollection either through the PropertyGrid or code. This allows for static values to be added to the control or using code both charts can be dynamically populated with a DataSet or XML source. Two new Attributes can be examined on this property: DesignerSerializationVisibility - This property will control how data from our indexed property is persisted, PersistenceMode - InnerDefaultProperty specifies that the persisted data will be stored as nested elements instead of attributes of the control.

Adding WebChart to the Toolbox

In order to use the WebChart control you must first build it. After the control has been compiled, you must reference it in you ASP.NET Web Application Project. Once the control has been referenced, go to your Toolbox and right-click. Select Customize Toolbox and go to the .NET Tab and browse for the .dll you compiled. After selecting the .dll you will see an icon (see picture at top of article). If you are not sure how to do any of the above, please look in VS.NET help documentation.

Example use

Adding the control at design-time is straight forward, use it like any of the native ASP.NET Controls. However, you must insert the following XML tags into your Web.config file directly underneath the opening <SYSTEM.WEB> tag (see below). This tag allows ASP.NET to track WebChart images via Application Variable. The <httpModules> tag is required for proper WebChart operation. The following code block shows how to create a pie type WebChart dynamically with an ADO.NET DataReader Object:

REQUIRED: Place the following httpModules XML in your local Web.config.

WebChart Credits

Special thanks to Mohammed Banat at eSense Software, Development and Consulting, for help on HTTP streaming which allows WebChart to draw charts directly to the Output.Response stream with no additional external web pages.

License

This article has no explicit license attached to it but may contain usage terms in the article text or the download files themselves. If in doubt please contact the author via the discussion board below.

Comments and Discussions

I was more interested in this article for creating the pie and bar charts as opposed to learning how to create a server control.The charts look great and are easy to use.Are there any updates to them? DatabindingDifferent Types of charts