The goal
of this blog entry is to explain how you can extend the Ajax
Control Toolkit with custom Ajax
Control Toolkit controls. I describe how you can create the two halves
of an Ajax
Control Toolkit control: the server-side
control extender and the client-side
control behavior. Finally, I explain how you can use the new Ajax
Control Toolkit
control in a Web Forms page. At the end
of this blog entry, there is a link to download a Visual Studio 2010 solution which contains the code for two Ajax
Control Toolkit controls: SampleExtender and PopupHelpExtender. The SampleExtender contains the minimum skeleton for creating a new Ajax
Control Toolkit
control. You can use the SampleExtender as a starting point for your custom Ajax
Control Toolkit controls. The PopupHelpExtender
control is a super simple custom Ajax
Control Toolkit
control. This
control extender displays a help message when you start typing into a TextBox
control. The animated GIF below demonstrates what happens when you click into a TextBox which has been extended with the PopupHelp extender. Here’s a sample
of a Web Forms page which uses the control: <%@ Page Language="C#" AutoEventWireup="true" CodeBehind="ShowPopupHelp.aspx.cs" Inherits="MyACTControls.Web.Default" %>
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
<html >
<head runat="server">
<title>Show Popup Help</title>
</head>
<body>
<form id="form1" runat="server">
<div>
<act:ToolkitScriptManager ID="tsm" runat="server" />
<%-- Social Security Number --%>
<asp:Label
ID="lblSSN"
Text="SSN:"
AssociatedControlID="txtSSN"
runat="server" />
<asp:TextBox
ID="txtSSN"
runat="server" />
<act:PopupHelpExtender
id="ph1"
TargetControlID="txtSSN"
HelpText="Please enter your social security number."
runat="server" />
<%-- Social Security Number --%>
<asp:Label
ID="lblPhone"
Text="Phone Number:"
AssociatedControlID="txtPhone"
runat="server" />
<asp:TextBox
ID="txtPhone"
runat="server" />
<act:PopupHelpExtender
id="ph2"
TargetControlID="txtPhone"
HelpText="Please enter your phone number."
runat="server" />
</div>
</form>
</body>
</html>
In the page above, the PopupHelp extender is used to extend the functionality
of the two TextBox controls. When focus is given to a TextBox
control, the popup help message is displayed.
An Ajax
Control Toolkit
control extender consists
of two parts: a server-side
control extender and a client-side behavior. For example, the PopupHelp extender consists
of a server-side PopupHelpExtender
control (PopupHelpExtender.cs) and a client-side PopupHelp behavior JavaScript script (PopupHelpBehavior.js).
Over the course
of this blog entry, I describe how you can create both the server-side extender and the client-side behavior.
Writing the Server-Side Code
Creating a
Control Extender
You create a
control extender by creating a class that inherits from the abstract ExtenderControlBase class. For example, the PopupHelpExtender
control is declared like this:
public class PopupHelpExtender: ExtenderControlBase {
}
The ExtenderControlBase class is part
of the Ajax
Control Toolkit. This base class contains all
of the common server properties and methods
of every Ajax
Control Toolkit extender
control.
The ExtenderControlBase class inherits from the ExtenderControl class. The ExtenderControl class is a standard class in the ASP.NET framework located in the System.Web.UI namespace. This class is responsible for generating a client-side behavior. The class generates a call to the Microsoft Ajax Library $create() method which looks like this:
<script type="text/javascript">
$create(MyACTControls.PopupHelpBehavior, {"HelpText":"Please enter your social security number.","id":"ph1"}, null, null, $get("txtSSN"));
});
</script>
The JavaScript $create() method is part
of the Microsoft Ajax Library. The reference for this method can be found here:
http://msdn.microsoft.com/en-us/library/bb397487.aspx
This method accepts the following parameters:
type – The type
of client behavior to create. The $create() method above creates a client PopupHelpBehavior.
Properties – Enables you to pass initial values for the properties
of the client behavior. For example, the initial value
of the HelpText property. This is how server property values are passed to the client.
Events – Enables you to pass client-side event handlers to the client behavior.
References – Enables you to pass references to other client components.
Element – The DOM element associated with the client behavior. This will be the DOM element associated with the
control being extended such as the txtSSN TextBox.
The $create() method is generated for you automatically. You just need to focus on writing the server-side
control extender class.
Specifying the Target
Control
All Ajax
Control Toolkit extenders inherit a TargetControlID property from the ExtenderControlBase class. This property, the TargetControlID property, points at the
control that the extender
control extends. For example, the Ajax
Control Toolkit TextBoxWatermark
control extends a TextBox, the ConfirmButton
control extends a Button, and the Calendar
control extends a TextBox.
You must indicate the type
of control which your extender is extending. You indicate the type
of control by adding a [TargetControlType] attribute to your
control. For example, the PopupHelp extender is declared like this:
[TargetControlType(typeof(TextBox))]
public class PopupHelpExtender: ExtenderControlBase {
}
The PopupHelp extender can be used to extend a TextBox
control. If you try to use the PopupHelp extender with another type
of control then an exception is thrown.
If you want to create an extender
control which can be used with any type
of ASP.NET
control (Button, DataView, TextBox or whatever) then use the following attribute:
[TargetControlType(typeof(Control))]
Decorating Properties with Attributes
If you decorate a server-side property with the [ExtenderControlProperty] attribute then the value
of the property gets passed to the control’s client-side behavior. The value
of the property gets passed to the client through the $create() method discussed above.
The PopupHelp
control contains the following HelpText property:
[ExtenderControlProperty]
[RequiredProperty]
public string HelpText {
get { return GetPropertyValue("HelpText", "Help Text"); }
set { SetPropertyValue("HelpText", value); }
}
The HelpText property determines the help text which pops up when you start typing into a TextBox
control. Because the HelpText property is decorated with the [ExtenderControlProperty] attribute, any value assigned to this property on the server is passed to the client automatically.
For example, if you declare the PopupHelp extender in a Web Form page like this:
<asp:TextBox
ID="txtSSN"
runat="server" />
<act:PopupHelpExtender
id="ph1"
TargetControlID="txtSSN"
HelpText="Please enter your social security number."
runat="server" />
Then the PopupHelpExtender renders the call to the the following Microsoft Ajax Library $create() method:
$create(MyACTControls.PopupHelpBehavior, {"HelpText":"Please enter your social security number.","id":"ph1"}, null, null, $get("txtSSN"));
You can see this call to the JavaScript $create() method by selecting View Source in your browser. This call to the $create() method calls a method named set_HelpText() automatically and passes the value “Please enter your social security number”.
There are several attributes which you can use to decorate server-side properties including:
ExtenderControlProperty – When a property is marked with this attribute, the value
of the property is passed to the client automatically.
ExtenderControlEvent – When a property is marked with this attribute, the property represents a client event handler.
Required – When a value is not assigned to this property on the server, an error is displayed.
DefaultValue – The default value
of the property passed to the client.
ClientPropertyName – The name
of the corresponding property in the JavaScript behavior. For example, the server-side property is named ID (uppercase) and the client-side property is named id (lower-case).
IDReferenceProperty – Applied to properties which refer to the IDs
of other controls.
URLProperty – Calls ResolveClientURL() to convert from a server-side URL to a URL which can be used on the client.
ElementReference – Returns a reference to a DOM element by performing a client $get().
The WebResource, ClientResource, and the RequiredScript Attributes
The PopupHelp extender uses three embedded resources named PopupHelpBehavior.js, PopupHelpBehavior.debug.js, and PopupHelpBehavior.css. The first two files are JavaScript files and the final file is a Cascading Style sheet file.
These files are compiled as embedded resources. You don’t need to mark them as embedded resources in your Visual Studio solution because they get added to the assembly when the assembly is compiled by a build task. You can see that these files get embedded into the MyACTControls assembly by using Red Gate’s .NET Reflector tool:
In order to use these files with the PopupHelp extender, you need to work with both the WebResource and the ClientScriptResource attributes.
The PopupHelp extender includes the following three WebResource attributes.
[assembly: WebResource("PopupHelp.PopupHelpBehavior.js", "text/javascript")]
[assembly: WebResource("PopupHelp.PopupHelpBehavior.debug.js", "text/javascript")]
[assembly: WebResource("PopupHelp.PopupHelpBehavior.css", "text/css", PerformSubstitution = true)]
These WebResource attributes expose the embedded resource from the assembly so that they can be accessed by using the ScriptResource.axd or WebResource.axd handlers. The first parameter passed to the WebResource attribute is the name
of the embedded resource and the second parameter is the content type
of the embedded resource.
The PopupHelp extender also includes the following ClientScriptResource and ClientCssResource attributes:
[ClientScriptResource("MyACTControls.PopupHelpBehavior", "PopupHelp.PopupHelpBehavior.js")]
[ClientCssResource("PopupHelp.PopupHelpBehavior.css")]
Including these attributes causes the PopupHelp extender to request these resources when you add the PopupHelp extender to a page. If you open View Source in a browser which uses the PopupHelp extender then you will see the following link for the Cascading Style Sheet file:
<link href="/WebResource.axd?d=0uONMsWXUuEDG-pbJHAC1kuKiIMteQFkYLmZdkgv7X54TObqYoqVzU4mxvaa4zpn5H9ch0RDwRYKwtO8zM5mKgO6C4WbrbkWWidKR07LD1d4n4i_uNB1mHEvXdZu2Ae5mDdVNDV53znnBojzCzwvSw2&t=634417392021676003" type="text/css" rel="stylesheet" />
You also will see the following script include for the JavaScript file:
<script src="/ScriptResource.axd?d=pIS7xcGaqvNLFBvExMBQSp_0xR3mpDfS0QVmmyu1aqDUjF06TrW1jVDyXNDMtBHxpRggLYDvgFTWOsrszflZEDqAcQCg-hDXjun7ON0Ol7EXPQIdOe1GLMceIDv3OeX658-tTq2LGdwXhC1-dE7_6g2&t=ffffffff88a33b59" type="text/javascript"></script>
The JavaScrpt file returned by this request to ScriptResource.axd contains the combined scripts for any and all Ajax
Control Toolkit controls in a page.
By default, the Ajax
Control Toolkit combines all
of the JavaScript files required by a page into a single JavaScript file. Combining files in this way really speeds up how quickly all
of the JavaScript files get delivered from the web server to the browser.
So, by default, there will be only one ScriptResource.axd include for all
of the JavaScript files required by a page. If you want to disable Script Combining, and create separate links, then disable Script Combining like this:
<act:ToolkitScriptManager ID="tsm" runat="server" CombineScripts="false" />
There is one more important attribute used by Ajax
Control Toolkit extenders. The PopupHelp behavior uses the following two RequirdScript attributes to load the JavaScript files which are required by the PopupHelp behavior:
[RequiredScript(typeof(CommonToolkitScripts), 0)]
[RequiredScript(typeof(PopupExtender), 1)]
The first parameter
of the RequiredScript attribute represents either the string name
of a JavaScript file or the type
of an Ajax
Control Toolkit
control. The second parameter represents the order in which the JavaScript files are loaded (This second parameter is needed because .NET attributes are intrinsically unordered).
In this case, the RequiredScript attribute will load the JavaScript files associated with the CommonToolkitScripts type and the JavaScript files associated with the PopupExtender in that order. The PopupHelp behavior depends on these JavaScript files.
Writing the Client-Side Code
The PopupHelp extender uses a client-side behavior written with the Microsoft Ajax Library. Here is the complete code for the client-side behavior:
(function () {
// The unique name
of the script registered with the
// client script loader
var scriptName = "PopupHelpBehavior";
function execute() {
Type.registerNamespace('MyACTControls');
MyACTControls.PopupHelpBehavior = function (element) {
/// <summary>
/// A behavior which displays popup help for a textbox
/// </summmary>
/// <param name="element" type="Sys.UI.DomElement">The element to attach to</param>
MyACTControls.PopupHelpBehavior.initializeBase(this, [element]);
this._textbox = Sys.Extended.UI.TextBoxWrapper.get_Wrapper(element);
this._cssClass = "ajax__popupHelp";
this._popupBehavior = null;
this._popupPosition = Sys.Extended.UI.PositioningMode.BottomLeft;
this._popupDiv = null;
this._helpText = "Help Text";
this._element$delegates = {
focus: Function.createDelegate(this, this._element_onfocus),
blur: Function.createDelegate(this, this._element_onblur)
};
}
MyACTControls.PopupHelpBehavior.prototype = {
initialize: function () {
MyACTControls.PopupHelpBehavior.callBaseMethod(this, 'initialize');
// Add event handlers for focus and blur
var element = this.get_element();
$addHandlers(element, this._element$delegates);
},
_ensurePopup: function () {
if (!this._popupDiv) {
var element = this.get_element();
var id = this.get_id();
this._popupDiv = $common.createElementFromTemplate({
nodeName: "div",
properties: { id: id + "_popupDiv" },
cssClasses: ["ajax__popupHelp"]
}, element.parentNode);
this._popupBehavior = new $create(Sys.Extended.UI.PopupBehavior, { parentElement: element }, {}, {}, this._popupDiv);
this._popupBehavior.set_positioningMode(this._popupPosition);
}
},
get_HelpText: function () {
return this._helpText;
},
set_HelpText: function (value) {
if (this._HelpText != value) {
this._helpText = value;
this._ensurePopup();
this._popupDiv.innerHTML = value;
this.raisePropertyChanged("Text")
}
},
_element_onfocus: function (e) {
this.show();
},
_element_onblur: function (e) {
this.hide();
},
show: function () {
this._popupBehavior.show();
},
hide: function () {
if (this._popupBehavior) {
this._popupBehavior.hide();
}
},
dispose: function() {
var element = this.get_element();
$clearHandlers(element);
if (this._popupBehavior) {
this._popupBehavior.dispose();
this._popupBehavior = null;
}
}
};
MyACTControls.PopupHelpBehavior.registerClass('MyACTControls.PopupHelpBehavior', Sys.Extended.UI.BehaviorBase);
Sys.registerComponent(MyACTControls.PopupHelpBehavior, { name: "popupHelp" });
} // execute
if (window.Sys && Sys.loader) {
Sys.loader.registerScript(scriptName, ["ExtendedBase", "ExtendedCommon"], execute);
}
else {
execute();
}
})();
In the following sections, we’ll discuss how this client-side behavior works.
Wrapping the Behavior for the Script Loader
The behavior is wrapped with the following script:
(function () {
// The unique name
of the script registered with the
// client script loader
var scriptName = "PopupHelpBehavior";
function execute() {
// Behavior Content
} // execute
if (window.Sys && Sys.loader) {
Sys.loader.registerScript(scriptName, ["ExtendedBase", "ExtendedCommon"], execute);
}
else {
execute();
}
})();
This code is required by the Microsoft Ajax Library Script Loader. You need this code if you plan to use a behavior directly from client-side code and you want to use the Script Loader. If you plan to only use your code in the context
of the Ajax
Control Toolkit then you can leave out this code.
Registering a JavaScript Namespace
The PopupHelp behavior is declared within a namespace named MyACTControls. In the code above, this namespace is created with the following registerNamespace() method:
Type.registerNamespace('MyACTControls');
JavaScript does not have any built-in way
of creating namespaces to prevent naming conflicts. The Microsoft Ajax Library extends JavaScript with support for namespaces. You can learn more about the registerNamespace() method here:
http://msdn.microsoft.com/en-us/library/bb397723.aspx
Creating the Behavior
The actual Popup behavior is created with the following code.
MyACTControls.PopupHelpBehavior = function (element) {
/// <summary>
/// A behavior which displays popup help for a textbox
/// </summmary>
/// <param name="element" type="Sys.UI.DomElement">The element to attach to</param>
MyACTControls.PopupHelpBehavior.initializeBase(this, [element]);
this._textbox = Sys.Extended.UI.TextBoxWrapper.get_Wrapper(element);
this._cssClass = "ajax__popupHelp";
this._popupBehavior = null;
this._popupPosition = Sys.Extended.UI.PositioningMode.BottomLeft;
this._popupDiv = null;
this._helpText = "Help Text";
this._element$delegates = {
focus: Function.createDelegate(this, this._element_onfocus),
blur: Function.createDelegate(this, this._element_onblur)
};
}
MyACTControls.PopupHelpBehavior.prototype = {
initialize: function () {
MyACTControls.PopupHelpBehavior.callBaseMethod(this, 'initialize');
// Add event handlers for focus and blur
var element = this.get_element();
$addHandlers(element, this._element$delegates);
},
_ensurePopup: function () {
if (!this._popupDiv) {
var element = this.get_element();
var id = this.get_id();
this._popupDiv = $common.createElementFromTemplate({
nodeName: "div",
properties: { id: id + "_popupDiv" },
cssClasses: ["ajax__popupHelp"]
}, element.parentNode);
this._popupBehavior = new $create(Sys.Extended.UI.PopupBehavior, { parentElement: element }, {}, {}, this._popupDiv);
this._popupBehavior.set_positioningMode(this._popupPosition);
}
},
get_HelpText: function () {
return this._helpText;
},
set_HelpText: function (value) {
if (this._HelpText != value) {
this._helpText = value;
this._ensurePopup();
this._popupDiv.innerHTML = value;
this.raisePropertyChanged("Text")
}
},
_element_onfocus: function (e) {
this.show();
},
_element_onblur: function (e) {
this.hide();
},
show: function () {
this._popupBehavior.show();
},
hide: function () {
if (this._popupBehavior) {
this._popupBehavior.hide();
}
},
dispose: function() {
var element = this.get_element();
$clearHandlers(element);
if (this._popupBehavior) {
this._popupBehavior.dispose();
this._popupBehavior = null;
}
}
};
The code above has two parts. The first part
of the code is used to define the constructor function for the PopupHelp behavior. This is a factory method which returns an instance
of a PopupHelp behavior:
MyACTControls.PopupHelpBehavior = function (element) {
}
The second part
of the code modified the prototype for the PopupHelp behavior:
MyACTControls.PopupHelpBehavior.prototype = {
}
Any code which is particular to a single instance
of the PopupHelp behavior should be placed in the constructor function. For example, the default value
of the _helpText field is assigned in the constructor function:
this._helpText = "Help Text";
Any code which is shared among all instances
of the PopupHelp behavior should be added to the PopupHelp behavior’s prototype. For example, the public HelpText property is added to the prototype:
get_HelpText: function () {
return this._helpText;
},
set_HelpText: function (value) {
if (this._HelpText != value) {
this._helpText = value;
this._ensurePopup();
this._popupDiv.innerHTML = value;
this.raisePropertyChanged("Text")
}
},
Registering a JavaScript Class
After you create the PopupHelp behavior, you must register the behavior as a class by using the Microsoft Ajax registerClass() method like this:
MyACTControls.PopupHelpBehavior.registerClass('MyACTControls.PopupHelpBehavior', Sys.Extended.UI.BehaviorBase);
This call to registerClass() registers PopupHelp behavior as a class which derives from the base Sys.Extended.UI.BehaviorBase class. Like the ExtenderControlBase class on the server side, the BehaviorBase class on the client side contains method used by every behavior.
The documentation for the BehaviorBase class can be found here:
http://msdn.microsoft.com/en-us/library/bb311020.aspx
The most important methods and properties
of the BehaviorBase class are the following:
dispose() – Use this method to clean up all resources used by your behavior. In the case
of the PopupHelp behavior, the dispose() method is used to remote the event handlers created by the behavior and disposed the Popup behavior.
get_element() -- Use this property to get the DOM element associated with the behavior. In other words, the DOM element which the behavior extends.
get_id() – Use this property to the ID
of the current behavior.
initialize() – Use this method to initialize the behavior. This method is called after all
of the properties are set by the $create() method.
Creating Debug and Release Scripts
You might have noticed that the PopupHelp behavior uses two scripts named PopupHelpBehavior.js and PopupHelpBehavior.debug.js. However, you never create these two scripts. Instead, you only create a single script named PopupHelpBehavior.pre.js.
The pre in PopupHelpBehavior.pre.js stands for preprocessor. When you build the Ajax
Control Toolkit (or the sample Visual Studio Solution at the end
of this blog entry), a build task named JSBuild generates the PopupHelpBehavior.js release script and PopupHelpBehavior.debug.js debug script automatically.
The JSBuild preprocessor supports the following directives:
#IF
#ELSE
#ENDIF
#INCLUDE
#LOCALIZE
#DEFINE
#UNDEFINE
The preprocessor directives are used to mark code which should only appear in the debug version
of the script. The directives are used extensively in the Microsoft Ajax Library. For example, the Microsoft Ajax Library Array.contains() method is created like this:
$type.contains = function Array$contains(array, item) {
//#if DEBUG
var e = Function._validateParams(arguments, [
{name: "array", type: Array, elementMayBeNull: true},
{name: "item", mayBeNull: true}
]);
if (e) throw e;
//#endif
return (indexOf(array, item) >= 0);
}
Notice that you add each
of the preprocessor directives inside a JavaScript comment. The comment prevents Visual Studio from getting confused with its Intellisense.
The release version, but not the debug version,
of the PopupHelpBehavior script is also minified automatically by the Microsoft Ajax Minifier. The minifier is invoked by a build step in the project file.
Conclusion
The goal
of this blog entry was to explain how you can create custom AJAX
Control Toolkit controls. In the first part
of this blog entry, you learned how to create the server-side portion
of an Ajax
Control Toolkit
control. You learned how to derive a new
control from the ExtenderControlBase class and decorate its properties with the necessary attributes.
Next, in the second part
of this blog entry, you learned how to create the client-side portion
of an Ajax
Control Toolkit
control by creating a client-side behavior with JavaScript. You learned how to use the methods
of the Microsoft Ajax Library to extend your client behavior from the BehaviorBase class.
Download the Custom ACT Starter Solution
