Creating Custom AJAX Client Controls

This overview shows you how to create a custom ASP.NET AJAX client control and use it in a page. In this overview you will learn how to do the following:

• Use the prototype design pattern in ECMAScript (JavaScript) to define a control class.

• Register a control as a class that derives from the Sys.UI.Control base class.

• Initialize the Control base class and invoke its methods.

• Create custom events that a page developer can bind to and handle.

• Use the client control in a page and bind to the control's events.

The overview provides an example of a complete client control that creates a button with hover behavior.

This overview focuses on client controls. There are three types of ASP.NET AJAX client component objects:

• Non-visual components that derive from the Sys.Component base class and that have no UI representation.

• Behaviors that derive from Sys.UI.Behavior.

• Controls that derive from Control.

The following table summarizes the differences between components, behaviors, and controls.

Prerequisites

To run the client control example provided in this topic, you will need:

• An AJAX-enabled ASP.NET Web site. If you have such a site already configured, you can use that site for this example. For more information about how to create a virtual directory or site, see How to: Create and Configure Virtual Directories in IIS 5.0 and 6.0.

Creating Basic Functionality for a Custom ASP.NET AJAX Client Control

An ASP.NET AJAX client control represents a DOM element as a client object and extends a markup representation or provides additional functionality for the element. For example, a client control might extend an HTML element to react to mouse events by applying different CSS styles.

A client control encapsulates JavaScript code that is intended to be reusable across applications. By deriving from the Control base class, your custom control automatically inherits many built-in cross-browser features, which includes the following:

• The ability to add and remove event handlers for DOM elements associated with the control and for event handlers for the control itself.

• Automatic registration of the control as a disposable object that implements the Sys.IDisposable interface.

• The ability to raise notification events when properties are changed.

• The ability to perform batch processing of control property settings. This is more efficient in script size and processing time than handling all logic in individual property get and set accessors.

Implementing a Client Control

The following table summarizes the steps for implementing a custom client control derived from Control. More detailed information about each step follows the table.

Defining a Control Class Using the Prototype Design Pattern

An ASP.NET AJAX client class, which includes a control class, is defined in JavaScript using the prototype design pattern. For details, see Creating a Client Component Class Using the Prototype Model.

A client control class must be derived from the Control base class. You register an ASP.NET AJAX client class as a class with the client application by using the Type.registerClass method. For more information, see Type.registerClass Method.

Initializing the Base Class

The base Control object is initialized in the control's constructor. In the control's constructor, you invoke the inherited initializeBase method and pass the DOM element that was received in the constructor argument to the base class. Typically the initializeBase method is invoked before any other code runs in the constructor. When the Control base class is initialized, its methods are available to the control, and it automatically registers the control as a disposable object with the Sys.Application instance. For more information, see Sys.IDisposable Interface.

The following example shows a constructor function for a control that derives from Control. The component's constructor calls the inherited initializeBase method.

Samples.SimpleControl = function(element)
{
    Samples.SimpleControl.initializeBase(this, [element]);
}

Defining Properties and Raising Property-changed Notifications

You define properties in the client control's class that page developers can get and set. You can also raise propertyChanged notification events for your component's properties. Page developers who use your component can then bind to these events. An ASP.NET AJAX component derived from the Component, Behavior, or Control base class inherits the Sys.Component.raisePropertyChanged method, which you call in order to raise a propertyChanged event. For more information, see Defining Custom Component Properties and Raising PropertyChanged Events.

Initializing Properties and Event Listeners

If your custom control must initialize any properties or event listeners, override the initialize method in the component's prototype. A client control that is derived from the Control base class typically binds any handlers to its DOM element events and sets the DOM element properties to initial values. As a final step, you call the base initialize method to enable the component's base class to complete initialization.

Releasing Resources

If your custom control must release resources before the control is disposed, override the dispose method and release the resources in the overridden method. This makes sure that the resources are released immediately before the control is disposed. Resources to release include handlers that are used to bind to DOM events. By verifying that any possible circular references between DOM elements and the component object are removed, you make sure that the object can be removed from memory. For more information, see Releasing Component Resources.

Using a Control in a Page

To use a custom client control in an ASP.NET Web page, you do the following:

• Register the client control's script library in the Web page.

• Create a client control instance.

The following sections provide details about these steps.

Registering A Control's Script Library in the Web Page

You can register scripts that are required for a client control on the page with a ScriptManager control, either declaratively or programmatically.

The following example shows the declarative markup for a ScriptManager control that registers a control script.

<form id="form1" runat="server">
  <asp:ScriptManager runat="server" ID="ScriptManager01">
    <scripts>
      <asp:ScriptReference path="HoverButton.js" />
    </scripts>
  </asp:ScriptManager>
</form>

The asp:ScriptManager element contains an asp:ScriptReference element inside a scripts node. The path attribute of the asp:ScriptReference element references the path of the HoverButton.js file that defines a control class. For more information, see Dynamically Assigning Script References and the ScriptManager class overview.

