ArcGIS Online moving to Google / Bing tiling scheme: What does this mean for you?

Earlier this year ESRI announced that ArcGIS Online services will be migrating to the Mercator-based tiling scheme used by Google Maps and Bing Maps. The ArcGIS Online engineers have been busy caching tiles for months in anticipation of this switch, which is anticipated to occur by the end of this year. This post is about how the change may affect you. At the end of the post we also provide steps on how to make the change for your services.

Why a tiling scheme change?

Since the release of ArcGIS Online three years ago, the 2D services have used the WGS 1984 geographic coordinate system and a 512 x 512 pixel tile size. Google and Bing, in contrast, use a modified Mercator projection and a 256 x 256 tile size. The scale sets used by both tiling schemes are similar, but not equivalent.

Why didn’t ArcGIS Online originally choose to match Google and Bing? Interestingly enough, the first ArcGIS Online services were designed in 3D for viewing in ArcGlobe and ArcGIS Explorer. Without getting into the technical details, it’s enough to say that the coordinate system and scales used in the 2D ArcGIS Online tiling scheme have their roots in the ESRI globe technology for which ArcGIS Online was originally built.

With the broad uptake of the ArcGIS Web APIs, the 2D ArcGIS Online services have become very widely used. Some organizations struggle with choosing either the ArcGIS Online tiling scheme to match their ESRI software stack, or the Google / Bing tiling scheme to match a better-known standard. With a unified tiling scheme for the three services, the decision gets a lot easier.

A few organizations are required to support mashups with both ArcGIS Online and Google Maps or Bing Maps. After the ArcGIS Online tiling scheme change, these organizations will no longer have to maintain two caches.

What does this mean for you?

If you are getting ready to create a very large cache to overlay ArcGIS Online, it may be best to create the cache in the Google / Bing tiling scheme, anticipating the change.

If you are not able to re-create your cache at this time, the old services will remain available for a minimum of six months. They will be offered “as is” and will not receive any further data or cartography updates.

Advantages of switching to the Google / Bing tiling scheme

The biggest advantage of switching to the Google / Bing tiling scheme is standardization. This tiling scheme is well-known and widely used. Whether you love the Mercator projection or hate it, it is now customary in Web maps designed for mass consumption. In the end, simplicity of math (you can fit the world on a square at the smallest scale) determined the way most Internet users expect to see the world.

There are some subtle performance advantages to the Google / Bing tiling scheme. Because the tiles are only 256 x 256 pixels, less tile area falls outside the periphery of the map. This means you have to send less data across the wire. The smaller tiles also enhance the perception of the map loading faster, compared with waiting for the 512 x 512 “chunks” of map to appear.

Challenges associated with the Google / Bing tiling scheme

If you re-create your caches in the Google / Bing tiling scheme, you need to anticipate a few issues. First, because the tiles are 256 x 256, you’ll be creating roughly four times as many tiles as you had previously in your ArcGIS Online cache. The larger number of files in your cache will increase cache copying time. The smaller tile size also means you have to send more files to the client during a map request.

Your cache size on disk will probably also increase. Some of the 256 x 256 tiles can get very small in size if they contain few features; much smaller than the 4K default minimum cluster size on Windows. Some organizations have saved space by storing their caches on disks or partitions formatted with a smaller minimum cluster size, such as 1K. This reduces the discrepancy between “Size” and “Size on disk”.

Finally, the Mercator projection is going to stretch your map vertically, especially if you work with extreme latitudes. Besides affecting the appearance of the map, this distortion may cause you to create many more tiles than you might otherwise expect. At these latitudes, it is critical to target your cache at just the scales and geographies that you need. You may want to enable on-demand caching for the most isolated regions. The distortion introduced by the Mercator projection also means that before you measure a feature such as a user-drawn polygon, you should project the feature into a more locally-tailored coordinate system such as UTM or State Plane.

How do you create a cache to match the Mercator-based ArcGIS Online services?

Here’s the workflow for caching a map to match the Mercator-based ArcGIS Online services:

1. Open your source map document in ArcMap and set your data frame coordinate system to WGS 1984 Web Mercator. You don’t have to re-project the source data, although this can make caching go faster. Some people even create a one-way replica of their geodatabase in the WGS 1984 Web Mercator coordinate system and use that replica just for caching.
2. Publish a map service.
3. Open the Service Properties and click the Caching tab. Choose to draw the map service Using tiles from a cache you will define below.
4. Click Load tiling scheme from and select Google Maps / Microsoft Virtual Earth. Once the scales load, do not add or remove scales or change the tile size.
5. Create tiles for just a small area of your map, using a feature class to constrain the caching extent if necessary.
6. Test your new cache. There are already a few new ArcGIS Online services that use the Google / Bing tiling scheme, such as the World Topographic Map. Build a simple test application with these maps to evaluate how your cache overlays with ArcGIS Online in the Mercator projection. If your data doesn’t align, see the alternate steps below for creating a cache in WGS 1984 Web Mercator (Auxiliary Sphere).
7. Once everything looks okay, open the caching tools again and create all the tiles for your cache.

Exceptions and Web Mercator (Auxiliary Sphere)

There are a few scenarios where you will have to follow some alternate steps to get your caches to overlay correctly with the Mercator-based ArcGIS Online services. The conditions are:

• You’re overlaying a cache with ArcGIS Online in the Web ADF OR
• Your data did not align correctly when building a test cache with the above steps. This is most often because your source data uses a datum other than WGS 1984 or NAD 83

