Udooz!

Sample VS2008 Project is available at http://snipurl.com/asp_net_extendercontrol_sample.zip

This is the continuation  of ASP.NET Extender Control: Decorating & Componentizing Web Controls with Client Behavior.  In this walkthrough, the following things are explained:

• Decorating or extending web control behavior.  A mouse hover effect which is implemented in JavaScript would be applied to controls of  type Button.
• Packaging client side implementation along with the extender control assembly.

The client side implementation should consume  ASP.NET AJAX JavaScript API, in order to get the benefit of this.

As explained in previous section,  this walkthrough explains how to add mouse over and mouse out effect to controls of type Button.

Steps

1. Implement decorator class based on ExtenderControl
2. Implement client side behavior
3. Make client side script as ASP.NET AJAX web resource
4. Consume extender control

Decorator Class Implementation

Based on your application architecture and/or decorator usage, define the decorator class either within web project or separate assembly.  HoverExtension is the decorator class which extends ExtenderControl.

Based on figure 3 in the previous post, the following are the steps need to be completed:

1. Define decorated properties in control
2. Map control and client side properties

 

using System;
using System.Web.UI;
using System.Web.UI.WebControls;
using System.Collections.Generic;

namespace Udooz
{
    [TargetControlType(typeof(Button))]
    public class HoverExtension : ExtenderControl
    {
        private string _hoverCssClass;

        public string HoverCssClass
        {
            get { return _hoverCssClass; }
            set { _hoverCssClass = value; }
        }
        private string _normalCssClass;

        public string NormalCssClass
        {
            get { return _normalCssClass; }
            set { _normalCssClass = value; }
        }

        protected override IEnumerable<ScriptDescriptor> GetScriptDescriptors(Control targetControl)
        {
            ScriptBehaviorDescriptor descriptor = new ScriptBehaviorDescriptor("Udooz.HoverExtension", targetControl.ClientID);
            descriptor.AddProperty("hoverCssClass", this.HoverCssClass);
            descriptor.AddProperty("normalCssClass", this.NormalCssClass);           
            return new ScriptBehaviorDescriptor[] { descriptor };
        }

        protected override IEnumerable<ScriptReference> GetScriptReferences()
        {
            ScriptReference reference = new ScriptReference();
            reference.Assembly = "HoverExtension";
            reference.Name = "Udooz.HoverExtension.js";
            return new ScriptReference[] { reference };
        }
    }
}

Define decorated properties in control

The TargetControlTypeAttribute (line 10 ) enables to specify to which web controls this decorator can be applied.  HoverExtension can only be applied to Button type.  The next step is to define decorated properties for the server side so that it can be used in ASPX page. NormalCssClass and HoverCssClass are two properties defined to set style name for normal and hover state (line 15 – 26).

Map control and client side properties

As discussed in the previous post, the decorated class implements IExtenderControl’s methods GetScriptDescriptors (line 28-34) and GetScriptReferences (line 36-42).  The ScriptBehaviorDescriptor does two things here:

• Based on the target server control given as an argument in the constructor, it specifies the client class to target control’s client ID (line 30).
• Map the server side properties to client side properties (line 31, 32).

The ScriptReference is used to specify on which assembly the client behavior script file will be included (line 39) and the script file name (line 40).

Client Side Behavior Implementation

Based on figure 3 in the previous post, the following are the steps need to be completed those are implemented in HoverExtension.js:

1. Define decorated properties for client side
2. Implement client side behavior

 

Type.registerNamespace('Udooz');

Udooz.HoverExtension = function(element)
{
    Udooz.HoverExtension.initializeBase(this, [element]);

    this._hoverCssClass = null;
    this._normalCssClass = null;
}

Udooz.HoverExtension.prototype =
{
    initialize: function() {
        Udooz.HoverExtension.callBaseMethod(this, 'initialize');             
        $addHandlers(this.get_element(),
                     { 'mouseover': this._onMouseOver,
                         'mouseout': this._onMouseOut
                     },
                     this);

        this.get_element().className = this._normalCssClass;
    },

    dispose: function() {
        $clearHandlers(this.get_element());

        Udooz.HoverExtension.callBaseMethod(this, 'dispose');
    },

    _onMouseOver: function(e) {
        if (this.get_element() && !this.get_element().disabled) {
            this.get_element().className = this._hoverCssClass;
        }
    },

    _onMouseOut: function(e) {       
        if (this.get_element() && !this.get_element().disabled) {
            this.get_element().className = this._normalCssClass;
        }
    },

    get_hoverCssClass: function() {
        return this._hoverCssClass;
    },

    set_hoverCssClass: function(value) {
        if (this._hoverCssClass !== value) {
            this._hoverCssClass = value;
            this.raisePropertyChanged('hoverCssClass');
        }
    },

    get_normalCssClass: function() {
        return this._normalCssClass;
    },

    set_normalCssClass: function(value) {
        if (this._normalCssClass !== value) {
            this._normalCssClass = value;
            this.raisePropertyChanged('normalCssClass');
        }
    }
}

