How to : Create Custom Ajax Extender Control

What is Ajax extender control?

Ajax extender control is a control whose purpose is to add a behavior to the

existing ASP.NET controls. These behaviors usually are client side behaviors

 that will extend the functionality of an existing ASP.NET control. I mention the

sentence "an existing ASP.NET control" twice, to ensure the concept of Ajax

Extender controls. The difference between Ajax extender control and custom

server controls is that the custom server controls allow you to create a new server

 control that will work separately without extending any other controls. 

One of the interesting features that Ajax extenders offer is calling web services; we

can hit the server and get some data from it without making the end-user notice.

For example, the AutoComplete Extender Control uses the web service for filtering

the typed text from Database without any flickers.

You can find a lot of resources and articles that talk about Ajax extenders, especially

here in aspalliance.com.

ASP.NET Ajax controls project

To create a new Ajax extender, open your Visual Studio, and then create a new

ASP.NET AJAX Control Project, as illustrated in Figure1.

Figure1

By default, this will create three files:

·         <your extender name>Behavior.js file: an embedded JavaScript file,

where we will locate our client-side logic.

·         <your extender name>Designer.vb file: a class that enables

 design-time functionality. You should not need to modify it.

·         <your extender name>Extender.vb file: a server-side control class

that will manage the creation of your extender, and allow you to set the

 properties at design-time. It also defines the properties that can be set

on your extender. These properties are accessible via code and at design

time and match properties defined in the Behavior.js file.

Ajax Library Shortcuts

There are several shortcuts methods for writing client-side functionality, such as:

·         $addhandler: enables you to assign a handler function to an event

·         $clearhandlers: clears all the handlers that you have created

·         $removehandler: removes a specific event handler

·         $get: a shortcut for document.getElementById

·         $find: allows you to access the class object, and use the methods

and properties

Ajax Extender Logic

Ajax extender logic is quite simple; the following steps explain this process with code samples.

Create a property in the Extender.vb class, similar to what I did in Listing 1.

Listing 1

<ExtenderControlProperty()> _
<DefaultValue("")> _
Public Property MyProperty() As String
Get
Return GetPropertyValue("MyProperty", "")
End Get
Set(ByVal value As String)
SetPropertyValue("MyProperty", value)
End Set
End Property

Declare a property variable at initializeBase function in the Behavior JavaScript file,

as illustrated in Listing 2.

Listing 2

this._myProperty = null; //Property Variable

Write get/set property for the above variable, as in Listing 3, and remember it is

case sensitive.

Listing 3

get_MyProperty: function()
{
  return this._myProperty;
}
,
set_MyProperty: function(value)
{
  this._myProperty = value;
}
,

Create a JavaScript function, which will be the container of your client-side logic.

Listing 4

_myFunction : function(e)
{
  alert(this._myProperty);
}

Finally, add an event handler using the Ajax Library Shortcut $addhandler inside

the initializefunction, as you can see in Listing 5. We added an event handler

for the mouse over event, but note that we have removed the "on" prefix word

and that is the role.

We have created a delegate function that will be mapped to the _myFunction 

function, which will be fired when the mouse is going to be over the extended control.

Listing 5

$addHandler(this.get_element(), 'mouseover', 
Function.createDelegate(this,this._myFunction));

Build the project, and that is it; you have created a simple Ajax Extender control.

Let us get back now for our new tool tip extender. We want to make this Tooltip look

 different than the regular Tooltip; i.e. page developer would customize the tool tip

background color, change font name/color, and it will be better if we can delay the

disappearing time of the tool tip.

Look at Figure 2 which illustrates what the extender will look like after finishing this article.

Figure 2

Now let us start building the Tool tip extender. As I mentioned, the ASP.NET Ajax Control

 Project Template will automatically create three files: (MyExtenderToolTipBehavior.js,MyExtenderToolTipDesigner.vb, and MyExtenderToolTipExtender.vb).

Listing 6: Tooltip Extender Class

<Designer(GetType(MyExtenderToolTipDesigner))> _
    <TargetControlType(GetType(WebControl))> _
    Public Class MyExtenderToolTipExtender
        Inherits ExtenderControlBase
        <ExtenderControlProperty()> _
           <DefaultValue("")> _
           Public Property ToolTipText() As String
            Get
                Return GetPropertyValue("ToolTipText", "")
            End Get
            Set(ByVal value As String)
                SetPropertyValue("ToolTipText", value)
            End Set
        End Property
        <ExtenderControlProperty()> _
          <DefaultValue(200)> _
          Public Property ToolTipWidth() As System.Web.UI.WebControls.Unit
            Get
                Return GetPropertyValue("ToolTipWidth", Unit.Pixel(200))
            End Get
            Set(ByVal value As System.Web.UI.WebControls.Unit)
                SetPropertyValue("ToolTipWidth", value)
            End Set
        End Property
 
        <ExtenderControlProperty()> _
           <DefaultValue("#5E8DD0")> _
           Public Property ToolTipBgColor() As String
            Get
                Return GetPropertyValue("ToolTipBgColor", "#5E8DD0")
            End Get
            Set(ByVal value As String)
                SetPropertyValue("ToolTipBgColor", value)
            End Set
        End Property
        <ExtenderControlProperty()> _
                <DefaultValue("Verdana")> _
                Public Property ToolTipFontName() As String
            Get
                Return GetPropertyValue("ToolTipFontName", "Verdana")
            End Get
            Set(ByVal value As String)
                SetPropertyValue("ToolTipFontName", value)
            End Set
        End Property
        <ExtenderControlProperty()> _
              <DefaultValue("White")> _
              Public Property ToolTipFontColor() As String
            Get
                Return GetPropertyValue("ToolTipFontColor", "White")
            End Get
            Set(ByVal value As String)
                SetPropertyValue("ToolTipFontColor", value)
            End Set
        End Property
        <ExtenderControlProperty()> _
        <DefaultValue(250)> _
        Public Property DisappearDelay() As Integer
            Get
                Return GetPropertyValue("DisappearDelay", 250)
            End Get
            Set(ByVal value As Integer)
                SetPropertyValue("DisappearDelay", value)
            End Set
        End Property
