Manning ASP.NET AJAX in Action PHẦN 8 ppsx

Chapter 11 is dedicated to XML Script: a declarative language similar to the ASP.NET markup, which is used to instantiate client components in the page.. XML Script is a declarative lang

the animation classes The following example will give you the opportunity toexperiment directly with the JSON syntax for creating animations

In this section, we’ll return on the PhotoGallery control built in section 8.4.5

So far, you’ve created a client control to browse a set of images stored in the site Your next goal is to enhance the control by adding an animated transitionbetween the images The transition you’ll build isn’t complex, but it’s effective, asshown in figure 10.18 While the next image is being loaded, you partially fade-outthe current image; then, you resize it until it reaches the width and height of thenext image to display Finally, the new image fades in and replaces the old image Let’s start by opening the PhotoGallery.js file that contains the code for the Pho-toGallery control You have to modify the code so that when the next image isloaded, a new method named _playTransition is called This method is respon-sible for playing the animated transition and then calling the _displayImagemethod as soon as the transition is completed First, you must rewrite the _onImage-ElementLoaded method, declared in the PhotoGallery’s prototype, as follows:_onImageElementLoaded : function() {

this._playTransition();

}

Figure 10.18 Example of an animated transition applied to the PhotoGallery control

The animations that make up the transition are defined through JSON objects.

Then, you must add a method called _playTransition to the constructor’s type The code for the _playTransition method is shown in listing 10.14.

B

Sequence animation C

The first animation you create is a fade-in B, stored in the fadeIn variable Theanimation is created with a call to the AjaxControlToolkit.Animation.create-Animation method This method accepts an object literal (a JSON object) andinstantiates the animations defined in the object In the JSON object, the value ofthe AnimationName attribute is the FadeIn string, which corresponds to a fade-inanimation You follow the same rule used in the XML description The name of ananimation is obtained by removing the Animation suffix from the name of the class The second attribute, AnimationTarget, specifies which element to animate.

In this case, it’s the img element that displays the current image The thirdattribute, Duration, is the duration of the animation; the last two attributes definethe values of the maximum and minimum opacity The fade-in effect is obtained

by animating the opacity value from 0.2 to 1

You use the same technique to create the sequence animation C that pletes the transition In this case, the AnimationChildren attribute holds an arraywith the child animations When the _playTransition method is called, the tran-sition is played in two parts First, the sequence animation is played To detect itsend, you subscribe to its ended event The event is handled by a function calledonSequenceEnded, declared in the _playTransition method When the sequenceanimation ends, the _displayImage method is called to replace the old photowith the new one Finally, the fade-in animation is played to complete the transi-tion between the two images

The JSON description is compact and leads to highly readable code The onlydrawback of this approach is that it’s slower than the imperative syntax because anadditional step is required to translate the JSON description into an instance of

Subscribe to ended event Play

transition

Handle ended event

the FadeInAnimation class For this reason, the imperative syntax is preferablewhen you need maximum performance In most cases, though, you’ll be able touse the shortest and most readable code

The Ajax Control Toolkit offers also a powerful framework for creating visualeffects and animations We explored the animation classes and explained how tocreate them in a web page using the AnimationExtender control You can createanimations using XML or JSON syntax, as we demonstrated by adding transitioneffects to the PhotoGallery control developed in chapter 8

In the next chapter, we’ll look at the XML Script declarative language, which isused to instantiate client components in a page using a declarative syntax

ASP.NET AJAX Futures

It’s been almost a year since the first official release of ASP.NET AJAX, andplans for the next release are well under way Currently, features for the nextrelease are available in a separate package called the ASP.NET Futures In thispart of the book, we’ll cover some of these features Chapter 11 is dedicated

to XML Script: a declarative language similar to the ASP.NET markup, which

is used to instantiate client components in the page Chapter 12 covers thedrag-and-drop engine, which you can use to drag and drop DOM elements inthe page By the end of these chapters, you’ll be ready to use the main fea-tures that will be included in future releases of ASP.NET AJAX

XML Script is a declarative language for creating instances of JavaScript objects atruntime, setting their properties, and specifying their behavior, using an XML-likesyntax similar to the ASP.NET markup code.

