I am currently working on an enterprise level ASP.NET AJAX application to be used in a call center, as most of the applications I create are for use in call center automation and task management. Because Update Panels are evil and this application was riddled with them, I have been slowly but surely stripping them out one by one. The problem, the application loads 90% of its screens and functionality based on configuration data, dynamically building pages and loading user controls located in both ASCX files and server controls located in external assemblies bound at run-time. The major roadblock is that our middle tier is all WCF, which works great, however they are all on a different domain than the web application and use secure SOAP (not REST), therefore I can’t call them from JavaScript. Not only that, there are only 4 pages in the entire application, everything else is dynamic. With over 130+ and growing user controls, and plug-and-play custom functionality, it would be impossible to put all of these methods in copy-cat services using WCF in the web application itself. Did I mention that the site uses a dozen or so host headers in IIS, which rules out WCF hosted svc files in the web site right there. Page methods seemed like a perfect fit, only I wasn’t about to put 200+ web methods on a single page when only one or two user controls would ever use them. That would be stupid and the JavaScript would take forever to compile in even a fast browser.

Everything I found on the web searching Google, MSDN forums, user groups, etc has turned up one and only one answer to my dilemma: This can not be done, only public, static methods on an actual ASPX page may contain page methods in this manner because ASCX controls do not have their own unique post-back address like a page does. I thought to myself, This is stupid! Of all the brilliant things Microsoft has done with ASP.NET you would think that they would have built the ability to register methods dynamically on the page through a child control, whether a user control or master page, either as a callback, delegate, etc, at least some model for doing this, but alas, apparently myself and the hundreds of other posters out there have not been diligent in filling out feature requests for this item, which I will do sometime later this week.

The solution:

While ASCX user controls may not contain page methods (ScriptMethod), pages can. Duh, right! So why can’t I create a single, general page method in my base page class which all of my site pages inherit from, and provide a means, through reflection and custom attributes, along with my base user control class that all my ASCX user controls ultimately inherit from, to dynamically create JavaScript wrappers for calling my page’s single page method, which in turn knows how to invoke my user control type’s public static method, passing in any collection of parameters and even providing a wrapper for JSON serialization of the method’s result back to the client, INCLUDING ANONYMOUS TYPES!!! OK, now I’m on to something.

The end result is a custom attribute which my base user control class detects on static, invoking, public methods, which then registers some well-crafted JavaScript script block with the page’s ScriptManager, which in turn know how to invoke the page’s ScriptMethod dynamically passing in some information about the type name and method name to invoke through reflection.

Now, to the code

First, we need to create an attribute to attach to our ultra-nifty public static methods in our user controls that we want to expose to our client as ScriptMethods. I’m going to call my attribute UserControlScriptMethodAttribute, but you can call it whatever you want. This is a very simple attribute, not much to do here. You could add some validation that it’s on a static and public member, but that’s up to you.

[AttributeUsage(AttributeTargets.Method, Inherited = false, AllowMultiple = false)]
public sealed class UserControlScriptMethodAttribute : Attribute
{
    /// <summary>
    /// Initializes a new instance of the <see cref="UserControlScriptMethodAttribute"/> class.
    /// </summary>
    public UserControlScriptMethodAttribute() { }
}

BasePage.cs

Then, I needed my base implementation for the “generalized” ScriptMethod. This would be on the page class that all of my pages inherit from, exposing the capability of using these ScriptMethod from any user control or master page that I want to.

There are several important things going on in the base page class. First, I needed to create my script method. This method has a simple signature, basically taking a fully qualified type name (including the assembly if need be), as well as the method name to invoke in that type and a boxed object array for any additional arguments which should be passed through as parameters when invoking the method. I’ve hard-coded my response format as JSON and HttpGet=false. You could theoretically create several versions of these method for different options and add these options as well to your custom parameter for consumption, but I didn’t need anything that sophisticated here.

[WebMethod(EnableSession = true)]
[ScriptMethod(ResponseFormat = ResponseFormat.Json, UseHttpGet = false)]
public static string PageServiceRequest(string typeName, string methodName, object[] args)
{
    Type ctl = Type.GetType(typeName);
    if (ctl != null)
    {
        object o = ctl.InvokeMember(
            methodName,
              System.Reflection.BindingFlags.Static
            | System.Reflection.BindingFlags.InvokeMethod
            | System.Reflection.BindingFlags.Public
            | System.Reflection.BindingFlags.IgnoreCase,
            null, null, args ?? new object[]{});
        if (o != null)
        {
            if (o is string || o.GetType().IsValueType)
                return o.ToString(); // If it is a string or value type, return a string

            // If it is a complex object, return a serialized version of it.
            JavaScriptSerializer serializer = new JavaScriptSerializer();
            return serializer.Serialize(o); // allow anonymous types, etc
        }
    }
    return "{}"; // return an empty JSON object
}

Notice that once I get the Type I need from the type name, getting the method using some simple binding flags is rather easy, then invoking it passing the arguments object array straight through. From there, I take the result of the method invocation and determine if it is a value type or a string, if it is, I simply return the value.ToString(), otherwise I’m serializing it to JSON and still returning a string (only this string is JSON). The JavaScriptSerializer even allows me to take an anonymous type from the invocation target and serialize it directly back to the client in JSON without having to any further work, which you’ll see a little later in this article, is really freakin’ cool!

Next, I need to expose a more friendly wrapper around the ScriptMethod in JavaScript so my user controls will have to know less about how to invoke this guy and it makes it a bit more usable.