// Optional descriptor for JSON serialization.
Udooz.HoverExtension.descriptor = {
    properties: [{ name: 'hoverCssClass', type: String },
                    { name: 'normalCssClass', type: String}]
}

// Register the class as a type that inherits from Sys.UI.Control.
Udooz.HoverExtension.registerClass('Udooz.HoverExtension', Sys.UI.Behavior);

if (typeof (Sys) !== 'undefined') Sys.Application.notifyScriptLoaded();

A client side class Udooz.HoverExtension is defined.  The constructor initialize the given “element”.  The element reference is the target web control which will be given by ASP.NET at run time using ASP.NET AJAX $create() method.

Define decorated properties for client side

There are two properties normalCssClass (line 56-65) and hoverCssClass (line 45-54) defined.

Implement client side behavior

The mouse over and mouse out events are registered (line 17-21) and those handlers are defined (line 32-42).

Make Client Side Script As ASP.NET AJAX Web Resource

To package the HoverExtension.js into HoverExtension.dll, this script needs to be declared as web resource so that ASP.NET AJAX identifies and consumes this as web resource and invoke this via ScriptResource.axd handler.  In the AssemblyInfo.cs file of HoverExtension.dll, the following code needs to be added.

 

[assembly: System.Web.UI.WebResource("Udooz.HoverExtension.js", "text/javascript")]

Consume Extender Control

Build the HoverExtension project and refer this into a ASP.NET 3.5 web project. The page should register HoverExtension type and can use wherever require.

<%@ Register Assembly="HoverExtension" Namespace="Udooz" TagPrefix="udooz" %>

Before consuming the control, the actual styles should be required.

 

<style type="text/css">
.Hover
{
    background-color:Red;
    border-color:Yellow;
}

.Normal
{
    background-color:Aqua;
    border-color:Blue;
}
</style>

 ASP.NET AJAX ScriptManager is required for runtime behaviors.

 
<pre>
 

<asp:ScriptManager ID="ScriptManager1" runat="server" />

 The actual button control definition and extender control usage would be

 
<pre>
 

<asp:Button ID="button" Text="Extended Button" runat="server" />       
<udooz:HoverExtension ID="extender1" HoverCssClass="Hover" NormalCssClass="Normal" TargetControlID="button" runat="server" /> 

When executing this page, ASP.NET AJAX creates the following for extension.

 <span lang="EN">
<script type="text/javascript">

//<![CDATA[

Sys.Application.initialize();

Sys.Application.add_init(function() {

$create(Udooz.HoverExtension, {"hoverCssClass":"HighLight","normalCssClass":"LowLight"}, null, null, $get("button"));

});

//]]>

</script>

Problem

ASP.NET server controls componentize (or encapsulate) the UI behaviors in a manageable way so that enhancements or modification is much simpler.  These are like swiss-army-knife, somebody use server side and client side features in balanced way, others may heavily stick with either server side or client side.  The major reason for people stick with server side code is to avoid client side script managebility.  Unlike ASP.NET controls those can be componentized in assemblies, JavaScript needs to be deployed separately in an uncontrollable way.  The problem with this are:

• Resolving script path
• Client side code control

Another problem is to decorate or extend a web control on demand basis is not standardized.

Forces

• To apply new or common behaviors to one or more web controls without affecting the controls.
• To send/generate extended feature set  on demand basis.
• To encapsulate client side behavior (none other than JavaScript files) within ASP.NET server control assembly.
• To separate group of concerns between client script and server side code.
• To control control’s client script path.  
• To manage and control’s client behavior.

Solution

Encapsulating client script with .NET assembly is one of the feature introduced in ASP.NET AJAX.   By this feature, ASP.NET 3.5 introduces “System.Web.UI.ExtenderControl” which enables you to extend or decorate one or more web controls without interrupting the actual controls.

ExtenderControl

ExtenderControl is the decorator here which in turn implements IExtenderControl interface. (See figure 1)

Figure 1

It contains two methods,

• GetScriptDescriptors - Implementer can return collection of ScriptDescriptor, each can include client side script behavior such as client types to create, properties to assign and event handlers to register.  One nice derived class of ScriptDescriptor is ScriptBehaviorDescriptor.
• GetScriptReferences – Implementer can return collection of ScriptReference, each can include actual JavaScript file detail.

From a decorator perspective, ExtenderControl facilitate you with some additional properties.  See figure 2.  It does not allow you for custom rendering. (See figure 2).

Figure 2

The TargetControlID is used to assign the extended behavior to a control in the page.

Example

In this example, you can understand how extender and its associated classes works, and how ASP.NET AJAX helps you to decorate a web controls and how to componentize client side behavior in to .NET assembly.  Figure 3 depicts how it is working.

Figure 3

Part 2 of this post will explain this in detail with sample.