ASP.NET AJAX for Developers

landyaddaInternet και Εφαρμογές Web

10 Νοε 2013 (πριν από 3 χρόνια και 1 μήνα)

209 εμφανίσεις









ASP.NET

AJAX

for Developers











Information in this document is subject to change without notice. The example companies,
organizations, products, people, and events depicted herein are fictitious. No association with
any real company, organizat
ion, product, person or event is intended or should be inferred.
Complying with all applicable copyright laws is the responsibility of the user. Without limiting
the rights under copyright, no part of this document may be reproduced, stored in or
introduce
d into a retrieval system, or transmitted in any form or by any means (electronic,
mechanical, photocopying, recording, or otherwise), or for any purpose, without the express
written permission of Microsoft Corporation.


Microsoft may have patents, patent
applications, trademarked, copyrights, or other intellectual
property rights covering subject matter in this document. Except as expressly provided in any
written license agreement from Microsoft, the furnishing of this document does not give you
any licen
se to these patents, trademarks, copyrights, or other intellectual property.


© 2007

Microsoft Corporation. All rights reserved.


Microsoft, MS
-
DOS, MS, Windows, Windows NT, MSDN, Active Directory, BizTalk, SQL Server,
SharePoint, Outlook, PowerPoint, Fron
tPage, Visual Basic, Visual C++, Visual J++, Visual
InterDev, Visual SourceSafe, Visual C#, Visual J#, and Visual Studio are either registered
trademarks or trademarks of Microsoft Corporation in the U.S.A. and/or other countries.


Other product and compa
ny names herein may be the trademarks of their respective owners.



Table of Contents


1.0

Introducing ASP.NET AJAX

................................
...............................

3

1.1

A Brief History of
AJAX

................................
................................

3

1.2

How AJAX Works

................................
................................
........

4

1.3

ASP.NET AJAX

................................
................................
...........

7

1.4

Feature Factoring

................................
................................
.....
10

2.0

The ASP.NET 2.0 AJAX Extensions

................................
.....................
12

2.1

Core AJAX Server Controls

................................
...........................
12

2.
1.1

ScriptManager and ScriptManagerProxy

................................
......
13

2.1.2

UpdatePanel

................................
................................
.....
15

2.1.3

UpdateProgress

................................
................................
..
18

2.2

ASP.NET AJAX Control Toolkit Server Controls

................................
....
19

2.3

ASP.NET AJAX Futures CTP Server Controls

................................
.......
22

2.4

Web Services

................................
................................
...........
23

2.4.1

Web Service Extensions
................................
.........................
25

2.4.2

The ScriptMethod Attribute

................................
....................
27

2.5

Page Methods

................................
................................
..........
27

2.6

JSON

................................
................................
.....................
28

2.7

Built
-
In Web Services

................................
................................
.
30

2.7.1

Authentic
ationService

................................
..........................
30

2.7.2

ProfileService

................................
................................
....
31

3.0

The Microsoft AJAX Library

................................
.............................
33

3.1

JavaScript Base Type Extensions

................................
....................
34

3.2

Global Functions and Variables

................................
.....................
34

3.3

JavaScript Type System (Adding OOP to JavaScript)

.............................
35

3.4

Script Core Library

................................
................................
....
38

3.5

Base Class Library

................................
................................
.....
39

3.6

PageRequestMana
ger

................................
................................
.
41

3.7

HTML Controls

................................
................................
.........
42

3.8

xml
-
script
................................
................................
...............
44

4.0

Summary

................................
................................
...................
47



1.0

Introduc
ing ASP.NET AJAX

ASP.NET

AJAX is a
free
framework that simplifies the development of
AJAX
-
enabled
Web
pages and Web
applications
.
It is both a set of
server
-
side
extensions to
Microsoft
ASP.NET
2.0
and a client
-
side library

written in JavaScript
that is
browser
-
independent
and
a
gnostic to
server platforms.

Indeed, the client half of ASP.NET AJAX can be used
with PHP, ColdFusion, and other non
-
Microsoft platforms

almost as easily as it is
used
with ASP.NET.

Because
ASP.NET AJ
AX is 100% browser
-
independent
,
pages built with it
work
not only in
Microsoft
Internet Explorer, but
in
Mozilla
Firefox,

Apple
Safari, and
other
modern
browsers
.

And ASP.NET AJAX bears the distinction of being the only
AJAX framework created by Microsoft

in fact, by the same team
that
produced
ASP.NET.


ASP.NET AJAX abstracts the mechanics of AJAX so developers can build AJAX
-
enabled
applications without having to become experts in JavaScript, XML
-
HTTP, and other
te
chnologies that make up

AJAX itself.

For
example, ASP.NET AJAX includes an
UpdatePanel

control that enables selected regions of a Web page to be updated via
AJAX.
Simply adding an
UpdatePanel

control to a page can often replace tens of hours
of tedious coding involving JavaScript, browser
Documen
t Object Models (
DOMs
)
,
and
XmlHttpRequest

objects.

Similar abstractions reduce the complexity of
other tasks

adding animations, popup panels, drag
-
and
-
drop support, and
more

to l
ittle more
than declaring controls in a Web page.


This document contains a t
echnical overview of ASP.NET AJAX and is specifically
intended to help developers

understand
, evalu
ate, and get started using ASP.NET
AJAX
.

Additional information

about ASP.NET AJAX
, as well as instructions for
downloa
ding and installing it
, can be foun
d
a
t
http://ajax.asp.net/
.

1.1

A Brief History of AJAX

The term “AJAX” was
coined in February 200
5 by Jesse James Garrett

in a seminal
paper
titled “
Ajax
: A New Approach to Web Applications
.”
The paper
identifies

the
following technologies as the constituent components of AJAX:




Standards
-
based presentation using XHTML and CSS



Dynamic display and interaction using the
DOM



Data interchange and manipu
lation using XML and XSLT



Asynchronous data retrieval using
XMLHttpRequest

objects



JavaScript binding everything together


AJAX stands for
Asynchronous JavaScript and XML
. “Asynchronous” alludes to the
asynchronous calls (or “callbacks”) that AJAX browser
clients make to Web servers

to
submit (and
often

to retrieve) data
.
C
allbacks are launched by JavaScript executing in
the browser
, and when a callback completes,
JavaScript
is used to
process the res
ults
.

The chief benefit to performing callbacks asynchron
ously is that it frees the browser
to execute code and continue responding to user input while waiting for callbacks to
complete.


The “XML” in “Asynchronous JavaScript and XML” alludes to the protocol used by
asynchronous callbacks (XML
-
HTTP) and to the b
rowser object used to execute XML
-
HTTP
requests

(
XmlHttpRequest
). AJAX

applications sometimes
use XML to serialize


data transmitted over the wire, but inceasingly, JSON

short for
JavaScript Object
Notation

is the serialization format of choice. JSON is mor
e compact than XML,
is
more readable to the human eye
, and
typically requires less time and processing
power to decode.
For these reasons, i
t’s the native serialization format employed by
ASP.NET AJAX.
You can read all about JSON at

http://www.json.org/
.


In the words of the creator of the term AJAX, “
Ajax isn’t a technology. It’s really
several technologies, each flourishing in its own right, coming together in powerful
new ways
.” Indeed, the two technolog
ies that form th
e foundation for all
AJAX

applications

JavaScript and
XmlHttpRequest

predate AJAX by
many years.


JavaScript
debuted in 1995 in a beta release of Netscape Navigator 2.0. Originally
titled “LiveScript,”
its

name changed to Ja
vaScript

before year’s end
. Shor
tly
thereafter, Microsoft
added support
to Internet Explorer
for an almost identical
scripting language
named JScript
.

JavaScript
was submitted to the European standards
body ECMA (European Computer Manufacturers’ Association)
as ECMAScript
in 1996 and
tod
ay is both an ECMA and ISO standard.


Whereas Netscape invented JavaScript, Microsoft invented the
XmlHttpRequest

object
.

XmlHttpRequest

was created
to enrich

the user interface of Outlook Web
Access (OWA) and was originally implemented as an ActiveX objec
t in Internet Explorer
5.
0.

(OWA was, in fact, the first AJAX application, although it wasn’t called that
because the term

AJAX


had yet to be
invented
.)
Other browser vendors followed
suit, and today virtually all modern browsers support
XmlHttpRequest

i
n one form or
another. Rather than implement
XmlHttpRequest

as an ActiveX object, third
-
party
browsers implement

it as a native browser object. For consistency with other browsers
and to avoid some of the security concerns involving ActiveX controls, Micro
soft
include
d

a native
XmlHttpRequest

object

in Internet Explorer 7
.

XmlHttpRequest

is
currently in the process of being standardized by the World Wide Web Consortium
(W3C). For the latest information

on the standardization process
, visit
http://www.w3.org/TR/XMLHttpRequest/
.


Today AJAX

is employed by numerous
Web applications to make browsing the Web a
richer
and more pleasing experience. Examples or popular Web applications that use
AJAX include
Windows
Live Local,
Outlook Web Access
,
Gmail
,

Google Suggests,
and
Google Earth.

In all likelihood, the
popularity
of AJAX
will only increase in coming
years and dri
ve the demand for
AJAX
frameworks
such as ASP.NET AJAX.

1.2

How AJAX Works

A classic use for AJAX
in Web applications is to improve the user experience by
replacing postbacks with asynchronous callbacks
. Traditional Web applications use
form submission events transmitted via HTTP POSTs

“postbacks” in ASP.NET
parlance

to
execute round trips

to the serve
r. Postbacks suffer two significant
drawbacks:




When a postback occurs, the browser discards the HTML it’s holding and
redraws the page using the HTML returned in the HTTP response. Consequently,
the
entire
page “flashes” even if only a fraction of the
pag
e

actually needed to
be redrawn.






When a postback occurs, all of the
form

input on the page

including ASP.NET
view state and other data stored in hidden input fields

is transmitted to the
server
, even if only a fraction of that

inpu
t is actually used
.


Re
placing postbacks with asynchronous
XML
-
HTTP
callbacks offers the following
benefits:




The browser no longer discards the HTML it’s ho
lding, eliminating the flashing
and vastly improving the user experience.




Rather than transmit all
form

input to the serv
er, an asychronous callback can
transmit just the input that’s needed, leading to better and more efficient
bandwidth utilization.


Figure 1
-
1 demonstrates
how replacing postbacks with callbacks improves the user
experience.

The browser
first
submit
s a con
ventional HTTP GET request to fetch HTML
content from a Web server. The browser renders the content to display the Web page.
When the user clicks a button on the page, what would normally be a postback in an
ASP.NET page is instead an asynchronous callback

thanks to a bit of JavaScript wired
to the button. The callback travels to the server in the form of an asynchronous XML
-
HTTP request. Significantly, the browser doesn’t discard the HTML it’s displaying, so
until the callback completes, the page remains
u
nchang
ed in the browser.



Figure 1
-
1: Using AJAX to perform partial
-
page

rendering






When the callback completes, JavaScript code downloaded to the browser retrieves
the results of the call and uses the browser DOM to update the content on the page. In
this example, the JavaScript updates an image on the page by changing an <img> tag’s
src

attribute. This scenario, in which an XML
-
HTTP request travels back to the server
and JavaScript on the client updates what the user sees using the results of

the call
, is
commonly known as
partial
-
page rendering
. The unsightly flashing that characterizes
many Web pages is e
liminated, and in some implementations
, the volume of data
traveling over the wire is greatly reduced.


The first step in

launching an asynchronous
XML
-
HTTP request is to instantiate an
XmlHttpRequest

object. The following JavaScript code does just that, and it employs a
multifaceted “discovery” strategy
for the
XmlHttpRequest