private void RegisterPageServiceRequestProxy()
{
    ScriptManager.RegisterClientScriptBlock(
        this,
        GetType(),
        "PageServiceRequestProxy",
        "function InvokeServiceRequest(typeName,methodName,successCallback,failureCallback){if(PageMethods.PageServiceRequest){try{var parms=[];for(var i=4;i<arguments.length;i++){parms.push(arguments[i]);}PageMethods.PageServiceRequest(typeName,methodName,parms,successCallback,failureCallback);}catch(e){alert(e.toString());}}}",
        true);
}

Wow, this a really long, condensed line of JavaScript which you don’t necessarily need to understand, other than the fact that it really will make life easy for you. Essentially it creates a wrapper method taking the type name, method name, callbacks and allows you to pass in any number of additional arguments; as many as you want after the failure callback. This wrapper will then simply take those extra parameters and build an Array object to pass as the “args” parameter to the base ScriptMethod. I need to call this method OnInit as seen below:

protected override void OnInit(EventArgs e)
{
    base.OnInit(e);
    RegisterPageServiceRequestProxy();
}

BaseUserControl.cs

Our base user control, which all ASCX pages will inherit is a bit more involved. For one, we need to obfuscate the innards of how our new attribute is consumed. We also want to hide all the minutia around passing fully qualified type names and method names, etc. We also want to expose some nicely formed methods on the client via JavaScript that can be called using the same method name and similar parameter signature as the method in the ASCX code-behind, with the exception of the callback client methods (the whole point of asynchronous client processing).

First, I want to emit and register my scripts and “stuff” during the Pre-Render phase of the page life-cycle, so I’m going to override OnPreRender to call my register method.

protected override void OnPreRender(EventArgs e)
{
    base.OnPreRender(e);
    RegisterUserControlWebMethods();
}

Next, let’s build out the implementation of our RegisterUserControlWebMethods method stub. I made it private because it doesn’t need visibility outside of our base class, remember our attribute will take care of this for us.

private void RegisterUserControlWebMethods()
{
    foreach (MethodInfo method in this.GetType().GetMethods(BindingFlags.Static | BindingFlags.Public | BindingFlags.InvokeMethod))
        if (method.GetCustomAttributes(typeof(UserControlScriptMethodAttribute), true).Length > 0)
            RegisterUserControlWebMethod(method);

    Type baseType = this.GetType().BaseType;
    if (baseType != null && (baseType.Namespace == null || !baseType.Namespace.StartsWith("System")))
        foreach (MethodInfo method in baseType.GetMethods(BindingFlags.Static | BindingFlags.Public | BindingFlags.InvokeMethod))
            if (method.GetCustomAttributes(typeof(UserControlScriptMethodAttribute), true).Length > 0)
                RegisterUserControlWebMethod(method);
}

In the example above, you can see our initial search within the current type for any methods with the appropriate binding flags, being static, public and invoke, as well as a test for our custom attribute. If we find any, for each one that we find we’re going to further call our RegisterUserControlWebMethod (more on this in a few lines). You’ll notice that we also do a second round through reflection to get the base type and check any methods in there for these super special attribute decorated methods. I could have made this a bit cleaner in the recursion department, but again, I didn’t need to for my purposes, I’m sure there are better ways to do this. The reason I’m doing this second loop on base types is simple, depending on your project structure, either a Web Project or Web Site, you will find that your methods exist not in the current type, but the base type as the current type you have loaded is some temporary type drummed up in the CLR at run-time or located in a special page or directory assembly, etc.

Now that we’ve found the methods we need to be able to invoke on the client, we need to emit and register wrappers for those methods, obfuscating the details around type names, method names, etc and providing a neat and concise means of invoking them on the client.

private void RegisterUserControlWebMethod(MethodInfo method)
{
    string blockName = string.Concat(method.Name, "_webMethod_uc");

    StringBuilder funcBuilder = new StringBuilder();
    funcBuilder.Append("function ");
    funcBuilder.Append(method.Name);
    funcBuilder.Append("(successCallback,failureCallback");
    foreach (var par in method.GetParameters())
        funcBuilder.AppendFormat(",{0}", par.Name);
    funcBuilder.Append("){if(PageMethods.PageServiceRequest){try{var parms=[];for(var i=2;i<arguments.length;i++){parms.push(arguments[i]);}PageMethods.PageServiceRequest(");
    funcBuilder.AppendFormat("'{0}','{1}'", method.DeclaringType.AssemblyQualifiedName, method.Name);
    funcBuilder.Append(",parms,successCallback,failureCallback);}catch(e){alert(e.toString());}}}");

    ScriptManager.RegisterClientScriptBlock(this, GetType(), blockName, funcBuilder.ToString(), true);
}

The RegisterUserControlWebMethod method takes the method info through reflection and builds a JavaScript function with the same name as the method, then adds the appropriate callback parameters which are always the first and second parameter respectfully, then takes the parameter collection (much like the base page registered method did) and passes those an a JavaScript Array, invoking the PageServiceRequest through the PageMethods namespace. When invoking the PageServiceRequest method, it also passes the fully qualified type name of the method info’s declaring type and the method name through reflection, keeping these values in the function wrapper as coded string values.

ServerTime.ascx

ServerTime is my example User Control which gets loaded on a simple page, Default.aspx. There i no code on Default.aspx, therefore there is no need to put anything here for it. All I did was drop the ServerTime.ascx user control onto the designer surface of Default.aspx in Visual Studio so the page would host my user control. Keep in mind I’m setting my base page type and base user control type in my web.confg as shown here:

<system.web>
    <pages pageBaseType="ScharfHoldings.BasePage" userControlBaseType="ScharfHoldings.BaseUserControl"