As an alternative to registering script files by using the ScriptManager control, you can manage client components by using a custom server control that implements the IScriptControl interface. A custom server control can automatically register the required component scripts and expose declarative markup for setting for component properties and event bindings. This makes it easier for a page developer to use your custom control. For more information, see the IScriptControl class overview.

Creating a Custom Control Instance

You instantiate a custom client control by calling the Sys.Component.create method or the $create shortcut during the Sys.Application.init event. The following table describes the parameters that you pass to the $create method when you create a client control.

This following example shows how to instantiate a control instance by calling the $create method.

$create(Demo.HoverButton, {text: 'A HoverButton Control',element: {style: {fontWeight: "bold", borderWidth: "2px"}}}, {click: start, hover: doSomethingOnHover, unhover: doSomethingOnUnHover},null, $get('Button1'));

For more information, see Sys.Component.create Method and Sys.Component $create Method.

Creating the Custom HoverButton Control

In this section you will create a simple custom client control named HoverButton that extends the Control base class, and then use the control in a page. The HoverButton control intercepts the click, focus, and mouseover events of an associated HTML button element. It also provides the controls with events that are bindable through the $create method. A page developer who uses the HoverButton control can bind to the control's hover event.

To create the code for the HoverButton control

1. In the root directory of an AJAX-enabled ASP.NET Web site, create a file named HoverButton.js.

2. Add the following code to the file:

   Type.registerNamespace("Demo");
   
   // Constructor
   Demo.HoverButton = function(element) {
   
       Demo.HoverButton.initializeBase(this, [element]);
   
       this._clickDelegate = null;
       this._hoverDelegate = null;
       this._unhoverDelegate = null;
   }
   Demo.HoverButton.prototype = {
   
       // text property accessors.
       get_text: function() {
           return this.get_element().innerHTML;
       },
       set_text: function(value) {
           this.get_element().innerHTML = value;
       },
   
       // Bind and unbind to click event.
       add_click: function(handler) {
           this.get_events().addHandler('click', handler);
       },
       remove_click: function(handler) {
           this.get_events().removeHandler('click', handler);
       },
   
       // Bind and unbind to hover event.
       add_hover: function(handler) {
           this.get_events().addHandler('hover', handler);
       },
       remove_hover: function(handler) {
           this.get_events().removeHandler('hover', handler);
       },
   
       // Bind and unbind to unhover event.
       add_unhover: function(handler) {
           this.get_events().addHandler('unhover', handler);
       },
       remove_unhover: function(handler) {
           this.get_events().removeHandler('unhover', handler);
       },
   
       // Release resources before control is disposed.
       dispose: function() {
   
           var element = this.get_element();
   
           if (this._clickDelegate) {
               Sys.UI.DomEvent.removeHandler(element, 'click', this._clickDelegate);
               delete this._clickDelegate;
           }
   
           if (this._hoverDelegate) {
               Sys.UI.DomEvent.removeHandler(element, 'focus', this._hoverDelegate);
               Sys.UI.DomEvent.removeHandler(element, 'mouseover', this._hoverDelegate);
               delete this._hoverDelegate;
           }
   
           if (this._unhoverDelegate) {
               Sys.UI.DomEvent.removeHandler(element, 'blur', this._unhoverDelegate);
               Sys.UI.DomEvent.removeHandler(element, 'mouseout', this._unhoverDelegate);
               delete this._unhoverDelegate;
           }
           Demo.HoverButton.callBaseMethod(this, 'dispose');
       },
   
       initialize: function() {
   
           var element = this.get_element();
   
           if (!element.tabIndex) element.tabIndex = 0;
   
           if (this._clickDelegate === null) {
               this._clickDelegate = Function.createDelegate(this, this._clickHandler);
           }
           Sys.UI.DomEvent.addHandler(element, 'click', this._clickDelegate);
   
           if (this._hoverDelegate === null) {
               this._hoverDelegate = Function.createDelegate(this, this._hoverHandler);
           }
           Sys.UI.DomEvent.addHandler(element, 'mouseover', this._hoverDelegate);
           Sys.UI.DomEvent.addHandler(element, 'focus', this._hoverDelegate);
   
           if (this._unhoverDelegate === null) {
               this._unhoverDelegate = Function.createDelegate(this, this._unhoverHandler);
           }
           Sys.UI.DomEvent.addHandler(element, 'mouseout', this._unhoverDelegate);
           Sys.UI.DomEvent.addHandler(element, 'blur', this._unhoverDelegate);
   
           Demo.HoverButton.callBaseMethod(this, 'initialize');
   
       },
       _clickHandler: function(event) {
           var h = this.get_events().getHandler('click');
           if (h) h(this, Sys.EventArgs.Empty);
       },
       _hoverHandler: function(event) {
           var h = this.get_events().getHandler('hover');
           if (h) h(this, Sys.EventArgs.Empty);
       },
       _unhoverHandler: function(event) {
           var h = this.get_events().getHandler('unhover');
           if (h) h(this, Sys.EventArgs.Empty);
       }
   }
   Demo.HoverButton.registerClass('Demo.HoverButton', Sys.UI.Control);
   
   // Since this script is not loaded by System.Web.Handlers.ScriptResourceHandler
   // invoke Sys.Application.notifyScriptLoaded to notify ScriptManager 
   // that this is the end of the script.
   if (typeof(Sys) !== 'undefined') Sys.Application.notifyScriptLoaded();
   

