Web ADF JavaScript Library

In this topic

About the Web ADF JavaScript Library

The Web Application Developer Framework (ADF) includes a set of JavaScript libraries (the Web ADF JavaScript Library) that supports and enhances the use of server-side Web ADF components in a browser. Asynchronous JavaScript and XML (AJAX) capabilities and client-server synchronization in the Web ADF are dependent on Web ADF JavaScript logic. 

Microsoft AJAX Library

Web ADF JavaScript Library capabilities are built on the Microsoft AJAX (JavaScript) Library. The Microsoft AJAX Library provides a comprehensive foundation on which to build AJAX-enabled solutions. This library manages interaction with remote services and server-based Web controls using well known partial postback and callback AJAX patterns. The Microsoft AJAX Library provides a mechanism for representing Web controls on the client (script controls) and for handling events in the browser. In addition, this library is for cross-browser support. These capabilities are leveraged in the Web ADF JavaScript Library. The following illustration shows these capabilities:
Documentation for the ASP.NET AJAX Library is provided by Microsoft as part of the AJAX client reference materials.

Browser-based technology

From the Web ADF developer perspective, the Web ADF JavaScript Library provides access to Web ADF capabilities using pure browser technology in a scripting environment. This means that you can use JavaScript to interact with .NET Web ADF server controls and capabilities, such as navigating a map, adding graphics to a map, or creating MapTips, without requiring any server-side code.
Changing the state of a Web ADF control via JavaScript is synchronized on both the client and server. Some Web ADF JavaScript objects are only persisted in browser memory, such as graphics that have no server-side representation. In any case, the Web ADF JavaScript Library provides a Web ADF developer with another tool to leverage when creating and enhancing a Web application. The Web ADF JavaScript Library is not designed to replace server-side programming or to be used on its own, without server-side controls.
The Web ADF JavaScript Library is different from the ArcGIS JavaScript application programming interfaces (APIs) that are for pure JavaScript applications. The Web ADF JavaScript Library is packaged with the Web ADF and is solely for use with Web ADF components and solutions. ArcGIS JavaScript APIs are not for use with the Web ADF.
The Web ADF JavaScript Library consists of JavaScript files embedded with Web ADF controls to support browser-based scriptable interaction with the controls. The JavaScript files are not installed on disk and cannot be modified. Rather, they provide components you can use and extend via custom JavaScript that you add to a page. As with the Web ADF server-side .NET components and classes, the Web ADF JavaScript Library includes namespaces and classes, and JavaScript objects, with which to interact at run time.
Adding a Web ADF control to a page also adds the libraries that constitute the Web ADF JavaScript Library with the page at run time. However, the developer experience is different than traditional .NET development in Visual Studio. Common Visual Studio capabilities used by .NET developers to enhance the code writing experience, such as IntelliSense, code completion, or integrated Help, are not available when coding JavaScript. In addition, JavaScript is an interpreted language (interpreted at run time by the browser), so preventing errors at compile time is not possible.
The Web ADF JavaScript Library can be utilized in the following areas:
As a client-side JavaScript API, the Web ADF JavaScript Library includes an object model diagram (OMD) and library reference within this Help system.

ASP.NET AJAX JavaScript Library

The ASP.NET AJAX JavaScript Library defines patterns for JavaScript object definitions, classes that support application interaction and Web request content, and convenient functions for common operations. It is important to understand some of these patterns, classes, and functions before starting work with the Web ADF JavaScript Library. 
Regardless of the AJAX pattern that is used on the server (callback or partial postback), the Web ADF JavaScript Library uses the ASP.NET AJAX JavaScript Library on the client browser.

Global shortcut functions

To find the script representation of a Web ADF control and work with it via JavaScript in the browser, ASP.NET AJAX provides the following global shortcut functions for common tasks:
  • $addHandler
  • $addHandlers
  • $clearHandlers
  • $create
  • $find
  • $get
  • $removeHandler
The $find function returns a reference to the JavaScript component. The $get function returns the element. Both use the client ID of a component or element to locate it on the page. You need a reference to the Web ADF JavaScript component to utilize it via client-side code. Since you know the client ID of the Web ADF control at run time, you can use the $find function to return a Web ADF JavaScript component as shown in the following code example:
[JavaScript] 
var map = $find('Map1');

JavaScript objects

You can explicitly create JavaScript objects using the constructor method (new) or the $create function. ASP.NET AJAX provides the $create function as a shortcut for performing several initialization steps in a single statement. Specifically, a call to $create does the following: 
  • Registers the JavaScript object as an AJAX component, enabling it to be retrieved later via the $find shortcut method. Otherwise, such registration requires explicitly setting the object's ID and passing the object to the global static Sys.Application.addComponent function.
  • Initialize properties. At a minimum, the id property must be specified.
  • Wire event handlers (optional).