The code-behind file, ServerTime.ascx.cs looks like this below:

using System;
using System.Collections.Generic;
using System.Linq;
using System.Web;
using System.Web.UI;
using System.Web.UI.WebControls;

public partial class ServerTime : ScharfHoldings.BaseUserControl
{
    [ScharfHoldings.UserControlScriptMethod]
    public static string GetTime()
    {
        // Return a simple string to the client. This by-passes serialization since it is only a string.
        return DateTime.Now.ToLongTimeString();
    }

    [ScharfHoldings.UserControlScriptMethod]
    public static ComplexTime GetComplexTime()
    {
        // Return a strongly typed object instance to the client.
        return new ComplexTime() { Time = DateTime.Now.ToLongTimeString(), MachineName = HttpContext.Current.Server.MachineName };
    }

    [ScharfHoldings.UserControlScriptMethod]
    public static object GetAnonymousTime()
    {
        // Return an anonymous type instance to the client.
        //    this anonymous type is intended to mimic our ComplexTime type, only it is anonymous, however will
        //    behave the exact same when it is serialized to the client through JavaScript.
        return new { Time = DateTime.Now.ToLongTimeString(), MachineName = HttpContext.Current.Server.MachineName };
    }

    [ScharfHoldings.UserControlScriptMethod]
    public static object GetTimeWithParameter(string clientMessage)
    {
        // Return an anonymous type instance to the client.
        //    The clientMessage parameter gets passed in dynamically from the client and we're going to set the
        //    MachineName property to this value to pass back from the server to prove we got the client value in the parameter.
        return new { Time = DateTime.Now.ToLongTimeString(), MachineName = clientMessage };
    }

    [Serializable]
    public class ComplexTime
    {
        public string Time { get; set; }
        public string MachineName { get; set; }
    }
}

As you can see I have 4 of my custom script methods to show-case the different capabilities built into this methodology. One is a simple call, with no parameters, which returns a string.

GetComplexTime takes no parameters and returns an object of type ComplexType which has a property, Time and MachineName.

GetAnonymousType showcases the ability for this method to return anonymous types to the client, which is a very powerful feature and presents itself more like JavaScript rather than .NET. The anonymous type I am created here is intended to look exactly like ComplexType for no other reason than to re-use code on client and show it can be done.

GetTimeWithParameter takes a simple type parameter (a string in this case) and returns another anonymous type, but this time plugging the parameter into the MachineName property instead of the server’s machine name. This again is for ease of example and code re-use.

Now, let’s take a look at the client side of this. First, I have a simple structure for displaying my data and a button to invoke all of my server methods asynchronously:

<%@ Control Language="C#" AutoEventWireup="true" CodeFile="ServerTime.ascx.cs" Inherits="ServerTime" %>
<div id="myTime">
    <div id="time"></div>
    <div id="complexTime"></div>
    <div id="anonymousTime"></div>
    <div id="parameterTime"></div>
    <input type="button" id="refreshMe" value="Get Time" title="Click here to refresh the time from the server" onclick="refreshTime();return false;" />
</div>

As you can see, I have a DIV for each method result to show the results of each method call and a simple button labeled Get Time that will call a simple JavaScript function, that in turn calls all of my user control Script methods.

Here is what the page and user control look like upon their initial state:

Now we need to make the button do something interesting. Below is the JavaScript block that provides the method that executes all the other methods, refreshTime() as well as the callback methods for success and failure of each ScriptMethod call that we make. the last two methods are simply for displaying the results of the script methods in their respectful DIV elements.

<script type="text/javascript">
//<![CDATA[
    function refreshTime() {
        try {
            // Call the UserControlWebMethod attributed functions on the server.
            GetTime(refreshTime_Success, refreshTime_Failure);
            GetComplexTime(refreshTimeComplex_Success, refreshTimeComplex_Failure);
            GetAnonymousTime(refreshTimeAnonymous_Success, refreshTimeAnonymous_Failure);
            GetTimeWithParameter(refreshTimeWithParameter_Success, refreshTimeWithParameter_Failure, 'the Client... Hi!');
        }
        catch (e) { alert(e.message); }
    }

    // Delegate functions for the GetTime method
    function refreshTime_Success(result) { displayTime(result); }
    function refreshTime_Failure(result) { }

    // Delegate functions for the GetComplexTime method
    function refreshTimeComplex_Success(result) { displayComplexTime(result, $get('complexTime')); }
    function refreshTimeComplex_Failure(result) { }

    // Delegate functions for the GetAnonymousTime method
    function refreshTimeAnonymous_Success(result) { displayComplexTime(result, $get('anonymousTime')); }
    function refreshTimeAnonymous_Failure(result) { }

    // Delegate functions for the GetTimeWithParameter method
    function refreshTimeWithParameter_Success(result) { displayComplexTime(result, $get('parameterTime')); }
    function refreshTimeWithParameter_Failure(result) { }

    // Simply set the innerText of the simple time element from the raw result of the service method.
    function displayTime(timeAsString) {
        document.getElementById('time').innerText = timeAsString;
    }

    // Evaluate and parse out the JSON object to a type using eval, then build a display string and display the result.
    function displayComplexTime(timeAsObj, ctrl) {
        try {
            var obj = eval('(' + timeAsObj + ')');
            if (obj) ctrl.innerText = obj.Time + ' on ' + obj.MachineName;
        }
        catch (e) { alert(e.message); }
    }
//]]>
</script>