In the above two scenarios, you need to publish your cache using the WGS 1984 Web Mercator (Auxiliary Sphere) coordinate system which is the exact coordinate system used by ArcGIS Online. The Web ADF requires an exact coordinate system match for cache overlays. Also, this coordinate system makes it easier to perform some datum transformations.

1. Open your source map document in ArcMap and set your data frame coordinate system to WGS 1984 Web Mercator (Auxiliary Sphere). While you are doing this, apply any datum transformations to WGS 1984 that you require.
2. Follow the steps in ESRI Knowledge Base Article 37329 to create a cache for the service.

Migrating map tiling schemes in the ArcGIS Online Help has more details about the switch and the WGS 1984 Web Mercator (Auxiliary Sphere) coordinate system used above.

Contributed by Sterling Quinn of the ArcGIS Server development team.

Looping through graphics using the ArcGIS API for JavaScript

When working with the ArcGIS API for JavaScript you'll often find yourself looping through arrays, like the collection of graphics stored in a graphics layer or the results of a QueryTask. In this post we'll explore two approaches for looping through arrays; using a standard for loop and working with a dojo implementation of one of the JavaScript Array Extras.

For Loop

First lets look at using a for loop to add query task results to a map. The results of QueryTask are returned as an array of Graphic features so we can use a for loop to iterate through the task results and add each graphic to the map.

 dojo.connect(queryTask,"onComplete",function(featureSet){
   for(var i=0; i < featureSet.features.length; i++){
     map.graphics.add(featureSet.features[i]);
   })

We can optimize the code a bit by storing the length of the array in a variable. Then the length of the array doesn't need to be recalculated on each loop. The stored length (il) is just compared to the value of the counter(i).

 for (var i=0; il = featureSet.features.length; i < il; i++){

JavaScript Array Extras

The JavaScript array extras are useful functions for working with arrays and are part of ECMAScript 5th Edition, the next revision of the standards on which JavaScript is based. The revised standard is still under development so not all browsers support this functionality. Thankfully Dojo has implemented similar functions as part of Dojo Core so we can take advantage of one of the array extras, dojo.forEach, to simplify the process of looping through an array of graphics. Dojo.forEach runs a function on each item in the array.

 dojo.connect(queryTask,"onComplete",function(featureSet){
   dojo.forEach (featureSet.features, function(feature) {
     map.graphics.add(feature);
   });
 });

Note that we no longer need the counter and array length variable which makes the code easier to read and can help avoid the following problems:

• Off-by-one errors
• Overwriting a global variable by forgetting to declare the loop counter as a local variable using the var keyword.

If you do need access to the iterator you can specify an additional argument to the function. This argument provides access to the current position in the array.

 dojo.forEach(featureSet.features,function(feature,index){
   //do something with the index here

 }

Links

• Click here to view a live sample that uses dojo.forEach to add graphics to a map.
• Information from Dojo on working with array utilities
• Details on ECMAScript

Contributed by Kelly Hutchins of the ArcGIS JavaScript API development team

ArcGIS API for Flex: Version 1.3 released today

It’s been just over one year since we released the first version of the ArcGIS API for Flex. Since then we’ve seen an amazing interest in our Flex API. Many users have created great web applications with the API, and the Flex forum is now the most active of all the ArcGIS Server forums.

Today we are pleased to announce the release of ArcGIS API for Flex 1.3. This API release is a minor release but has several useful "goodies".

Here’s a short summary of what’s new in version 1.3:

• Support for Adobe’s Flex 3.4 SDK. The older versions 3.0 thru 3.3 are still supported.
• Additional styling options for InfoContainer (used by InfoWindow and InfoSymbol).
• More miscellaneous API improvements and bug fixes.
• Well-known ID 102100 (WGS_1984_Web_Mercator_Auxiliary_Sphere) is now a supported projection for Web Mercator-based overlays (including Bing Maps). It is now also used in WebMercatorUtil for projecting coordinates between Geographic and Web Mercator.
• New and updated samples.

Please read the more complete list of 1.3 API changes in the What's New page in our Resource Center.

Contributed by Bjorn Svensson of the ArcGIS API for Flex development team

Working with info windows in the ArcGIS JavaScript API

An easy way to add interactivity to your ArcGIS JavaScript applications is through info windows that display information in response to a user action. From working with other APIs, you might know info windows as "balloons", "map tips", "callouts", or "popups". The concept is the same: the user clicks or hovers over a location on the map and sees HTML-based information about that particular location.

 

How does an info window work in the ArcGIS JavaScript API?

In the ArcGIS JavaScript API, the Map has an InfoWindow that can be shown or hidden in response to events.

Every info window has a title and content. The title is the bold text that appears at the top of the info window. The content is the HTML that appears below. When you work with info windows, you’ll frequently call methods to set the title and content.

The default event when a graphic is clicked is to show an info window. However, in order for this to happen, you need to have defined an InfoTemplate for the graphic. The InfoTemplate specifies the title and content that should be used in any info windows that result from clicking the graphics.

You can use the notation ${<FIELD>} to pull attributes directly into an info template.

var infoTemplate = new esri.InfoTemplate();
infoTemplate.setTitle("${NAME}");
infoTemplate.setContent("<b>2000 Population: </b>${POP2000}<br/>"
        + "<b>2000 Population per Sq. Mi.: </b>${POP00_SQMI}<br/>"
        + "<b>2007 Population: </b>${POP2007}<br/>"
        + "<b>2007 Population per Sq. Mi.: </b>${POP07_SQMI}");

This code would create an info window similar to what you see below.

 

You can handle a graphics layer’s onClick event yourself to show an info window. This can be useful if you need to use JavaScript in some way to construct what you put in the info window. The following function does some math to calculate the population density when a user clicks the graphics layer. The population density is then reported through an info window using the Map.infoWindow.setTitle() and Map.infoWindow.setContent() methods.

dojo.connect(myGraphicsLayer, "onClick", function(evt) {
  var graphicAttributes = evt.graphic.attributes;
  var title = graphicAttributes.NAME;
  var populationDensity = graphicAttributes.POP2007 / graphicAttributes.SQMI;
  var content = "The population density in 2007 is <i>" + populationDensity.toFixed(2); + "</i>.";
  map.infoWindow.setTitle(title);
  map.infoWindow.setContent(content);
  map.infoWindow.show(evt.screenPoint,map.getInfoWindowAnchor(evt.screenPoint));
});

These Map.infoWindow.setTitle() and Map.infoWindow.setContent methods are also handy if you want to show an info window in response to a query or some other action that doesn’t involve a graphic. Here’s a function designed to show an info window with lat/lon coordinates when the user clicks anywhere on the map.

dojo.connect(map, "onClick", addPoint);
function addPoint(evt) {
  map.infoWindow.setTitle("Coordinates");
  map.infoWindow.setContent("lat/lon : " + evt.mapPoint.y + ", " + evt.mapPoint.x);
  map.infoWindow.show(evt.screenPoint,map.getInfoWindowAnchor(evt.screenPoint));
}

What can you do with info windows?

You can put almost anything in an info window because it displays HTML. Images, hyperlinks, tables, dynamically rendered charts, and any other type of element that can be requested or created with HTML can be placed in an info window.

You can take advantage of Dojo libraries to enhance your info windows. This picture shows information organized in a Dojo TabContainer in the info window.

 

Here’s a chart dynamically constructed for an InfoWindow using the Dojo charting library:

 

Just because you can put something in an info window doesn’t always mean that you should. The BorderContainer and other elements in the Dojo layout libraries can help you organize information in sidebars, footers, and accordion containers on your page. (See this post for an introduction to Dojo layouts.) In some scenarios these might be more efficient than an info window.

The application pictured below avoids info windows in favor of a right-hand content pane containing charts and other information. Click the image if you're interested in downloading the code.

 

Designing a good info window

Although info windows can display all kinds of content, you should not use info windows as a "dumping ground" for information. A well-designed info window has:

• A descriptive title – Keep the title short and clear
• Formatting that is easy on the eyes - A few well-placed spaces, tabs, or line breaks can go a long way toward making the content easy to read.
• Clear labels for attributes - A non-GIS user looking at your application may not understand raw field names such as "PARCEL_NO". Instead, use clear descriptions or field aliases, such as "Parcel number". Avoid the ${*} shortcut that lists all field/value pairs.
• Attributes that are important to the end user – Many GIS datasets contain fields that are only of interest to a GIS analyst, not end users. "OBJECTID" is one example of a field that should probably never appear in a public-facing application.
• A manageable amount of information - Use tabs, sidebars, data grids, or links to other HTML pages if your info windows are getting too crowded and require the user to scroll.

Contributed by Sterling Quinn of the ArcGIS Server development team

Working with TextSymbol in the ArcGIS JavaScript API

This post discusses how you can add text to your map using the ArcGIS JavaScript API. Your map service probably already has some labeling in it, but you may want to add descriptive information about graphics that you add on top of your map through tasks or queries. The ArcGIS JavaScript API does not have a built-in labeling engine with conflict detection and label placement algorithims, but you can use the TextSymbol class to add text at a specific point location on the map.

The TextSymbol class has several properties that you can use to fine-tune the position and content of the text element such as angle, offset, font, and kerning (spacing between the letters).

Use the TextSymbol.setFont() method to specify a font for the text. You can use the Font class to set properties like text size, style and weight.

Creating a text graphic

Let's look at a code snippet that uses several of the Font and TextSymbol properties to create a new TextSymbol and add it to our map as a text graphic. This graphic will denote an unexplored area on our map using an old cartographic phrase "Here be dragons". First, we'll create the Font object and specify the font weight and size.

    
         var font  = new esri.symbol.Font();
         font.setSize("12pt");
         font.setWeight(esri.symbol.Font.WEIGHT_BOLD);       

Now we need to create a new TextSymbol and specify that it should be maroon, set at a 15-degree angle and be aligned to the start of our input point.Next, we use the setFont() method to assign the font we just created to the TextSymbol. Finally, we create a new graphic, assign it the newly created TextSymbol, then add the graphic to the map.

         var textSymbol = new esri.symbol.TextSymbol("Here be dragons");
         textSymbol.setColor( new dojo.Color([128, 0, 0]));
         textSymbol.setAlign(esri.symbol.Font.ALIGN_START);
         textSymbol.setAngle(15);
         
         textSymbol.setFont(font);      
        
         var pt=  new esri.geometry.Point(x,y,map.spatialReference)
         var gra = new esri.Graphic(pt,textSymbol);      
         map.graphics.add(gra);

Simplifying the code

The code above is written in a verbose style to make it easier to examine the values we set for the TextSymbol and Font properties. We can reduce the length of the code snippet by using object constructors and chaining method calls. Let's explore this approach a bit:

• First, use map.graphics to get access to the map's default graphics layer.
• The GraphicsLayer has an add method that takes a Graphic object as a parameter, we'll create a new graphic within the method call using the Graphic constructor.
• Graphics consist of geometry, symbol, attributes and an infoTemplate. In our example, we don't need attributes or an infoTemplate so we'll use the Graphic constructor and provide only a geometry (Point) and symbol (TextSymbol)
• Let's examine the TextSymbol section a bit more closely. Many of the JavaScript objects, like Graphic and TextSymbol, have setter methods that return the object. Because of this we can chain method calls. In the snippet below, we create a new TextSymbol, define the text in the constructor, then chain setColor, setAlign, setAngle and setFont to reduce the amount of code we have to write.

     map.graphics.add(
            new esri.Graphic(
            new esri.geometry.Point(x,y, map.spatialReference),
            new esri.symbol.TextSymbol("Here be dragons").setColor(
                    new dojo.Color([128,0,0])).setAlign(esri.symbol.Font.ALIGN_START).setAngle(45).setFont(
                    new esri.symbol.Font("12pt").setWeight(esri.symbol.Font.WEIGHT_BOLD))          
            )
        )

One caveat to this approach is that it can make the code more difficult to read; however, with a bit of practice it becomes second nature.

Samples

• Click here to see a live sample that generates text graphics
• The Graphic Symbology Code Generator on the Code Gallery generates JavaScript code for symbols and is a great tool to explore various symbol properties.
• To label polygon graphics, use the GeometryService.labelPoints() method to generate a point inside the polygon. You can then designamte this point as the label position. View the Create points for labeling sample for details on how to use this method.
• Some text information may be better suited to display in an info window. The Show an info window sample shows how to display text in an info window at a specific location

Notes

There are several browser-specific issues to be aware of when working with fonts and text symbols. These issues are well documented in the dojox.gfx documentation. Some of the more common issues are:

• The font family property does not work in Internet Explorer 7; Arial is always used.
• Several browsers including Internet Explorer 7, Firefox and Opera 9 do not support the rotated and decoration properties for text symbols.

Contributed by Kelly Hutchins of the ArcGIS JavaScript API development team.

Which ESRI Web mapping API should I choose?

Since the release of ArcGIS Server, ESRI has offered Web application developer frameworks (ADFs) for .Net, and Java. Last year, ESRI also released Web mapping APIs for JavaScript, Flex, and Silverlight, further expanding the choices for developers.

One of the most common questions we’ve received at the ESRI User Conference and other recent seminars is: “Which API should I use?” When presented with this question, I like to respond with some questions of my own.

Which platform are your developers most comfortable with?

The APIs are functionally very similar, and often the most important question is not “What do you want to do?” but rather “Which platform are your developers most comfortable with?” If you’ve been working with the Microsoft stack and your developers are inclined in that direction, .Net and Silverlight look like good choices for you. Using similar logic, if your developers have spent the past 10 years adding custom scripts to your ArcIMS applications, they’ll probably find the JavaScript API to be a nice fit.

Choosing a platform that your developers already know and enjoy can save you ramp-up costs and keep morale high. This is where the variety of APIs offered becomes a benefit instead of a burden.

What’s the experience level of your developers?

Many beginning developers find the JavaScript, Flex, and Silverlight APIs to be easier to learn than the Web ADFs because they have a more basic architecture. These APIs also have online Resource Centers, where you can watch videos, read tutorials, and examine working samples that are designed for beginners. ESRI has made sample ArcGIS Server deployments available so that you can practice with the APIs. In fact, you can get a JavaScript mapping application running on your machine with just Notepad and an Internet connection.

In contrast, some developers like the deep functionality and familiar coding patterns of the .Net and Java ADFs; especially developers who have already worked with a lot of .Net, Java, or ArcObjects in the past.

Are browser plug-ins an option?

The ArcGIS APIs for Flex and Silverlight require browser plug-ins. If your application absolutely cannot require a plug-in, the JavaScript API or one of the ADFs will need to be your choice.

The ArcGIS API for Flex requires the Flash plug-in, which Adobe asserts is present in “99% of Internet-enabled desktops in mature markets”. The Silverlight plug-in has not yet reached the same level of ubiquity, but can be expected to gain ground.

Plug-ins come in different versions, which may also present a hurdle in getting end users to experience your Web site in the way you expect. If you choose to use Flex or Silverlight, it’s wise to consider how flexible your clients are in their ability to upgrade plug-in versions. The ArcGIS API for Flex requires Flash Player 9 or above, or Adobe AIR. The 1.0 release of the ArcGIS API for Silverlight requires Silverlight 2 or above.

Future editions of these APIs may require higher versions of the plug-ins. Also, any functionality that you add that is not native to the ESRI APIs may require higher versions.

Do you want to use an IDE? If so, which one?

When you choose an API, you are also making choices about the environment where you’ll spend your time coding. Flex users are probably going to need Flex Builder. .Net and Silverlight users will be doing work in Visual Studio or Visual Web Developer Express. Expression Blend is another option for Silverlight developers. Java developers can use Eclipse or NetBeans. JavaScript programmers probably have the most choices, including the option to just write code in a text editor.

The pros and cons of these IDEs are beyond the scope of this post. Some IDEs cost money, but the time they save you in designing and debugging applications may help you recuperate the cost. If funds are tight, you may be able to get by without an IDE, especially if you are using JavaScript. Many commercial IDEs offer trial versions or free development versions that can help you decide if you want to make the purchase.

Do you need to edit features over the Web?

The .Net and Java ADFs offer access to fine-grained ArcObjects, which can be used to edit feature geometries. The ADFs contain out-of-the-box tasks (widgets) for basic Web editing operations. If you need to build an application with Web editing right now, one of the ADFs is your most likely option.

Web editing is planned for the JavaScript, Flex, and Silverlight APIs at the release of ArcGIS Server 9.4 in 2010.

Do you need to overlay basemaps from Microsoft or Google?

Your organization may require you to use base data from Microsoft’s Bing Maps (formerly Virtual Earth), or Google Maps in your application. This can affect your decision of API.

• Bing Maps is supported as a layer in the ArcGIS APIs for JavaScript, Flex, and Silverlight, as well as the .Net ADF. There is also an ArcGIS JavaScript Extension for the Virtual Earth API.
• Google Maps is available in the ArcGIS JavaScript Extension for the Google Maps API.

Are you more comfortable with established technologies or emerging technologies?

Some organizations approach new technologies with caution, whereas others jump at the chance to develop with the newest thing. Your organization’s attitude toward emerging technologies is important to consider, especially if you’re choosing between something like JavaScript, which has been around “forever”, and Silverlight, which just came on the scene in late 2007. This question is largely a matter of opinion, but can tip the balance in organizations where opinions run strong.

Have you talked with others who have made this decision?

ESRI conferences, forums, user groups, and blogs are a good place to learn from people who may have gone through a similar decision process. In fact, many of you who are reading this post may have additional advice, insight, or opinions on this question to share with others who are making the decision. Have you gone through this process before? Did you make a good choice? Is there anything you would have done differently? Leave a comment here.

Contributed by Sterling Quinn of the ArcGIS Server software development team.

Using JavaScript to populate a ComboBox with unique values

In this post we'll answer a question that comes up frequently in the ArcGIS API for JavaScript section of the ESRI Discussion Forum, "How do I populate a ComboBox with unique values"?

Create a ComboBox

First let's look at how to build a ComboBox, in this example, we'll use the Dojo ComboBox dijit (read more details on why at the end of this post). The option tags define the items in our list. In the example below we hardcoded four zoning types (Residential, Commercial, Office and Special).

<select id="mySelect" dojoType="dijit.form.ComboBox">
    <option>RESIDENTIAL</option>
    <option>COMMERCIAL</option>
    <option>OFFICE</option>
    <option>SPECIAL</option>
  </select>

If you have a small, static set of options manually building the list like this is fine; however in cases where you have a large and potentially changing set of choices, it’s a better idea to dynamically populate the list using JavaScript.

Let’s back up and start with an empty ComboBox that we’ll populate programmatically.

<select id="mySelect" dojoType=”dijit.form.ComboBox”>
</select>

Set up the Query Task

We want the ComboBox to be populated when the page loads so let's use dojo.addOnLoad to register an init function that will be executed on page load. In the init function we'll use a Query Task to return the records that meet the following query criteria.

• Specify false for the query's returnGeometry since we're just retrieving field values in this query; we don't need to display any features on the map
• Set the query's outFields to the name of the column in your dataset that contains the values you want to display in the ComboBox
• Optionally define a where clause that restricts the query to a subset of the features in the service

In the example below we define the query to return all non null values for the ZONING_TYPE field.

function init() {
       queryTask = new esri.tasks.QueryTask
                ("http://sampleserver1.arcgisonline.com/ArcGIS/rest/services/Louisville/LOJIC_LandRecords_Louisville/MapServer/2");

       query = new esri.tasks.Query();
       query.returnGeometry = false;
       query.outFields = ["ZONING_TYPE"];
       query.where = "ZONING_TYPE<> ''";
       queryTask.execute(query,populateList);
 }

Manipulate the Results and Populate the ComboBox

Once the query completes, the populateList function is called and we have access to the query results. In our query results we have duplicate values for each ZONING_TYPE so we'll need to perform the following steps to determine the unique values:

• Loop through the results and test each record to see if we've seen it before
• If the record is a value we haven't seen, build a {name:value} string for that type and store it in an array
• Create a Dojo ItemFileReadStore and populate it with the {name:value} strings for each zoning type . The ItemFileReadStore is a read only data structure we can use as the datasource for widgets like a Dojo DataGrid or ComboBox.
• Find the ComboBox using dijit.byId and set the store property to the ItemFileReadStore we created

    function populateList(results) {
        //Populate the ComboBox with unique values
        var zone;
        var values = [];
        var testVals={};

        //Add option to display all zoning types to the ComboBox 
        values.push({name:"ALL"})
        
        //Loop through the QueryTask results and populate an array
        //with the unique values
        var features = results.features;
        dojo.forEach (features, function(feature) {
          zone = feature.attributes.ZONING_TYPE;
          if (!testVals[zone]) {
            testVals[zone] = true;
            values.push({name:zone});
          }
        });
        //Create a ItemFileReadStore and use it for the 
        //ComboBox's data source
        var dataItems = {
               identifier: 'name',
               label: 'name',
               items: values
        };
        var store = new dojo.data.ItemFileReadStore({data:dataItems});
        dijit.byId("mySelect").store = store;
    }
    dojo.addOnLoad(init);

Click here to see an example that populates a ComboBox with unique values from a map service.

Notes:

• Those of you who have worked with Query Tasks frequently may notice a potential pitfall with this approach. Query Tasks are set up to return a maximum of 500 records by default. The server administrator can increase this value, but this typically isn't recommended. If your query definition will retrieve more than 500 records, there is a chance that the results you receive will not contain all the possible unique values and you may want to explore other options for getting a complete list of unique values.
• So why didn't we just use a regular HTML select element? Our sample would have required us to set the innerHTML of the select element, and you'll run into a bug if you try to do this with Internet Explorer. There are workarounds for the bug but they require different approaches for different browsers. The Dojo ComboBox is more versatile.

Kelly Hutchins of the ArcGIS JavaScript API development team contributed this post.

ArcGIS JavaScript API 1.5 released

Version 1.5 of the ArcGIS JavaScript API is now available! To take advantage of the new version, change your script reference to the ArcGIS JavaScript API to use v= 1.5, like this:

<script type="text/javascript" src="http://serverapi.arcgisonline.com/jsapi/arcgis/?v=1.5" />

Version 1.5 adds:

• Support for Firefox 3.5
• Support for Dojo 1.3.2
• Ability to force a mouse cursor style change
• Optional HTTPS access of the ArcGIS JavaScript API
• Bug fixes

For more details on these items, take a look at the What's New in Version 1.5 document.

The ArcGIS JavaScript Extension for the Google Maps API and the ArcGIS JavaScript Extension for Microsoft Virtual Earth (now Bing Maps) were not updated at this release.

Achieving smooth transitions with adjacent services

In your ArcGIS Server application you might have reason to work with adjacent map and image services. This is most often occurs when you want to display your authoritative data for a small area while using a public service (ArcGIS Online, Bing Maps, or Google Maps) for the surrounding area. This is very common when viewing your services in ArcGIS Explorer. For example, you may have recent aerial photography for your area, and you want to blend it with the basemap imagery available in ArcGIS Explorer. This can present a challenge because your service may include a white collar around the map. The discussion below focuses on how to remove this white collar for different service configurations.

Dynamic map services

The example below is a dynamic map service containing aerial photography for Jefferson County, Kentucky shown in ArcGIS Explorer.

 

With this dynamic map service, ArcGIS Explorer is requesting a JPEG image because the service contains so many colors. Since JPEG does not support transparency, you get a white collar around the image. To clip the white area out of a map service for your desktop clients (ArcMap, ArcGIS Explorer, etc.), simply create a feature class that represents the boundary of your data. Then you can use the Data Frame Clipping capability as described below.

1. In the ArcMap table of contents, right-click the data frame and click Properties.
2. Click the Data Frame tab and then check Enable under Clip to Shape.
   
3. Choose Outline of Features and choose your boundary layer.
   
4. Click OK to all the dialogs.

After updating your map document you need to restart your map service for the changes to take effect. Then the map service will display in ArcMap or ArcGIS Explorer nicely without a collar as in the example below.

Image services

When dealing with image services you could run into the same white collar around your image. In this case the boundary feature and footprint features need to be clipped to the exact boundary of your imagery. Again, a feature class containing the exact boundary of your imagery would be very useful. You could replace the default boundary feature with your boundary feature and then clip all the footprints to the new boundary. Simply start an edit session, delete the existing boundary and copy and paste your existing boundary into the boundary feature class. After you save your edits and stop editing, right-click on the Footprint layer and click Recompute Footprint > By Clipping to Boundary. You can read about the many other ways to adjust image service footprints in the online help.

NoData and Web APIs/ADFs

The above two approaches for dynamic map services and images services use a boundary feature to differentiate between data and NoData. Any areas outside of the boundary features are NoData. The desktop clients like ArcMap and ArcGIS Explorer don’t render the NoData values. However, all of the Web APIs (JavaScript, Flex, Silverlight) and ADFs (.Net and Java) do render the NoData values as white if the requested image does not support transparency.

In the aerial photography example above, the Web application should request a JPEG image to preserve appropriate quality. Since JPEG does not support transparency, this image could not be used with another basemap service. In cases where a PNG image would work, the white collar will not display, but PNG should only be used with services that contain fewer colors than an aerial photo.

Since your basemaps should be cached anyway for Web applications, the discussion below dealing with cached map services is more appropriate for Web application basemaps.

Cached map services that use JPG tiles

Cached map services can produce an even larger white collar, as the example below illustrates.

This is a cached map service using JPEG image format. As has been discussed in another post, JPEG is by far the best image format for cached map services that contain aerial photography to be used in a Web application. You can see in this example that the cached map service doesn't work all that well in ArcGIS Explorer. The larger white boundary is from the empty cache tiles around the map. Since the JPEG image format does not allow for transparency, you get a white collar. There is nothing you can do to get rid of this white collar in ArcGIS Explorer, ArcMap, or any of the Web ADFs or APIs. To mitigate this problem with JPEG services in ArcGIS Desktop or ArcGIS Explorer you have three options:

1. Use layer files to control the visibility of the map service
2. Include the surrounding data in your map cache
3. Provide a second dynamic map service for desktop clients

Using layer files to control the visibility of the map service

Using a layer file, you can use scale dependent rendering to make sure the layer only turns on when zoomed way in. To do this follow these steps.

1. Add the cached map service to ArcMap
2. Zoom in on the data until you can start to see reasonable amounts of detail (that wouldn't otherwise be in ArcGIS Online or Bing maps).
3. Right-click on the layer and click Zoom to Nearest Cache Resolution. This ensures your layer visibility corresponds to your cache tile level.
4. Open the properties for the layer and set the minimum scale to your current scale.
5. Right-click the layer and click Save As Layer Package.

Now you can share the layer file with all of your desktop users. The white collar will still be visible, but only when zoomed way in. At this larger scale, your users will likely be more interested in your map service than the surrounding data.

Including the surrounding data in your map cache

The second option of adding surrounding data to your map cache can also improve the usability of the service by your desktop clients. This can be done for the smaller scales of your map cache with little overall impact to the total size of your cache tiles. For more on map caching see the online help. This does mitigate the problem but essentially you have pushed the problem further away from your study area.

Providing a second dynamic map service for desktop clients

The third option is to use two services: a cached map service for your Web applications, and a dynamic map service for your ArcMap and ArcGIS Explorer users. If you are working with imagery like that in this example, an image service would be preferred to the dynamic map service. Since ArcMap and ArcGIS Explorer have local caching capabilities after the first time an area is drawn, a dynamic image service would likely perform very well. To make this easily consumable by your desktop clients you could simply share a layer file pointing to the image service for those users. You should also set the minimum scale in the layer as described above to control the number of dynamic requests and only show your basemap when appropriate.

Cached map services that use PNG tiles

Cached map services that use PNG do not display a collar because PNG supports transparency. This is a good solution for StreetMap-type basemaps, which can use PNG 8 or 32 (you should never use PNG 24 due to IE 6 limitations). Below is a cached streets basemap service that uses PNG32.

PNG is an acceptable choice in this example because it maintains crisp lines and text while still keeping the file size low. If this map contained a lot of gradient fills and other shading affects, JPEG with compression quality 90 would be a better choice. Using JPEG would mean the service would not be very useful with other basemaps but it would give you the best performance and quality in a Web application.

Warning! Be very careful when using PNG 32 for your basemap services. As the number of colors increase, so does the file size. Using PNG 32 for aerial photography, for example, can result in tiles being approximately ten times larger than the same service cached using JPEG. If the tiles are ten times larger, then the map will be ten times slower. Using an image format like JPEG 90 would give more consistently sized tiles for all scales, whereas PNG 32 would have much larger tiles at the small scales but smaller tiles at the large scales. The best approach is to build a test cache and validate that all scales have acceptable tile sizes.

Summary

With dynamic map service and image services you can easily clip the imagery to the extent of your data allowing you to blend multiple adjacent basemaps in your desktop applications like ArcMap or ArcGIS Explorer. You will still have the challenge of getting the base maps to look similar in a single application but the published map templates should help in this area. With cached map services that use JPEG tiles you should consider maintaining two services: the JPEG cache and a dynamic map or image service. The JPEG cache would be used in web applications and the dynamic service would be used in desktop applications like ArcMap or ArcGIS Explorer. Cached map service that use PNG work very nicely for integrating multiple adjacent services but should not be used as an "ultimate" solution as JPEG caches can be much more efficient for map services with high color variation.

Contributed by Tom Brenneman of the ESRI Technical Sales team.

Print Task templates with the 9.3.1 .NET Web ADF

The 9.3.1 ArcGIS Server Web ADF for .NET introduces an extensibility point to the Print Task that allows you to customize the look of your printouts using template files on the Web server.

A new property called LayoutTemplateFile is introduced to define the template file. This property can point to any file on disk but must be accessible via a web URL. The file may be part of the same application or can reside in a separate application (for example, the aspnet_client folder).

In Visual Studio, select the PrintTask control and you'll see the new property. Clicking the Browse button allows you to browse to the custom template file.

How do you create a simple custom template?

An easy way to create a template is to modify the ADF's default template.

1. Within Visual Studio, right-click your project and choose "Add New Item..." from the menu. When the dialog appears, choose "HTML Page" and give it a suitable name. This will create an HTML document which you can use as the template.
2. Open the default template file which is typically installed in the ADF runtime folder (Example: C:\Inetpub\wwwroot\aspnet_client\ESRI\WebADF\PrintTaskLayoutTemplates\default.htm). This file defines the default appearance and layout of the Print Task output window.
3. Overwrite the markup of the new page with the contents from default.htm.
4. Modify the markup and CSS to obtain the output you desire.

What can you do with these custom templates?

Using custom templates, you can:

• Control the layout of elements and their styles

  In the template file, you can define the position and dimensions of the different elements on the page such as the map title, map image, and legend information. You can style the template page using inline CSS or an externally linked style sheet.

• Inject dynamic content

  The template file is not restricted to static HTML files but can reference resources which generate dynamic content (such as .aspx files or .ashx files). For example, the current time stamp could be included in the print output using a dynamic page.

• Control the display of results

  You can control the styling of task results through CSS and you may also choose to render the result entirely, forgoing the default generated table view. If you want to get more advanced, you might add an image generated using the Google Chart API or a report section rendered using a browser plugin like Silverlight.

• Use JavaScript hooks

  In addition to providing extensibility with respect to layout and rendering, the Print Task also exposes JavaScript events which can be used to completely control and customize the output. This is achieved by having "callback functions" defined in the template file which are invoked at specific stages of the output rendering.

Further reading

The SDK sample Common Print Task demonstrates the above capabilities where a chart is drawn dynamically using the Google Chart API

Contributed by Nikhil Shampur of the ArcGIS Server .NET software development team.

New paper on high-capacity map services; functionality matrix updated

We’ve just published a new paper that discusses strategies for creating a dynamic map service that supports heavy user loads. The paper is the latest release in the ArcGIS Server in Practice Series, which describes how to optimally configure ArcGIS Server to address selected workflows. In this case, we took the challenge of developing a map service that can generate over 250,000 maps an hour dynamically. The map service also supports on-the-fly projection, is multiscale, and enables feature filtering.

The paper also gives several tips for optimizing the map service and explores strategies for scaling out deployments of ArcGIS Server. You can access it here: High-Capacity Map Services: A Use Case with CORINE Land-Cover Data

Additionally, we wanted to mention that the 9.3.1 ArcGIS Server Functionality Matrix has been updated. The functionality matrix describes the characteristics of each ArcGIS Server edition and is a high-level guide to selecting the edition that best meets your needs.

Contributed by Ismael Chivite and Derek Law, ESRI Product Management

Dealing with underscore characters in your Web server name

Today, many individuals and organizations have conventions in place that restrict how a machine or web server can be named. Commonly, underscore characters ( _ ) are used to separate strings and numeric labels, such as SERVER_1234, or to assure that special domain names are not confused with host names. Although the use of underscore characters is effective, they may cause unexpected behavior when you attempt to log in to ArcGIS Server Manager, create services, or manage Web applications using Microsoft Internet Explorer.

Interestingly enough, the origin of this behavior is related to the development of the Domain Name System or “DNS” by Paul Mockapetris in 1983. His spec mandated that the hostname’s labels only contain the letters A – Z, the digits 0 – 9, and the hyphen. No other symbols, punctuation, or blank spaces were permitted. Despite a few modifications to the DNS hierarchy in the past 25 years, underscore characters are still not supported.

You may now be asking yourself, “How does the DNS hierarchy relate to my immediate problem of not being able to open Manager?” Essentially, the DNS acts a phone book for the internet by translating human-friendly machine names into unique numerical identifiers. So, “MyServer” could translate into “123.45.678.910”. When a character, such as an underscore, is introduced into the Web server name, the DNS gets confused since the character does not conform to the DNS hierarchy. Often, this results in failure of the Web server.

In light of this information, we developed the help topic Retaining underscore characters in the Web server name. It provides a workaround that will allow you to preserve your current naming conventions in ArcGIS Server 9.3.1.

Additionally, external topics by IBM and the IETF highlight best-practices when considering host name values and machine naming conventions.

Contributed by Michael Frates, Greg Reeve, and Nikhil Shampur of the ArcGIS Server development team.

New white paper gives metrics, best practices for a workgroup ArcGIS Server deployment

You probably wonder how much you can get out of a four-core machine with ArcGIS Server. The answer depends on what you do... We've prepared a new white paper document where you can see some interesting metrics on the throughput of a workgroup ArcGIS Server deployment and an application based on the Flex Viewer.

Throughout the document you'll learn the steps we followed to create a typical Web application for use within a local government office. We also provide figures showing how the application performed under load. While every map and every workflow is different, the document provides some insight into what you can expect from ArcGIS Server and gives some tips on how to approach the creation of web applications to get the most out of your server.

View the document Best Practices for Creating an ArcGIS Server Web Mapping Application for Municipal/Local Government.

Contributed by Ismael Chivite and Derek Law, ESRI Product Management

ArcGIS JavaScript API printing through PDF

A common question we received at this year's ESRI User Conference is how to print maps from the ArcGIS JavaScript API. One way to get a printable map is to export to PDF. ESRI's Rahul Ravikumar recently uploaded a sample to the Code Gallery that captures an ArcGIS JavaScript API map in a PDF, which can then be printed. He calls this sample Map2PDF.

Map2PDF is a RESTful service that prints all types of layers, including cached (or tiled) map layers, dynamic map layers, and client-side graphics. The sample includes a script PrintMap.js, which helps in serializing ‘map state’ and sends it to the web service. This service uses an open source iText PDF rendering engine to create the PDF.

The Map2PDF sample uses Java Servlet technology and can be deployed any Servlet / J2EE container including Apache Tomcat 6, IBM Websphere, Oracle Weblogic etc. Deployment instructions are included with the Code Gallery download.

Download the Map2PDF sample from the Code Gallery

See an example

ArcGIS API for Silverlight / WPF version 1.0 released

The ArcGIS API for Microsoft Silverlight / WPF version 1.0 final has now been released. The release follows an open beta period in which many of you provided your experiences and feedback relating to the API. We thank you for your participation during the beta.

This API allows you to access ESRI maps, data, and analysis tools in applications that you develop with Silverlight and WPF (Windows Presentation Foundation), Microsoft's latest technologies for building interactive Web and desktop applications, respectively.

From today's ESRI news release:

Developers can program with the API without installing any ArcGIS software on their machines as long as they have access to an ArcGIS Server via a URL. Since the API is built on the Microsoft Silverlight framework, developers can take advantage of all the Silverlight components, such as data grids, sliders, panels, and text controls, when building custom applications.

The What's New document describes important changes that occurred during the beta period that may require you to change your existing code.

The ArcGIS API for Silverlight / WPF delivers interactive and flexible mapping components that will help you build great end user experiences. Hope you enjoy it!