The 4 Base Methods

Be sure to have read the Ensuring your AJAX control on the client-side loads after the DOM - Load functions documentation before reading this page.

You enable a custom control with the capabilities of the AJAX Control Framework by implementing the IAjaxControl interface or by deriving from either the AjaxControl or AjaxUserControl classes. Every control you do this to will have access to the 4 following base AJAX Control Framework methods (which can be invoked with JavaScript):
  • update - when called against an AJAX control's client-side object, this method will cause your custom control to be re-rendered on the server-side and have the resultant HTML returned.
  • invoke - when called against an AJAX control's client-side object, this method will cause a server-side method, the name for which you specify as a parameter, to be invoked asynchronously and have its return value sent back to the browser. All parameters sent to the server-side function are automatically serialized into JSON notation and deserialized before the actual method is invoked on the server-side. If an value/object is returned by the server-side method, it is serialized to JSON and deserialized on the client-side before invoking the onSuccess or onFailure callback handler functions.
  • globalUpdate - this method allows the developer to retrieve the rendered HTML output from any control defined within the application (note that this "global" control does not have to be referenced at all in the markup of the current page and can be located in an entirely different section of the application).
  • globalInvoke - this method allows the developer to invoke a server-side method of any control defined within the application (note that this "global" control does not have to be referenced at all in the markup of the current page and can be located in an entirely different section of the application). All parameters sent to the server-side function are automatically serialized into JSON notation and deserialized before the actual method is invoked on the server-side. If an value/object is returned by the server-side method, it is serialized to JSON and deserialized on the client-side before invoking the onSuccess or onFailure callback handler functions.

An important note.

Whenever the AJAX Control Framework re-renders a control, (either by a call to the "update" or "globalUpdate" base methods, or by a call to "invoke" or "globalInvoke" with the "returnHtml" or "autoUpdateHtml" option set to true) the relevant events of the page event lifecycle are invoked against the control. This means that the Init, Load, Render and Unload events will be performed. This allows you to develop your custom controls as you would normally without the AJAX Control Framework and not have to worry about some special procedure that you must follow. You could, for instance, invoke a server-side method that changes a parameter or un-hides a Panel (by setting Panel1.Visible = true) and if you provided a value of "true" for the "returnHtml" or "autoUpdateHtml" option, the Init, Load, Render, and Unload events would be automatically invoked, thus re-rendering your control in response to an action you performed on it. So, when you're developing an AJAX enabled control, write its code as if it were any normal custom control that would be driven by standard postbacks.


All 4 of these methods are always attached to the client-side object representation of your custom control. This object representation of your control is made available to you as the single parameter passed to the loading function you define for your AJAX controls. The object would be the "obj" parameter in the example below:

window["load_BingMapsSample_ucSearchResultsMap"] = function(obj) {
        ...
};

Here are the prototypes of the 4 base Javascript methods:

update: function(options)
invoke: function(methodName, options) // methodName is required.
globalUpdate: function(controlType, options) // controlType is required.
globalInvoke: function(controlType, methodName, options) // controlType and methodName are required.
}


Here are descriptions of each of the available parameters to the 4 base methods:
  • options (object) - This is a JSON object that contains the following properties:
    • returnHtml (boolean) - This property tells the CallbackStrategy whether or not to re-render the control and return its HTML after invoking a server-side method. This parameter is only considered for "invoke" and "globalInvoke" calls.
    • autoUpdateHtml (boolean) - This property tells the AJAX Control Framework to automatically replace the current markup of a control with that returned by any of the 4 base methods. Providing a value of "true" for this property implies a value of "true" for the returnHtml property, if its provided or not. <-- CHECK THIS OUT
    • onSuccess (function) - The handler function that, if provided, will be executed upon successful completion (no uncaught exceptions) of the base method.
    • onFailure (function) - The handler function that, if provided, will be executed upon unsuccessful completion (an uncaught exception occurred) of the base method. If no handler function is provided, a default handler is attached that will announce the exception details within an alert box. A serialized JSON exception is returned to the client (which includes the StackTrace property for debugging, but is not displayed by the default onFailure handler so as to not expose any code to the user) and passed to the onFailure handler function through as a parameter.
    • params (array) - This property allows for the developer to list the parameters that are required by the server-side method to be invoked. The order of the values stored in this array must match up to the order and type of the parameters of the server-side method. This property is ignored for the "update" and "globalUpdate" base methods.
    • async (boolean) - Tells the AJAX Control Framework whether or not to use an asynchronous AJAX call when communicating with the server.
  • methodName (string) - This is the name of the server-side method to be invoked. This property is ignored for the "update" and "globalUpdate" base methods.
  • controlType (string) - This is the fully qualified type name of the "global" control you wish to update or invoke a server-side method against. The fully qualified type name is structured as follows: namespace + "." class name + ", " + assembly name. Here's an example from the BingMapsSample project: "BingMapsSample.ucPlaceDescription, BingMapsSample". This property is ignored for the "update" and "invoke" base methods.


Here are the prototypes of the "onSuccess" and "onFailure" handler functions:

onSuccess: function(result, commandName);
onFailure: function(exception, commandName);

Here are the descriptions of the parameters passed to the "onSuccess" and "onFailure" handler functions:
  • result (object) - This is the server response to whatever base method being performed against the custom control. It is a JSON object with the following properties:
    • Html (string) - This property holds the rendered HTML of a control for all "update" and "globalUpdate" calls and those calls to "invoke" and "globalInvoke" where the "returnHtml" or "autoUpdateHtml" options are provided and set to true.
    • Result (object) - This is a JSON object representing the value that the invoked server-side method returns. If the server-side method is returns void, the value of the property will be undefined. Also, if the return value is a .NET Value type, the property will have the equivalent JavaScript type (i.e. int, string, decimal).
  • exception (object) - This is a JSON object in the form of the uncaught .NET exception that caused the base method to fail. It has a property value for the main public properties of whatever .NET Exception class it represents. The most notable properties are: Message (string) and StackTrace (string).


Alrighty! Time for an example.

Here is an example pulled from the BingMapsSample project demonstrating how the "globalInvoke" base method would be invoked:

JavaScript

(function($) {
    window["load_BingMapsSample_ucSearchResultsMap"] = function(obj) {
        
        // Variables.
        ucSearchResultsMap = obj;

        ...

        ucSearchResultsMap.setPlaceDescription = function(shape) {
            ucSearchResultsMap.globalInvoke("BingMapsSample.ucPlaceDescription, BingMapsSample", "RenderPlaceDescription", {
                params: [shape.Place.Name],
                returnHtml: true,
                onSuccess: function(result) {
                    shape.SetDescription(result.Html);
                    map.ShowInfoBox(shape);
                }
            });
        };

        ...

Code-Behind

public void RenderPlaceDescription(string placeName)
{
    HttpContext.Current.Items["Place"] = SearchResultsController.GetSearchResults(base.ParentPage.Keyword).FirstOrDefault(p => p.Name == placeName);
}
Notice that the "RenderPlaceDescription" method being invoked on the server-side is merely causing a property of the control to change and it is having the "returnHtml" option set to true in the client-side call that causes the Event lifecycle to be performed against the control and have it rendered.

One more thing to notice is that in the context of the BingMapsSample project, no where in any of the markup is the "BingMapsSample.ucPlaceDescription" control referenced and that the"RenderPlaceDescription" method is not annotated with the AjaxControlMethod attribute. The AJAX Control Framework will still be able to find the control on the backend, instantiate it and invoke its method.

Last edited May 29, 2010 at 4:46 AM by peanutbutterlou, version 14

Comments

No comments yet.