As you can see, when we’re getting back an object (rather than a simple or value type) we have to call eval() on that object’s JSON string, wrapped in parenthesis in order to get the actual object instance from the JSON (otherwise it is still just a string). Once I have an instance from the JSON using eval, I can get property values from that object, such as you see here, which are exactly the same name as the properties specified in both the ComplexTime class, as well as both uses of the anonymous types.

The end result looks like this once I click the button (notice, depending on your computer’s speed, you may see all the lines appear or refresh at the same time or like me you may see a slight delay in the asynchronous processing of each of the methods.

Viola! That’s all there is to it. NEVER let anyone tell you ever again that you can’t create page methods in an ASCX user control, because using these technique, you most definitely can!

Source Code Download

I’ve created a simple, sample web site in Visual Studio 2008, .NET 3.5 to show off the capabilities and give you a starting point to play around with the code. This is the full working source code that I based the article on. I look forward to getting your comments, feedback and improvements you’ve made or found or any bugs you might have encountered. I’m really excited about using this functionality and have already been successfully incorporating it in our enterprise software with great success. Enjoy!

~ Chad.

Creating a Page method (ScriptMethod) within an ASCX user control using AJAX, JSON, base classes and reflection is a post from: Chad Scharf's Weblog. For software consulting services please visit Scharf Holdings, LLC

Blank (or unset): , Checked (or granted): , and unchecked (or denied): .

I recently had some very difficult requirements to fulfill on an access control and configuration application with a web front end. Those of you who have designed or implemented access control interfaces know this is a daunting task, especially when the access control needs to be fairly flexible. Although it’s easy to implement a user interface that directly represents your data model, your users may not always be able to easily use or understand how to accomplish tasks using it. Usability is important to consider when tackling complex concepts or data structures through web UI.

The requirements for our security model were for granting or denying access to specific data elements in the database. By default a user has access to everything. If you explicitly grant access to an element, the user then only has access to those elements you’ve explicitly granted access to. You can also deny access to a given element; however a single element can only have one preference state, un-specified, grant access, or deny access. To top it all off, all the elements are in a recursive tree structure (always makes things more fun).

I had immediately made the decision that whatever we did, it needed to be in a tree fashion to show the end user the structure of what they were granting access to, however the question remained as to how to represent each state in an intuitive and easy to understand way. Enter the 3-State check box.

Checkboxes only have 2 states

This is a very real statement, and there is no way around it. Although you can typically represent a 3^rd pseudo state by setting the checkbox’s disabled property, this may not always be intuitive to the end user as to what the intention of this state really is. To solve this I first needed to conceptualize what this 3^rd state looks like, and bingo! Here are the 3 states, which I created in Adobe Photoshop from a screen shot of a normal checkbox; Blank (or unset): , Checked (or granted): , and unchecked (or denied): .

Why AJAX?

Given that I’ve decided to create a new server control to handle my 3-state check-box, I need to make some decisions about its behavior. The Microsoft AJAX library in .NET 3.5 offers some powerful APIs for implementing your own behaviors, wiring events and using well-fashioned OO JavaScript among other features. Since on my screen in particular I wasn’t sure if I wanted to use a WCF service on the checkbox’s changed event to update the database, or if I wanted a full or partial post-back to completely rebind the tree after a click, the control needed to be as flexable as possible and easily scripted both on the client and server. Because I needed to manage both client and server side behavior in a consistent manner, I decided to go the MS AJAX route.

The good stuff

The first step in creating my server control was to create a class library project to put my server control in. I’m using the .NET 3.5 framework and used the ASP.NET AJAX server control project template to create my new project. After creating a directory for the images in their own folder, I set their build action in the properties to “Embedded Resource”. I also had to remove the [WebResource] and [ScriptResource] assembly attributes from the AssemblyInfo.cs file (I like putting these on their relevant pages). Next I need to create my server control. The first thing I do is allocate my embedded resources as web resources at the top of the code page under the using statements and before my namespace declaration. I do this simply as a preference to keep embedded resources together with the specific code page that is using them. If they’re more universal to your project you may want to put this back in the AssemblyInfo.cs file.

[assembly: System.Web.UI.WebResource("ChadScharf.ThreeStateCheckBox.images.blank.gif", "image/gif")]
[assembly: System.Web.UI.WebResource("ChadScharf.ThreeStateCheckBox.images.checked.gif", "image/gif")]
[assembly: System.Web.UI.WebResource("ChadScharf.ThreeStateCheckBox.images.unchecked.gif", "image/gif")]
[assembly: System.Web.UI.WebResource("ChadScharf.ThreeStateCheckBox.ThreeStateCheckBox.js", "text/javascript", PerformSubstitution = true)]

Server Control, ThreeStateCheckBox

The ThreeStateCheckBox server control inherits System.Web.UI.WebControls.CompositeControl (since I’ll be using child controls and need a wrapper tag, this was the easiest way to get started). I’m also going to explicitly implement the System.Web.UI.INamingContainer and System.Web.UI.IScriptControl (since we’re using AJAX behaviors).

[PersistChildren(false)]
[ParseChildren(true)]
[ToolboxData(@"<{0}:ThreeStateCheckBox runat=""server""> </{0}:ThreeStateCheckBox>")]

public class ThreeStateCheckBox : CompositeControl, INamingContainer, IScriptControl

I need 2 child controls to manage the checkbox, an ImageButton control and a HiddenField control. The ImageButton will be the actual checkbox. The HiddenField control will represent our client-side state of the checkbox control, therefore our script can modify its value and track it across post-backs if several changes to several of our controls are made at once.

protected ImageButton checkBox;
protected HiddenField hidden;

Next, I need a private ScriptManager property with a getter. Since this is an AJAX dependant control, it requires that a ScriptManager control be on the page it’s on, therefore we use something like this:

private ScriptManager ScriptManager
{
get
{
ScriptManager manager = ScriptManager.GetCurrent(this.Page);
if (manager == null)
throw new InvalidOperationException(string.Format(System.Globalization.CultureInfo.InvariantCulture, “The control with ID ‘{0}’ requires a ScriptManager on the page. The ScriptManager must appear before any controls that need it.”, new object[] { this.ID }));
return manager;
}
}

Now, I needed to decide what properties would be relevant for working with the control. CompositeControl already exposes some properties relevant to style and CssClass, however we need more meaty, behavioral properties. We’ll start with the reasoning that we may not want to post-back when the checkbox is clicked, so let’s add a Boolean AutoPostBack property, which we’ll store in ViewState. Next let’s expose the ImageButton’s CausesValidation property (common among other controls that AutoPostBack such as a DropDownList or CheckBox). Since it could cause validation, we need to expose the ImageButton’s ValidationGroup property. Next to last we need to convey the state of the checkbox, so we’ll expose an enumeration value representing the Checked state, called Checked. This could be a number 0 through 2 or any other relevant property if you wish to change it. We’ll store the Checked state as a string in the HiddenField’s Value property. Finally, I need to be able to assign a data key value to my checkbox so if there is a key, user id, or other relevant data related to this checkbox I can easily pass it around on the client side as well as the server side if we put it in a more complex container control such as a TreeView, etc. The DataKey value will be stored in our ImageButton’s CommandArgument value so we can easily retrieve it later.

Event Handling

In my protected override void CreateChildControls() I’m going to wire up the ImageButton’s Command event and handle that in my server side code. That in turn will check the current Checked state, and change it appropriately, then call OnCheckChanged, which will call the public event CheckChanged, triggering any server side delegates from there.

In the PreRender stage of the page’s lifecycle I’m going to set the ImageButton’s ImageUrl property based on the state of the checkbox pulling from the embedded resource images that we set up earlier. Then, the more important stage of this is to use our IScriptControl interface implementation to register the control with the ScriptManager and register the ScriptDescriptors (we’ll get to that shortly, but we need a call to it anyway).

base.OnPreRender(e);
switch (Checked)
{
case CheckedState.Blank:
checkBox.ImageUrl = Page.ClientScript.GetWebResourceUrl(this.GetType(), “ChadScharf.ThreeStateCheckBox.images.blank.gif”);
break;
case CheckedState.Checked:
checkBox.ImageUrl = Page.ClientScript.GetWebResourceUrl(this.GetType(), “ChadScharf.ThreeStateCheckBox.images.checked.gif”);
break;
case CheckedState.Unchecked:
checkBox.ImageUrl = Page.ClientScript.GetWebResourceUrl(this.GetType(), “ChadScharf.ThreeStateCheckBox.images.unchecked.gif”);
break;
}
this.ScriptManager.RegisterScriptControl<ThreeStateCheckBox>(this);
this.ScriptManager.RegisterScriptDescriptors(this);

IScriptControl Interface Implementation

There are 2 methods in the IScriptControl interface, IEnumerable<ScriptReference> GetScriptReferences(), and IEnumerable<ScriptDescriptor> GetScriptDescriptors(). GetScriptReferences simply returns an enumerable list of script references, in our case we only need one:

yield return new ScriptReference(“ChadScharf.ThreeStateCheckBox.ThreeStateCheckBox.js”, “ChadScharf.ThreeStateCheckBox”);

And GetScriptDescriptors returns a enumerable list of ScriptDescriptor, in our case a ScriptControlDescriptor that we’re going to use to initialize our new type client-side in the AJAX framework, setting specific properties to the client instance so it matches our server-side instance.

if (this.Page != null && this.Visible)
{
ScriptControlDescriptor desc = new ScriptControlDescriptor(“ChadScharf._ThreeStateCheckBox”, this.ClientID);
desc.AddProperty(“checked”, this.Checked.ToString());
desc.AddProperty(“imgBlank”, this.Page.ClientScript.GetWebResourceUrl(this.GetType(), “ChadScharf.ThreeStateCheckBox.images.blank.gif”));
desc.AddProperty(“imgChecked”, this.Page.ClientScript.GetWebResourceUrl(this.GetType(), “ChadScharf.ThreeStateCheckBox.images.checked.gif”));
desc.AddProperty(“imgUnchecked”, this.Page.ClientScript.GetWebResourceUrl(this.GetType(), “ChadScharf.ThreeStateCheckBox.images.unchecked.gif”));
desc.AddProperty(“buttonId”, this.checkBox.ClientID);
desc.AddProperty(“autoPostBack”, this.AutoPostBack);
desc.AddProperty(“hiddenFieldId”, this.hidden.ClientID);
desc.AddProperty(“dataKey”, this.DataKey);
yield return desc;
}

Client Side Script

Now it’s time to create our client behavior, YAY! JavaScript is every web developers favorite technology to work with (GAG!), so I’ll try to keep this part as simplistic as possible and if you don’t want to learn the “why” and “how” you can simply lift the code and be happy . No one will blame you.

As you can see earlier I referenced my script file as an embedded resource using the WebResource directive, passing PerformSubstitution = true. This is not imperitive, however I like the Substitution ability with embedded web resources so you can reference other embedded resources without having to write code to do so (e.g. in embedded CSS files referencing embedded images, etc). I use this to set the 3 image URLs appropriately in the JS file.

The first thing I do in my behavior script is reference the MicrosoftAjax.js file so I can have intellisense (THANK YOU VS 2008!) and register the client-side namespace for my behavior:

/// <reference name=”MicrosoftAjax.js”/>
Type.registerNamespace(‘ChadScharf’);

I won’t go into too many details on specifying the client side behavior code however I’ll try to give a good overview.

The next thing I want to do is declare my constructor for my behavior “type”. In the constructor function I’m going to specify defaults for all my private properties:

ChadScharf._ThreeStateCheckBox = function ChadScharf$_ThreeStateCheckBox(element) {
this._checked = ‘Blank’;
this._buttonId = null;
this._hiddenFieldId = null;
this._autoPostBack = false;
this._clickHandler = null;
this._dataKey = null;
this._imgBlank = ‘<%=WebResource(“ChadScharf.ThreeStateCheckBox.images.blank.gif”)%>’;
this._imgChecked = ‘<%=WebResource(“ChadScharf.ThreeStateCheckBox.images.blank.gif”)%>’;
this._imgUnchecked = ‘<%=WebResource(“ChadScharf.ThreeStateCheckBox.images.blank.gif”)%>’;
// Call base initializer
ChadScharf._ThreeStateCheckBox.initializeBase(this, [element]);
}

If you’ll notice, the type name, ChadScharf._ThreeStateCheckBox is the same as we have in our GetScriptDescriptors() method on the server side, and you’ll also notice some commonalities in the properties we’re setting there using the AddProperty method. This is a neat feature of the AJAX framework for writing custom behaviors and makes your client code work more like your server code with far fewer headaches. The most important part here is to call our base initialization method (OO JavaScript and Inheritance rocks!).

Next are all the property accessors for the client control behavior. In the MS AJAX model, we use the syntax get_propertyName() {}, and set_propertyName(value) {}, where propertyName is the actual name of the property. The framework automatically implies these are get and set property accessors (pretty neat!).

function ChadScharf$_ThreeStateCheckBox$get_checked() {
if (arguments.length !== 0) { throw Error.parameterCount(); }
return this._checked;
}
function ChadScharf$_ThreeStateCheckBox$set_checked(value) {
this._checked = value;
if ($get(this._buttonId)) { $get(this._buttonId).setAttribute(‘checked’, value); }
if ((this._hiddenFieldId) && $get(this._hiddenFieldId)) { $get(this._hiddenFieldId).value = value; }
}
function ChadScharf$_ThreeStateCheckBox$get_imgBlank() {
if (arguments.length !== 0) { throw Error.parameterCount(); }
return this._imgBlank;
}
function ChadScharf$_ThreeStateCheckBox$set_imgBlank(value) {
this._imgBlank = value;
}
function ChadScharf$_ThreeStateCheckBox$get_imgChecked() {
if (arguments.length !== 0) { throw Error.parameterCount(); }
return this._imgChecked;
}
function ChadScharf$_ThreeStateCheckBox$set_imgChecked(value) {
this._imgChecked = value;
}
function ChadScharf$_ThreeStateCheckBox$get_imgUnchecked() {
if (arguments.length !== 0) { throw Error.parameterCount(); }
return this._imgUnchecked;
}
function ChadScharf$_ThreeStateCheckBox$set_imgUnchecked(value) {
this._imgUnchecked = value;
}
function ChadScharf$_ThreeStateCheckBox$get_buttonId() {
if (arguments.length !== 0) { throw Error.parameterCount(); }
return this._buttonId;
}
function ChadScharf$_ThreeStateCheckBox$set_buttonId(value) {
this._buttonId = value;
}
function ChadScharf$_ThreeStateCheckBox$get_autoPostBack() {
if (arguments.length !== 0) { throw Error.parameterCount(); }
return this._autoPostBack;
}
function ChadScharf$_ThreeStateCheckBox$set_autoPostBack(value) {
this._autoPostBack = value;
}
function ChadScharf$_ThreeStateCheckBox$get_hiddenFieldId() {
if (arguments.length !== 0) { throw Error.parameterCount(); }
return this._hiddenFieldId;
}
function ChadScharf$_ThreeStateCheckBox$set_hiddenFieldId(value) {
this._hiddenFieldId = value;
}
function ChadScharf$_ThreeStateCheckBox$get_dataKey() {
if (arguments.length !== 0) { throw Error.parameterCount(); }
return this._dataKey;
}
function ChadScharf$_ThreeStateCheckBox$set_dataKey(value) {
this._dataKey = value;
}

WOW!… that was a lot of getters and setters. Now we need to expose our checkChanged event so other components or client scripts can consume our events using event handlers. In this case the add_ and remove_ prefixes next to our method’s that take a single parameter (handler) act similarly to our getters and setters, they are simply for adding or removing an event handler to a specific event of your element, and since our base type exposes the get_events() method, which allows us to add or remove handlers to our Sys.UI.Control, this is all the code we need to accomplish this feat:

function ChadScharf$_ThreeStateCheckBox$add_checkChanged(handler) {
this.get_events().addHandler(‘checkChanged’, handler);
}
function ChadScharf$_ThreeStateCheckBox$remove_checkChanged(handler) {
this.get_events().removeHandler(‘checkChanged’, handler);
}

Next we need our own event handler methods for when our image button is clicked and when our checked state is changed:

function ChadScharf$_ThreeStateCheckBox$_onButtonClick(eventElement) {
switch (this._checked) {
case ‘Blank’:
this._checked = ‘Checked’;
eventElement.target.src = this._imgChecked;
break;
case ‘Checked’:
this._checked = ‘Unchecked’;
eventElement.target.src = this._imgUnchecked;
break;
case ‘Unchecked’:
this._checked = ‘Blank’;
eventElement.target.src = this._imgBlank;
break;
}
eventElement.target.setAttribute(‘checked’, this._checked);
$get(this._hiddenFieldId).value = this._checked;
if (!this._autoPostBack) {
eventElement.preventDefault();
this._onCheckChanged();
}
}
function ChadScharf$_ThreeStateCheckBox$_onCheckChanged() {
var handler = this.get_events().getHandler(‘checkChanged’);
if (handler) {handler(this, Sys.EventArgs.Empty)};
}

We also need our most important initialize and dispose methods to clean up our event handlers and delegates to prevent memory leaks in IE:

function ChadScharf$_ThreeStateCheckBox$dispose() {
// IDisposable
if (this._clickHandler && $get(this._buttonId)) {
$removeHandler($get(this._buttonId), ‘click’, this._clickHandler);
this._clickHandler = null;
}
ChadScharf._ThreeStateCheckBox.callBaseMethod(this, ‘dispose’);
}
function ChadScharf$_ThreeStateCheckBox$initialize() {
// Initializer
ChadScharf._ThreeStateCheckBox.callBaseMethod(this, ‘initialize’);
if (!this._autoPostBack) {
this._clickHandler = Function.createDelegate(this, this._onButtonClick)
$addHandler($get(this._buttonId), ‘click’, this._clickHandler);
}
}

Implement the behavior

Finally in order to register our control behavior and make it useable we need to create the prototype for it and then register it, specifying its inheritance). The prototype will stage the public properties and methods from our type definition above and package it in a nice neat container that we can register with the ScriptManager and the AJAX framework for use in our code elsewhere.