Code Discussion

The code registers the Demo namespace by calling the Type.registerNamespace method. The constructor invokes the inherited initializeBase method so that the Control base class methods are available. The initialized base class in turn registers the Demo.HoverButton instance with the client application as a disposable object.

In the prototype, the code declares the public events click, hover, and unhover. The page developer can add and remove handlers that listen for those events. These methods in turn add or remove the specified handler through the control's event-handler collection. You add and remove handlers in your control class through the control's Sys.EventHandlerList object. The EventHandlerList object contains a collection of the control's event handlers through the inherited Sys.Component.events property. In the example, the code invokes the Sys.EventHandlerList.addHandler and Sys.EventHandlerList.removeHandler methods of the returned EventHandlerList object in order to add or remove the handlers.

The HoverButton class overrides the base dispose method to safely dispose any control resources (such as handlers for DOM events) before the control is disposed. Finally, the code calls the base dispose method to enable the application to release the control.

Using the HoverButton Control in a Web Page

In this section, you will learn how to create a control instance by using client script in a Web page.

To create a page to use the HoverButton control

1. In the application root directory where you put the HoverButton.js file, create a file named DemoHoverButton.aspx.

2. Add the following markup and code to the file:

   <!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "https://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
   
   <html xmlns="https://www.w3.org/1999/xhtml" >
   <head id="Head1" runat="server">
   
       <style type="text/css">
           button {border: solid 1px black}
           #HoverLabel {color: blue}
       </style>
       <title>Control Demo</title>
   </head>
   <body>
       <form id="form1" runat="server">
           <div id="ResultDisplay"></div>
   
               <asp:ScriptManager runat="server" ID="ScriptManager01">
                   <scripts>
                      <asp:ScriptReference Path="HoverButton.js" />
                   </scripts>
               </asp:ScriptManager>
   
               <script type="text/javascript">
                   var app = Sys.Application;
                   app.add_init(applicationInitHandler);
   
                   function applicationInitHandler(sender, args) {
                       $create(Demo.HoverButton, {text: 'A HoverButton Control',element: {style: {fontWeight: "bold", borderWidth: "2px"}}}, {click: start, hover: doSomethingOnHover, unhover: doSomethingOnUnHover},null, $get('Button1'));
                   }
   
                   function doSomethingOnHover(sender, args) {
                       hoverMessage = "The mouse is over the button."
                       $get('HoverLabel').innerHTML = hoverMessage;
                   }
   
                   function doSomethingOnUnHover(sender, args) {
                      $get('HoverLabel').innerHTML = "";
                   }
   
                   function start(sender, args) {
                      alert("The start function handled the HoverButton click event.");
                   }
               </script>
   
               <button type="button" id="Button1"></button>&nbsp;
           <div id="HoverLabel"></div>
       </form>
   
   </body>
   </html>
   

Code Discussion

The DemoHoverButton.aspx file is an ASP.NET Web page that hosts the custom control. In the page, the functions that are bound to the custom control are defined in the script element. In the Sys.Application.init event handler, the HoverButton control is instantiated in client script by calling the $create method. The code passes the following arguments to the $create method:

• The type argument contains the Demo.HoverButton class that you created earlier.

• The properties argument contains a JSON object that contains the required control ID value, followed by property name-value pairs that specify property names with initial values.

• The events argument contains an object that contains event names paired with their handlers.

In the ScriptManager control, the path attribute of the asp:ScriptReference node references the path of the HoverButton.js file that defines the Demo.HoverButton control class.

Setting DOM-element Event Handlers and Component Event Handlers

AJAX functionality in ASP.NET includes classes that provide standardized event management for components and for DOM elements. You manage your control's events by using members of the Sys.EventHandlerList class, such as addHandler and removeHandler. For more information, see the Sys.EventHandlerList class overview.

You manage event handlers for DOM elements or for window object events by using static methods of the Sys.UI.DomEvent class, addHandler or removeHandler. For more information, see the Sys.UI.DomEvent class overview.

Accessing DOM-element Properties

The Sys.UI.DomElement class contains members that enable you to add, remove, and toggle CSS class associations for client controls and elements. These members also provide standardized access to DOM element properties. For more information, see Sys.UI.DomElement Class.

See Also

Tasks

Creating Custom Non-Visual Client Components

Dynamically Assigning Script References

Reference

Sys.Component Class

ScriptManager

Concepts

Using the ASP.NET UpdatePanel Control with Data-Bound Controls

Working with Partial-Page Rendering Events