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