ChadScharf._ThreeStateCheckBox.prototype = {
get_checked: ChadScharf$_ThreeStateCheckBox$get_checked,
set_checked: ChadScharf$_ThreeStateCheckBox$set_checked,
get_imgBlank: ChadScharf$_ThreeStateCheckBox$get_imgBlank,
set_imgBlank: ChadScharf$_ThreeStateCheckBox$set_imgBlank,
get_imgChecked: ChadScharf$_ThreeStateCheckBox$get_imgChecked,
set_imgChecked: ChadScharf$_ThreeStateCheckBox$set_imgChecked,
get_imgUnchecked: ChadScharf$_ThreeStateCheckBox$get_imgUnchecked,
set_imgUnchecked: ChadScharf$_ThreeStateCheckBox$set_imgUnchecked,
get_buttonId: ChadScharf$_ThreeStateCheckBox$get_buttonId,
set_buttonId: ChadScharf$_ThreeStateCheckBox$set_buttonId,
get_autoPostBack: ChadScharf$_ThreeStateCheckBox$get_autoPostBack,
set_autoPostBack: ChadScharf$_ThreeStateCheckBox$set_autoPostBack,
get_hiddenFieldId: ChadScharf$_ThreeStateCheckBox$get_hiddenFieldId,
set_hiddenFieldId: ChadScharf$_ThreeStateCheckBox$set_hiddenFieldId,
get_dataKey: ChadScharf$_ThreeStateCheckBox$get_dataKey,
set_dataKey: ChadScharf$_ThreeStateCheckBox$set_dataKey,
add_checkChanged: ChadScharf$_ThreeStateCheckBox$add_checkChanged,
remove_checkChanged: ChadScharf$_ThreeStateCheckBox$remove_checkChanged,
_onButtonClick: ChadScharf$_ThreeStateCheckBox$_onButtonClick,
_onCheckChanged: ChadScharf$_ThreeStateCheckBox$_onCheckChanged,
dispose: ChadScharf$_ThreeStateCheckBox$dispose,
initialize: ChadScharf$_ThreeStateCheckBox$initialize
}
ChadScharf._ThreeStateCheckBox.registerClass(‘ChadScharf._ThreeStateCheckBox’, Sys.UI.Control);