In an HTML page, you can separate content (the markup code) from style byembedding the style information in a CSS file Similarly, in an ASP.NET page, youusually define the page layout using declarative markup code in an ASPX page.Then, you can use a separate code-behind file to specify the behavior of servercontrols and how they’re wired together, using the classic imperative syntax XMLScript lets you achieve this kind of separation and instantiate JavaScript compo-nents using a declarative script language embedded in a web page

XML Script, like declarative languages, has a number of advantages over theimperative syntax Building designers for markup is easier than building them forcode Great visual tools, like the Visual Studio Designer, take care of generatingmarkup code for you If a client can parse declarative markup, you can makeserver controls render the markup more easily than rendering imperative code

In addition, declarative markup carries semantics For example, an applicationthat parses a TextBox tag knows that it has to instantiate a text field, but it’s up tothe application to decide to instantiate a simple text field rather than a more com-plex auto-complete text box—for example, based on browser capabilities Finally,declarative code can be more expressive and less verbose than imperative code

Features like bindings help keep the values exposed by object properties

synchro-nized, without the need to deal with multiple event handlers

This chapter illustrates these aspects of XML Script, beginning with the basics

of the language and moving to advanced features like actions, bindings, and formers Keep in mind that because they’re part of the ASP.NET Futures package,the features illustrated in this chapter aren’t currently documented or supported

trans-by Microsoft

11.1 XML Script basics

Your first goal is learning how to write XML Script code and understanding howit’s turned into instances of client objects at runtime As we’ll explain in amoment, writing XML Script code is similar to writing ASP.NET declarative code.The main difference is that whereas you use ASP.NET markup to create instances

of server-side classes, you use XML Script code to create JavaScript objects Before you begin using XML Script, you need to enable it in a web page Thisturns out to be an easy job, because you have to reference the PreviewScript.js file

in the ScriptManager control, as shown in listing 11.1 This file is embedded as a

web resource in the Microsoft.Web.Preview assembly, which is shipped with theASP.NET Futures package You can find more information on how to install thispackage in appendix A.

<asp:ScriptManager ID="TheScriptManager" runat="server">

of an XML Script code block looks like:

As with any programming language, a “Hello, World!” example is the idealice-breaker for introducing basic XML Script features It’s also a good startingpoint for learning how XML Script code is structured and to give you confidencewith its syntax

11.1.1 Hello XML Script!

This example shows how a block of XML Script code is structured and how youcan deal with client objects using declarative code You’ll see how to handle anevent raised by a client component using XML Script code Normally, you’daccomplish this task by retrieving a reference to the component and writing thenecessary JavaScript code to add an event handler Listing 11.2 shows how todeclaratively hook up the init event raised by Sys.Application, the Applicationobject introduced in chapter 2 As promised, the event handler is a JavaScriptfunction that displays a “Hello XML Script!” message onscreen

Listing 11.1 Enabling XML Script in an ASP.NET page

<%@ Page %>

<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN"

"http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">

<html xmlns="http://www.w3.org/1999/xhtml" >

<head runat="server">

<title>Hello XML-script</title>

</head>

<body>

<form id="form1" runat="server">

<asp:ScriptManager ID="TheScriptManager" runat="server">

<Scripts>

<asp:ScriptReference Assembly="Microsoft.Web.Preview"

Name="PreviewScript.js" />

</Scripts>

</asp:ScriptManager>

<script type="text/xml-script">

<page xmlns="http://schemas.microsoft.com/xml-script/2005"> <components>

<application init="pageInit" />

</components>

</page>

</script>

<script type="text/javascript">

function pageInit() { alert("Hello XML Script!"); }

// >

</script>

</form>

</body>

</html>

Let’s have a closer look at the block of XML Script code B contained in the page

It has a root element called page and a single child element called components The page element defines a global XML namespace associated with the following Uniform Resource Identifier (URI):

http://schemas.microsoft.com/xml-script/2005

The page/components structure is the basic form of an XML Script code block All the blocks of XML Script code in the page must have this structure in order to be