End Class

Listing 6 is the Tool tip extender class; you can see many properties and

attributes in there.

 Since it is a tool tip at the end, it should be targeting all web controls types.

 Therefore, theTargetControlType(GetType(WebControl) attribute will be used

to allow our extender to target any web control in the page. This attribute will

insert all the extender properties as new collection properties in the target control.

The DisappearDelay property will delay the disappearing time of the tool tip in

 milliseconds, the default value attribute is set to be 250 milliseconds.

Now we need to set the position of the tool tip to be an absolute position,

the z-index should be equal to 100, and that will occur in the embedded

Style Sheet file, as you can see in Listing 7.

Listing 7

.tooltipdiv{
position:absolute;
padding: 2px;
border:1px solid black;
font-size:12px;
font-weight:normal;
line-height:18px;
z-index:100;
}

You should add the style sheet file to the extender web resources assembly, as in Listing 8.

Listing 8

<Assembly: System.Web.UI.WebResource("MyExtenderToolTip.MyExtenderToolTipCss.css", 
"text/css")>

In addition, we need to add it to the client cascade style sheet resources, as you see in Listing 9.

Listing 9

<ClientCssResource("MyExtenderToolTip.MyExtenderToolTipCss.css")>

The client-side logic will be located in the behavior JavaScript file, discussed in the next section.

The major goal is to extend the behavior of the ASP.NET control, so the Behavoir.js file will play

a key role in that process.

As I explained in "Brief explanation about creating a new Ajax extender" section, 

we should create a property variable in the initializeBase function for each public property in the

Extender Class, as you see in Listing 10.

Listing 10

this._toolTipText = '';
this._toolTipWidth = '200px'; 
this._toolTipBgColor = '#5E8DD0'; 
this._toolTipFontName='Verdana';
this._toolTipFontColor='White';
this._disappearDelay=250;

If you recall, we need to write a get/set client-side property for each variable,

which is shown in Listing 11.

Listing 11

get_ToolTipText: function()
{
  return this._toolTipText;
}
,
set_ToolTipText: function(value)
{
  this._toolTipText = value;
}
 
, set_ToolTipWidth: function(value)
{
  this._toolTipWidth = value;
}
 
, get_ToolTipWidth: function()
{
  return this._toolTipWidth;
}
 
, set_ToolTipBgColor: function(value)
{
  this._toolTipBgColor = value;
}
 
, get_ToolTipBgColor: function()
{
  return this._toolTipBgColor;
}
 
, set_ToolTipFontName: function(value)
{
  this._toolTipFontName = value;
}
 
, get_ToolTipFontName: function()
{
  return this._toolTipFontName;
}
 
, set_ToolTipFontColor: function(value)
{
  this._toolTipFontColor = value;
}
 
, get_ToolTipFontColor: function()
{
  return this._toolTipFontColor;
}
 
, set_DisappearDelay: function(value)
{
  this._disappearDelay = value;
}
 
, get_DisappearDelay: function()
{
  return this._toolTipFontColor;
}
,

Now lets do the trick, as you can see in Listing 12, we have created a new HTML Div element in initialize function, which will be the tool tip. 

Listing 12

 var newDiv = document.createElement('div');
 newDiv.id = this.get_element().id + '_fixedtipdiv';
 newDiv.style.visibility='hidden';
 newDiv.style.width=this._toolTipWidth;
 newDiv.style.backgroundColor=this._toolTipBgColor;
 newDiv.style.fontFamily=this._toolTipFontName;
 newDiv.style.color=this._toolTipFontColor;
 newDiv.className='tooltipdiv';
 document.body.appendChild(newDiv);

We will add an event handler when the mouse is over and out of the content.

These handlers will be located at the initialize function, as you see in Listing 13.

Note that I have removed the "On" prefix word from the event name.

If you download the source code, you will see the _fixedtooltip function, and the

 _delayhidetipfunction in more details; these two JavaScript functions are responsible

of show/hide the tool tip.In addition, many JavaScript functions are responsible for

creating the client-side behavior for the extender.

Listing 13

$addHandler(this.get_element(), 'mouseover',Function.createDelegate(this, 
this._fixedtooltip));
$addHandler(this.get_element(), 'mouseout', 
Function.createDelegate(this,this._delayhidetip));

Now let us test our new extender.

To add the extender in your Toolbox, follow the subsequent steps.

Right click on the toolbox window then choose "Add Tab."

Type the name you want for the new tab then right click over it, and click "Choose Items."

Click on Browse button in the ".NET Framework Components" tab, go to the

tool tip extender project, open the bin folder, and choose MyExtenderToolTip.dll.

The result is shown Figure 3.

Figure 3

That is it, all you need now is to drag the extender, and target the web control over which

 you want to display the custom tool tip.

As you see in Figure 4 and Figure 5, I dragged two tool tip extenders, one for the textbox

and the other for the button. Moreover, I customized the Tooltip to match my requirements.

Figure 4

Figure 5

Figure 6 shows you how the extender properties are added as new collection properties

in the Textbox control.

Figure 6

The article covered the concept of the Ajax extenders, and how you can create a new

extender. In addition, we have created a new custom Tooltip Ajax extender from scratch.

It is you turn now to create your own Ajax extender.

I hope you found this informative.