ASP.NET Custom Server Controls: Cute ASP.NET TextBox with Help Tips

---

A downloadable file for this article is available here.

---

The sample downloadable solution (zip) is entirely developed using Visual Studio.NET 2003 Enterprise Architect on Windows Server 2003 Standard Edition.  But, I am confident that it would work with other versions of Windows (which support .NET 1.1) as well.

Introduction

My previous articles have already shown you how to create any custom control from scratch.  Now, I will not be going into the details of creating a solution, project, etc.  I will just take this opportunity to explain the features available and how they have been implemented in the above downloadable VS.NET solution.

When we developed an ASP.NET product in our organization, one of our customers asked us to enhance the product with “help” wherever possible.  As you know, if it is a web application, just tool tips should do the job.  But they rejected our proposal.  We asked them if they needed a popup. Again, the answer was NO.

They asked us to provide some type of “help tips” (always at some corner) for each and every field (during data entry) they would input.  Finally, we understood that when any “server control” receives a focus (or on mouse events), some “help tips” have to be displayed in some “panel” (so that we can place the panel at any corner).

As you know, this is not really ASP.NET. We needed to add extra JavasScript “tidbits” for each and every control.  As we had already completed that project, there exists no other way to accomplish this, apart from adding JavaScript for every control throughout the application.  But, what if we needed to provide the same thing for a new project?  The solution would be to develop our own server controls by extending the existing ones, and adding some JavaScript at the control rendering level to emit it at client-side (along with design-time support). 

In this article, we develop a simple textbox with help tip support, right from scratch (even without extending from an existing textbox control in ASP.NET).  I used four new methods of rendering.  They are as follows:

• RenderBeginTag
• RenderContents
• RenderEndTag
• AddAttributesToRender

To be frank, all of the above methods are not really necessary for the TextBox control I developed.  But, this gives me an opportunity to explain all four simultaneously.  We can also implement all of our controls in a single “render” method as well.  But, the above methods give much more flexibility by separating various divisions of rendering.

Understanding the life cycle – Rendering methods

The default “Render” method (when not overridden by us) usually calls “RenderBeginTag” before calling any other methods.  The “RenderBeginTag” method in my control has been implemented something like this:

Public Overrides Sub RenderBeginTag(ByVal writer As
System.Web.UI.HtmlTextWriter)
        AddAttributesToRender(writer)
        writer.RenderBeginTag(HtmlTextWriterTag.Input)
    End Sub

Within the above method, I am trying to call the “AddAttributesToRender(Writer)” statement to add any attributes to my textbox control (the INPUT tag).  In fact, it is not a user defined method; it has already been defined within the “WebControl” class and I am about to override it.  Usually, the “AddAttributesToRender” method gets initiated from within the “RenderBeginTag” method (as the first statement).  I hope you can understand the second statement, which actually renders only an INPUT tag (with all the attributes emitted by “AddAttributesToRender” method).

Coming to the next code fragment, I have an empty method as follows:

Protected Overrides Sub RenderContents(ByVal writer As
System.Web.UI.HtmlTextWriter)

    End Sub

The above method does nothing.  Then is it necessary to include it?  Maybe YES and maybe NOT.  If we don’t include an empty “RenderContents” method, it will try to search for child controls within our textbox control and try to render them by calling “base.Render(writer)” internally.  In this case, we don’t have any child controls.  So, I don’t need the default implementation (which actually calls the base class related “render” method to render all child controls).  So, I override that method and made it empty. 

It doesn’t matter, even if you omit the above code fragment without writing, as it would do an unnecessary search for child controls and finally leave off.  Including the above is a professional way to let the others know about the life cycle.

Going further we have the following:

Public Overrides Sub RenderEndTag(ByVal writer As
System.Web.UI.HtmlTextWriter)
        writer.RenderEndTag()
    End Sub

The above method simply contains a statement “writer.RenderEndTag”.  We already opened a beginning tag using “writer.RenderBeginTag(…)” within the “RenderBeginTag” method.  We didn’t close it anywhere.  And we do that using the above method.  You need not even specify which tag to close.  It could automatically understand (from our proper HTML hierarchy) which tag to close.  That’s the beauty of ASP.NET custom control development.

Understanding the life cycle – Attributes

In the previous section, we have already seen the methods implemented for rendering the control.  But, we didn’t deal much with the “AddAttributesToRender” method.  In this section, we will deal with it.

The “AddAttributesToRender” method is basically used (or overridden) to add HTML attributes and styles that need to be rendered for the respective custom control.  In my solution, it has been implemented as follows:

Protected Overrides Sub AddAttributesToRender(ByVal writer As System.Web.UI.HtmlTextWriter)
        MyBase.AddAttributesToRender(writer)
        writer.AddAttribute (HtmlTextWriterAttribute.Name,
Me.UniqueID)
        writer.AddAttribute (HtmlTextWriterAttribute.Id,
Me.ClientID)
        writer.AddAttribute (HtmlTextWriterAttribute.Type,
"text")
        writer.AddAttribute (HtmlTextWriterAttribute.Value, Text)
        writer.AddStyleAttribute
(HtmlTextWriterStyle.BorderColor, ColorTranslator.ToHtml
(Color.DarkGray))
        writer.AddStyleAttribute
(HtmlTextWriterStyle.BorderStyle, "solid")
        writer.AddStyleAttribute
(HtmlTextWriterStyle.BorderWidth, "1px")
.
.
    End Sub