Listing 11.2 Code for the “Hello XML Script!” example

Block of XML Script code B

parsed correctly In section 11.1.5 we’ll return to the use of XML namespaces withXML Script.

NOTE An XML namespace is a collection of names, identified by a URI reference,

used in XML documents as element types and attribute names For moreinformation on XML namespaces, check http://www.w3schools com/xml/xml_namespaces.asp

The components tag always contains the list of client objects declared in the page.These objects are represented by XML elements and are instances of classes cre-ated with the Microsoft Ajax Library In this chapter, we’ll focus on client compo-nents, which are classes that derive from Sys.Component The reason is that theXML Script engine already knows how to properly parse and instantiate suchclasses If you recall, the creation process for a client component is rather elabo-rate, as we discussed in chapter 8

In listing 11.2, application is the unique child node of components In XMLScript—as in the ASP.NET markup, for example—a tag is mapped to a class, and theelement represents an instance of that class The application tag is always mapped

to the Application object, stored in the global Sys.Application variable When theXML Script parser processes the application tag, it retrieves a reference to theApplication object Then, it recognizes the init attribute as the name of an eventraised by the Application object As a consequence, its value—pageInit—is treated

as the name of the event handler

The pageInit function declared in the JavaScript code block at the bottom ofthe page is invoked when the Application object raises the init event This causesthe greeting message to be displayed in a message box onscreen, as shown in fig-ure 11.1

Figure 11.1 The message displayed by a JavaScript function that handles the init event raised by Sys.Application The

init event is hooked up declaratively

The page still includes some JavaScript code, but you were able to perform thelogic for attaching the event handler using only declarative code Later, you’ll seehow to make the JavaScript code disappear

So far, you know how to access the Application object using XML Script ally, a rich web application hosts multiple components and even controls associ-ated with DOM elements Can you access them in declarative code and hook uptheir events? The answer is that all the kinds of client components can be instanti-ated and accessed using XML Script

Usu-NOTE As you may have noticed while typing the first listing in Visual Studio,

code completion isn’t available at the moment for XML Script In tion, no support is provided for debugging XML Script code and for theVisual Studio Designer As we said in the introduction, XML Script is part

addi-of the ASP.NET Futures package and is still under development

11.1.2 Controls and XML Script

In chapter 8, we introduced client controls and promised that they would be usefulwhen dealing with XML Script Client controls, when created as element wrappers, arethe way to reach DOM elements using XML Script An element wrapper is a controlassociated with a DOM element As a wrapper, the client control exposes properties,methods, and events to deal with the associated element and enhance its function-ality As a client component, a control can be used in XML Script with little effort.The Microsoft Ajax Library ships with a collection of ready-to-use controls associ-ated with the most-used DOM elements, such as labels and input elements Listing 11.3 is a slight variation on listing 11.2 It uses a button and a label todisplay the greeting message, instead of accessing the Application object

B

Label element

C

Label component D

Button component E

dis-We say that the DOM elements have been upgraded to client controls.

At runtime, the XML Script engine creates an instance of the view.UI.Label control and passes the span element as the associated element.Similarly, it creates an instance of the Sys.Preview.UI.Button control and passesthe input element as the associated element The value of the id attributebecomes the value of the id property exposed by the controls This allows them to

Sys.Pre-be referenced in XML Script code

The click attribute of the button tag E is mapped to the click event raised

by the Button control Its value is the name of the JavaScript function that handlesthe event The function onGreetButtonClick uses the $find method to accessthe Label control and set the text of the associated span element through theset_text method

Table 11.1 lists the element wrappers defined in the Sys.Preview.UInamespace Note that you obtain the name of the associated tag—which is caseinsensitive—by removing the namespace prefix from the class name

Table 11.1 Element wrappers defined in the Sys.Preview.UI namespace

Sys.Preview.UI.Button Wraps an input element of type button button Sys.Preview.UI.Label Wraps a span element label Sys.Preview.UI.CheckBox Wraps an input element of type checkbox checkbox

