Developing Web Applications with the Web ADF  

Customizing the Web Mapping Application



Many applications created using Manager are customized to meet specific needs.  The Web Mapping Application can be customized using Visual Studio or Visual Web Developer 2005 Express Edition.   A great deal of customization can be done in Visual Studio that does not require programming. However, if you want, you can modify the application further by taking advantage the different application programming interfaces (API's).

This topic focuses on making customizations in Visual Studio without programming. Once you become familiar with your  and how to customize without programming, your next step is to understand the different API's available. A good place to begin is Developing Web Applications using the Web ADF, which provides more details on developing and customizing applications using the different API's.

Opening an application in an IDE

The first step in customizing Web Mapping Application is to open it in Visual Studio or Visual Web Developer 2005 Express Edition (Express). When you first open the application in your IDE, it is opened in Source view, and you see the HTML and Javascript that makes up the main page called Default.aspx. When you change the view to Design view, you see a visual representation of the same information. You can use both views interchangeably. As you make changes to one view, they are reflected in the other view. You likely want to start in Design view, but there are occasions where it is easier to make modifications directly in the source.



Source view:
Source view

Design view:
Design view

The Web Mapping Application contains a number of Web controls, which are server-side objects included as part of the Web ADF. In many cases, the control represents a part of the user interface. The application includes Web controls specific to mapping such as Map, OverviewMap, and Toc (table of content) controls, among others. A control can also exist that is not seen on the page. The Web ADF has several of these types of controls for connecting to different data sources. The application also includes a number of HTML elements such as DIV and TABLE used in formatting the page. The following view is a closeup of the Web Mapping Application in Design view showing a visual representation of some of the Web controls.

Web controls


Each Web control contains a set of properties. If you look at the HTML source, each property has an attribute. In Design mode, the properties are summarized in a Properties dialog, which is located in the lower right of your IDE. The property is listed on the left, and the property value is on the right.


Properties dialog

How to open an application in an IDE

  1. Open Visual Studio or Visual Web Developer 2005 Express Edition (Express).
  2. Open your Web Mapping Application.

    Visual Studio: Click File | Open | Web site
    Express: Click File | Open Web site
  3. In the left panel, click Local IIS if it is not already selected.
  4. Select your application from the list and click Open.
  5. After the application opens, double click Default.aspx in Solution Explorer located in the upper right of the IDE. Default.aspx is the main Web page that shows the layout of the application either graphically or in HTML.
  6. By default, the page opens in Source mode, which shows the HTML source. In the lower left area of the IDE, click on the Design tab Design mode to switch to Design mode.

Accessing the Properties dialog

You can access Web control properties in the Property dialog one of two ways:
  1. Click on a Web control.

    Dropdown list
  2. Pick the Web control from the dropdown list in the Properties dialog box.

Adding tools to the toolbox when using Express

When you open Express the first time, the ESRI Web controls may not be included in the toolbox, and you must manually add them. You only need to do this procedure once.
  1. Expand the Toolbox if it is not already opened.

    Toolbar
  2. Right click below the General tab, and select Add Tab.
  3. Type in a name for the tab such as ESRI. The Web ADF controls will be placed under this tab.
  4. Right click below the new tab, and select Choose Items.
  5. In the dialog that appears, click Browse. Note: the dialog may take some time to appear.
  6. Navigate to <ArcGIS install directory>\dotnet.
  7. Select ESRI.ArcGIS.ADF.Web.UI.WebControls.dll, and click Open.
  8. Check everything in the ESRI.ArcGIS.ADF.Web.UI.WebControls namespace, which will likely be highlighted by default. You can sort the namespaces alphabetically by clicking on the Namespace tab.
  9. Click OK. The Web controls are added to the toolbox.

File structure of a Web Mapping Application

When you open a Web Mapping Application in an IDE, you will see the following folders and files:
Solution explorer

The Web Mapping Application may also use files in the common ASP.NET folder aspnet_client stored in the root IIS folder. These files are normally in C:\Inetpub\wwwroot\aspnet_client\ESRI\WebADF. This folder contains images, JavaScript libraries, and stylesheets used by the ESRI Web controls. The ESRI Web controls will use these resources if the control has its UseDefaultWebResources set to false (if true, then these resources are pulled from the ESRI .NET assemblies installed on the server). If you deploy a Web Mapping Application to a new server, these files must be made available by installing, at a minimum, the ADF Runtime.

Mapping page: Default.aspx

Default.aspx is the main mapping page in the Web application. It contains Web controls to display a map along with related items such as a table of contents, an overview map, and tools to interact with the map. In addition to Web controls, the page uses a combination of panel controls, div elements and tables to format the page. At the highest level, the page is divided into three ASP.NET panel controls.


In design view, the application resembles the following:


Panels in Design view


Web controls on the mapping page

The Default.aspx page contains a number of controls for displaying and interacting with map information. These include (bold = ESRI Web ADF controls):
Selecting a different overview map

In Manager, you can select whether you want to include an overview map and which service to use.  Manager restricts the list of services to those already selected for display in the map. In many cases, your maps show detail appropriate for its size on the screen, including labels and symbols. Overview maps are much smaller, and it is often better to show less detail. This can be accomplished by selecting a secondary service for the overview map.

If you want to select a different overview map not in the map, you can make this change in your IDE. The process for selecting a different overview map is to first add a service to the list of map resources. Next, you hide this map from view and from the table of contents. Finally, you associate the overview map with the new map you added to the list of map resources.

Further reading

For more details about the OverviewMap control, see the topic OverviewMap control.

For more information about adding services, see MapResourceManager Control.

How to select a different overview map

  1. In Design view, click the MapResourceManager control, or select MapResourceManager1 from the dropdown list in the Properties window.
  2. Click on the ResourceItems property, and then click the ellipsis Ellipsis button. The MapResourceItem Collection Editor appears.
  3. Click Add. A new resource is added.
  4. On the right-hand side, click on the Definition property, and then click the ellipsis button. The Map Resource Definition Editor appears.
  5. In the editor, select the type of service you want to add from the dropdown list.
  6. Click the ellipsis button for Data Source. Add the required information for your data source.
  7. Click the ellipsis button for Resource, and select a service from the dropdown list. Click OK.
  8. Click OK to dismiss the Map Resource Definition Editor.
  9. On the right-hand side of the Collection Editor, click on the Name property. Type in the name of your service.
  10. Click on the DisplaySettings property, and then click the ellipsis button. The Map Resource Display Settings Editor appears.
  11. Uncheck Visible, and uncheck Display in the Table of Contents. Click OK to dismiss the editor.

    Uncheck properties
  12. Click OK to dismiss the MapResourceItem Collection Editor.
  13. Next you must reference the new service in the overview map. Click the OverviewMap control in the lower left of the Design area, or select OverviewMap1 from the dropdown list in the Properties window.
  14. Click on the OverviewMapResource property. Select the service you want for the overview map from the dropdown list.
  15. Save your changes.
  16. To see your changes in a browser, select File from the menu, and click View in Browser.

     
Changing navigation properties

The navigation control allows users to pan the map by clicking on different points of the control. In Manager, you can select whether you want to include a navigation control and which font symbol or image should be used. In your IDE, you can also change the size of the north arrow, the output image format, and how quickly the map moves when it is used for navigation.

Further reading

For more details about the Navigation control, see the topic Navigation control.

How to change Navigation control properties

  1. Click on the Navigation control in the left area of the design area, or select Navigation1 from the Properties dropdown menu.
  2. Change property values as desired. Some common properties are:
    • DisplayCharacter: the font and character index of a glyph.
    • ImageFormat: Output format for the image.
    • Size: Size of the image in points.
    • Speed: the higher the value, the faster the map moves.
  3. Save your changes.
  4. To see your changes in a browser, select File from the menu, and click View in Browser.

Changing table of contents properties

In Web Manager, you can select whether you want to include a table of contents (Toc), if users can turn layers on and off in the Toc, and whether to include swatches. When using your IDE, you can also change the font and set the Toc to be fully expanded when the application is first opened.

Further reading

For more details about the Toc control, see the topic Toc control.

How to change Toc control properties

  1. Click on the Toc control, or select Toc1 from the Properties dropdown menu.
  2. Change property values as desired. Some common properties are:
    • ExpandDepth: a value of 2 means the Toc will expand to the second level by default. This expansion is enough to see the swatches.
    • Font: font used for specifying layer names.
    • ForeColor: font color.
    • ShowLayerCheckBoxes: allow users to turn layers on and off.
    • ShowResourceCheckBoxes: allow users to turn services on and off.
    • TocType: choose whether to include swatches.
  3. Save your changes.
  4. To see your changes in a browser, select File from the menu, and click View in Browser.

Changing scale bar properties

In Web Manager, you can select whether you want to include a scale bar, and you can also set the scale bar units, bar color, and text color. When using your IDE, you can also change the scale bar font, bar height, and bar length.

The scale bar can be used with ArcGIS Server services and ArcIMS 9.2+ Image Services. No scale bar is displayed for ArcMap Image Services, WMS services, ArcWeb Services, or Image Services from a 9.1 or earlier server.

Further reading

For more details about the Scalebar control, see the topic ScaleBar control.

How to change Scalebar control properties

  1. Click on the Scalebar control, or select Scalebar1 from the Properties dropdown menu.
  2. Change property values as desired. Some common properties are:
    • BarColor: scale bar color
    • BarFont: font used for scale bar text
    • BarHeight: height of the scale bar
    • BarUnits: scale bar units such as miles or kilometers
    • ForeColor: font color
    • Width: bar length
  3. Save your changes.
  4. To see your changes in a browser, select File from the menu, and click View in Browser.

Adding a copyright to your map

You cannot add a copyright to a Web application in Web Manager. However, you can add one in your IDE. The easiest way to add a copyright is through the HTML source rather than in Design view. In the following example, "Copyright ©2006" is added to the lower left area of the map. 
<div style="position:absolute; bottom:15px; left:20px; z-index:99;font-family:Arial; font-size:small; color:Black">
Copyright ©2006
</div>

In this example, the text is placed inside a div tag. You can format the placement location and text by using the style attribute.

Style property and value Description
position:absolute; Use absolute positioning with the text so that it does not move.
bottom: 15px; left:20px; The placement of the text. In this case, the text is placed 15 pixels from the bottom and 20 pixels from the left.
z-index; Sets the order of the element in the stack. You want to use a high number so that the copyright is always on top.
font-family:Arial; font-size:small; color:Black; The font family, size, and color you want to use.

If you are familiar with using the copyright in the ArcIMS HTML Viewer, you should be aware of the following:

How to add a copyright statement

  1. Click on the Source tab to access the HTML page.

    Source tab
  2. Search for "Map_Panel". You should see the following lines of HTML code: 
    <div id="Map_Panel" style="...">
  <esri:Map ID="Map1" runat="server" ...>
  </esri:Map>
</div>
  3. Before the final closing</div>, place the following line containing the copyright information. Modify the style attribute for your application as desired. 
    <div style="position:absolute; bottom:15px; left:20px; z-index:99;font-family:Arial; font-size:small; color:Black">
Copyright ©2006
</div>
  4. Save your changes.
  5. To see your changes in a browser, select File from the menu, and click View in Browser.

Aadding a north arrow to your map

When using Web Manager, no option is available for including a north arrow on the map. However, you can add one in your IDE. Adding a north arrow to the map is in addition to using the Navigation control , which can also be used a north arrow.

The easiest way to add a north arrow is through the HTML source rather than in Design view. In the following example, a north arrow is added to the lower left area of the map. 
<div style="position:absolute; bottom:25px; left:20px; z-index:98; font-family:ESRI North; font-size:36pt;color:Black;">
&#176
</div>

In this example, the text is placed inside a div tag. You can format the placement location and north arrow symbol by using the style attribute.

Style property and value Description
position:absolute; Use absolute positioning with the text so that it does not move.
bottom: 25px; left:20px; The placement of the text. In this case, the text is placed 25 pixels from the bottom and 20 pixels from the left.
z-index; Sets the order of the element in the stack. You want to use a high number so that the copyright statement is always on top.
font-family:ESRI North; font-size:36pt; color:Black; The font family, size, and color you want to use. In this example, ESRI North is the font, the color is black, and the north arrow will be one half inch high based on 72 points per inch.

The north arrow is represented by a keyboard character or a character entity. The following table gives two examples:

Character Symbol
Capital letter I or &#68 Char 68
&#176 (no keyboard equivalent in English) Char 176

Note: When using the ArcIMS HTML Viewer, a north arrow is included by default and is included on the map in an acetate layer. When using a Web Mapping Application, you must add the north arrow using HTML and Javascript rather than as an acetate layer.

How to add a north arrow

  1. Click on the Source tab to access the HTML page.

    Source tab
  2. Search for "Map_Panel". You should see the following lines of HTML code: 
    <div id="Map_Panel" style="...">
  <esri:Map ID="Map1" runat="server" ...>
  </esri:Map>
</div>
  3. Before the final closing </div>, place the following line containing the north arrow. Modify the style attribute for your application as desired. 
    <div style="position:absolute; bottom:25px; left:20px;z-index:98; font-family:ESRI North;
font-size:36pt;color:Black;">
&#176
</div>
  4. Save your changes.
  5. To see your changes in a browser, select File from the menu, and click View in Browser.

Using themes and style sheets

Themes are a built-in feature of ASP.NET 2.0. A theme defines the look and feel of pages and controls. Once a theme is properly referenced, all pages in an application use the same style as defined by the theme. Each theme is self-contained, making it easy to switch among different themes without affecting any of the code in the application.

Themes consist of a *.skin and *.css file plus any supporting images. These files can have any name, but the Web Mapping Application has standardized on the following: For the Web Mapping Application, each theme is created as a separate subdirectory inside the App_Themes folder. You can modify an existing theme or create a new one.

App_Themes directory

Some of the controls in the Web Mapping Application do not reference a theme's style sheet. Instead, colors and fonts are set within the properties of the control. These values will override any attributes set in the style sheet. In the following example, the Font and ForeColor (font color) properties have been set in the Properties window.

Properties


When an HTML page is sent to the client, the font information is included in the style attribute, which overrides any attributes in the style sheet. 
<span id="MapViewer_TitleTextShadowLabel" style="color:White;font-family:Verdana;font-size:12pt;font-weight:bold;position:
absolute; left: 5px; top: 5px;">Web Mapping Application</span>
In order to reference a style sheet, the property values for Font and ForeColor would need to be removed, and a value for CssClass would need to be added that references a class in the style sheet.

Modifying an existing theme in an application

  1. In Solution Explorer, double-click Web.Config to open the file.
  2. Scroll until you see the reference to the theme. The name of the theme reflects the directory your application is currently referencing. 
    <pages theme="Blue_Bridge" />
    Navigate to this directory in Solution Explorer.
  3. Double-click Default.skin or MapViewerStyleSheet.css to open the files. Make changes to fonts, colors, and other formatting attributes.
  4. Save your changes.
  5. Make Default.aspx the active page by clicking on the Default.aspx tab.

    Default.aspx tab
  6. To see your changes in a browser, select File from the menu, and click View in Browser.

Adding a new theme to an application

  1. Add a theme directory under App_Themes.
    • In Solution Explorer, right click on App_Themes, and select Add ASP.NET folder.
    • Add and rename the folder.
    • Right click on the new folder, and select Add Existing Item. Navigate to the location of the theme folder you want to use. Copy the *.css and *.skin file you want to use.
    • If necessary, repeat the procedure to add addition subfolders such as one for images.
    As an alternative, you can copy an existing directory under App_Themes.
  2. Make any changes to the files as needed.
  3. Update Web.Config to point to the new theme. In Solution Explorer, double-click Web.Config to open the file.
  4. Scroll until you see the theme reference. Change the theme reference to the new folder name. 
    <pages theme="mytheme" />
  5. Save your changes.
  6. Make Default.aspx the active page by clicking on the Default.aspx tab.

    Default.aspx tab
  7. To see your changes in a browser, select File from the menu, and click View in Browser.

Referencing a theme's style sheet in a control

  1. In Design view, click on a control, or select a control from the dropdown list in the Properties window.
  2. Check if the control has a CssClass property. If this property is populated, the control is referencing MapViewerStyleSheet.css.
  3. To reference the style sheet, set the value for CssClass to one of the classes in MapViewerStyleSheet.css. For example, you could set the CssClass value for MapViewer_TitleTextShadowLabel to "MapViewer_TitleBarStyle".
  4. In the next set of steps, you must remove attributes referencing fonts, colors, and other formatting attributes from the source code. First, click on the Source tab.

    Source tab
  5. If the cursor is not already at the control you want to change, search for the control.
  6. Remove any font, color, or other formatting attributes that are included in the style sheet. For example, for MapViewer_TitleTextShadowLabel, you would want to remove all the font attributes since these are already included in the MapViewer_TitleBarStyle class.

    Original:
    <asp:Label ID="MapViewer_TitleTextShadowLabel" runat="server" Text="Web
Mapping Application" Font-Size="12pt" Font-Names="Verdana" ForeColor="White"
Font-Bold="True" style= "position: absolute; left: 5px; top:
5px;"CssClass="MapViewer_TitleBarStyle">
</asp:Label>

    After font attributes have been removed:
    <asp:Label ID="MapViewer_TitleTextShadowLabel" runat="server" Text="Web
Mapping Application" style="position: absolute; left: 5px; top: 5px;"
CssClass="MapViewer_TitleBarStyle">
</asp:Label>
  7. Save your changes.

Adding or modifying template themes


If you want to make a theme available in Manager or Web Manager, you can add a new theme or replace an existing theme in the templates.
  1. Create a new theme or modify an existing theme inside one of your applications.
  2. Copy the theme directory from your application to the Manager or Web Manager templates directory typically located in the following locations:

    ArcIMS Web Manager:
    C# template: \Inetpub\wwwroot\ArcIMS\Manager\Applications\Templates\mv_cs\App_Themes
    VB template: \Inetpub\wwwroot\ArcIMS\Manager\Applications\Templates\mv_vb\App_Themes

    ArcGIS Server Manager:
    C# template: \Inetpub\wwwroot\ArcGIS\Manager\Applications\Templates\mv_cs\App_Themes
    VB template: \Inetpub\wwwroot\ArcGIS\Manager\Applications\Templates\mv_vb\App_Themes
  3. Close all browsers.
The next time you open Manager or Web Manager, your new or updated theme will be included in the dropdown list in Page Properties.

Adding and removing tools from the toolbar

When you use Manager, you can select whether or not you want to include a toolbar. The toolbar contains the following:

Toolbar

If you want to add or remove some tools, you can do so in your IDE using the Toolbar Collection Editor. Note that the toolbar may not be accessible in Design view when using Express editions.

You can easily add and remove zoom and pan tools. You should be aware that when you remove a tool and then add it back in, you will be adding an image from a different directory. When a Web Mapping Application is created, toolbar images are referenced from the image directory within the Web Mapping Application directory structure. When you add tools using the Toolbar Collection dialog, images are referenced from the aspnet_client\ESRI directory under wwwroot. The functionality is the same with these images, but the icons are different.

The Identify, Measure, and Magnifier tools are custom tools and cannot be added back easily through the Toolbar Collection Editor. Therefore, if you want to remove them, you may want to do it in the Source view. Using this workflow, you can easily add the images back in at a later date.

Further reading

For more details about the Toolbar Web control, see the topic Toolbar control.

Removing tools from the toolbar in Design view

  1. In Design view, click the Toolbar control in the upper left of the design area, or select Toolbar1 from the dropdown list in the Properties window.
  2. Click on the ToobarItems property, and then click the ellipsis Ellipsis button. The Toolbar Collection Editor appears containing a list of available toolbar items and current toolbar contents.
  3. In the Toolbar Items column, select a tool to remove.
  4. Click Remove.
  5. When done, click OK.
  6. Resize the toolbar, if necessary.
  7. Save your changes.
  8. To see your changes in a browser, select File from the menu, and click View in Browser.


Adding tools to the toolbar in Design view

  1. In Design view, click the Toolbar control in the upper left of the Design area, or select Toolbar1 from the dropdown list in the Properties window.
  2. Click on the ToobarItems property, and then click the ellipsis button. The Toolbar Collection Editor appears containing a list of available toolbar items and current toolbar contents.
  3. Select a tool you want to add from the left panel, and click Add.
  4. If you want to change the reference to the location of the image, click Show Properties. Otherwise, click OK.
  5. Click on the DefaultImage property, and then click the ellipsis button.
  6. Manually type in the path and image name. To reference the images directory associated with the application use "~/Images/" followed by the image name. An example is "~/Images/zoom-in.png"
  7. Save your changes.
  8. To see your changes in a browser, select File from the menu, and click View in Browser.

Removing and adding tools in Source view

  1. In Source view, search for "Toolbar1".
  2. Scroll a few lines until you see <ToolbarItems>.
  3. If you want to remove a tool, use HTML comment codes (<!-- . . .-->) to comment out the tool you do not want included in the toolbar. 
    <!--
    
<esri:Tool ClientAction="startMeasure()" DefaultImage="~/images/measure.png"
HoverImage="~/images/measure.png" JavaScriptFile="" Name="Measure"
SelectedImage="~/images/measure.png" Text="Measure" ToolTip="Measure" />
    
-->
  4. If you want to add a tool back in, remove the HTML comment code.
  5. Save your changes.
  6. To see your changes in a browser, select File from the menu, and click View in Browser.