I removed some of the statements (explained later) from the above method for the sake of clarity.  Within the above method, if you carefully observe, the first statement is “base.AddAttributesToRender(writer)”.  Is this necessary?  Of course, YES.  It is always a good practice to have the statement “Base.AddAttributesToRender(Writer)” as the first statement within the above method.  Never remove it (unless you have a reason to do so).  There also exists one more secret behind it. 

During the design time of VS.NET, you may be moving the control to your favorite location (or adjusting its size, or even changing some of its properties).  All of that information (say CSS) would be remembered and again written back to our control using this statement.  If you forget this statement, your control works in a floating manner at the left-top of the web page (without having any design time attributes set).

You must have observed that there exist some statements starting with “writer” as following:

writer.AddAttribute (HtmlTextWriterAttribute.Value, Text)
        writer.AddStyleAttribute (HtmlTextWriterStyle.BorderColor, ColorTranslator.ToHtml
(Color.DarkGray))

The first statement (writer.AddAttribute) is generally used to emit an attribute of a tag.  You can use all existing attributes from “HtmlTextWriterAttribute” or simply provide your own string in quotations.  The second statement (writer.AddStyleAttribute) is generally used to add style (or inline CSS) to a tag.  You can use all existing styles from “HtmlTextWriterStyle” or simply provide your own string in quotations.  Finally, I am happy to say that we have “ColorTranslator” to emit .NET based color constants to HTML based color constants.

Emitting necessary properties

Since we now understand some of the rendering methods of this control, let us go through some of the properties which may be necessary at design time.  I exposed five properties to facilitate customization.  They are as follows:

• Text
• HelpTipDispControl
• HelpTipText
• ShowHelpTipsOnFocus
• ShowHelpTipsOnMouse

All of the above properties are supported with “viewstate”.  If you are new to “viewstate”, I suggest you to go through my previous set of articles (in the same series).  Now, let us look at each of them.

I hope everyone could easily imagine the “Text” property, the classic property for displaying some text in the textbox.  We have one more property resembling this,  called “HelpTipText”.  The developer can use this property to assign some text which needs to be displayed as “help” (at some corner within the web page).

Once we assign the “help tip” text, where do we want it to display?  This is where the property “HelpTipDispControl” comes in.  The developer can use this property to assign a container control name (in general it should be the name of a panel created on a web page to hold our help tips) that displays text specified in “HelpTipText”.  You can fix the control (panel) at any location on the web page.  If this property is omitted, the help tips would never be displayed. 

Proceeding further, we have two more properties, “ShowHelpTipsOnFocus” and “ShowHelpTipsOnMouse”.  I can control the display of help tips using both of these properties.  When “ShowHelpTipsOnFocus” is set to true (at design time), we get help tips displayed, when the textbox receives focus (and of course, it vanishes when the focus gets lost).  When “ShowHelpTipsOnMouse” is set to true, we get help tips displayed, when we hover the mouse on textbox (and of course, it vanishes when the mouse is out of the control).

To understand all of the above properties practically, I suggest you download the solution and play with properties.

Briefly understanding the JavaScript implementation

As you understand by now, my control needs to work with JavaScript (to display help tips dynamically), so I implemented each of those JavaScripts as separate methods which together can be registered to the page within the "AddAttributesToRender” method.  The following are the four core methods which emit their respective JavaScripts:

getJS4GotFocus
getJS4LostFocus
getJS4MouseOver
getJS4MouseOut

All of the above user-defined methods (which emit JavaScripts), together with the following code-fragment, made it convenient for me to achieve what I expected:

'emit javascript only at run-time
        If Not IsDesignTime Then
            'focus events
            If Me.ShowHelpTipsOnFocus Then
                If Not Page.IsStartupScriptRegistered(Me.UniqueID
& "_GotFocus") Then
                    Page.RegisterStartupScript(Me.UniqueID &
"_GotFocus", getJS4GotFocus(Me.UniqueID))
                End If
                If Not Page.IsStartupScriptRegistered(Me.UniqueID
& "_LostFocus") Then
                    Page.RegisterStartupScript(Me.UniqueID &
"_LostFocus", getJS4LostFocus(Me.UniqueID))
                End If
                writer.AddAttribute("onFocus", Me.UniqueID &
"_GotFocus();")
                writer.AddAttribute("onBlur", Me.UniqueID &
"_LostFocus();")
            End If
            'mouse events
            If Me.ShowHelpTipsOnMouse Then
                If Not Page.IsStartupScriptRegistered(Me.UniqueID
& "_MouseOver") Then
                    Page.RegisterStartupScript(Me.UniqueID &
"_MouseOver", getJS4MouseOver(Me.UniqueID))
                End If
                If Not Page.IsStartupScriptRegistered(Me.UniqueID
& "_MouseOut") Then
                    Page.RegisterStartupScript(Me.UniqueID &
"_MouseOut", getJS4MouseOut(Me.UniqueID))
                End If
                writer.AddAttribute("onMouseOver", Me.UniqueID &
"_MouseOver();")
                writer.AddAttribute("onMouseOut", Me.UniqueID &
"_MouseOut();")
            End If
        End If

Remarks

This control has been developed just to initiate and show the power of custom controls to control everything right from the beginning through to the end, including client-side JavaScript emission.  I didn’t quite implement all of the features of original ASP.NET Textbox control (as it would take a series of articles).  You just need to learn a few more interfaces and methods to implement all of the original features along with your own features. 

I leave it to the developers to further enhance the same control.  The areas for improving the control would include eventing, better JavaScript for validation, data-binding, and so on.  Good luck.

Any comments, suggestions, bugs, errors, feedback etc. are highly appreciated at jag_chat@yahoo.com.

blog comments powered by Disqus