Creating a JavaScript object using new requires a call to the class constructor, which can define a set of input parameters. Properties and event handlers must then be explicitly initialized in subsequent statements. 
The following code example shows both techniques for creating and configuring a new Web ADF ESRI.ADF.Graphics.GraphicFeatureGroup JavaScript object with the same properties and behavior. A GraphicFeatureGroup is used to store and render graphics (GraphicFeatures).
The following code example shows how to create a JavaScript object using the constructor:
[JavaScript] 
var geomGroup = new ESRI.ADF.Graphics.GraphicFeatureGroup(
    "customGraphicFeatureGroup1", symbol);
geomGroup.set_highlightSymbol(highlightSymb);
geomGroup.add_mouseOver(onMouseOverGfx);
geomGroup.add_mouseOut(onMouseOutGfx);
Sys.Application.addComponent(geomGroup);
The following code example shows how to create a JavaScript object using the $create function:
[JavaScript] 
var geomGroup = $create(ESRI.ADF.Graphics.GraphicFeatureGroup, {
    "id": "customGraphicFeatureGroup1", "symbol": symbol, "highlightSymbol":
        highlightSymb
}

, {
    "mouseOver": onMouseOverGfx, "mouseOut": onMouseOutGfx
}

);

Sys.UI.DomElement getBounds Method

To determine the size and location of a Hypertext Markup Language (HTML) element or component in the browser at run time, use the Sys.UI.DomElement getBounds method. It returns an associative array containing the height, width, and x,y location of the upper left corner of the element. This process is shown in the following code example:
[JavaScript] 
var bounds = Sys.UI.DomElement.getBounds($get('Map1'));

Sys.UI.DomElement setLocation Method

To move an element at run time, use the Sys.UI.DomElement setLocation method as shown in the following code example:
[JavaScript] 
var bounds = Sys.UI.DomElement.getBounds($get('Map1'));
Sys.UI.DomElement.setLocation($get('Map1'), bounds.x + 75, bounds.y);

Constructors and members

As with .NET classes, JavaScript objects can have constructors and members, such as properties, methods, and events. Constructors enable you to create an instance of a JavaScript object. In many cases, JavaScript objects already exist on the page. For example, if a Web ADF Map control is on the page, a JavaScript Map object was created in the client browser and is available via JavaScript. You only need to find the component on the page using the $find function. If you need to create a component, you can create an object using its constructor to maintain a reference, define a variable, and assign its value as shown in the following code example:
[JavaScript] 
var newEnvelope = new ESRI.ADF.Geometries.Envelope( - 100, 35,  - 90, 45);
Properties are listed by name in the ASP.NET AJAX and Web ADF JavaScript Library references. However, to get or set property values for component properties, you must call property accessor methods that are named with the get_ and set_ prefixes. For example, to get or set a value for a property such as extent, call the get_extent or set_extent method as shown in the following code example:
[JavaScript] 
var map = $find('Map1');
var newEnvelope = new ESRI.ADF.Geometries.Envelope( - 100, 35,  - 90, 45);
map.set_extent(newEnvelope);
Likewise, to add or remove event handlers for component events, you must call the event accessor methods that are named with the add_ and remove_ prefixes. For example, to add or remove a handler for the mouseMove event, call the add_mouseMove or remove_mouseMove method as shown in the following code example:
[JavaScript] 
var map = $find('Map1');
map.add_mouseMove(mouseMove);

function mouseMove(sender, eventArgs){
    window.status = sender.get_id() + ': ' + eventArgs.coordinate.get_x().toFixed(3)
        + ', ' + eventArgs.coordinate.get_y().toFixed(3);
};
JavaScript classes can contain private members that support the client-script infrastructure and are not intended to be used directly from your code. Names of private members begin with an underscore.

Application object

The Sys.Application class represents the client application environment associated with a page. The Application object is created when an ASP.NET AJAX page is viewed in the browser, and it persists for the life of the page. The Application object is responsible for managing page events and adding and removing child components. You can use the Application object regardless of the server-side AJAX pattern being used. You can use it to execute code after initialization by handling the init event.
If adding JavaScript code to the .aspx page, add it to a script tag after the form on the page. This guarantees that the content of the form (for example, controls and elements) is available as shown in the following code example:
[JavaScript] 
. . . <  / form >  < script type = "text/javascript" > Sys.Application.add_init
    (onInitialize);

function onInitialize(){}
 <  / script >

PageRequestManager

The Sys.WebForms.PageRequestManager class represents the ScriptManager control on the server. It is only available if a ScriptManager control is on the page. PageRequestManager manages and provides access to asynchronous postback requests and response content. If you are working with the partial postback pattern, you can use this component to handle custom data items generated on the server and processed by the client as shown in the following code example:
[JavaScript] 
function onInitialize(){
    Sys.WebForms.PageRequestManager.getInstance().add_pageLoading(PageLoadingHandler)
        ;
}

function PageLoadingHandler(sender, args){
    var dataItems = args.get_dataItems();
    if (dataItems['{0}'] != null)
        dataItems['{0}']();
}
There is only one instance of a PageRequestManager per page.