Introduction

As we've seen in the part 2 and part 3 of the tutorial, if a client side type exposes an event in its type descriptor, we can handle it declaratively using xml-script. A powerful way to handle events with xml-script is by using actions; in this article we'll see how to build custom actions to handle events declaratively.

Actions

An action encapsulates a block of JavaScript code that is executed when a particular event is fired. An example is the SetProperty action, which allows setting the value of a property exposed by a client side component, or the InvokeMethod action, which enables invoking a method and pass parameters to it.

The Microsoft Ajax Library defines a third built-in action called PostBackAction. The purpose of this action is to postback the page (using the ASP.NET postback mechanism, i.e. a call to the __doPostBack function) in response to a particular event.

The following example illustrates the PostBack action; it is a simple HTML button that, when clicked, causes a postback of the page.

In this case, clicking the button causes the following JavaScript code to be executed:

Custom actions

If we want to create a custom action, the easy way is to create a class that inherits from Sys.Preview.Action and override the performAction method.

The following example shows a simple AlertAction that can be used to display an alert on screen using xml-script. Create a fresh JavaScript file and name it AlertAction.js. Then, save it inside a ScriptLibrary folder in your Ajax CTP-enabled website and add the following code:

The AlertAction class exposes a property called message that can be used to set the message to display in the alert box. The performAction is overridden to call the JavaScript alert method that displays the message on screen. Note that the AlertAction class inherits from Sys.Preview.Action and exposes a type descriptor (returned by the static descriptor expando) and this allows using the class in declarative code.

Finally, here is the code showing the new AlertAction in action.

Namespaces

The code is pretty simple to understand, since the custom action is used in the same way as the built-in actions provided by the Microsoft Ajax Library. However, since the AlertAction class is contained in the Samples namespace, we have to bind this namespace to a custom XML namespace.

To do this, we have to add a namespace prefix as an attribute to the page element:

And then use the defined prefix in the alertAction tag:

The reason why we don't use a prefix for elements like button, label, textBox or postBackAction is that the xml-script parser searches for the corresponding classes inside a set of default namespaces:

• Sys
• Sys.UI
• Sys.Net
• Sys.Preview
• Sys.Preview.UI
• Sys.Preview.Net
• Sys.Preview.Data
• Sys.Preview.UI.Data
• Sys.Preview.Services.Components

All the classes declared in different namespaces need to have their namespace mapped to a XML namespace to be correctly used in declarative code.

Anyways, for XML compliancy, it is always recommended to declare at least the global namespace in the root element of a portion of XML code, like we're doing in the root page element:

Summary

In this fourth part of the tutorial we've seen how to use the PostBack action to postback a page declaratively and how to build custom actions by inheriting from the base Sys.Action class and overriding the performAction method. Actions are a great way to encapsulate a portion of JavaScript code and execute it through declarative code.

About Alessandro Gallo

Alessandro "Garbin" Gallo is a Microsoft MVP in the Visual ASP/ASP.NET category and a .NET developer/consultant. He is a contributor for the Ajax Control Toolkit project, owned by Microsoft. Alessandro won the Grand Prize at the "Mash-it-up with ASP.NET AJAX" contest held by Micr... This author has published 23 articles on DotNetSlackers. View other articles or the complete profile here.