What if you need to target an element like div, which doesn’t have an associatedwrapper control? You have to write an XML Script-enabled custom control thatwraps it But if you only need to wrap an element and access the base functionalityprovided by the Sys.UI.Control class, the easiest way is to use a control element.The control tag wraps a DOM element with a given id, with an instance of theSys.UI.Control class, like so:

<control id="elementID" />

In XML Script, the markup code is always mapped to the properties of controls,not to the properties of the associated DOM elements You need client compo-nents to interact with DOM elements using declarative code

So far, we’ve talked about the components shipped with the Microsoft AjaxLibrary You’ll probably want to use custom components in XML Script In the fol-lowing section, you’ll see how XML namespaces help the XML Script engine locatecustom client classes

XML namespaces

An XML namespace declaration tells XML Script where to find the client class sponding to an element declared in the markup code In XML Script, you usuallydeclare a global namespace in the page element, with the following code:

Table 11.1 Element wrappers defined in the Sys.Preview.UI namespace (continued)

a shortcut that refers to the URI For example, suppose you have a custom nent declared as SomeSpace.SomeComponent Because SomeSpace is a customnamespace, you have to declare an XML namespace if you want to use the compo-nent in XML Script To do that, you have to act on the page element as follows:

<page xmlns="http://schemas.microsoft.com/xml-script/2005"

xmlns:cc="javascript:SomeSpace, SomeSpace.ChildSpace">

This code tells the XML Script parser which namespaces to search for the classcorresponding to an element declared with the cc prefix The prefix should be ashort and, if possible, meaningful string In this case, cc stands for custom control.Assuming it exposes a proper type descriptor, you can use the custom component

in XML Script as follows:

<cc:SomeComponent />

As explained in the previous section, the type descriptor maps an element’sattributes to properties of the component The rules for writing XML Script codeapply to custom components

You may have noticed that the global namespace doesn’t have a prefix Elementswithout a prefix belong to the global namespace Under the hood, the global XML

namespace is associated with the script prefix; so, this prefix refers to thenamespaces listed earlier

Before you learn how to use the custom classes in XML Script, you shouldunderstand how XML Script code is parsed and turned into JavaScript code Thiswill give you some insight into how things work under the hood of the XML Scriptengine Then, you’ll be ready to explore some of the powerful features of thedeclarative language

11.1.3 From XML Script to JavaScript

The process of converting the XML Script declarative code into JavaScript tive code starts when a web page is loaded in the browser If XML Script is enabled

impera-in the page, the Microsoft Ajax runtime impera-instructs the XML Script parser to filter allthe script tags with the type attribute set to text/xml-script The XML Scriptparser is a JavaScript object stored in the Sys.Preview.MarkupParser variable Itexposes a group of methods for extracting and processing the XML Script code

As the XML Script blocks are extracted, they’re collected in an array and cessed sequentially For each block, a sanity check is performed on its structure,

pro-to ensure that a root element called page exists Also, the page element musthave a child node called components The parser ignores all the other tags in thepage element

NOTE The parser performs an additional check to see if a references element

is declared in the page node The references element was used in ous CTPs to provide a list of paths to script files to load in the page, butit’s not supported in the latest CTP If a references tag is found, the

previ-XML Script parser throws an error

As the current XML Script block is processed, all the child elements of the nents tag are extracted and stored in an array These are all the client objects thatneed to be instantiated The instantiation process is performed by the parseNodemethod, which is called by the parser on each tag to parse the markup code andcreate an instance of the object

First, the parseNode method needs to determine the fully qualified name of theclass to instantiate To locate the class, it extracts the tag name and the namespaceprefix from the markup code The tag name is the case-insensitive name of the class;it’s turned to uppercase The information on the namespace is retrieved from theXML namespace prefix used in the tag Finally, the fully qualified name of the class

is obtained by appending the class name to its containing namespace

If the class exists, the parser checks whether it exposes a static method calledparseFromMarkup This method must be defined in a class in order to be used inXML Script It receives the markup code and is responsible for parsing it and cre-ating a new instance of the class This process is repeated for each XML Scriptblock and for each tag extracted from the components node When all themarkup has been processed, all the client objects have been instantiated and can

