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);

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.

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!

ArcGIS API for Flex events at the 2009 ESRI User Conference

Yesterday we posted about events for JavaScript developers at the 2009 ESRI International User Conference. Today here's a look at some of the offerings for Flex developers.

Special Interest Group

Tuesday, July 14th, 12 - 1 PM, Room 28A

Come to meet the development team and hear Kevin Hoyt, Adobe platform evangelist talk about the Adobe Flex framework. Kevin will provide sneak peeks in to the upcoming Flex 4 functionality. Royce Simpson, GIS Analyst for the City of Greely will also share his experience in working with the ArcGIS API for Flex.

Demo Theaters

The demo theaters are 45-minute presentations on specialized topics, offered in a smaller setting than the technical workshops. These Flex-related demo theaters are offered at the ArcGIS Server showcase in Exhibit Hall C.

Designing Effective User Experiences for Flex Applications

Tuesday, July 14, 2 - 3 PM

This session will discuss some ways to effectively use tools and functionality in designing engaging applications. We will also discuss some common pitfalls in designing Web applications and ways to avoid them.

Styling your Flex components

Wednesday, July 15th, 3 - 4 PM

This session will show ways to create a unique look and feel in your Flex applications. We'll discuss various ways to use styles and colors and also look at tools that will help in this regard.

Network Analyst Server: Routing for Web Applications Using ArcGIS JavaScript and Flex APIs

Thursday, July 16th, 9 - 10 AM

In this demo theater you can learn about creating and publishing network analysis services using ArcGIS Server 9.3.1. You'll then see how to use those services to add routing to JavaScript and Flex Web applications.

Technical Workshops

The technical workshops take place in a larger group setting than the demo theaters. This year's User Conference agenda offers the following ArcGIS API for Flex workshop:

Building Rich Internet Applications with the ArcGIS API for Flex

Wednesday, July 15th, 10:15 - 11:30 AM, Room 6E
Thursday, July 16th, 3:15 - 4:30 PM, Room 6C

This session will introduce you to the ArcGIS API for Flex and walk you through the experience of building a Web application with it. No prior knowledge of Flex is needed.

Lightning Talks

Monday, July 13th, 4:30 - 6:30 PM, Room 6A

New at this year's conference are a series of "Lightning Talks", which are five-minute presentations where users demonstrate their own inventive Web and mobile applications. We expect that various Flex-based applications will be showcased at the Lightning Talks, where you can meet and exchange ideas with their creators.

ArcGIS API for JavaScript events at the 2009 ESRI User Conference

If you're developing with the ArcGIS API for JavaScript, or you want to get started, there's plenty to learn at the 2009 ESRI International User Conference. Here's what you can look forward to.

Special Interest Group

Come join fellow JavaScript developers at the first ArcGIS API for JavaScript SIG. We are proud to have Dylan Schieman, CEO of SitePen and Co-founder of the Dojo Toolkit come and present to us. Dojo is a wonderful resource for building rich web applications. Dylan will talk about Dojo and what possibilities Dojo provides for you, the ESRI JavaScript developer.

Demo theaters

The demo theaters are 45-minute presentations on specialized topics, offered in a smaller setting than the technical workshops. All JavaScript-related demo theaters are offered at the ArcGIS Server showcase in Exhibit Hall C.

Enhancing ArcGIS JavaScript Applications using Dojo Dijits

Thursday, July 16th 12-1PM

Describes how you can add interactivity to your Web applications with Dojo dijits. You'll see how the presenters built this San Diego Neighborhoods example application that uses Dojo layouts, buttons, accordion containers, and charts.

Network Analyst Server: Routing for Web Applications using ArcGIS APIs for JavaScript and Flex

Thursday July 16th 9 - 10 AM

In this demo theater you can learn about creating and publishing network analysis services using ArcGIS Server 9.3.1. You'll then see how to use those services to add routing to JavaScript and Flex Web applications.

Technical workshops

The technical workshops take place in a larger group setting than the demo theaters. This year's User Conference agenda offers the following ArcGIS API for JavaScript workshop:

Building Mashups Using the ArcGIS API’s for JavaScript

Wednesday, July 15th 1:30-2:45PM, Room 6E
Thursday, July 16th 10:15-11:30AM, Room 6E

This session will teach you how to build applications with the ArcGIS API for JavaScript by walking you through the online samples in the SDK and covering best practices.

GIS Design Methods

Tuesday, July 14th 8:30 - 9:45 AM, Room 30B

Applicable for ArcGIS API for JavaScript developers, this session will talk about preparing data for the Web and how to effectively expose that data from a Web application.