Finally

Finally! Now that I’ve probably copied and pasted WAY too much code in my blog post we get ready to do the final implementation of our three state checkbox control, consume it in a web page.

We’ll start by creating a web site in VS 2008, and adding a project reference to our class library. Then, in the Web.config file we’ll add a simple entry so we can use our new control without any other code in any of the pages:

<pages>
<controls>
…
<add tagPrefix=“chad“ namespace=“ChadScharf.ThreeStateCheckBox“ assembly=“ChadScharf.ThreeStateCheckBox“/>
</controls>
</pages>

Now with that out of the way, we can test the new control by putting it on a page:

<chad:ThreeStateCheckBox ID=”MyCheckBox” runat=”server” AutoPostBack=”false” CausesValidation=”false” />

Of course, I could wire up an event to it as well, such as the CheckChanged event. This event will only be called if AutoPostBack is set to true.

OnCheckChanged=”MyCheckBox_CheckChanged”

protected void MyCheckBox_CheckChanged(object sender, EventArgs e)
{
// …
}

You can control whether your control posts back or not by setting AutoPostBack=”true” or “false”. If you set it to “false” (the default), your page will not post-back when you click the checkbox, but you should see the state change instantly, and if another control, like a button, causes a post-back, you will also notice the server side state of the control has changed as well!