be safely accessed in the application code This process is illustrated in figure 11.2 Luckily, you can avoid writing the logic needed to parse the markup code andcreate an instance of a client class The Sys.Component class exposes and imple-ments the parseFromMarkup method; it’s a good choice to derive the customclasses from the base Sys.Component class This way, you can take advantage of thefeatures offered by the client component model and also use the custom class inXML Script with little effort The only requirement is that every component mustexpose a type descriptor in order to be used in XML Script

11.1.4 Type descriptors

A type descriptor is an object that provides information about a particular type In

the NET framework, you can perform reflection on objects to learn about theirstructure For example, you can extract every sort of information about the fields,properties, methods, and events exposed by a class On the server side, typedescriptors can be used to provide additional reflection capabilities On the clientside, type descriptors have been introduced to achieve the same goal

Figure 11.2 The XML Script parser extracts component declarations from XML

Script code blocks Then, it parses the declarative code and creates instances of

the corresponding JavaScript objects.

In chapter 3, we introduced the enhanced type system provided by theMicrosoft Ajax Library, together with the methods used to reflect on client classes.Reflection on client objects is less powerful because many object-oriented con-

structs are simulated by extending function objects You can use client type

descrip-tors to partially fill this gap and provide information about the properties,methods, and events defined in a client class

NOTE In the NET framework, type descriptors are used to enhance reflection

capabilities, especially for components that take advantage of the VisualStudio Designer For more information on NET type descriptors, browse

to http://msdn2.microsoft.com/en-us/library/ms171819.aspx

A client class can expose a type descriptor by storing it in a static descriptorproperty added directly to the constructor For example, you would store andretrieve the type descriptor of a class called SomeSpace.SomeClass with the follow-ing statements:

SomeSpace.SomeClass.descriptor = {};

var descriptor = SomeSpace.SomeClass.descriptor;

Another way to expose a type descriptor is by implementing the peDescriptorProvider interface This interface defines a single method calledgetDescriptor, which must be implemented as an instance method of the clientclass The implementation of the method should return the type descriptor associ-ated with the client class, as in the following code:

Structure of a type descriptor

In the previous code snippets, you returned {}—an empty object—as the typedescriptor The information should be packaged following specific rules that we’llexplain in a moment In general, a client type descriptor is a JavaScript object thatcan provide custom information about the client type The XML Script enginerecognizes the following properties:

■ properties—Holds an array of property descriptors

■ methods—Holds an array of method descriptors

■ events—Holds an array of event descriptors

Each array, in turn, holds objects, each of which describes a property, a method,

or an event exposed by the client class To help you understand what a typedescriptor looks like, listing 11.4 shows the one exposed by the Sys.Pre-view.UI.Button class

Sys.Preview.UI.Button.descriptor = {

properties: [ { name: 'command', type: String },

{ name: 'argument', type: String } ],

events: [ { name: 'click' } ]

}

The type descriptor of the Button class exposes two property descriptors and oneevent descriptor The first property is called command, and the correspondingproperty descriptor is an object with two properties: name and type The nameproperty returns a string with the name of the property you’re describing Thetype property returns the type of the value exposed by the property Here’s theproperty descriptor extracted from the type descriptor:

{ name: 'command', type: String }

Similarly, the second property descriptor tells you that the Button class exposes aproperty called argument, of type String We’re talking about client properties asdefined by the Microsoft Ajax Library, which we discussed in chapter 3 Theunique event descriptor in listing 11.4 is relative to a click event It’s an objectwith a name property that returns a string with the name of the event:

{ name: 'click' }

The Button class doesn’t provide any method descriptors Describing a methodrequires additional work because you also have to describe its parameters Fig-ure 11.3 shows a method descriptor extracted from the type descriptor exposed

by the Sys.Preview.InvokeMethodAction class The method is called invoke,and it accepts a single parameter called userContext, of type Object You’ll

encounter this method again when we talk about actions in section 11.2.

Listing 11.4 Type descriptor exposed by the Sys.Preview.UI.Button class

In general, a method descriptor is an object with two properties, name and params.The name property returns a string with the name of the method The paramsproperty returns an array of parameter descriptors A list of the properties thatcan be used in a parameter descriptor can be found in chapter 13, where weexplain the parameter-validation mechanism Method parameters are described

