Migration to 10 Ajax Framework

There are some notable changes in migrating existing 9.3 Ajax Web ADF applications to 10.  We outline the steps below: 

In the 10 web application, the core ADF JavaScript files you are familiar with no longer exist in the same structure under the 'js' directory. We have adopted the Dojo distribution structure and now the JavaScript structure is as followed.

Domains

Two domains are introduced in the 10 Web ADF

This domain has the following classes:
adf.Map, adf.Callout, adf.core, adf.edit, adf.Maptip, adf.overview, adf.graphics.SvgElement, adf.graphics.VmlElement, adf.navigator, adf.scalebar, adf.slider, adf.task, adf.PrintTask, adf.window, adf.UploadUtil, adf.WindowManager, adf.Toolbar, adf.Toc

This domain has the following classes:
wma.identify, wma.layout, wma.Resource, wma.results, wma.slider

Scoping

dojo’, ‘dijit’, ‘dojox’ are scoped to ‘adfdojo’, ‘adfdijit’ and ‘adfdojox’ correspondingly to allow you to take advantage of the updated releases of dojo in the future.

Examples

1. If you want to connect to an event handler to a button’s ‘onclick’ event, instead of ‘dojo.connect(button, ‘onclick’, eventhandler)’, use ‘adfdojo.connect(button, ‘onclick’, eventhandler)’.

2. If you want to create ‘Button’ dijit on the fly, instead of ‘new dijit.form.Button’, you should use ‘new adfdijit.form.Button’.

Here is a code example:

3. If you want to use dijit in markup, the attribute ‘dojoType’ you may be familiar with in Dojo should be changed to ‘adfdojoType’. Here is an example:

<button id="myfirstButton" adfType="adfdijit.form.Button">declaritive dijit button</button>

JavaScript Reference

ADF JavaScript library uses Dojo’s package system to load the module user needs.
For example, to load classes in ‘adf’ domain, user can use “adfdojo.require (‘adf.adf’)”. To load classes in ‘wma’ domain, users can use “adfdojo.require (‘wma.app’)”. Users can decide which module to load. User can load ‘wma.results’ module by calling adfdojo.require (‘wma.results’) instead of loading all modules by calling adfdojo.require (‘wma.app’).

The classes without namespace have become deprecated. For example, class ‘EsriMap’ has become deprecated and ‘adf.Map’ is recommended for use. The difference between ‘adf.js’ and ‘adf-deprecated.js’ is that ‘adf-deprecated.js’ keeps the deprecated classes while ‘adf.js’ has only the new class with ‘adf’ as its name space. For example, class ‘EsriMap’ is available in ‘adf-deprecated.js’ while not in ‘adf.js’.
There is a simple way to map deprecated class to ‘adf’ class---replace the first 4 letter ‘Esri’ to ‘adf.’. For example, ‘EsriMapPoint’ maps to ‘adf.MapPoint’.

Before you start to migrate, determine which category you fall into and get an estimate of migration effort.

Category 1:
I use the out-of-the-box WMA without any developer customizations. My customizations are limited to the options available in Manager (tasks, map elements, layer definitions, themes, etc).

Category 2:
 I have my own tasks and make use of ADF JavaScript API to achieve AJAX functionality.

Category 3:
 I have leveraged the ADF's JavaScript API to make some customizations to my application. Some ADF JavaScript source file has been modified for my specific usage.

Category	Effort	Time Estimate
1	Server side change, JSP Change	Minimum (1 Day)
2	Server side change, JSP change, ADF Function usage change	Medium (1 - 2 days)
3	Server side change, JSP change, ADF function usage change, Integrate modified ADF JavaScript classes	Maximum (1 week or more, difficult to predict)

Now migrate your application to 10 based on the effort table.
   
Server side change

The server side change is mainly about ‘faces-config.xml’ modification. The 10 ADF adopts JSF 1.2. so the ‘faces-config.xml’ needs to be updated based on JSF1.2 specs.

JSP change

For both manager generated application and custom application

The dojo.js file needs to be referenced on the top.  Other module is loaded afterwards. Resource file needs to be loaded for localization.

 

 

The Locale class needs to be imported in JSP file to enable localization.

 

 

 

The style sheet needs to be updated. If you do not use WMA application, remove the bottom wma.css and theme style reference.

 

 

If adf.Utils.sendAjaxRequest function is implemented, its fourth parameter should be a handler function with XMLhttp object as its parameter.

 

 

In body tag of your JSP page, add theme class name

 

 

 

For map viewer application, the following changes needs to be made in mapviewer.jsp

initLayout() function is replaced with wma.initLayout()

 

 

resizePanelContentLayout is replaced with wma.resizePanelContentLayout

 

‘request.getParameter(‘width’)’ is replaced with ‘#{param.width}’, ‘request.getParameter(‘height’)’ is replaced with ‘#{param.height}’

 

For ‘overview’ button, ‘onload’ event is connected to ‘onHandleImage’ function

 

For task link, ‘toggleWindow()’ is replaced with ‘wma.toggleWindow(…)’

 

For editing task, ‘showEditorWindow()’ is replaced with ‘adf.EditTask.showEditorWindow()’

 

Remove the ‘task’ div in the ‘mapviewer.jsp’ if no task exists(for IE6 user)

 

It is recommended that you generate a map viewer application through manager, and then compare the differences of ‘mapviewer.jsp’ between 9.3 and 10.

 

Include ‘adf-deprecated.js’ file in your JSP file to achieve maximum backward compatibility

By this way, you don’t need to change the old function name in 9.3. For example, if you have client action ‘EsriMapRectangle’ in your tool, the client action can stay intact.

 

Use the same function in ‘adf’ domain instead of deprecated function

Take ‘bookmark’ sample in the ArcGIS Java Server install directory as an example, ‘adf.Controls’ is used instead of ‘EsriControls’; ‘adf.Utils’ is used instead of ‘EsriUtils’;
Example(9.3.1):

 

Example(10):

 

 

If you have ‘this.inheritsFrom(src)’ usage in your own JavaScript class for inheritance purpose, change it.

You can change the code to ‘EsriUtils.inheritsFrom(this, src)’ if ‘adf-deprecated.js’ is included; otherwise you can use ‘adf.Utils.inheritsFrom(this, src)’.

 

For user who makes change in the ADF JavaScript class file, (for example, user has modified ‘esri_maptip’ file to have his own map tip behavior). The first thing we recommend is to take advantage of custom event in ADF JavaScript object, for example, ‘onFeaturesChanged’ event in ‘adf.MapTip’ class.  If user’s customization has crossed the limit of custom event of ADF JavaScript object, we recommend user to use ‘adfdojo.extend’ function to integrate their modification.
For example, suppose a user has modified  function ‘_mapTipHandler’ in ‘adf.MapTip’, he can create a new JavaScript file and reference it, and then copy his code to the file like this:

 

One alternative is that you can reference the uncompressed ADF JavaScript source file in your application, and modify the source file directly. This approach is risky since the source file change might create unexpected behavior. It would also degrade performance at some level since the JavaScript file is no longer minimized.
 
Suppose you have modified the ‘_mapTipHandler’ function of ‘adf.MapTip’ class inside of ‘adf.js.uncompressed.js’ file , you need to reference the uncompressed file as followed:

 

How long the integration takes depends on developer’s familiarity with the ADF JavaScript working mechanism. The migration effort would vary from a week to a month.