That’s it

This was simply a high level overview; however you can always download the entire source code here. Feel free to modify the images, scripts etc or just let me know what you think. This is definately a quick-fix for a not-so-simple business requirements problem using creative design. The 3-stage checkbox is a bit more common in windows forms applications and I’ve seen a lot of requests for this type of control on web development forums, typically asking how you would do a tree showing not all the options under a parent node are checked/selected. This could be done by simply altering the 3rd state of the checkbox and image to reflect whatever you wanted it to.

3-State CheckBox using Microsoft AJAX is a post from: Chad Scharf's Weblog. For software consulting services please visit Scharf Holdings, LLC

The Storage Container

The basic structure of the HashTable is comprised of an enumerable collection of KeyValuePair objects. To mimic this, I had to define my KeyValuePair object on the client. I decided to use Microsoft’s AJAX Client Library included in the .NET 3.5 Framework.

KeyValuePair = function(key, value) {
KeyValuePair.initializeBase(this);
// Add custom initialization here
    this._key = key;
    this._value = value;
}
KeyValuePair.prototype = {
    // Returns the current Dialer Status key
    get_key : function() {
        return this._key;
    },
    set_key : function(key) {
        this._key = key;
    },
    // Returns the next to execute Dialer Command
    get_value : function() {
        return this._value;
    },
    set_value : function(val) {
        this._value = val;
    },
initialize: function() {
KeyValuePair.callBaseMethod(this, ‘initialize’);
},
dispose: function() {
KeyValuePair.callBaseMethod(this, ‘dispose’);
}
}
KeyValuePair.descriptor = {
properties: [ {name: 'key', type: String},
{name: 'value', type: String} ]
}
KeyValuePair.registerClass(‘KeyValuePair’, Sys.Component);

