How to attach AJAX capabilities to your custom controls

You can attach the AJAX Control Framework's AJAX capabilities to your own Controls (whether they are a special extensions of TextBox or are the UserControls that make up the screens of your web application) in either of the 2 following ways:
  • Automatically, by extending either the AjaxControl or AjaxUserControl base classes that are available out-of-the-box with the AJAX Control Framework. This is your best option if when creating new controls that aren't bound to an existing type hierarchy.
  • Manually, by having your Control inherit from the IAjaxControl interface and attaching the Callback strategy to the Event Life-cycle of the Page. (This really easy and only a few lines of code.) If you have an existing type hierarchy and can't set either the AjaxControl class or the AjaxUserControl class as your base, this is your best option.


DISCLAIMER: The purpose of this tutorial is to provide you with a thorough explanation. As a whole this tutorial is rather long, but fight the urge to be intimidated. The process described here is truly simple and, in the end, the knowledge you gain from reading it is "where to copy and paste the code that attaches AJAX to my controls."

Automatic Attachment (AjaxControl/AjaxUserControl)

public partial class MyCustomUserControl : AjaxUserControl
{
    ...
}
orrrr

public class CalloutPanel : AjaxControl
{
    ...
}
That's all there is to it. You can immediately start using AjaxControlMethods.

Now, this raises the question "What if I want the Ajaxified Control to use a custom Script strategy or State strategy?" This is where the AjaxControlOptions attribute comes in handy. The AjaxControlOptions attribute is a class-level attribute that provides a streamlined and declarative way for you to specify the use of strategies other than the defaults.

This raises another question: "What are the default strategies assigned to an AJAX Control?"

Type of Strategy Default Implementation Type
Callback AjaxControlFramework.ControlCallbackStrategy
Script AjaxControlFramework.ControlScriptStrategy
State AjaxControlFramework.DiskStateStrategy


The AjaxControlOptions attribute allows you to specify custom strategies by Type to be attached to your AJAX enabled controls. Here is an example:

[AjaxControlOptions(
    CallbackStrategyType = typeof(MyCustomCallbackStrategy),
    StateStrategyType = typeof(VelocityStateStrategy),
    ScriptStrategyType = typeof(MyCustomScriptStrategy))]
public class CalloutPanel : AjaxControl
{
    ...
}


Manual Attachment (IAjaxControl)

There are 2 simple steps to manually attaching AJAX capabilities:
  1. Inherit from the IAjaxControl interface, implementing the properties and methods it declares.
  2. Call the AjaxControl.Initialize(IAjaxControl control) method in your Control's constructor.

public class ErrorCallout : WebControl, IAjaxControl
{
    [Bindable(false), Browsable(false)]
    public virtual AjaxControlContext AjaxContext { get; set; }

    [Bindable(false), Browsable(false)]
    public virtual bool IsUpdating { get; set; }

    [Bindable(false), Browsable(false)]
    public virtual StateStrategy StateStrategy { get; set; }

    [Bindable(false), Browsable(false)]
    public virtual CallbackStrategy CallbackStrategy { get; set; }


    public ErrorCallout()
    {
        AjaxControl.Initialize(this);
    }


    public void RaiseCallbackEvent(string eventArgs)
    {
        CallbackStrategy.ProcessCallback<CallbackStrategyArguments>(eventArgs);
    }

    public string GetCallbackResult()
    {
        return CallbackStrategy.GenerateCallbackResult();
    }
}

Notice how the properties declared by the IAjaxControl interface can easily be defined using Auto-Implemented Properties. Also, take note that the IAjaxControl interface itself inherits from the ICallbackEventHandler interface, requiring the RaiseCallbackEvent and GetCallbackResult methods to be defined. Rarely, if ever, should you have reason to provide code for the body of these two methods that is different from what you see in the example.

Lastly, notice how the 2nd step of the Manual Attachment process is accomplished within the constructor of the above example class. Making the call to the static AjaxControl.Initialize method, and passing to it a reference to your AJAX enabled control that has just been instantiated, will force all the properties of the IAjaxControl interface that you have not set manually to their defaults and attaches the strategies to the Event Life-cycle. It is this call to the AjaxControl.Initialize method that does the actual attaching of the AJAX Control Framework's capabilities to your control.

If you do not want to use the AjaxControlOptions attribute or would like to restrict other developers, who might be extending your control, from overriding the custom strategy implementations you provide, set the appropriate IAjaxControl properties before making the call to the AjaxControl.Initialize method. You will do all this within the body of the constructor.

More often than not, your control will be able to use the code provided in this example, without modification (except for changing the class name and constructor name). So that means you can just copy and paste the body of the ErrorCallout class defined in this example, change the name of the constructor to the name of your class, and append IAjaxControl to the class signature and you're all set. You can AJAX enable your existing server-side only controls in just a minute or two without modifying any existing code. Think of this process as more of an "extension" than a "modification".


"When should I implement a custom strategy?"

INCOMPLETE



For an example of manually attaching AJAX capabilities, check out the UpdateRegion.cs file found in the source code.

Last edited May 31, 2010 at 11:07 PM by peanutbutterlou, version 23

Comments

No comments yet.