in the same way in type descriptors and in validation routines

Thanks to type descriptors, the XML Script engine can discover which bers are exposed by a client class and map them to attributes declared in themarkup code For example, by querying the type descriptor of the Button class,the XML Script parser knows that the value of the click attribute of a button tagshould be treated as an event handler for the click event exposed by the class Byiterating the same processing to all the elements, the XML Script code can easily

mem-be converted into JavaScript code

So far, we have presented the syntax and the main rules to write XML Scriptcode You also possess the skills to enable XML Script usage in the custom compo-nents This is the right moment to examine the main features of the language.You must understand concepts like actions, bindings, and transformers to runcomplex client code without writing a single line of JavaScript

11.2 Actions

In the previous examples, you saw how to hook up an event raised by a client ponent using XML Script code Things went smoothly, and you didn’t have towrite any client code to attach the handler to the event But you did have to

declare the function that handles the event, so some JavaScript code is stillpresent in the page Our main goal was to demonstrate that XML Script can effec-tively replace JavaScript code in many situations Now we’re ready to introduce

actions, which are classes that encapsulate portions of JavaScript code This code

can be executed in response to events raised by client components Actions areperfectly suited for handling events declaratively

As usual, examples will help to clarify this concept Let’s start with an overview

of the built-in actions in the Microsoft Ajax Library Later, you’ll create customactions and use them in XML Script

11.2.1 SetPropertyAction

A typical task performed when handling an event is to set one or more properties

of an object For example, you can intercept the click event of a button object anddisplay some text in a label To do the same thing using declarative code, you needthe help of the SetProperty action The SetPropertyAction class encapsulates theclient code needed to set the value of a property exposed by a client object Like allactions, this class can be used in XML Script The code in listing 11.5 handles theclick event of a button with the SetProperty action, in order to display a greetingmessage in a label

<div><input type="button" id="greetButton" value="Click Me" /></div>

To handle an event with XML Script, you have to do two things: First you turn thename of the event into an XML element; then, you declare one or more actions inthe event element The code encapsulated by each action is executed in response

to the event

The code has a click element in the button tag This element represents theclick event raised by the Button control In the click element, you declare asetPropertyAction element, which represents a SetProperty action The tar-get attribute specifies the ID of the client component that exposes the propertyyou want to set The property attribute holds the name of the property you’reinterested in The value attribute is set to the value you want to assign to theproperty As a consequence, the text “Hello XML-script!” is displayed in the label With the SetProperty action, you can also access the properties of the DOMelement associated with a control Add the following markup in the click node inlisting 11.5, just after the first setPropertyAction tag:

<setPropertyAction target="msgLabel"

property="element"

propertyKey="style.backgroundColor"

value="#FFFF00" />

In this case, you have an additiona propertyKey attribute that contains the path

to the backgroundColor property of the span element associated with the bel control Let’s compare the markup code with the equivalent imperative code:

msgLa-$find('msgLabel').get_element().style.backgroundColor = '#FFFF00';

The property attribute, in this case,

refers to the get_element method, which

returns the associated DOM element The

value of the propertyKey attribute is

appended to the object returned by

get_element, and the result is the

prop-erty to set This causes the background

color of the span element to become

yel-low Figure 11.4 shows the example in

list-ing 11.5 runnlist-ing in Firefox

Did you see any JavaScript code in

list-ing 11.5? With actions, you can wrap any

kind of JavaScript code and execute it

Figure 11.4 The SetProperty action lets you set properties of client components without writing a single line of JavaScript code.

declaratively The next built-in action we’ll examine is PostBack; it’s used to ger a postback of the page

trig-11.2.2 PostBackAction

ASP.NET pages use a JavaScript function called doPostBack to post form databack to the server The PostBack action wraps the call to doPostBack to triggerthe postback of the page from XML Script code Let’s change the behavior of thebutton declared in listing 11.5 If you replace the button tag with the followingcode, you can make it trigger a postback when it’s clicked:

doPostBack('greetButton', '');