I then had to create the container to wrap a collection, or in JavaScript’s case an Array, of these KeyValuePair objects and make them indexed, searchable, and easy to use just like the .NET HashTable class.

HashTable = function() {
HashTable.initializeBase(this);
// Add custom initialization here
    this._items = new Array();
    this._deletedIndexes = new Array();
    this._isDeleted = function(index) {
        for (var i = 0; i < this._deletedIndexes.length; i++) {
            if (this._deletedIndexes[i] == index) {
                return true;
            }
        }
        return false;
    }
}
HashTable.prototype = {
    // Returns the next to execute Dialer Command
    get_value : function(key) {
        for (var i = 0; i < this._items.length; i++) {
            if (!this._isDeleted(i)) {
                var item = this._items[i];
                if (item.get_key() == key){
                    return item.get_value();
                }
            }
        }
        return null;
    },
    set_value : function(key, val) {
        for (var i = 0; i < this._items.length; i++) {
            if (!this._isDeleted(i)) {
                var item = this._items[i];
                if (item.get_key() == key){
                    item.set_value(val);
                    this._items[i] = item;
                }
            }
        }
    },
    get_count : function() {
        return this._items.length;
    },
initialize: function() {
HashTable.callBaseMethod(this, ‘initialize’);
},
dispose: function() {
        this._items = null;
HashTable.callBaseMethod(this, ‘dispose’);
},
addPair : function(pair) {
        if (pair == null) { return; }
        var exists = this.get_value(pair.get_key());
        if (exists) { return; }
        this._items.push(pair);
},
remove : function(key) {
        for (var i = 0; i < this._items.length; i++) {
            if (!this._isDeleted(i)) {
                if (this._items[i].get_key() == key){
                    this._items[i].set_key(null);
                    this._items[i].set_value(null);
                    this._deletedIndexes.push(i);
                    return;
                }
            }
        }
},
addItem : function(key, value) {
        this.addPair(new KeyValuePair(key, value));
}
}
HashTable.descriptor = {
properties: [ {name: 'count', type: Number} ]
}
HashTable.registerClass(‘HashTable’, Sys.Component);

And that’s it! With this new client component I can store configuration entries on the client for use by my page’s script. I simply do the following on the server, in my code behind in order to create the collection itself.

Client:

// Declare our global config variable
var Config = new HashTable();

ASP.NET Form:

<%=GetConfigScript()%>

Server:

public string GetConfigScript()
{
    StringBuilder script = new StringBuilder();
    script.AppendLine(“<script type=\”text/javascript\”>”);
    script.AppendLine(“//<![CDATA[");
    foreach (string key in ConfigurationManager.AppSettings.AllKeys)
        script.AppendFormat("Config.addItem(\"{0}\",\"{1}\");",
            key.Replace(@"\", @"\\"),
            ConfigurationManager.AppSettings[key].Replace(@”\”, @”\\”));
    script.AppendLine(“//]]>”);
    return script.ToString();
}

Conclusion

Now, whenever I want to access a configuration setting on the client, I call Config.get_value(“key”); and it returns that value or null, just like using Configuration.AppSettings["key"] or a HashTable to store values by key, I just happened to use it for configuration settings but it could be used any time I need a searchable HashTable for storing key-value pairs.

Creating a JavaScript HashTable is a post from: Chad Scharf's Weblog. For software consulting services please visit Scharf Holdings, LLC

I decided to flex the muscle of the prototype, which in JavaScript allows you to extend a types method and properties. This new method I created, called shrink(), aptly removes all of the nulls from my array and shrinks the total length without losing any data. I’m not sure how efficient it is, but it works and I no longer have to check for null where at least it doesn’t make sense to anyway.

Array.prototype.shrink = function() {
    var sync = new Array();
    while (this.length > 0) {
        var obj = this.shift();
        if (obj !== null) sync.push(obj);
    }
    while (sync.length > 0) {
        var obj = sync.shift();
        if (obj !== null) this.push(obj);
    }
}

Shrinking JavaScript Arrays is a post from: Chad Scharf's Weblog. For software consulting services please visit Scharf Holdings, LLC