object
that works in
virtually all modern browsers:


var xhr = null;


if (w
indow.XMLHttpRequest)

{


xhr = new XMLHttpRequest();

// IE 7, Firefox, etc.

}

e
lse

// Older IE browsers

{


try


{


xh
r = new ActiveXObject("Msxml2
.XMLHTTP");


}


catch (ex)


{


xh
r = new ActiveXObject("Microsoft
.XMLHTTP");



}

}


The next step is to launch the callback itself. That’s accomplished by
opening
the
XmlHttpRequest

object

(and
in the process providing key information such as the URL
ta
rgeted by the XML
-
HTTP request
)
and calling its
send

method. The “true” passed

in
the third parameter specifi
es that the request should be submitted async
hronously
rather than synchrono
usly:


xhr.open ('GE
T', 'AjaxDemo.aspx
', true);

xhr.onreadystatechange = checkForCompletion;

xhr.send ();



...


function checkForCompletion()

{


if (xhr.readyState == 4 && xhr.status == 200)


{


window.alert(xhr.responseText);


}



}


Because

the call is asynchronous,
send

returns immediately.
In this example, the
checkForCompletion

function
is called each time the
XmlHttpRequest

object

s ready
state

changes. A
readyState

property equal to 4 indica
tes that the
asynchronous
request

has completed
, and a
status

code of 200 indicates it completed successfully
.
This
example uses
window.alert

to display the response
returned by the
callback
,
wh
ich is
accessed through the
XmlHttpRequest

object’s
responseText

property
.
(If the
response contains an XML document

rather than raw text
,
responseXML

can be used
instead.)
In real life, JavaScript code
of greater complexity
is typically provided to do
som
ething
more tangible
wit
h the

response

for example, to
update content on the
page.


As
an added co
mplication when AJAX is hand
-
coded
, it is the developer’s responsibility
t
o serialize and deserialize
data passed over the wire in the request and response.
P
assing simple data types such
as strings is easy; passing complex data such as
instances of custom data types
is commensurately more difficult.


Writing AJAX code without the benefit of an AJAX framework can be tedious and time
-
consuming due to differences

between browsers and the need to write JavaScript code
to process the re
sults of XML
-
HTTP requests. AJAX frameworks such as ASP.NET AJAX
simplify the development process by encapsulating and abstracting key aspects of
AJAX itself, and even by abstracting
the differences between browsers.

1.3

ASP.NET AJAX

AJAX frameworks represent the second step in the evolution of AJAX (the first step
being the invention of AJAX itself) and prov
ide much
-
needed abstractions
that enable

AJAX Web
pages
to

be built in minutes

rather than hours or days.

ASP.NET AJAX is
the
AJAX framework from Microsoft
. It is divided in
to two distinctly different
yet
interrelated halves:




The ASP.NET 2.0 AJAX Extensions, which reside on Web servers



The Microsoft AJAX Library, which resides in b
rowser clients


The ASP.NET 2.0 AJAX Extensions are the server half of ASP.NET AJAX. A schematic
appears in Figure 1
-
2.

The box labeled “
AJAX
S
erver
C
ontrols


represents

controls such
as
UpdatePanel

and
UpdateProgress
,

which

provide easy
-
to
-
use
wrappers ar
ound AJAX
.
The application services bridge is a set of Web services that expose key ASP.NET 2.0
services such as membership and profiles to browser clients. The asynchrono
us
communications layer permits
ASMX
Web
methods

and special
ASPX
methods known as
pa
ge methods

to serve as endpoints for AJAX callbacks
. It also
enhances ASP.NET
2.0
with support for JSON serialization and deserialization. The ASP.NET 2.0 AJAX
Extensions are described more fully in Section 2.0.



Figure 1
-
2: The ASP.NET 2.0 AJAX Extension
s






The Microsoft AJAX Library is the client half of ASP.NET AJAX.

Its structure is shown in
Figure 1
-
3.
The Base Class Library and Script Core Library are JavaScript libraries that
make JavaScript an easier and more productive
language

in which to work.

They can
be leveraged directly with hand
-
written JavaScript code, but more importa
ntly, they
can be
(and are)
leveraged
by
code and markup emitted by AJAX server controls.
The
asynchronous communic
ations layer provides
support for network communications
(
including asynchronous XML
-
HTTP requests) and JSON serialization and
deserialization. The browser compatibility layer enables ASP.NET AJAX applications to
work in a wide variety of browser types.

The Microsoft AJAX Library is described more
fully in Sectio
n 3.0.



Figure 1
-
3: The Microsoft AJAX Library






Here are four ke
y points to keep in mind regarding ASP.NET AJAX:




AJAX server controls make it extremely easy to add AJAX support to ASP.NET
Web pages. Simply declare a control on the page and the control

does the rest.




AJAX server controls require ASP.NET on the server. They emit code (and
sometimes markup) that leverages the Microsoft

AJAX Library on the client
.




The Microsoft AJAX Library, which is browser
-
independent

and written entirely
in JavaScript
, is the engine that
drives ASP.NET AJAX
.

It can be leveraged
by
declaring AJAX server
controls on a page, or
by writing JavaScript code that
u
s
es
the
Microsoft AJAX
Library directly
.




The Microsoft AJAX Library is
independent

of

server platforms
; it doesn

t
require ASP.NET or any other platform, for that matter
. You could leverage it
from PHP or other platforms simply by embedding JavaScript in your pages. Or
you could write server
-
side PHP wrappers that em
it code and markup just like

ASP.NET 2.0 AJAX Exte
nsions server controls.



1.4

Feature

Factoring

ASP.NET AJAX
can be downloaded from the ASP.NET AJAX downloads page at
http://ajax.asp.net/default.aspx?tabid=47&subtabid=471
.
That page feat
ures four
separate downloads
:




ASP.NET AJAX

1.0



ASP.NET AJAX Control Toolkit



ASP.NET AJAX Futures
CTP



Microsoft AJAX Library


The ASP.NET AJAX
1.0
download contains the core features of the platform, including
the
UpdatePanel

server
control
and the
browser

c
ompatibility layer and
asynchronous
communications layer

on the client. These features
are fully tested a
nd fully
supported by Microsoft
.


The ASP.NET AJAX Control Toolkit adds several additional server controls to the
package as well as a software devel
opment kit (SDK) for developing controls of your
own.
The ASP.NET AJAX Control Toolkit is a shared
-
source, community
-
supported
project
.

It is fully tested
, vetted by the community, and considered robust enough for
use on production servers.
It’s hosted at
CodePlex (
http://www.codeplex.com/
) and is
constantly being updated with new controls and code samples.


The ASP.NET AJAX Futures CTP

further
expands the feature set and provides a
mechanism for
Microsoft to deliver n
ew features and collect

feedback

on those
features
. CTP stands for “Community Technology Prev
iew” and is the term used to
describe
features that are still under development. Conservat
ive shops that prefer to
use
onl
y fully tested, fully supported
features
of the platform
can

do so by installing
only the core ASP.NET AJAX download

(and optionally the control toolkit)
. More agile
shops that want to leverage ASP.NET AJAX to the fullest can install the Futures CTP
and enjoy access to a wider range of features.
Figure 1
-
4
documents
the division of
features between core and CTP.



Figur
e 1
-
4: ASP.NET AJAX feature matrix


Server

Feature

ASP.NET AJAX

ASP.NET AJAX

January 2007
Futures CTP

Asynchronous client
-
to
-
server networking




ScriptManager

and
ScriptManagerProxy

controls




UpdatePanel

control




UpdateProgress

control




Timer

control




Application services bridge




Page methods




DragOverlayExtender

control




ProfileService

control







Client

Feature

ASP.NET A
JAX

ASP.NET AJAX

January 2007
Futures CTP

JavaScript
type extensions




JavaScript type system




JSON serialization

and deserialization




Client
-
side application services bridge




Calling
Web services from JavaScript




Debugging aids




HTML

c
on
trol
s (
Button
,
CheckBox
,
Label
, etc.)




Data controls (
ListView
,
ItemView
, etc.)




Validation controls




Drag
-
and
-
drop support




Animation
support




x
ml
-
s
cript support






The fourth download

the Microsoft AJAX Library

contains the JavaScript f
iles that
make up the Microsoft AJAX Library. Developers
building applications for non
-
ASP.NET
platforms
can
use these files to
enjoy all the benefits of ASP.NET AJAX in browser
client
s

without the need for ASP.NET on the server
.



2.0

The ASP.NET 2.0 AJAX
Extensions

The ASP
.NET 2.0 AJAX Extensions extend

AS
P.NET 2.0 with new controls, features, and
capabilities, including the
ability to use ASMX Web methods

and ASPX page methods
as
endpoints for
asynchronous
XML
-
HTTP requests and support for JSON serializat
ion and
deserializa
tion.

They also include

built
-
in Web services that enable
the ASP.NET 2.0

membership and profile services to be accessed by JavaScript clients.


Core features of the ASP.NET 2.0 AJAX Extensions are contained in the assembly
System.Web.Ex
tensions.dll, which is added to the Global Assembly Cache (GAC) when
ASP.NET A
JAX is installed
.

The ASP.NET AJAX Control Tool
kit is packaged in

a separate
assembly named AjaxControlToolkit.dll, while the Futures CTP
lives

in
Microsoft.Web.Preview.dll.
Ajax
ControlToolkit.
d
ll
and Microsoft.Web.Preview.dll
are
no
t installed in the GAC;
instead
, they’re

privately
deployed in
the
Bin subdirectory.


The sections that follow introduce the ASP.NET 2.0 AJAX Extensions and offer

a guided
tour
of its features
.

2.1

Cor
e
AJAX Server Controls

The most visible component of the ASP.NET 2.0 AJAX Extensions is the family of
controls know
n

as the
AJAX server controls
. These controls
abstract
AJAX and
greatly
simplify the
process of
building
AJAX
-
enabled Web pages.


The AJAX se
rver controls
supple
ment the
server controls built into
ASP.NET (
TextBox
,
Panel
,
TreeView
, and so on) and confor
m to the same programming model

and usage
patterns. In Visual Studio, AJAX server controls can be dragged from the Toolbox and
dropped onto a pa
ge to add AJAX capabilities to that page.

Figure 2
-
1

lists the
core
AJAX server controls included in
ASP.NET
AJAX 1.0
.



Figure 2
-
1
: Core
AJAX server controls


Control

Description

ScriptManager

Enables

ASP.NET AJAX to be used in a Web page.

ScriptManager
Proxy

Enables
content pages to add
script references and
service references to a
ScriptManager

control declared in
a master page.

UpdatePanel

Implement
s partial
-
page

rendering
in

a Web page.

UpdateProgress

Displays
a custom user interface (UI
) while upda
tes are
pending in
UpdatePanel

controls.

Timer

Implements a programmable callback timer.



The
following

sections provide a brief overview
of
these controls. The

goal isn’t to
provide

an exhaustive reference, but to provide
helpful
information regarding
the
controls’ capabilities
and syntactical help

using them
.



2.1.1

ScriptManager

and
ScriptManagerProxy

Every ASP.NET AJAX page begins with a
ScriptManager

control.
The
ScriptManager

control’s
primary duties include:




Downloading
Microsoft
AJAX
Library
Java
Script files to the browser if they
haven’t been downloaded
already




Declaring service references
that enable

Web services to be called directly
from the
browser

through JavaScript pr
oxies




Providing control over error handling

what happens when an excepti
on is
thrown on the server
during

an asynchronous callback


ScriptManager

controls
also provide script registration methods (so custom controls
that emit JavaScript can be compatible with
UpdatePanel

controls), al
l
ow

localization
features to be enabled and

disabled
, control

whether the debug or release version of

the Microsoft AJAX Library is download
ed, and more.


A page that uses ASP.NET AJAX must contain one

and only one

ScriptManager

control.

The declaration can be as simple as this:


<asp:ScriptManager

ID=
"
ScriptManager1
"

runat=
"
server
"

/>


Figure 2
-
2

offers a more comprehensive look at the
ScriptManager

schema.

The
<Services> element declares Web service references, enabling those Web services to
be called through
JavaScript proxies (Section 2.4
). The

<Scripts> element enables a
page to download JavaScript files that aren’t downloaded by default. For example,
the following
ScriptManager

declaration downloads PreviewScript.js, which contains
many of the Microsoft AJAX Library features found in the ASP.N
ET AJAX Futures CTP
,
as well as a custom JavaScript file named UIMap.js
:


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


<Scripts>


<asp:ScriptReference

Name="
PreviewScript.js
"


Assembly="System.Web.
Preview
" />


<asp:ScriptReference Pa
th="~/Scripts/UIMap.js" />


</Scripts>

</asp:ScriptManager>



Figure 2
-
2
: ScriptManager schema

<asp:ScriptManager ID=
"
ScriptManager1
"

runat=
"
server
"


EnablePartialRendering="true|false"


EnablePageMethods=
"true|false"


AsyncPostBackTimeout="
seconds
"


AsyncPostBackErrorMessage="
message
"


AllowCustomErrors
Redirect
="true|false"


OnAsyncPostBackError="
handler
"


EnableScriptGlobalization="true|false"


EnableScriptLocalization="true|false"





ScriptMode="Auto|Inherit|Debug|Release"


ScriptPath="
path
">



<Scripts>


<!
--

Declare
script references
here
--
>


</Scripts>


<Services>


<!
--

Declare Web service references here
--
>


</Services>

</asp:ScriptManager
>



Additional configuration options can be specified through properties of the
ScriptManager

control
.

For example, setting
EnablePartialRendering

to true allows the
page to host
UpdatePanel

controls, while
ScriptMode
=“Debug” runs the debug version
of the Microsoft AJAX Library rather than the release version.


The
ScriptManager

control’s

Error

pr
operties provide control over error handling. By
default, if an exception is thrown during an asynchronous
ASP.NET AJAX
callback
, the
custom error page
registered in the <customErrors> section of
Web.config is displayed.
If no custom error page is designat
ed, then ASP.NET AJAX displays the exception’s
Message

property in an
alert

window on the client.

You can set
the
AllowCustomErrorRedirect

property
to false to prevent custom error pages from being
shown,
and
use
the
AsyncPostBackErrorMessage

property
to
o
verride

the default error
message with a custom one.

Additionally, you can use
the
OnAsyncPostBackError

event
to execute a handler on the server if an exception occurs during
an asynchronous
callback. From

the handler, you can
specify
the error message
ret
urned to

the client.


The
ScriptManager

control
is complemented by the
ScriptManagerProxy

control. If you
declare a
ScriptManager

control in a mas
ter page and want

to declare additional script
or service references in a content page, you can declare a
Scri
ptManagerProxy

control
in the content page and add your scri
pt and service references there, as illustrated in
Figure 2
-
3.



Figure 2
-
3: Using the ScriptManagerProxy control







2.1.2

UpdatePanel

Sometimes called the “crown jewel of ASP.NET AJAX,” the
Upd
atePanel

control
is
more aptly
described as “partial
-
page

rendering in a box.” It
so thoroughly
abstracts
the mechanics of partial
-
page

rendering that
using it completely shields the developer
from having to understand
XML
-
HTTP and

JavaScript.


Figure 2
-
4

illustrates how
UpdatePanel

controls

perform partial
-
page

rendering,
and
why partial
-
page

rendering eliminates the excessive flashing that
characterizes
many
ASP.NET Web pages. In a traditional update, the page posts back to the server. The
browser erases
the page and redraws it using the conte
nt returned in the response.
A
page with an
UpdatePanel

control
works differently.
The
UpdatePanel

a
utomatically
converts postbacks
from controls inside it into asynchrono
us XML
-
HTTP callbacks
. The
browser doesn’t era
se the page, and when the callback completes,
the
UpdatePanel

control
updates its
content using JavaScript. Thus, less rendering is pe
rformed on the
server (only
controls inside the
UpdatePanel

undergo

a rendering cycle),

less
data
come
s back in the respon
se,

and the user experience is improved because the page
doesn’t flash.



Figure 2
-
4
: Partial
-
page

rendering

with UpdatePanel controls







To use an
UpdatePanel

control
, you sim
ply declare it on
the page
where
you
want
partial
-
page rendering to take place

and
then put the content i
n a <ContentTemplate
>
elemen
t, as demonstrated in Figure 2
-
5
.



Figure 2
-
5
: Using an UpdatePanel control

<asp:UpdatePanel ID=
"
UpdatePanel1
"

runat=
"
server
"
>


<ContentTemplate>


<!
--

Declare content here
--
>


</ContentTemplate
>

</asp:UpdatePanel>



If the <ContentTemplate> contains
Button
s or
LinkButton
s or other controls that
generate postbacks,
the
UpdatePanel

control
converts
the postbacks
i
nto asynchronous
callbacks. The page looks no different than b
efore, but when a contr
ol in

the
UpdatePanel

posts (calls) back to the server, the
UpdatePanel

control
replaces the old
markup in the <ContentTemplate> with
the new markup

returned
in the response,
producing a clean, fli
cker
-
free re
fresh
.


The
UpdatePanel

control
also supports e
xplicitly defined
triggers
. Triggers come in
two varieties. The
AsyncPost
B
ackTrigger

allows controls outside an
UpdatePanel

to
trigger updates of the
UpdatePanel
’s content. Under the hood
,

AsyncPostBackTrigger

convert
s

postbacks
generated by the specified
controls
into asynchronous callbacks.
The other trigger type,
PostBackTrigger
, allows controls inside an
UpdatePanel

to post
back rather than call back.

In Figure 2
-
6
, the
UpdatePanel

control
converts postbacks
from all the controls
declared
inside it
and

postbacks generated by a
Button

control
outside the
UpdatePanel

into asynchron
ous callbacks

that refresh the
UpdatePanel
:





Figure 2
-
6
: UpdatePanel triggers

<asp:Button ID=
"
Button1
"

Text=
"
Click Me
"


OnClick=
"
Button
1
_Clicked
"

runat=
""

/>


...

<asp:Updat
ePanel ID=
"
UpdatePanel1
"

runat=
"
server
"
>


<Triggers>


<asp:AsyncPostBackTrigger ControlID=
"
Button1
"


EventName=
"
Click
"

/>


</Triggers>


<ContentTemplate>


<!
--

Declare content here
--
>


</ContentTemplate>

</asp:UpdatePanel>



On the server,
t
he
Button

control’s
Click

handler

Button1_Clicked

is

called
inside
the callback
just as if
a conven
tional postback

had occurred
. This is one of
the
UpdatePanel

control
’s greatest assets: the fact that you can write code using the same
server
-
centric model

you’re
accustom
ed to in ASP.NET. T
he code works
as if
a
postback had occurred
, and
the
UpdatePanel

control
eliminates
flashing and flickering
on the client.


UpdatePanel

control
s

are frequently combined with
Timer

control
s

to periodically
refresh content
on a page.

This is

one way to synchronize data displayed in a browser
with data
that is continually changing
on a server.


A page can contain multiple
UpdatePanel

controls. By default, when an update is
triggered in one
UpdatePanel

control
, other
UpdatePan
el

control
s

on the page
rerender, too.

In some cases, that’s what you

want; in most cases, it’s not. (
M
ore
UpdatePanel

control
s

updating

in response to a callback means
more rendering code
executes

on the server and

more data comes back in the response.)
T
o selectively
trigger updates, you can set each
UpdatePanel

control
’s
UpdateMode

property to
“Condtional”
(the default is “Always”), When an
event handler is called inside a
callback from one
UpdatePanel

control
,
you then
call the
Update

method of other
Up
datePanel
s
that need updating
. When
UpdateMode
=“Conditional,” an
UpdatePanel

control
only rerender
s

its contents if one of
the controls inside it
triggers
a callback or
its
Update

method is
called.


In order for
an
UpdatePanel

control
to work, the page tha
t hosts it must also contain a
ScriptManager

control. In addition,
the
ScriptManager

control
must be configured to
enable partial
-
page

rendering, as shown here:


<asp:ScriptManager ID=
"
ScriptManager1
"

runat=
"
server
"


EnablePartialRendering=
"
true
"

/>


The
EnablePartialRendering
=“true” attribute

ensures that the JavaScript file
containing the client
-
side support that
UpdatePanel

requires is
downloaded to the
browser.

Because

the
EnablePartialRendering

property defaults to true,
simply


declaring a
ScriptManag
er

control on the page (without explicitly setting
EnablePartialRendering

to true) is sufficient to
enable

partial
-
page rendering.


Most controls can be hosted inside an
UpdatePanel
, but some cannot. In particular,
controls that emit JavaScript of their ow
n cause myriad problems
with

UpdatePanel

controls
unless they use
RegisterClientScriptBlock
,
RegisterStartupScript
, and other

ScriptManager

registration methods
to register the script they return.
For more
information on
script

registration and
how to buil
d
custom
controls

that are
compatible with the
UpdatePanel

control
, read the
post

entitled “
HOWTO: Write
controls compatible with
UpdatePanel

without linking to the ASP.NET AJAX DLL
” by
Eilon Lipton, lead developer of the
UpdatePanel

control, at
http://forums.asp.net/thread/1445844.aspx
.


The
UpdatePanel

control
does have one drawback:

its callbacks aren’t as efficient on
the wire as
hand
-
coded
AJAX callbacks.

The data transmitted to
the
server include
s
view state and other form input and is in fact almost identical to what’s transmitted in
a traditional postback. The
response includes all the freshl
y rendered content. The
size of that content is roughly proportional to the
size of the
UpdatePanel

contr
ol’s
<ContentTemplate>
.

In other words, if the
UpdatePanel

control
encompasses half the
page, then the response
size is roughly half
that gener
ated by a traditional postback.
UpdatePanel

callbacks aren’t as efficient as
hand
-
coded
AJAX callbacks once they
reach the server, either, because the page undergoes a nearly complete life cycle.
Techniques exist for optimizing
UpdatePanel

usage and even replacing
UpdatePanel

control
s

with Web services and JavaScript, but those techniques are beyond the scope
of this

document. Suffice it to say that
UpdatePanel

controls emphasize

ea
se
-
of
-
use
over efficiency

proo
f once more that there’s no such thing as a free lunch.

2.1.3

UpdateProgress

The
UpdateProgress

control is a companion to
the
UpdatePanel

control
. It enables
p
ages that host
UpdatePanel

controls to display
special content

elements
when an
update is in progress

for example, an animated GIF depicting a progress bar or a clock
with spinning hands. I
t can also be used to display
UI
s

for canceling
update
s

that
haven’
t completed
.


The markup
in Figure 2
-
7

declares an
UpdateProgress

control that display
s an
an
imated GIF each time an
UpdatePanel

control updates and hides the GIF when
the
update completes.
DisplayAfter
=“500” prevents the image
from being shown if the
upda
te requires less than half a second

(500 milliseconds) to complete.



Figure 2
-
7
: Using the

UpdateProgress control

<asp:UpdateProgress ID="
UpdateProgress1
"
runat=
"
server
"


DisplayAfter="500"
>


<ProgressTemplate>


<asp:Image ID="ProgressBarImage" r
unat
="server"


ImageUrl="~/Images/
ProgressBar.
gif" />


</ProgressTemplate>

</asp:UpdateProgress>





You can create more sophi
sticated progress UIs by
declaring them in the control’s
<ProgressTemplate>. The example
in Figure 2
-
8

displays a Cancel button if

the update
takes more than 1 second to complete
,

and
it
uses a bit of J
avaScript to cancel the
update

if the button is clicked
:



Figure 2
-
8
: Canceling a pending update

<asp:UpdateProgress ID="
UpdateProgress1
"
runat=
"
server
"


DisplayAfter="1000"
>


<Prog
ressTemplate>


<
asp:Button ID="CancelButton" r
unat="server" Text="Cancel"


OnClientClick="cancelUpdate(); return false
;
" />


</ProgressTemplate>

</asp:UpdateProgress>


<script type="text/javascript">

function cancelUpdate()

{


var obj = Sys.Web
Forms.PageRequestManager.getInstance();


if (obj.get_isInAsyncPostBack())


obj.abortPostBack();

}

</script>



By default, if a page contains just one
UpdateProgress

control, the control displays its
content when any
UpdatePanel

control on the pag
e updates.

However, you can
declare multiple
UpdateProgress

controls on a page and associate each with a
specific
UpdatePanel

using

the
UpdateProgress

control’s
AssociatedUpdatePanelID

property.
This is useful when a page contains multiple
UpdatePanel

cont
rols and you want
to
display
a different
progress
UI

for each

one
.

2.2

ASP.NET AJAX Control Toolkit Server Controls

The ASP.NET AJAX Control Toolkit
expands the capabilities of the
ASP.NET 2.0 AJAX
Extensions
by adding more

than 30
new
server controls
.

Fig
ure 2
-
9

lists the c
ontrols
included in the toolkit as of January 2007
.



Figure 2
-
9
: ASP.NET AJAX Control Toolkit server controls


Control

Description

Accordion

Displays “accordion”
=
rf=co湳楳t楮朠g映浵汴楰汥
=
灡湥猬s
o湬y=
o湥=o映睨楣栠楳=
癩獩扬e
=
at=a=t業攮
=
AlwaysVisible
Control
Extender

Pins
controls
in

a
specified

position
as

the page
is scrolled or resized.

Animation
Extender

Adds animation effects to Web pages.

AutoComplete
Extender

Adds context
-
sensitive drop
-
down completion
lists to
TextBox

controls.

Ca
lendar

Adds popup calendars to date
-
entry
TextBox



controls.

CascadingDropDown

Connects
DropDownList

controls so that a
change to one updates content in the others.

CollapsiblePanel
Extender

Implements
content panels

that can be
interactively
expanded and
collapsed
.

ConfirmButton
Extender

Enhances button controls with popup
confirmation boxes
.

DragPanel
Extender

Enables

Panel

controls
to be
interactively
dragged and repositioned.

DropDown
Extender

Adds SharePoint
-
style drop
-
down menus to
other

controls.

Dr
opShaow

Adds drop shadows to
Panel

controls.

DynamicPopulate
Extender

Populates controls by calling Web methods or
page methods asynchronously.

FilteredTextBoxExtender

Filters input to
TextBox

controls.

HoverMenu
Extender

Adds popup
“hover”
m敮畳=to=ot桥r
=
co湴牯r献
=
MaskedEdit
Extender

Adds
visual formatting cues to
TextBox

controls.

ModalPopup
Extender

Displays content modally
.

MutuallyExclusiveCheckBox
Extender

Groups
CheckBox

controls and ensures that
only one member of the group is checked.

NoBot

Uses
challenge
-
response mechanism to filter
out “bot” input without user intervention.
=
NumericUpDown
Extender

Adds up
-
down buttons to
TextBox

controls.

PagingBulletedList
Extender

Adds sorting and paging to
BulletedList

controls.

PasswordStrength

Enhances pass
word
-
entry

TextBox

controls with
visible indication of password strength.

PopupControl
Extender

Attaches popup content to other controls.

Rating

Display
s

interact
ive rating UI
.

ReorderList

Implements
lists

whose items can be reordered
by the user
.

Resiz
ableControl
Extender

Allows content to be resized interactively.

RoundedCorners
Extender

Adds rounded corners to existing elements.

Slider
Extender

Adds sliders

to
TextBox

controls.

Tab
Container

and
TabPanel

Implements interactive tabbed UI
.

TextBoxWaterm
arkExtender

Adds watermark text to
TextBox

controls.

ToggleButton
Extender

Enhances
CheckBox

controls with images that
toggle between checked and unchecked mode.

UpdatePanelAnimation
Extender

Plays animations when
UpdatePanel

control
s

update.

ValidatorCal
loutExtender

Adds popup UIs to ASP.NET validator controls.



One of the most compelling controls
in the ASP.NET AJAX Control
Toolkit is the
AutoCompleteExtender

control, which adds context
-
sensitive drop
-
down completion
lists to
TextBox

controls (see Figu
re 2
-
10
). As the user types, the list is updated, and
at any time the user can stop typing and simply choose an item from the list. Items in
the list come from a Web service, and it is the developer’s responsibility to provide


that Web service.
AutoComplet
eExtender

does the rest, automatically calling the Web
service each time the text in the
TextBox

changes and passing as input what the user
has typed thus far.



Figure 2
-
10
: TextBox control with a drop
-
down completion list





Figure 2
-
11

shows how
AutoC
ompleteExtender

control
s

are declared in Web pages.
The
TargetControlID

property identifies the
TextBox

that the
AutoCompleteExtender

control extends, while
ServicePath

and
ServiceMethod

identify the Web service and
Web method that are called on each keyst
roke to generate a context
-
sensitive
completion list. (The Web service is a conventional ASMX Web service tagged with the
ScriptService

attribute desc
ribed in Section 2.4
.)
MinimumPrefixLength
=”2” instructs
the
AutoComplet
e
Extender

to make the first call t
o the Web service after two
characters have been typed, and
CompletionSetCount
=”20” tells it to display up to 20
items in the completion list. If desired, you can also use the
CompletionListElementID

property to identify an ASP.NET
Panel

contro
l that acts
as a proxy
for the completion
list. Explicitly declaring the completion list in this way is useful for styling it using
control properties or CSS.



Figure 2
-
11
: Using the AutoCompleteExtender control

<asp:TextBox ID="ZipCodeTextBox" runat="server" />


..
.

<ajaxToolkit
:AutoCompleteExtender
runat="server"


I
D="ZipCodeAutoCompleteExtender"


TargetControlID="ZipCode
TextBox
"


Se
rvicePath="ZipCodeService.asmx"


Serv
iceMethod="GetMatchingZipCodes"


MinimumPrefixLength="2"


CompletionSetCount="20"

/>



The
Web method called to generate the completion list can have any name you want,
but it must have the following signature:




public string[] GetMatchingZipCodes
(string prefixText,


int count);


When the method is called,
prefixText

specifies the text curren
tly displayed in the
TextBox
,

and
count

specifies the maximum number of strings to return in the string
array. The strings returned by the method are used to populate the completion list.

2.3

ASP.NET AJAX
Futures CTP Server Controls

The
ASP.NET AJAX
Januar
y Futures CTP adds two server controls to the ASP.NET 2.0
AJAX Extensions: the
DragOverlaye
r
Extender

control and the
ProfileService

control.
The former adds dra
g
-
drop support to existing controls
; the latter can be used to
persist the positions of
controls

paired with

DragOverlayExtender

controls
.


The
DragOverlayExtender

control

extends existing ASP.NET controls such as
Image

controls and
Panel

controls by making them “floatable.”
Users can reposition floatable
elements
with

the
ir

mouse.

The
DragOverlayExt
ender

control
relies on
the rich
drag
-
and
-
drop support
present in

the Microsoft AJAX Library.

It provides
no explicit support
for drag
-
sourcing or drop
-
targeting (
for example, it does not raise an event
when a
drop occurs or provide control

over
when
and w
here
drops occur), even though the
drag
-
and
-
drop classes
in the Microsoft AJAX Library
offer
support
for
all this and more
.


The markup

in Figure 2
-
12

declares an
Image

control and converts it into a floatable
image with a
DragOverlayExtender

control
. The
TargetControlID

property identifies
the
Image
.

DragOverlayExtender

can be applied to

Panel
s
,
Image
s
, and
a variety of
other control types
, but it cannot be used with controls that generate HTML <input>,
<button>, <sel
ect>, <textarea>, or <label> element
s.

You can’t, for example,
apply a
DragOverlayExtender

control
to

a
TextBox

control.



Figure 2
-
12
: Using
the
DragOverlayExtender
control
to create a floatable image

<asp:Image ID=
"
Logo
"

runat=
"
server
"


ImageUrl=
"
~/Images/Company_Logo.jpg
"

/>


...

<asp:Dr
agOverlayExtender r
unat="server"


ID="DragOverlayExtender1"


TargetControlID="
Logo
"


Enabled="true
"

/>



By default, the positions of elements floated with
DragOverlayExtender

are not
per
sistent;
elements snap back to their original positions when the p
age is refreshed
or revisit
ed. You can make them

persistent by combining
DragOverlayExtender

with a
ProfileService

control.

The
ProfileService

control uses the
ProfileService

Web service
in

the ASP.NET 2.0 AJAX Extensions to communicate with the ASP.NET 2.
0 profile
service on the server

and
to
store positions on a per
-
element, per
-
user basis
. The
P
rofile
Service

Web service is discussed in

Section 2.7
.2.



2.4

Web Service
s

Virtually all AJAX frameworks provide a means
to call
methods on the server using
asynch
ronous XML
-
HTTP requests. ASP.NET AJAX is no exception.

The primary
mechanism

for exposing callback methods to JavaScript clients in ASP.NET AJAX is the
ASMX Web method. (W
indows
C
ommunication
F
oundation

Web services will be
supported in a future releas
e
.)


To make an ASMX Web service accessible from ASP.NET AJAX clients, you first
attribute the Web service class with a
System.Web.Script.Services.ScriptService

attribute. (This attr
ibute can be applied in lieu

of or in addition to the traditional
WebService

attribute.)

Figure 2
-
12

shows the
C#
code
-
behind class for a simple Web
service
whose
lone
Web method

is

ca
llable from JavaScript
.



Figure 2
-
12
: Code
-
behind class for a Web service that’s callable from JavaScript

[
System.Web.Script.Services.
ScriptService]

public class ZipCodeService : System.Web.Services.WebService

{


[WebMethod]


public str
ing[] GetCityAndState
(string zip)


{


...


}

}



The next step is to add
a se
rvice reference
.

The service reference identifies the Web
service by URL a
nd
downloads
a JavaScript proxy
through which
the Web service

can
be called
. Service references can be created
declaratively using
the <Services>
element of a
ScriptManager

or
ScriptManagerProxy

control, as shown in Figure 2
-
13
.



Figure 2
-
13
: Declaring a
service reference

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


<Services>


<asp:ServiceReference Path="
~/
ZipCodeService.asmx" />


</Services>

</asp:ScriptManager
>



The JavaScript proxy generated by the service reference has the same name a
s

the
Web service
class
. Figure 2
-
14

demonstrates how an ASP
.NET AJAX
client can call the
GetCityAndState

method
shown in Figure 2
-
12 to convert a ZIP

code into a city and
state. Th
e call is asynchronous
, so the pa
rameter list on the client
always contains

at
least one more
parameter

than the p
arameter list on the server
. The extra parameter
is the name of the JavaScript function
that’s
called when the asynchronous callback
completes.





Figure 2
-
14
: Calling the
GetCityAndState method from JavaScript

ZipCode
Service.GetC
ityAndState("98052", onComplete
);


.
..

function onComplete

(result)

{


window.alert(result);

}



In practice, you’ll probably want to know if the callback

fails so you can respond
gracefully. Figure 2
-
15

demonstrates how to call
GetCityAndS
tate

and
specify

a
JavaScript
function

(
onFailed
)
that’s called if
the call fails

for example, if an
exception is thrown on the server

or the call times out
.



Figure 2
-
15
: Handling errors in Web service calls

ZipCodeService.GetCityAndState("98052", onComp
leted, onFailed);


.
..

function onCompleted (result, context, methodName)

{


window.alert(result);

}


function onFailed (err, context, methodName)

{


window.alert(err.get_message());

}



In traditional ASP.NET applications, Web service calls

use

XML

and SOAP.

Calls to Web
services from ASP.NET AJAX clients are very different.
By default, d
ata is encoded

in
J
SON (more on this in Section 2.6
)
, and the packet format is
a custom one that is much
lighter
-
weight

than SOAP. Moreover, none of the view state
and other form input that
travels to the server in a
normal

ASP.NET
postback is transmitted. The net result is
maximum efficiency on the wire and little wasted motion on either the client or
server.


Figure 2
-
16

shows the request and response packets gener
ated when
the
GetCityAndState

method is called through a JavaScript proxy

generated by ASP.NET
AJAX
.

The actual payload

the request and response bodies

contain JSON
-
encoded
input and output and nothing more. Clearly,
calling ASMX endpoints from ASP.NET
AJA
X clients is
b
oth
lightweight

and efficient
.



Figure 2
-
16
: Request and resp
onse generated by a
call

to GetCityAndState







2.4
.1

Web Service Extensions

Much of the magic

that underlies asynchronous XML
-
HTTP requests to ASMX endpoints
lie in the Web servi
ce extensions
included in the ASP.NET 2.0 AJAX Extensions
.

T
hese
ext
ensions
allow the requests to be handled on the server,
provide the JSON support
needed to serialize and deserialize parameters and return values
,
and generate the
JavaScript proxie
s
.


Whe
n you declare a service refe
rence like the one in Figure 2
-
13
,
the
ScriptManager

control emits the following markup:


<script src="ZipCodeService.asmx/js" type="text/javascript">

</script>


The browser

submits an HTTP request for

ZipCodeService.asmx/
js, an
d the server
responds by returning a JavaScript proxy. (You can see th
e

proxy by manually
submitting the same request yourself, or by including an
InlineScript
=”true” attribute
in the <asp:ServiceReferen
ce> tag and
then examining
the
resulting
source code
in
your browser.)


How does the server
know
how to handle
a
n ASMX

request with a
“/js” at the

end
?
Because of t
he following statements in the <httpHandlers> section of
the
Web.config

file of an ASP.NET AJAX Web site
, which map

all requests for ASMX resourc
es to an
ASP.NET 2.0 AJAX Extensions class named
ScriptHandlerFactory
:




<remove verb="*" path="*.asmx"/>

<add verb="*"

path="*.asmx" validate="false"


type="System.Web.Script
.Services.ScriptHandlerFactory, ...
"

/>


ScriptHandlerFactory

delegates “normal”
ASMX requests to the default ASMX handler
(
System.Web.Services.Protocols.WebServiceHandlerFactory
). But when it sees special
extensions such as “
/js” in the URL, it handles the requests

itself

or rather,
handles
them
by delegating to other classes in Syste
m.Web.Extensions.dll
, as shown in Figure
2
-
17
.

One of the key classes represented by the block labeled “Helper Classes” is
WebServiceClientProxyGenerator
, which generate
s

JavaScript proxies.



Figure 2
-
17
: ASMX request processing





N
otice the URL target
ed by the HTTP request

in Figure 2
-
16
:


/AtlasRC/ZipCo
deService.asmx/GetCityAndState


W
hen a
client places a
call to a
Web method through a JavaScript proxy,
the proxy
appends the
method
na
me to

the
URL.

The request

is

ul
timately processed
by the
RestHandl
er

class, which deseri
alizes the input parameters,
invokes the Web

method,
and returns the serialized output to the caller.


Although ASP.NET AJAX
currently

supports
only ASMX Web services
, support could be
added for other Web service platforms by extendin
g those platforms to support the
same
special
URL
semantics
as

ScriptHandlerFactory

and friends.



2.4
.2

The
ScriptMethod

Attribute

The
GetCityAndState

method in Figure 2
-
12

is
decorat
ed with the
WebMethod

attribute
used in virtually all ASMX Web services
. W
eb methods called from JavaScript
can altern
a
tively be
mark
ed with the
ASP.NET 2.0 AJAX Extensions’
System.Web.
Script.Services.ScriptMethod

attribute, which provides added control
over the format of the

data that passes over
the wire. Key properties of the

attribute
include
:




ResponseFormat
, which specifies whether output values should be serialized
into JSON (
ResponseFormat.Json
) or XML (
ResponseFormat.Xml
). The default is

ResponseFormat.Json
.




UseHttpGet
, which, if true,
generates JavaScript proxies that
invoke

script
methods using

HTTP GETs rather than HTTP POST
s
. The default is false.




XmlSerializeString
, which
, if true and if
the response format is
ResponseFormat.Xml
, serializes
all

values in the response, including strings,
into XML
. The default is fal
se.


The
ResponseFormat

property is particularly useful for serializing data types that
aren’t compatible with JSON into XML
, and with
methods that return
XML data
.

The
following Web method uses a
ScriptMethod

attribute to prevent an
XmlDocument

from
being

serialized into JSON:


[
ScriptMethod

(ResponseFormat=ResponseFormat.Xml
)
]

public
XmlDocument GetData(
)

{


...

}


Of course,
the
XML
must be parsed
on the client to extract data from it.

2.5

Page Methods

In addition to allowing conventional Web methods to

serve as targets for XML
-
HTTP
requests, ASP.NET AJAX also supports a special type of Web method known as
the
page
method
. Page methods are Web methods implemented in Web pages

that is, in ASPX
files or code
-
behind files rather than
in
ASMX files.

Page met
hods enable developers to
provide endpoints for XML
-
HTTP
callback
s without building dedicated Web services.


Page methods

must be public static m
ethods and must be decorat
ed with the
WebMeth
od

or
ScriptMethod

attribute
.

(
The latter performs the same functi
on for
page methods as it does for Web methods.
)

Figure 2
-
18

shows the
C#
code
-
behind class
for a page
that implements

the
GetCityAndState

method
from Figure 2
-
12
as a page
method
rather than

as
an ASMX Web method.



Figure 2
-
18
: Code
-
behind class containi
ng a page method

public partial class
My
Page : System.Web.UI.Page

{




[WebMethod]


public
static
string[] GetCityAndState(string zip)


{


...


}

}



On the client
, page methods are called
from JavaScript
through the special
PageMethods

prox
y
, as shown in Figure 2
-
19
. Page methods don’t require service
references as Web services do. That is, you don’t need to declare a service reference
in a
ScriptManager

(or
ScriptManagerProxy
) control to facilitate calls to page methods.

You do, however, ha
ve to enable page methods by setting a
ScriptManager

control’s
EnablePageMethods

property to true:


<asp:ScriptManager ID=
"
ScriptManager1
"

runat=
"
server
"


EnablePageMethods=
"
true
"

/>


Setting
EnablePageMethods

to true downloads the
PageMethods

proxy to th
e client. If
EnablePageMethods

is false,
PageMethods

is undefined on the client

even if the page
contains page methods
.



F
igure 2
-
19
: Calling a page method

from JavaScript

PageMethods
.GetCityAndState("98052", onCompleted, onFailed);


.
..

function onCompl
eted (result, context, methodName)

{


window.alert(result);

}


function onFailed (err, context, methodName)

{


window.alert(err.get_message());

}



Under the hood, page methods offer the same efficiency as Web methods.

View state
and other input
is

n
ot transmitted to the server when page methods are called, and
because page methods are static,
the
ASP.NET
2.0 AJAX Extensions
can call them
without
instantiating

a page object. A call to a page method does not
invoke
the page
life cycle that
is triggered

by conventional
ASP.NET

requests
.

2.6

JSON

ASP.NET AJAX clients that call Web methods and page methods aren’t limited to
passing strings and other pri
mitive data types
;
they can pass complex data types, too.

By default, ASP.NET AJAX serializes data passed

to and from Web methods and page
methods using the
industry
-
standard
JavaScript Object Notation (JSON) format.

JSON
is a lightweight data interchange format whose syntax is based on JavaScript itself. It


is
less verbose than XML (leading to greater effi
ci
ency on the wire) and
easier to parse
and deserialize,
thanks
in part
to
the JavaScript

eval

function.
In an ASP.NET AJAX

client, JSON
support is provided by the
Sys.Serialization.JavaScriptSerializer

class
. On

the server, it’s provided by
the
System.Web.S
cript.Serialization.
JavaScriptSerializer

class
.


Suppose a Web method or page method returns a
Point

object

an instance of the .NET
Framework’s
System.Drawing.Poin
t

type
.

Under the hood, the ASP.NET 2.0 AJAX
Extensions call
JavaScriptSerializer.Serialize

t
o serialize the
Point

object. If the
object’s
X

and
Y

properties are initialized to 100 and 200, respectively, here’s the
JS
ON representation of the object
passed

over the wire
to the caller:


{"IsEmpty":false,"X":100,"Y":200}


Had the
Point

object been se
rialized with the .NET Framework’s XML serializer
instead, it would have
been serialized
this

way
:


<?xml version="1.0"?>

<Point xmlns:xsi="http://www.w3.org/2001/XMLSchema
-
instance"


xmlns:xsd="http://www.w3.org/2001/XMLSchema">


<X>100</X>


<Y>200</Y>

</Point>


On the client, the
JSON
-
serialized
Point

object can be handled this way:


WebServiceName
.GetPoint(onComplete);


...

function onComplete(result)

{


// Displays "100, 200"


win
dow.alert(result.X + ', ' + result.Y);

}


T
he Microsoft AJAX Lib
rary’s
JavaScriptSerializer.deserialize

method turns the JSON
string representation of the object (
{"IsEmpty":false,"X":100,"Y":200}
) into a JavaScript
object. This is transparent to the developer
, who simply passes objects back and forth
in method calls a
nd relies on ASP.NET AJAX to serialize and deserialize them as
needed.


N
ot all types are
JSON
-
compatible
.
JSON does not, for example,
include
provision
s

for
handling circular references.

When you need to
return

complex
data
types that aren’t
JSON
-
compatib
le,
you can
use the
ScriptMethod

attribute with
the
response format
set to
ResponseFormat.Xml

to serialize the types into XML

as described in Section
2.4
.2.

Alternatively, you can build and register custom JSON
convert
ers that allow
types that aren’t norma
lly JSON
-
compatible to be serial
ized and deserialized
.

The
ASP.NET AJAX
January
Futures CTP contains three such converters: one for
DataSet
s,
one for
DataTable
s, and one for
DataRow
s.


ASP.NET AJAX’s JSON serializers provide special handling for one common

.NET data
type that isn’t handled natively by JSON:

System.DateTime
. The serialization format


used is specif
i
c to .NET and would require special handling to be used on other
platforms.

2.7

Built
-
In Web Services

ASP.NET AJAX includes two built
-
in Web servi
ce
s (and corresponding client

proxies)
that enable JavaScript clients to call
the ASP.NET 2.0

membership and profile services
on the server.

Together, these Web services form the application serv
ices bridge
depicted in Figure
1
-
2.

2.7
.1

AuthenticationServi
ce

Sys.S
ervices.AuthenticationService
, which is an instance of the
Sys.Services.
_
AuthenticationService

class defined in the Microsoft AJAX Library, is the
cli
ent
-
side proxy for the ASP.NET 2.0

membership service.

Sys.Services.AuthenticationService

methods
enable JavaScript clients to log users in
and out
(
login

and
logout
)
and determine whether they’
re currently logged in
(
get_isLoggedIn
)

by invoking the membership service on the server
.

The JavaScript
code in Figure 2
-
20

attempts to log in a user
by passin
g a
user name and password.
The
result

parameter passed to
onLoginCompleted

indicates whether the login
succeeded (that is, whether the supplied credentials were valid

and the user is
currently permitted to log in
). If the call itself fails

(rather than th
e login)
,
onLoginFailed

is called instead.



Figure
2
-
20
: Using
Sys.Services.AuthenticationService

to log in a user

Sys.Servi
ces.AuthenticationService.login
(username, password,


false, null, null, onLoginCompleted, onLoginFailed);


...

function onL
oginCompleted(result, context, methodName)

{


window.alert(result ? 'Login succeeded' : 'Login failed');

}


function onLoginFailed(err, context, methodName)

{


window.alert(err.get_message());

}



In order for this to work, the authentication mode mu
st be set to “Forms” on the
server. In addition, the ASP.NET AJAX Web service that front
-
ends the membership
service on the server must be enabled. (It is disabled by default). The following
configuration section enables the Web service:


<microsoft.web>



<scripting>


<webServices>


<authenticationService enabled="true"

/
>


</webServices>


</scripting>



</microsoft.web>


The <authenticat
ionService>
configuration
element also supports a Boolean
requireSSL

attribute that indicates whether calls to

the Web service must

travel
over encrypted
connections. The defaut is false. In practice,
requireSSL

should always be set to true
to prevent user names and passwords from being transmitted in plain

text
.

2.7
.2

ProfileService

A separate JavaScript proxy na
med
Sys.Services.
Profile
Service

(
an instance of the
Sys.Services.
_
Profile
Service

class defined in t
he Microsoft AJAX Library) provides a
client
-
side interface to

the ASP.NET 2.0

profile

service.

It enables JavaScript clients to
use the profile service to s
tore per
-
user data persistently. One
use for this feature

is
to
store personalization data in back
-
end databases on the server
(as oppos
ed to
storing
it

in cookies
, for example
).


Sys.Services.
Profile
Service

exposes two methods for loading and saving profi
le
property values:
load

and
save
.

It also exposes a property named
properties

through
which property values are accessed.
Figure 2
-
21

shows how to

load a profile property
named
ScreenName

f
or the current user; Figure 2
-
22

shows how to save it. The first
p
arameter passed to
load

and
save

is an ar
ray of profile property names. T
o load or
save several
property values
, simply
pass

an array containing all the property names.



Figure
2
-
21
: Reading profile properties from the client

Sys.Services.ProfileService.l
oad(['ScreenName'], onLoadCompleted,


onLoadFailed);


...

function onLoadCompleted(result, context, methodName)

{


window.alert


(Sys.Services.ProfileService.properties.ScreenName);

}


function onLoadFailed(err, context, methodName)

{



window.alert(err.get_message());

}




Figure
2
-
22
: Saving profile properties from the client

Sys.Services.ProfileService.properties.ScreenName = 'Bob';

Sys.Services.ProfileService.save(['ScreenName'], onSaveCompleted,


onSaveFailed);


...

function

onSaveCompleted(result, context, methodName)

{


window.alert('Save succeeded');

}




function onSaveFailed(err, context, methodName)

{


window.alert(err.get_message());

}



Profile properties must be defined on the server before they can

be accessed f
rom the
client
.
The following
configuration section
define
s

a profile containing a single
string
-
type
property named
ScreenName
:


<system.web>


<profile>


<properties>


<add name=
"
ScreenName
"

/>


</properties>


</profile>

</system.web>


Like t
he authentication Web service, the profile Web service must be enabled before
it can be used. The following
example shows how to

enable it and
expose the
ScreenName

property
to the client:


<microsoft.web>


<scripting>


<webServices>


<profileServ
ice enabled="true"


readAccessProperties="
ScreenName
"


writeAccessProperties="
ScreenName
"


/>


</webServices>


</scripting>

</microsoft.web>


Only properties identified using the
readAccessProperty

and
writeAccessProperty

attributes
can be read and written with
Sys.Services.
Profile
Service
, no matter how
many profile properties are defined.
To expose multiple profile properties to the
client,
pass

comma
-
delimited lists of property name
s

to
readAccessProperties

and
writeAccessProperties
.



3.0

The Microsoft AJAX Library

The Microsoft AJAX Library is the name given to the JavaScript
library
that makes up
the client half of ASP.NET AJAX. Written in 100% JavaScript, it extends JavaScript by
adding new functions, a JavaScript type system, sup
port for classes and namespaces
and other
features

of object
-
oriented programming (OOP), and a
n extensive

library of
classes that make JavaScript a richer and more productive
language

in which to work.
Moreover, it works in a variety of browser types, incl
uding Internet Explorer, Firefox,
and
Apple
Safari
.


The Microsoft AJAX Library is
independent of
server platforms. It can be used with or
without the ASP.NET 2.0 AJAX Extensions, and developers can easily build pages in
PHP, ColdFusion, and other
language
s
that emit JavaScr
ipt code that

leve
rage
s

the
Microsoft AJAX Library

just as pages built with the ASP.NET 2.0 AJAX Extensions do.


The Microsoft AJA
X Library
is
physically
packaged in
the

JavaScript
files listed in
Figure 3
-
1
.
The files come in
both debug

and release versions. T
he
release versions

are
stripped down to the bare essentials (even white space is remo
ved) to minimize
download size.
ASP.NET developers use
ScriptManager

and
ScriptManagerProxy

controls to download these files to the clie
nt. Howeve
r, developers who want

to use
the Microsoft AJAX Library with other platforms can
use

<script>
element
s to download
the files.



Figure 3
-
1
:
Core
Microsoft AJAX Library JavaScript files

File

Description

MicrosoftAjax.js

Type system,
base type extensions,
networking classes,
and other
core infrastructure

MicrosoftAjaxTimer.js

_
Timer

class

implementing client
-
side
programmable
timer

MicrosoftAjaxWebForms.js

PageRequestManager

and other classes that sup
port
partial
-
page

rendering



The Microsoft AJAX Li
bra
ry is factored into
individual
files for download granularity. By
default, MicrosoftAjax.js is the only file downloaded. The uncompressed size of the
release ve
rsion is 79
K, and after the file is GZIPped
, the size drops to approximately
15K

on the wire
. Pa
ges that use
UpdatePanel

controls also download
MicrosoftAjaxWebForms.js,
which adds

another
5K or so to the compressed download.
Browsers cache JavaScript files, so between the compactness of the compressed files
and the fact that they
aren’t
downloaded v
ery often, users shouldn’t
notice

the
downloads and in fact probably won’t be aware that the
files were downloaded
.


The ASP.NET AJAX January Futures CTP extends the Microsoft AJAX Library with the
JavaScript files listed in Figure 3
-
2. These files aren’t
required if you only use the core
features of ASP.NET AJAX, but they add to the platform a variety of useful features
including support for animations and drag
-
and
-
drop operations.





Figure 3
-
2: January Futures CTP JavaScript files

File

Description

Previe
wScript.js

Extensive library of classes (including control classes)

PreviewGlitz.js

Animation classes and other classes for building
“glitzy” UIs

PreviewDragDrop.js

_DragDropManager

and other classes that support drag
-
and
-
drop operations

PreviewWebParts
.js

AJAX support for ASP.NET Web parts



The sections that follow
document the content and structure of the Microsoft AJAX
Library
(including
some of
the features added by the January Futures CTP)
and provide
helpful guidance to developers
who are interes
ted

in
understand
ing

and
extend
ing

it.

3.1

JavaScript
Base Type
Extensions

To make JavaScript easier to work with, the Microsoft AJAX Library add
s new functions
to the JavaScript
Array
,
Boolean
,
Date
,
Error
,
Number
,
Object
, and
String

data types.
These ext
ensions are implemented in MicrosoftAjax.js and are documented at
http://ajax.asp.net/docs/ClientReference/Global/JavascriptTypeExtensions/default.a
spx
. Fig
ure 3
-
3

provides a brief summary

of
the function
s

that are
added.



Figure 3
-
3
: JavaScript base type extensions

Type

Functions Added

Array

a
dd
,
addRange
,
clear
,
clone
,
contains
,

d
equeue
,
enqueue
,
forEach
,
indexOf
,
insert
,
parse
,
remove
,
removeAt

Boolean

p
arse

Date

f
ormat
,
localeFormat
,
p
arse
Locale
,
parse
Invariant

Error

a
rgument
,
argumentNull
,
argumentOutOfRange
,
argumentType
,
argumentUndefined
,
create
,
format
,
invalidOperation
,
notImplemented
,
parameterCount
,
popStackFrame

Number

f
ormat
,
localeFormat
,
p
arse
Locale
,
parse
Invariant

Object

getType
,
getTypeName

String

endsWith
,
format
,
localeFormat
,
startsWith
,
trim
,
trimEnd
,
trimStart



Here’s a q
uick example of the base type extensions
in use:


var s = String.format ('{0}, {1}, and {2}', 1, 2, 3);

windo
w.alert (s);

// Displays
"
1, 2, and 3
"


This example uses the
String
.
format

function, which is similar to the .NET
Framework’s
String
.
Format

method, to build a string without using concatenation
operators.

3.2

Global Functions

and Variables

In addition to
enhancing JavaScript base types, the Microsoft AJAX Library

defines
several global functions and variables designed to make programming
and debugging


easier

(and for use
elsewhere in
the Microsoft AJAX Library)
. Figure 3
-
4

list
s the global
functions; docum
entation
regarding them
can

be found at
http://ajax.asp.net/docs/ClientReference/Global/default.aspx
.
Look through the
Microsoft AJAX Library so
urce code and you’ll see
these functi
ons used extensively.



Figure 3
-
4
:

Global functions defined in

the Microsoft AJAX Library

Function

Description

$addHandler

Registers a handler for a DOM event

$addHandlers

Registers
handlers for DOM events

$clearHandlers

Un
registers handlers for DOM ev
ents

$removeHandler

Un
registers a handler for a DOM event

$create

Creates an initializes a component

$find

Returns a reference to the specified component

$get

Returns a reference to the specified DOM element (e
quivalent
to

document.getElementById
)



T
he Microsoft AJAX Library
defines several global variables that provide
easy

access
from anywhere
to parts of its own infras
tructure. Among them are
Sys.Application
,
which represents the application and refers to an instance of
Sys._Application
;
Sys.Servi
ces.AuthenticationService
, which provides access to the ASP.NET 2.0
membership s
ervice on the server (
see
Section 2.7
.1
); and
Sys.Services.ProfileService
,
which provides access to the ASP.NET 2.0 profile s
ervice on the server (
see
Section
2.7
.2
).


The Micr
osoft AJAX Library also creates an instance of its own
Sys._Debug

class and
assigns a reference to it to
the global variable
Sys.Debug
.
Sys._Debug

contains useful
methods to assist in debugging, including
assert
,
fail
,
trace
, and
traceDump
,
faci
litating
Ja
vaScript code like the following:


// Assert

var happy = false;

Sys.D
ebug.assert(happy == true, 'happy is NOT true', false);


// Break into the debugger

Sys.D
ebug.fail('Somebody is NOT happy');

3.3

JavaScript Type System (Adding OOP to JavaScript)

JavaScri
pt is an object
-
based language, but

not an object
-
oriented
one
.

It
has

no
intrinsic support for classes, namespaces, inheritance,
or

other features
found in
object
-
oriented languages such as C++ and C#.


The Microsoft AJAX Library changes that by adding OO
P to JavaScript. At least it
creates the
illusion

of OOP; in truth, all it’s doing is making creative use of JavaScript
to make it seem as if you can define classes, namespaces, interfaces, and so on. But
the illusion is an effective one, and it is the fou
ndation for the types featured in the
Script Core Library and the Base Class Library discussed in the next two sections.




To make JavaScript seem more like an object
-
oriented programming
language
, the
Microsoft AJAX Library exploits the fact that JavaScrip
t allows functions to be treated
as data types

and
instantiated with the
new

operator. It also uses the
prototype

property introduced in JavaScript 1.1 to
make functions feel more like classes and to
enact the JavaScript equivalent of inheritance.


As an

e
xample, the code in Figure 3
-
5

implements a JavaScript

class


named
Point
.

The
Point

function
acts as

a constructor
, and the statements inside the function
declare and initialize what are essentially instance fields named
_x

and
_y
.

Point.prototype

is the
n used to define
get_x

and
get_y

methods that are
included

in
all instances of
Point
.

This class implementation makes the following JavaScript code
perfectly legal:


p = new Point(100, 200);

alert(p.get_x() + ", " + p.get_y());

//
Displays
"
100, 200
"


Puri
sts might argue that this isn’t really OOP, but it certainly feels like OOP.

And it’s
very similar to the
pattern

that the Microsoft AJAX Library
uses to
impleme
nt

classes.



Figure 3
-
5
: JavaScript Point class

Point = function(x, y)

{


this._x = x;


this._y = y;

}


Point.prototype =

{


get_x: function() { return this._x; },


get_y: function() { return this._y; }

}



Of course, most OOP programming languages support more than just classes; they also
support namespaces, interfaces, base classes an
d derived classes, and the like. Some
even support type reflection so that information about types can be discovered at run
-
time.


Enter the second ingredient in the Microsoft AJAX Library’s recipe for adding OOP to
JavaScript: the
Type

class. Among other
things, the
Type

class
implements

methods
for registering classes and namespaces so they can be reflected on at run
-
time. Its
registerClass

method makes a class elig
ible for run
-
time discovery and
allows the
registrar to specify a base class.
Furthermore,
Type

define
s an
initializeBase

method
that a “derived” class can call in its constructor to initialize the base class
, as well as

a
callBaseMethod

for invoking

method
s

in the base class
. You can read all about
Type

at
http://ajax.asp.net/docs/ClientReference/Global/TypeClass/default.aspx

and view
its source code in MicrosoftAjax.js. It is arguably the most important class in the entire
client
framework
.




An example w
ill hel
p
paint a picture of how
Type

is combined with functi
ons and
prototypes to add
OOP
-
like
behavior to
JavaS
cript
.

The JavaScript
in Figure 3
-
6

uses
Type.registerNamespace

to register a n
a
m
espace named
Custom
.

Then it adds a class
named
Person

to the namespac
e.
At the end, a call to the
registerClass

method added
to the
Person

class
through

Type.prototype

registers the
Person

class with the
Microsoft AJAX Library.



Figu
re 3
-
6
: Implementing a Person class

Type.registerNamespace("Custom");



Custom.Person =
function(name)

{


this._name = name;

}


Custom.Person.prototype =

{


get_name: function()

{

return this._name;

}

}


Custom.Person.registerClass('Custom.Person');



Once the
Person

class is defined in this manner, it can be exercised with the followin
g
JavaScript code:


var p = new Custom.Person('Jeff');


// Displays "Jeff"

window.alert(p.get_name());


// Displays "Custom.Person"

window.alert(Object.getTypeName(p));


Note the use of
Object.
getTypeName
, which is

one of the JavaScript base type
extension
s mentioned in Section 3.1.


What if you wanted to derive from
Person

to

create a
Programmer

class?
Type

helps
make that possible
, too.

Figure 3
-
7

shows how such a class might be implemented.
Note the call to
initializeBase

in the constructor, and the base

class (
Custom.Person
)
specified in
the
registerClass

method
’s second parameter. Also note the
call to

callBaseMethod

in
get_name

to invoke the same method in the base class.



Figu
re 3
-
7
: Deriving from the Person class

Custom.Progra
mmer = function(name, l
anguage)

{


Custom.Programmer.initializeBase(this, [name]);


this._language = language;



}



Custom.Programmer.prototype =

{


get_name: function()


{


var name =

Custom.Programmer.callBaseMethod

(this,


'get_name');


return name + ' (Programmer)';


},



get_language: function()


{


return this._language;


}

}


Custom.Programmer.registerClass

('Custom.Programmer',


Custom.Person);



The following JavaScript code
creates

a
Programmer

object and
puts it through its
paces:


var p = new Custom.Programmer('Jeff', 'C#');


// Displays "Jeff (Programmer)"

window.alert(p.get_name());


// Displays "C#"

window.alert(p.get_language());


// Displays "Wintellect.Programmer"

window.alert(Object.getTypeName(p))
;


Everything behaves as you would expect, including the call to
Object.getTypeName
,
which returns the name of the derived class rather than
of
the base class.

3.4

Script Core Library

MicrosoftAjax.js contains the Script Core Library
, which forms the nucleus

o
f the
Microsoft AJAX Library.

This is where the JavaScript base type extensions described in
Section 3.1, the global functions discussed in Section 3.2, and the
Type

class described
in the Section 3.3 are implemented.

It’s also where the core networking in
frastructure
used to perform asynchronous

callbacks to servers and serialize and deserialize JSON
data is located.

In short, the Script Core Library contains everything that the rest of
the Microsoft AJAX Library
has to have
in order
to run.


The Script Co
re Library implements approximately 25 classes grouped
into the five

namespaces listed in Figure 3
-
8
.

Some, like
StringBuilder
, are utility classes. Others,
such as
JavaScriptSerializer

and
WebRequest
, are
fundamental to the operation of
the


ASP.NET AJAX

f
ramework
.
The following code uses
Sys.Net.WebRequest

to launch an
asynchronous XML
-
HTTP request and
resembles
plumbing deep inside the Microsoft
AJAX Library that
does the same
:


var request = new Sys.Net.WebRequest();

request.set_url("AjaxDemo.aspx?mode=c
allback");

request.add_completed


(Function.createDelegate(this,

onCallbackCompleted));

request.invoke();


...

function onCallbackCompleted(response, args)

{


if (response.get_statusCode() == 200)


window.alert(response.get_responseData());

}


Under the hood,
WebRequest
.invoke

delegates to
WebRequestManager.executeRequest
, which in turn
delegates to an “executor.”

The
default executor is
Sys.Net.XMLHttpExecutor
, whose
own
executeRequest

method

is
the launch pad for asynchronous XML
-
HTTP reques
ts in ASP.NET AJAX.



Figure 3
-
8
:
Key
Script Core Library
c
lasses and n
amespaces

Namespace

Key

Classes

Sys

StringBuilder
,
Component
,
CultureInfo
,
_
Application
, _
Debug

Sys.UI

DomEvent
,
DomElement
,
Behavior
,
Control

Sys.Net

_
WebRequestManager
,
WebRequestE
xecutor
,
WebRequest
,
XMLHttpExecutor

Sys.Serialization

JavaScriptSerializer

Sys.Services

_
AuthenticationService
, _
ProfileService
,
ProfileGroup



3.5

Base Class Library

The Script Core Library is supplemented by a larger and richer set of JavaScript classes
that comprise
the Base Class Library, or BCL. The majority of the roughly 100 classes
in the BCL
are

implemented in

PreviewScript.js, but some
live in PreviewGlitz.js
,

PreviewDragDrop.js
, and MicrosoftAjaxWebForms.js
.

A
s such, most of the BCL is

available

only
if you insta
ll the ASP.NET AJAX Futures CTP

the only exception being
the classes in MicrosoftAjaxWebForms.js.


Figure 3
-
9

lists some of the key classes and namespaces in the
BCL
.

One of the most
important is the
PageRequestManager

class, which is the

client half of the
UpdatePanel

control and is discussed in greater detail in the next section.

The classes
in the
Sys.Preview.UI

namespace (and its chi
ldren)
abstract

HTML DOM elements

and
open the door to

animations, transparencies, drag
-
and
-
drop, clie
nt
-
side rendering of
server
data
, and other visual effects. A handful of these capabilities are
accessible
through

server controls (for example,
the
DragOverlayExtender

control
emits code
that
wraps
instances of
Sys.Preview.UI.FloatingBehavior

around DOM ele
ments
)
, but in


general, you have to
write JavaScript that runs on the client
to tap
into the full power
of
Sys.Preview.UI
. S
ome of its features can
, however,

be leveraged
using
ser
ver
controls

in
the
ASP.NET AJAX Control Toolkit.



Figure 3
-
9
: Key Base Cla
ss Library classes and namespaces

Namespace

Key

Classes

Sys
.Preview

Binding
,
Action
,
InvokeMethodAction
,
SetPropertyAction
,
Counter
,
Timer

Sys.Preview.Data

DataColumn
,
DataRow
,
DataTable
,
DataView
,
DataSource

Sys.
Preview.UI

Button
,
CheckBox
,
HyperLink
,
Image
,
Label
,
Selector
,
TextBox
, _DragDropManager,
FloatingBehavior, DragDropList

Sys.
Preview.UI.Data

ListView
,
ItemView
,
DataControl

Sys.
Preview.UI.Effects

OpacityBehavior
,
LayoutBehavior
,
Animation

Sys.WebForms

PageRequestManager



To h
ave some fun w
ith the BCL

(and see what it’s like to program it directly), try
inserting the following <script> block into an ASP.NET AJAX page
that contains

a
n

image

whose ID is “SplashImage”
:


<script type="text/javascript">

function pageLoad()

{


var image = new S
ys.Preview.UI.Image ($get('SplashImage'));


var fade = new Sys.Preview.UI.Effects.FadeAnimation();


fade.set_target(image);


fade.set_effect (Sys.Preview.UI.Effects.FadeEffect.FadeIn);


fade.set_duration(3);


fade.set_fps(20);


fade.play(
);

}

</script>


For this code sample to work, you’ll need

to download

PreviewGlitz.js

to the page
.
Here’s how to download it with
a
ScriptManager

(or
ScriptManagerProxy
) control
:


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


<Scripts>


<asp:
ScriptReference Name="PreviewGlitz.js"


Assembly="System.Web.Preview" />


</Scripts>

</asp:ScriptManager>


Now display
the page
in your browser and
watch the image
.




S
ections
3.6 and 3.7

provide additional information
about
selected
BCL

classes. The
ASP.NET AJAX Web site contains a detailed reference to

them all at
http://ajax.asp.net/docs/ClientReference/default.aspx
.

3.6

PageRequestManager

One
BCL
class

that deserves special mention

is

Sys.WebForms.PageRequestManager
,
which is implemented in MicrosoftAjaxWebFo
rms.js and provides client
support for
partial
-
page

rendering.
The
UpdatePanel

control
facilitates partial
-
page

rendering on
the server, but
the
PageRequestManager

class
, which
is the client
-
side counterpart to
UpdatePanel
,
facilitates

it on the client.


When you
set
EnablePartialRendering

to true in a
ScriptManager

control
,
ScriptManager

emits markup that creates and initializes a
PageRequestManager

object.

PageRequestManager

ma
nages the asynchronous callbacks transmitted to the
server to update
UpdatePanel

control
s
, and

it provides the logic on the client that
replaces the old content in an
UpdatePanel

control
with fresh content after
an
update.


PageRequestManager

also exposes
a JavaScript API. Methods such as
abortPostBack

enable asynchronous upda
tes to be canceled in progress, while
getInstance

retrieves a
reference to the page’s
PageRequestManager

object
. (F
or an example

in which both
methods are used
, refer to

Figure
2
-
8.)

P
ageRequestManager

also
rais
es life
-
cycle
events
i
n the
b
rowser that

indicate

when upda
tes have occurred or are about to occur
.

Arguably the most important of these events is
pageLoaded
, which fires each time the
page is refreshed following an asynchronous
callback or a synchronous postback.


Normally,
PageRequestManager

works quietly behind the scenes
in support of

UpdatePanel

controls
, and most developers don’t even realize it’s there
. But o
ne very
practical reason to program

PageRequestManager

directly
is

to
implement “update
highlighting.” Because
UpdatePanel

updates are clean and flicker
-
free, some Microsoft
customers have requested a means for highlighting
UpdatePanel

control
s that have
undergone
updates
in order to draw the user’s attention to the
upda
ted

content.


Figure 3
-
10

shows one way to implement such a feature. When the page loads,
JavaScript
code registers an event handler
for
PageRequestManager
’s
pageLoaded

event
. The
args

parameter passed to the event

handler is a
P
ageLoadedEventArgs

object
,
which has
a
get_panelsUpdated

method
that identifies

the

UpdatePane
l

contro
l
s

that

were just updated.

The event handler enumerates updated
UpdatePanel

control
s and calls a local helper function named
flashPanels

to flash each
UpdatePanel

on and off three t
imes.



Figure 3
-
10
: Highlighting updated
UpdatePanel

controls

<script type="text/javascript">


var prm = Sys.WebForms.PageRequestManager.getInstance();

prm.add_pageLoaded(pageLoaded);


var _panels, _count;




function pageLoaded(sender, args)

{


if (_pan
els != undefined && _panels.length > 0)


{


for (i=0; i < _panels.length; i++)


_panels[i].dispose();


}



var panels = args.get_panelsUpdated();



if (panels.length > 0)


{


_panels = new Array(panels.length);




for (i=0; i < panels.length; i++)


_panels[i] = new Sys.UI.Control(panels[i]);



flashPanels(3);


}

}


function flashPanels(count)

{


_count = (count << 1) + 1;




for (i=0; i < _panels.length; i++)


_panels[i
].set_visible(false);



window.setTimeout(toggleVisibility, 50);

}


function toggleVisibility()

{


for (i=0; i < _panels.length; i++)


_panels[i].set_visible(!_panels[i].get_visible());




if (
--
_count > 0)


window.setTimeout
(toggleVisibility, 50);

}

</script>



3.
7

HTML
Controls

Among
the many classes in the
Microsoft AJAX Libr
ary BCL are the control classes
found in the
Sys.Preview.UI

namespace.
These classes wrap HTML elements such as
<input> and <select>. They

are implemen
ted in PreviewScript.js and
are therefore
available
only
if you elect to use the ASP.NET AJAX Futures CTP.


Figure 3
-
11

lists some of
the control classes featured in PreviewScript.js
.

Not shown
are validator controls such as
RequiredFieldValidator

and
Rege
xValidator
, which serve


the same purpose in Microso
ft AJAX Library applications that

ASP.NET validator
co
ntrols
do
in ASP.NET applications. Remember also that the Microsoft AJAX Library
includes a
Sys.Preview.UI.Data

namespace

featuring a very rich set of
data controls
with names
such as
ListView

and
ItemView
. Though beyond the scope this document,
the data controls enable client
-
side data binding to data sources on the server in the
same way that
GridView
,
DetailsView
, and other ASP.NET server controls
fac
ilitate
rich
server
-
side data binding.



Figure 3
-
11
: HTML control classes in PreviewScript.js

Class

Description

Button

HTML button controls (e.g., <input type=“button”>

elements)

CheckBox

HTML check box controls (e.g., <input type=“checkbox”>

elements
)

HyperLink

HTML hyperlinks (
e.g.,
<a> elements)

Image

HTML images (<img> elements)

Label

HTML label controls (<span> elements)

Selector

HTML selector controls (<select> elements)

TextBox

HTML text box controls (e.g., <input type=“text”>

elements
)



Al
l the classes in Figure 3
-
11

derive
either directly or indirectly
the

Sys.UI.Control

class f
ound

in the Sc
ript Core Library. A
s such
, they

inherit a common set of features
.
Among those features are
get_visible

and
set_visible

methods for controlling visibi
lity
in a browser
-
independent

way
, a
get_element

method for accessing

underlying DOM
e
lement
s
, and the ability to bubble DOM
events.


Figure 3
-
12

contains
selected portions

of a DHTML page
that implement
s

an interactive
UI driv
en entirely from the client
.
The UI consists

of a text box, a button, and an
empty <span> element.

When the button is clicked, the
onClick

function uses the
browser DOM to
read

the contents

of

the t
ext box and display

it
to the right of the
button
by
assign
ing it to
the
<span> element
’s
innerHTML

property
.

As a result,
what
the user types into the text

box is echoed to the page
when
the
button is clicked
.



Figure 3
-
12
: Simple
DHTML

page

<input type="text" id="Input" />&nbsp;

<input type="button" id="
My
Button" value="Click Me"


onclic
k="on
Click();" />&nbsp;

<span id="Output" />


<script type="text/javascript">

function on
Click()

{


document.getEl
ementById('Output').innerHTML =


document.getElementById('Input').value;

}

</script>





Figure 3
-
13

contains the e
quivalent page writ
ten with
Microsoft AJAX Library HTML
controls.
The JavaScript
code
contains a
pageLoad

function that wraps
TextBox
,
Button
, and
Label

controls around the
corresponding

DOM elements
. It also
registers a
h
andler for
the
B
utton

control
’s
click

ev
ents.
(If pre
s
ent in an ASP.NET AJAX Web
page
,
a
pageLoad

function
is automatically called after the page loads and the library
is initialized.)
The handler echoes the user’s input to the page by reading it from the
TextBox

control and writing it to the
Label

control.

Note

that the
JavaScript code
never accesses the
browser DOM directly; instead,
it accesses it indirectly by
interacting with the controls
that wrap

th
e
DOM
elements.



Figure 3
-
13
: Using

the HTML control classes

from JavaScript

<input type="text" id="Inpu
t" />&nbsp;

<input type="button" id="MyButton" value="Click Me" />&nbsp;

<span id="Output" />


<script type="text/javascript">

var g_textBox;

var g_label;


function pageLoad()

{


g_textBox = new Sys.Preview.UI.TextBox($get('Input'));


var button = n
ew Sys.Preview.UI.Button($get('MyButton'));


g_label = new Sys.Preview.UI.Label($get('Output'));


button.initialize();


button.add_click(onClick);

}


function onClick()

{


g_label.set_text(g_textBox.get_text());

}

</script>



Are there advantag
es to writing JavaScript his way? Yes

in fact, there are two. One,
the same code works not just in Internet Explorer, but in Firefox and Safar
i and all the
other browser
s that ASP.NET AJAX suppo
rts. Rather than devote
time to testing and
tweaking the code
to work in

different browsers, you can let Microsoft sweat thos
e
details for you. Two, the
control classes simplify certain tasks involving HTML controls.
Rather than iterate through the items in a <select> element to find the one you wish
to select, for e
xample, you can call
Selector.
set_selectedValue

to select
the

item.

3.8

xml
-
s
cript

The Microsoft AJAX Library can be programmed impe
ratively using JavaScript. I
t can
also be programmed
declaratively

using a language known as
xml
-
script
.




S
upport
for xml
-
sc
ript
is
found
in
PreviewScript.js, which is part of
the ASP.NET AJ
AX
Futures CTP
.
xml
-
script

played a huge role
in pre
-
B
eta releases of ASP.NET AJAX, then
known by the code name “Atlas.” (In early releases, ASP.NET AJ
AX server controls
rendered xml
-
script
instead of JavaScript.) Its role is greatly diminished today, and in
fact it doesn’t have to be used at all. But certain tasks in the Microsoft AJAX Library

especially
one
s that involve
templated controls

such as
Sys.Preview.UI.Data.ListView

are implemente
d mo
re easily in
xml
-
script than in
JavaScript.

Therefore,
xml
-
script is
a feature that ASP.NET AJAX developers should at least be aware of, whether they
choose to use it or not.


Figure 3
-
14

shows the xml
-
script version of the page in
Figure 3
-
13
. The pag
es are
identical on the outside,
but
very different

on the inside
.

Elements such as <t
extBox>
and <button> in xml
-
script
declare instances of
TextBox

and
Button

controls and link
them to DOM elements.

The <click> element inside the <button> element registe
rs a
handler for
click

events, and the <invokeMethodAction> element inside the <click>
element invokes a method named
evaluateIn

on an object named “TextBinding” when
a
click

event is raised
. What is “TextBinding?” It’s a
Binding

object

(an instance of
Sys
tem.Preview.Binding
)

create
d with a <binding> element. It
binds the
text

property
of the
TextBox

control to the
text

property of the
Label

control. When the binding is
evaluated (that is, when its
evaluateIn

method is called), the contents of the
TextBox

c
ontrol
are copied to the
Label

control
.



Figure 3
-
14
:
Using the HTML control classes from
xml
-
script

<input type="text" id="Input" />&nbsp;

<input type="button" id="MyButton" value="Click Me" />&nbsp;

<span id="Output" />



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


<page


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


<components>



<textBox id="Input" />


<button id="MyButton">


<click>


<invokeMe
thodAction target="TextBinding"


method="evaluateIn" /
>


</click>


</button>


<label id="Output">


<bindings>


<binding id="TextBinding" dataContext="Input"


dataPath="text" property="text" automatic="false" />


</bindings>


</label>


</components>


</page>

</script>





This is a very different
way
of exercising the Microsoft AJAX Library, and the jury is
stil
l out on what role, if any,

xml
-
script
will play in future versions of ASP.NET AJAX.
On the negative side, there are currently no tools to suppor
t it (no
special
editors or
Int
elliSense engines, for example). I
t imposes extra overhead on the client due to XML
parsing,
it’s difficult to debug,
and there’s precious li
ttle documentation describing

it.

On the positive side, with the p
roper tool support
, writing xml
-
script could be easier
than wri
ting JavaScript, and an XML scripting language brings to mind some enticing
possibilities involving XAML.



4.0

Summary

AJAX has gained widespread popularity in recent years as a means for making Web
applications ric
her and more interactive

in short, to make them feel less like Web
applications and m
ore like rich client
s.

ASP.NET AJAX is an AJAX framework that
abstracts and simplifies AJAX. With it, developers who know little about JavaScript,
XML
-
HTTP, and other pill
ars of AJAX can write AJAX
-
enabled applications and get
them to market in a timely fashion.


ASP.NET AJAX shortens the development cycle by providing high
-
level AJAX wrappers
such as
UpdatePanel

controls on the server and a rich library of JavaScript types and
extensions on the client. The server half of the platform, the ASP.NET 2.0 AJAX
Extensions, transform
s

ASP.NET 2.0 into a great platform for AJAX applications. The
client half, the Microsof
t AJAX Library, makes browsers a richer and more productive
environment in which to work and offer
s

not only browser independence, but
independence from the server platform as well.