To encapsulate the client behavior for use by ASP.NET page developers, you can use an extender control. An extender control is a Web server control that inherits the ExtenderControl abstract class in the System.Web.UI namespace. Extender controls can be applied to specific Web server control types. You identify the types of Web server controls to which an extender control can be applied by using the TargetControlTypeAttribute attribute.
The extender control in this tutorial can be applied to any kind of Web server control. The following example shows the class definition.
The new extender control includes two properties that are used to implement the client requirements:
The following table lists members of the ExtenderControl abstract class that you must implement in an extender control.
Member | Description |
|---|
GetScriptDescriptors | Returns a collection of ScriptDescriptor objects that represent ECMAScript (JavaScript) client components. This includes the client type to create, the properties to assign, and the events to add handlers for. |
GetScriptReferences | Returns a collection of ScriptReference objects that contain information about the client-script libraries to be included with the control. The client-script libraries define the client types and include any other JavaScript code that is required for the control. |
The extender control in this tutorial uses the GetScriptDescriptors()()() method to define the instance of the client behavior type. The control creates a new ScriptBehaviorDescriptor object (the ScriptBehaviorDescriptor class derives from the ScriptDescriptor class) and includes the object in the return value for the GetScriptDescriptors method.
The ScriptBehaviorDescriptor object includes the name of the client class (Samples.FocusBehavior) and the ClientID value for the associated (target) Web server control. The client class name and the ClientID property values are supplied to the constructor for the ScriptBehaviorDescriptor object. A reference to the target Web server control is supplied as a parameter to the GetScriptDescriptors(Control) method. The reference can be used to determine the ClientID value of the target Web server control, which is the id value for the rendered DOM element.
The ScriptBehaviorDescriptor class is used to set the client behavior's property values, which are obtained from properties of the extender control on the server. To define the client behavior's properties, the extender control uses the AddProperty method of the ScriptBehaviorDescriptor class. The extender control then specifies the name and value for the property of the client behavior, based on the corresponding property of the server extender control. This example uses a ScriptBehaviorDescriptor object to set the values for the highlightCssClass and nohighlightCssClass properties in the client behavior.
The extender control supplies the ScriptBehaviorDescriptor object in the return value for the GetScriptDescriptors method. Therefore, whenever the Web server control is rendered to the browser, ASP.NET renders JavaScript that creates an instance of the client behavior with all defined properties and event handlers. The behavior instance is attached to the DOM element, based on the ClientID property that is rendered from the target Web server control. The following example shows declarative ASP.NET markup that includes an ASP.NET server control and the extender control from this tutorial in a page.
<asp:TextBox ID="TextBox1" runat="server" />
<sample: FocusExtender runat="server"
ID="FocusExtender1"
HighlightCssClass="MyHighLight"
NoHighlightCssClass="MyLowLight"
TargetControlID="TextBox1" />
The rendered output of the page includes a call to the $create method that identifies the client behavior to create. It also provides values for the client behavior's properties and the id value of the DOM element that the client behavior targets. The following example shows a rendered $create method.
$create(Samples.FocusBehavior, {"highlightCssClass":"MyHighLight","nohighlightCssClass":"MyLowLight"}, null, null, $get('TextBox1'));
The extender control in this tutorial uses the GetScriptReferences method to pass the location of the script library that defines the client behavior type. In the example, this is a URL to the script file named FocusBehavior.js, which is created later in this tutorial. The reference is made by creating a new ScriptReference object, and then setting the Path property to the URL of the file that contains the client code.
The following example shows the implementations of the GetScriptDescriptors and GetScriptReferences methods.
Protected Overrides Function GetScriptReferences() As IEnumerable(Of ScriptReference)
Dim reference As ScriptReference = New ScriptReference()
reference.Path = ResolveClientUrl("FocusBehavior.js")
Return New ScriptReference() {reference}
End Function
Protected Overrides Function GetScriptDescriptors(ByVal targetControl As Control) As IEnumerable(Of ScriptDescriptor)
Dim descriptor As ScriptBehaviorDescriptor = New ScriptBehaviorDescriptor("Samples.FocusBehavior", targetControl.ClientID)
descriptor.AddProperty("highlightCssClass", Me.HighlightCssClass)
descriptor.AddProperty("nohighlightCssClass", Me.NoHighlightCssClass)
Return New ScriptDescriptor() {descriptor}
End Function
protected override IEnumerable<ScriptReference> GetScriptReferences()
{
ScriptReference reference = new ScriptReference();
reference.Path = ResolveClientUrl("FocusBehavior.js");
return new ScriptReference[] { reference };
}
protected override IEnumerable<ScriptDescriptor> GetScriptDescriptors(Control targetControl)
{
ScriptBehaviorDescriptor descriptor = new ScriptBehaviorDescriptor("Samples.FocusBehavior", targetControl.ClientID);
descriptor.AddProperty("highlightCssClass", this.HighlightCssClass);
descriptor.AddProperty("nohighlightCssClass", this.NoHighlightCssClass);
return new ScriptDescriptor[] { descriptor };
}