Another typical task performed by event handlers is invoking an object method.The Microsoft Ajax Library provides the InvokeMethod action to invoke a methoddeclaratively in XML Script

11.2.3 InvokeMethodAction

The InvokeMethod action is powerful because it invokes a method exposed by aclient component and makes it possible to process the results using only declara-tive code To demonstrate the InvokeMethod action, we’ll introduce a built-in cli-ent component called Sys.Preview.Net.ServiceMethodRequest You can usethis class to invoke a web method and process the results in a callback function

To add some spice, you do so using only XML Script code In listing 11.6, youdeclare the Web Service used in the example The only web method, GetTimeAs-String, returns the current date and time on the web server In the example, youretrieve this information and display it in a label

<%@ WebService Language="C#" Class="DateTimeService" %>

using System;

using System.Web;

Listing 11.6 Code for the DateTimeService class

to true in the ScriptMethod attribute You can find all the information needed

to access Web Services with ASP.NET AJAX in chapter 5

The Web Service is configured, so we can move on to the XML Script code.Listing 11.7 shows how to make a declarative call to the web method defined inthe Web Service and access the returned string

<h2>

<span>Time on Web Server: </span>

<asp:Label ID="DateTime" runat="server"></asp:Label>

B

Request component

ServiceMethod-C

The ServiceMethodRequest class raises a completed event when the result ofthe web method call is available This is a good occasion to handle the event declar-atively D and access the result property, which stores the returned string You use

a SetProperty action and a new tag (a binding) to extract the value of the resultproperty and display it in the label We’ll introduce bindings in section 12.3 Fornow, it’s enough to say that a binding can be used to synchronize the value exposed

by two properties In this case, you’re synchronizing the result property with thelabel’s text property As soon as the result property is set, the same happens withthe text property

The InvokeMethod action E, which is the action you’re interested in, is used

to handle the load event of Sys.Application As soon as the load event is raised,

Handle completed event

D

Call invoke method

E

the InvokeMethod action calls the invoke method on the ServiceMethodRequestinstance E Note that the instance can be referenced because you assigned it an

id Figure 11.5 shows the date string displayed in the label

The built-in actions provided by the Microsoft Ajax Library enable you to form the most common tasks in declarative event handlers But the real funbegins when you encapsulate the JavaScript code in custom actions This can dra-matically decrease the amount of JavaScript code you write, while expanding thenumber of tasks that can be accomplished with XML Script code Before we dis-cuss the base classes for creating custom actions, we need to talk briefly about how

per-to set complex properties using the XML Script syntax

Complex properties

Suppose you have a client component that exposes a property whose value is asimple JavaScript object (represented by an object literal) or an array A goodquestion would be whether you can expand the simple object or add elements tothe array declaratively, using XML Script The answer is positive

Consider the example of a declarative web service call, from listing 11.7 Youknow the ServiceMethodRequest class can be used to call a method defined in aWeb Service and process its results It’s a client component, and it exposes a typedescriptor As a consequence, you can use the class in XML Script But what hap-pens if the web method that you want to invoke accepts parameters? How can youpass them using XML Script code?

If you look at the type descriptor exposed by the ServiceMethodRequest class,you’ll see that the class has a property called parameters, which is of type Object.Here’s the property descriptor we’re talking about:

Figure 11.5 Result of the example in listing 11.7 The InvokeMethod

action invokes a method on a client object that, in turn, calls a method

defined in a local Web Service.

The property is marked read-only because it returns a reference to a simple objectthat you can further expand Whenever you add a property to this object, you add

a parameter that will be passed to the web method The name of the property resents the name of the parameter, and the property’s value is the value of theparameter For example, let’s say you’ve rewritten (or overloaded) the GetTime-AsString method as follows:

prop-NOTE In the case of the ServiceMethodRequest class, the names of the

prop-erties added to the parameters object must match the names and thecase of the parameters declared in the web method Otherwise, an excep-tion will be raised at runtime

Arrays

A similar notation is used for properties that return arrays In XML Script, theproperty is represented, as usual, by a tag with the same name as the property.The difference is that every child element is parsed as an instance of a clientobject and then added to the array For example, suppose the client component