Web ADF JavaScript Library Overview

The Web ADF includes a set of JavaScript libraries, termed the "Web ADF JavaScript Library " which are designed to support and enhance the use of server-side Web ADF components in a browser.   AJAX capabilities and client-server synchronization in the Web ADF are heavily dependent on Web ADF JavaScript logic.  The 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.  It manages interaction with remote services and server-based Web controls using well known partial postback and callback AJAX patterns.  It provides a mechanism for representing Web controls on the client (Script controls) and handling events in the browser.  In addition, it's designed for cross-browser support.  All of these capabilities are leveraged in the Web ADF JavaScript Library.    Documentation for the ASP.NET AJAX JavaScript Library is provided by Microsoft as part of the AJAX client reference materials.   

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 have the ability to use JavaScript to interact with .NET Web ADF server controls and capabilities, such as navigating a map, adding graphics to a map, or creating map tips, without requiring any server-side code.  Changing the state of a Web ADF control via JavaScript is synchronized on both the client and server for you.  Some Web ADF JavaScript objects are only persisted in browser memory, such as graphics which have no server-side representation.   In any case, the Web ADF JavaScript Library merely provides a Web ADF developer with another tool to leverage when creating and enhancing a Web application.    It is not designed to completely replace server-side programming or to be used on its own, without server-side controls. 

Note, the Web ADF JavaScript Library is different than the ArcGIS JavaScript APIs designed for pure JavaScript applications.  The Web ADF JavaScript Library is packaged with the Web ADF and designed solely for use with Web ADF components and solutions.  ArcGIS JavaScript APIs are not designed for use with the Web ADF.  

The Web ADF JavaScript Library actually consists of a set 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.  Instead, they provide set of components to use and extend via custom JavaScript you add within a page.  Like the Web ADF server-side .NET components and classes, the JavaScript Library includes a set of namespaces and classes, or JavaScript objects within which to interact at runtime. 

Merely adding a Web ADF control to a page will include the libraries that constitute the Web ADF JavaScript Library with the page at runtime.   Note however that the developer experience is different than traditional .NET development within Visual Studio.  Common Visual Studio capabilities used by .NET developers to enhance the code writing experience are not available when coding JavaScript, such as intellisense, code completion, or integrated help.  In addition, JavaScript is an interpreted language (interpreted at runtime by the browser) so catching errors at compile time is not possible.

To get started working with the Web ADF JavaScript Library, consider the following three areas in which it can be utilized.  A discussion is provided for each area: 

• Mapping
• Graphics and MapTips
• Dynamic layers
        

As a client-side JavaScript API, the Web ADF JavaScript Library includes an object model diagram and library reference within this help system.  

     
Getting started with ASP.NET AJAX JavaScript   

The ASP.NET AJAX JavaScript Library defines patterns for JavaScript object definitions, classes to support application interaction and Web request content, and convenient functions for common operations.  It's important to understand a few of these patterns, classes, and functions before working with the Web ADF JavaScript Library.  Note, regardless of the AJAX pattern being used on the server (callback vs. partial postback) the Web ADF JavaScript Library still uses the ASP.NET AJAX JavaScript library on the client browser.

• At some point, you'll probably want to find the script representation of a Web ADF control to work with it via JavaScript in the browser.  ASP.NET AJAX provides a set of global shortcut functions for common tasks: $addHandler, $addHandlers, $clearHandlers, $create, $find, $get, and $removeHandler.  The $find function will return a reference to the JavaScript component.  The $get function will return the element.   Both use the client id of a component\element to locate it in the page.   You will 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 runtime, you can use the $find function to return a Web ADF JavaScript component. 
  
  [JavaScript]
  

  var map = $find('Map1'); 

• You may choose to explicitly create JavaScript objects.   You can use two methods: $create or new.  ASP.NET AJAX provides the $create function as a shortcut for performing several initialization steps in a single statement.  Specifically, a call to $create will: 
  • Register 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).
  Newing a JavaScript object requires a call to the class constructor, which may define a set of input parameters.  Properties and event handlers must then be explicitily initialized in subsequent statements. 
  
  The following code samples illustrate both techniques for creating and configuring a new Web ADF ESRI.ADF.Graphics.GraphicFeatureGroup JavaScript object with the same properties and behavior.  Note, a GraphicFeatureGroup is used to store and render graphics (GraphicFeatures).
  
  Using "$create":
  
  [JavaScript]

  var geomGroup = $create(ESRI.ADF.Graphics.GraphicFeatureGroup,{"id":"customGraphicFeatureGroup1","symbol":symbol, 
    "highlightSymbol":highlightSymb},{"mouseOver":onMouseOverGfx,"mouseOut":onMouseOutGfx});

  Using "new":
  
  [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); 

• To determine the size and location of an HTML element or component at runtime in the browser, use the Sys.UI.DomElement's getBounds() method.  It returns an associative array containing the height, width, and x, y location of the upper left corner of the element. 
  
  [JavaScript]
  

  var bounds = Sys.UI.DomElement.getBounds($get('Map1'));
  

• To move an element at runtime, use the Sys.UI.DomElement's setLocation() method.
  
  [JavaScript]
  

  var bounds = Sys.UI.DomElement.getBounds($get('Map1'));
  Sys.UI.DomElement.setLocation($get('Map1'), bounds.x + 75, bounds.y);

   
• Like .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 will already be created for you in the page.  For example, if a Web ADF Map control is in the page, a JavaScript Map object was created in the client browser and available via JavaScript - you merely need to find the component in the page using $find().  If you need to create a component, you can create a new object using its constructor.  To maintain a reference, define a variable and assign it's value.
  
  [JavaScript]
  

  var newEnvelope = new ESRI.ADF.Geometries.Envelope(-100, 35, -90, 45);
  

  
  Properties are listed by name in ASP.NET AJAX and Web ADF JavaScript library reference. 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, you call the get_extent or set_extent methods.
  
  [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, you call the add_mouseMove or remove_mouseMove methods.
  
  [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 may 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.   
  
• 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 persists for the life of the page.  It is responsible for managing page events and adding\removing child components.  Regardless of the server-side AJAX pattern, you can use the Application object.  In many cases, you'll use it to execute code after initialization by handling the init event.  If adding JavaScript code to the aspx page, it's recommended that you add it to a script tag after the form in the page.  This will guarantee that the content of the form (e.g. controls, elements, etc.) are available.
  
  

  . . .
  </form>
      <script type="text/javascript">
      Sys.Application.add_init(onInitialize);
  
      function onInitialize() {}
      </script>
  

• The Sys.WebForms.PageRequestManager class represents the ScriptManager control on the server, thus it will only be available if a ScriptManager control is present in the page.  The PageRequestManager manages and provides access to asynchronous postback request and response content.   If you're working with the partial postback pattern, you will likely use this component to handle custom data items generated on the server and processed by the client.  There is only one instance of a PageRequestManager per page.
    
  [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}']();
  }