Creating Custom ASP.NET AJAX Client Controls—IScriptControl.GetScriptDescriptors Method

Microsoft .NET Framework, ASP.NET, Visual C# (CSharp, C Sharp, C-Sharp) Developer Training, Visual Studio

CSharp-Online.NET:Articles

ASP.NET Articles

Creating Custom ASP.NET AJAX Client Controls Prerequisites Extend existing controls Extend Image web control Creating ImageEx custom web control Registering the client control Implementing the IScriptControl Interface GetScriptDescriptors method GetScriptReferences method Building the client control Client control Prototype Registering the client control References What's Next

edit

IScriptControl.GetScriptDescriptors method

You must implement GetScriptDescriptors() method to define the instance of the client control type. To do so, you’ll need to create new ScriptControlDescriptor object and includes it in the return value for the GetScriptDescriptors() method. It worth to mention that ScriptControlDescriptor inherits indirectly from ScriptDescriptor.

The ScriptControlDescriptor object includes the name of the client class, e.g. SCS.WebControls.ImageEx and the ClientID value for the Web server control. This value is used as the id value for the rendered DOM element. The client class name and the ClientID value are passed to the constructor for the ScriptControlDescriptor object.

The ScriptControlDescriptor class is used to set the client control's property values, whose values are obtained from properties of the Web server control. To implement this associate, the server control uses the AddProperty method of the ScriptControlDescriptor class. It then specifies a name and value for the property of the client control, based on the corresponding property of the Web server control.

ImageE web control will ScriptControlDescriptor object to set the values of the normalImageUrl, hoverImageUrl, activeImageUrl and disabledImageUrl properties in the corresponding client control.

The control supplies the ScriptControlDescriptor instance in the return value for the GetScriptDescriptors() method.

IEnumerable<ScriptDescriptor> IScriptControl.GetScriptDescriptors()
{
  ScriptControlDescriptor descriptor = new ScriptControlDescriptor(
                                        "SCS.WebControls.ImageEx", this.ClientID);
  descriptor.AddProperty("normalImageUrl", 
                        this.ResolveClientUrl(this.ImageUrl));
  descriptor.AddProperty("hoverImageUrl", 
                        this.ResolveClientUrl(this.HoverImageUrl));
  descriptor.AddProperty("activeImageUrl",
                        this.ResolveClientUrl(this.ActiveImageUrl));
  descriptor.AddProperty("disabledImageUrl", 
                        this.ResolveClientUrl(this.DisabledImageUrl));
 
  return new ScriptDescriptor[] { descriptor };
}

Therefore, whenever the Web server control is rendered to the browser, ASP.NET AJAX renders JavaScript that creates an instance of the client control with all properties and event handlers. The control instance is attached to the DOM element, based on the ClientID rendered from the Web server control as mentioned earlier. Bellow is an example shows declarative ASP.NET markup that includes the ImageEx Web server control.

<scs:imageex id="ImageEx1" runat="server" Enabled="true"
        ImageUrl="~/images/btn_new.gif"
        HoverImageUrl="~/images/btn_new_hover.gif"
        ActiveImageUrl="~/images/btn_new_active.gif"
        DisabledImageUrl="~/images/btn_new_disabled.gif">
</scs:imageex>

We will look at the rendered output of the page, you'll notice that it includes a call to the $create method that identifies the client class to create. It also provides values for the client properties and the id value of the DOM object that the client control is associated with.

ImageEx client control initialization output (program output)

$create(SCS.WebControls.ImageEx, {"activeImageUrl":"../images/btn_new_active.gif", "disabledImageUrl":"../images/btn_new_disabled.gif", "hoverImageUrl":"../images/btn_new_hover.gif", "normalImageUrl":"../images/btn_new.gif"}, null, null, $get("ImageEx1"));