An ASP.NET AJAX client class, which includes a component class, is defined in JavaScript using the prototype design pattern. To define a component class by using the prototype design pattern, you do the following:

• Register the namespace for your component class.

• Create the component's constructor function, and in the constructor function, define any private fields and set their initial values.

• Define the component's prototype.

• Register the component function as a class derived from Component.

For more information, see Creating a Client Component Class Using the Prototype Model.

In the component's constructor function, you invoke the inherited Type.initializeBase method to initialize the base type of your registered class. A non-visual component class is registered as a class that has a base type of Component. When the Component base class is initialized, its methods are available to the component, and it automatically registers the component as a disposable object with the AJAX-enabled ASP.NET application. For more information, see Sys.IDisposable Interface.

Any component class that derives from Component must initialize its base class from the constructor. You typically call initializeBase before any other code runs in the constructor. The following example shows the constructor function of a non-visual component that derives from Component.

Samples.SimpleComponent = function()
{
    Samples.SimpleComponent.initializeBase(this);
}

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

If your custom component must initialize any properties or event listeners, you should override the Sys.Component.initialize method in the component's prototype. For example, a non-visual component that derives from Component might assign a delegate to an event such as window.onFocus. As a final step, you call the base initialize method to enable the component's base class to complete initialization.

ASP.NET provides classes and methods to provide standard event management for components and for DOM elements. To manage your component's events, use the Sys.EventHandlerList class. For example, bind events by using the Sys.EventHandlerList.addHandler method, and release them by using the Sys.EventHandlerList.removeHandler method. For more information, see Sys.EventHandlerList Class.

To manage event handlers for DOM elements or for the window object, use the Sys.UI.DomEvent class. For example, you can bind and unbind event handlers by using the Sys.UI.DomEvent addHandler and Sys.UI.DomEvent removeHandler methods. For more information, see Sys.UI.DomEvent Class.

If your custom component must release resources before the component 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 component is disposed. Resources that should be released might include handlers for 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.

You can register scripts 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 component script.

<form id="form1" runat="server">
  <asp:ScriptManager runat="server" ID="ScriptManager01">
    <scripts>
      <asp:ScriptReference path="DemoTimer.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 .js file (in the example, DemoTimer.js) that defines a component 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 the client components by using a custom server control that implements the IScriptControl interface. The custom server control can automatically register the required component scripts and expose declarative markup for setting component properties and event bindings. If you register scripts by using a custom server control, you can make it easier for a page developer to use your component. For more information, see the IScriptControl class overview.

Note:
All standalone script files to be registered with the ScriptManager control must call the notifyScriptLoaded method to notify the application that the script has finished loading. Scripts that are embedded in an assembly should not call this method in most cases. For more information, see Sys.Application.notifyScriptLoaded Method.

You instantiate a client component by calling the Sys.Component.create method or the $create shortcut. You pass parameters to the $create method to specify the component type. You also pass a JSON object that contains a required ID value and optional initial property values and optional event-handler bindings.

The following example shows how to instantiate a component instance by calling the $create method.

var app = Sys.Application;
app.add_init(applicationInitHandler);

function applicationInitHandler(sender, args) 
{
    $create(Demo.Timer, {enabled:true,id:"demoTimer1", interval:2000}, 
        {tick:OnTick}, null);
}

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

The code registers the Demo namespace by calling the Type.registerNamespace method. It is recommended that you declare and initialize all private fields in the constructor, such as interval in this example. The constructor invokes the inherited initializeBase method so that the Component base class methods are available. The initialized base class in turn registers the Demo.Timer instance with the client application as a disposable object.

In the prototype, the code declares and initializes two public properties: interval and enabled. The property definitions include private fields to hold their values, and get and set accessors for each property. In the set accessor method for each public property, the code raises a propertyChanged event by invoking the raisePropertyChanged method. This event notifies page developers every time that the property is changed.

The add_tick and remove_tick methods enable a page developer to add and remove methods that will listen for the tick event. These methods in turn add or remove the specified handler through the component's Sys.EventHandlerList collection. The EventHandlerList object contains a collection of the component'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 specified handler.

The Demo.Timer class overrides the base class's dispose method to update the enabled property and to indicate to consumers that the component has been disabled. The set accessor for the enabled property raises the propertyChanged event to send the notification. The code invokes the private _stopTimer method to stop tick events from being raised. Finally, the code calls the base dispose method to enable the application to release the component.

The example page loads the TestDemoTimer.js by using JavaScript code that contains two functions, OnTick and applicationInitHandler. The OnTick function handles the Demo.Timer component's tick event and updates a counter value in a span HTML element.

The applicationInitHandler function is a handler for the app_init event. In the function, the Demo.Timer component is instantiated in client script by invoking the $create method, passing the following arguments:

• The type argument is the Demo.Timer class that you created earlier.

• The properties argument consists of a JSON object that contains the required component ID value followed by property name/value pairs that specify property names with initial values. For demonstration purposes, the interval property is initially set to 2000 milliseconds so that the timer will raise a tick event every 2 seconds. (In a production application, you would probably set the interval to a greater value to reduce network traffic.) The component's enabled property is set to true so that the timer will start immediately after it is instantiated.

• The events argument contains an object that has event names paired with their handlers. In this case, the onTick handler is assigned to the tick event, which is defined in the page's script element.

The DemoTimer.aspx file is an ASP.NET Web page that hosts the component. In the page's ScriptManager control, the path attribute of the asp:ScriptReference element references the path of the DemoTimer.js file that defines the Demo.Timer component class.