Developing applications  

Extending Manager Web applications



To create feature rich Web applications without writing code, use the Manager Web application.  See the section titled  Developing Web Applications with Manager for additional details.   Manager creates a predefined Web application, ready for deployment.  Although Manager provides a number of options to customize your Web application, you may choose to extend it further.

Web applications created from Manager use the same template as is used when creating a new website in Visual Studio 2005 with the "Web Mapping Application" template. Manager sets properties in the template, such as the map servers and services, as well as tasks included and the theme (colors, logos, etc.) of the application.

Whether created in Manager or Visual Studio, a web mapping application contains standard web page design elements, plus web controls. These web controls include both standard ASP.NET web controls, as well as ESRI ADF-specific web controls.

You can modify the contents of a web mapping application by adding, removing and modifying web controls and other web content.

Contents of a web mapping application

The web mapping application contains the following items: Web Mapping Application file list

The web mapping application also uses 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 web mapping application must have access to these files to function properly. If you deploy a web mapping application to a new server, these files must be made available by installing the ESRI ADF, either by installing the ADF Runtime or the ADF from the ArcGIS Server or ArcIMS CD. File-based websites using the built-in Visual Studio web server ("Cassini") may also have issues if the common folder is not accessible.

Mapping page: Default.aspx

Default.aspx is the main mapping page in the web application. It displays by default when the application opens. 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.

This page also has code for communicating with the server, such as for obtaining map image tiles. The page communicates with the page without refreshing the entire web page. It does this with a technique known as callbacks. This allows sending messages to the server and displaying the result within just the relevant section of the page. For example, the page manages callbacks when the user clicks on the map with the Identify tool, in which the information is obtained and displayed in the Task Results panel without a full page postback.

The default.aspx page contains a set of web controls and formatting elements. In design view in Visual Studio 2005, the application resembles the following:

Web Mapping Application design view

The web mapping 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.

Web Mapping Application layout

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

Theme sample

Themes

Themes are a new feature in ASP.NET 2.0. A theme defines the look of pages and controls across the entire site. Themes allow easy switching between different looks and styles in the web applications. These changes can occur without affecting any of the code in the application. Themes consist of three types of files on disk:

Each theme is created as a separate subdirectory inside the App_Themes folder of the web application.
Theme files

The ESRI web mapping application contains a number of available themes. Manager allows you to set the theme. The theme name is stored in the web.config file. You can modify the theme by changing the theme attribute in the pages property:

    <pages theme="Map_Viewer">

You can also modify existing themes or create your own themes for a customized look and feel to your application.

For more information on themes, see http://msdn2.microsoft.com/en-us/library/ykzx33wh.aspx.

SiteMap for hyperlinks

SiteMap is another new feature in ASP.NET 2.0. It allows you to define website structure and relationships between pages. A typical use is to show "breadcrumb" navigation, where a user drills down into subsections of a website. The web mapping application uses a SiteMap to display hyperlinks to other web pages. The Manager application allows you to define these links. For example, you might add a hyperlink to the home page of your organization.

To use a SiteMap, we set up several items in the website. First, we define the links in a file called Web.sitemap. You will find this file in the main web application directory. The default sitemap links if you do not change them are:

<?xml version="1.0" encoding="utf-8" ?> 
  <siteMap xmlns="http://schemas.microsoft.com/AspNet/SiteMap-File-1.0" > 
    <siteMapNode url="~/Default.aspx" title="Map Viewer" description="Map Viewer"> 
    <siteMapNode url="http://www.esri.com" title="ESRI" description="ESRI" />
    <siteMapNode url="http://support.esri.com" title="ESRI Support Center" description="ESRI Support Center" /> 
    <siteMapNode url="Help/Default.htm" title="Help" description="Help" /> 
 </siteMapNode> 
</siteMap>

Second, a SiteMapDataSource control is added to the page. In source view of the web mapping application, you will find this control inside the LinkBar panel following the Toolbar control. It appears similar to the following:

<asp:SiteMapDataSource ID="SiteMapDataSource1" runat="server" ShowStartingNode="false" SiteMapProvider="AspnetXmlSiteMapProvider" />

Third, a Menu control is added to the page, and its DataSourceID is set to the SiteMapDataSource just added. This binds the site map's data to the menu control.

<asp:Menu ID="TitleMenu" runat="server" DataSourceID="SiteMapDataSource1" BackColor="Transparent" 
    Orientation="Horizontal" Font-Size="8pt" OnDataBound="TitleMenu_DataBound" SkinID="TaskBarSkin" Target="_Blank">
  <StaticMenuItemStyle ItemSpacing="4px" />
</asp:Menu>

This displays the links in the browser, which the user can click on to navigate:
SiteMap links in browser

JavaScript resources

The web mapping application uses JavaScript to perform many client-side functions, such as map-click interaction and retrieving data from the server via callbacks. JavaScript library files may be retrieved from the server in one of three ways:

The ESRI web controls that use JavaScript resources have two properties that determine where the resources are drawn from:

Tools

The toolbar in the web mapping application template includes both standard and custom tools. The standard tools are: zoom in, zoom out, pan, and full extent. The custom tools are: identify, measure, and magnifier. Standard tools may be added using the ToolbarItems property dialog in Visual Studio. The three custom tools all act using client-side JavaScript functions. These settings may be observed in the ToolbarItems property dialog.

For more information on the toolbar, see the Toolbar control discussion. For information on creating custom tools, see Creating custom tools and commands.

Tasks

Tasks are focused units of work that are packaged into components. These components may be added to the web mapping application via the Task framework. Typically, you add the task to the Task Manager control that is already in the application. The task component interacts with the map or other data, and generates results. Those results are typically displayed in the TaskResults web control.

Tasks included with the Web ADF are: Editing, FindAddress, FindPlace, Geoprocessing, QueryAttributes, and SearchAttributes. Some tasks work only with certain data source. For example, the Editing task only works with ArcGIS Server Local data sources, and requires that the data layers be in an ArcSDE geodatabase. For more information on standard tasks, see Configuring tasks in the ArcGIS Server Help, or see the ArcIMS Manager Help, under the topic "Configuring Tasks".

For information about creating custom tasks, see Working with Tasks. More information may also be available online at http://edn.esri.com.

The web mapping application includes a Measure function that has some similarities to a task, although it uses a different approach. The Measure function is opened via a toolbar item, and displays in a floating panel. It allows users to measure distance and area on the map.

Walkthrough: Adding a custom tool to the web mapping application

This walkthrough shows how to create a custom tool and add it to the web mapping application. This tool will allow the user to click on the map to add a graphic point. To accomplish this customization, do three types of steps. First, we add a graphics layer to the MapResourceManager control. Second, we create a class library that contains the code for the tool implementation. Third, we add the tool to the Toolbar control and use the class library we created.

  1. To start, create a Web application using ArcGIS Manager or ArcIMS Web Manager, or use the QuickStart Creating a Web application with the template as a guide.
  2. Start Visual Studio 2005 (or Visual Web Developer Express), and use the Start Page or the File-Open-Website option to open the website you just created. In the dialog for opening the website, use the Local IIS option to navigate to the website and open it. The files of the website will display in the Solution Explorer (see the example at the top of this page).
  3. Double-click the Default.aspx page in Solution Explorer to open it. It will display initially in the HTML code view. Click the Design tab at the bottom of Visual Studio to switch to design view. The design should resemble the graphic shown above under the Mapping Page topic.
  4. Next we add a graphics layer resource to the map. The graphics layer will hold the points that the user adds.
    1. Click the MapResourceManager1 control on the page to select it. Click the "smart tag" in the upper right of the control to expose the context menu, and click Edit Resources to display the MapResourceItem Collection Editor:
      MapResourceManager smart tag
      down arrow
      MapResourceItem collection editor
      Note that you can also open the MapResourceItem Collection Editor from the properties of the MapResourceManager, under the ResourceItems property.
    2. In the MapResourceItem Collection Editor, click Add to add a second resource item. It will be named MapResourceItem1.
    3. With the new resource item highlighted, click in the Name property on the right side, and rename the resource to graphicsLayer.
    4. Click in the Definition property, which displays an ellipsis button (...). Click the button, which opens a new dialog for the Map Resource Definition Editor.
    5. In the MapResource Definition Editor, click the Type drop-down and select Graphics Layer. No other properties need to be set for this resource type. Click OK to dismiss this dialog.
    6. Before closing the MapResourceItem Collection Editor, move the graphics layer to the top of the map control's display. To do this, make sure the graphics layer item is highlighted in the left side of the dialog. Then click the up-arrow in the upper middle part of the dialog, which will move the new resource item to the top, above the map (which is named MapResourceItem0). Your dialog should resemble the following:

      MapResourceItem Collection Editor with graphics layer
    7. Click OK to close the MapResourceItem Collection Editor.
  5. Next we will create the class library for the custom tool. We will add this class library as a code file within the application itself, in the App_Code directory. ASP.NET 2.0 uses this folder for application-level class libraries. If you wanted to create a class library to share among many applications, you would probably author it in a separate Visual Studio project, compile it, and then you could copy the compiled DLL into the bin directory of the website. We will just use the application-level approach here.
    1. With the website open in Visual Studio 2005 (or Visual Web Developer Express), right-click in the Solution Explorer on the App_Code folder within the website. In the menu that pops up, choose Add New Item. The Add New Item dialog opens. In this dialog, make sure the Class item is highlighted in the Templates area. For the name, enter GraphicPointTool.vb (if using VB, use the .vb extension; if using CSharp, use .cs). Make sure the language option is set to the one in your website -- you can only have one language type in the App_Code directory and page-behind files. Click OK to add the file and open it in the editor. Note that the new class is named the same as the file.
    2. At the top of the new class file, before the Public Class GraphicPointTool statement, add these references to your class file. This enables us to use classes within these namespaces without citing the full path.

      [C#] 
      using ESRI.ArcGIS.ADF.Web.DataSources;
using ESRI.ArcGIS.ADF.Web.DataSources.Graphics;
using ESRI.ArcGIS.ADF.Web.Display.Graphics;
using ESRI.ArcGIS.ADF.Web.Display.Symbol;
using ESRI.ArcGIS.ADF.Web.Geometry;
using ESRI.ArcGIS.ADF.Web.UI.WebControls;
using ESRI.ArcGIS.ADF.Web.UI.WebControls.Tools;
      [VB] 
      Imports ESRI.ArcGIS.ADF.Web.DataSources
Imports ESRI.ArcGIS.ADF.Web.DataSources.Graphics
Imports ESRI.ArcGIS.ADF.Web.Display.Graphics
imports ESRI.ArcGIS.ADF.Web.Display.Symbol
Imports ESRI.ArcGIS.ADF.Web.Geometry
Imports ESRI.ArcGIS.ADF.Web.UI.WebControls
Imports ESRI.ArcGIS.ADF.Web.UI.WebControls.Tools
    3. To use our new class as a tool in the mapping application, it must implement the IMapServerToolAction interface. We must add two items to the class in this case. First, we add the IMapServerToolAction interface designation to the class itself. Second, IMapServerToolAction requires the ServerAction method. Add code to your class for these two requirements (Visual Studio may insert the method automatically when you add the interface name):

      [C#] 
      public class GraphicPointTool: IMapServerToolAction
{
    void IMapServerToolAction.ServerAction(ToolEventArgs args)
    {
    
    }

}
      [VB] 
      Public Class GraphicPointTool
    Implements IMapServerToolAction

    Public Sub ServerAction(ByVal args As ToolEventArgs) Implements IMapServerToolAction.ServerAction

    End Sub
    
End Class

      All of the code below will be inserted into the ServerAction method, before the End Sub or the first closing brace "}".
    4. Now we add code inside the ServerAction method to add the graphic point to the map where the user clicked. The args argument contains the screen location of the click. We can also get a reference to the Map control from args. Add this code inside the ServerAction method:

      [C#] 
          // Get a reference to the map from the method argument
    Map map = (Map)args.Control;

    // Get the point the user clicked from the method argument
    PointEventArgs pea = (PointEventArgs)args;
    System.Drawing.Point screen_point = pea.ScreenPoint;
      [VB] 
          ' Get a reference to the map from the method argument
    Dim map As Map = CType(args.Control, Map)

    ' Get the point the user clicked from the method argument
    Dim pea As PointEventArgs = CType(args, PointEventArgs)
    Dim screen_point As System.Drawing.Point = pea.ScreenPoint
    5. We then convert the pixel coordinates to map coordinates:

      [C#] 
       ESRI.ArcGIS.ADF.Web.Geometry.Point
    point; point = ESRI.ArcGIS.ADF.Web.Geometry.Point.ToMapPoint(screen_point.X,
        screen_point.Y, map.Extent, (int)map.Width.Value, (int)map.Height.Value);
      [VB] 
          Dim point As ESRI.ArcGIS.ADF.Web.Geometry.Point
    point = ESRI.ArcGIS.ADF.Web.Geometry.Point.ToMapPoint(screen_point.X, _
        screen_point.Y, map.Extent, CInt(map.Width.Value), CInt(map.Height.Value))
    6. We will add the point to the GraphicsLayer resource that we created earlier in the MapResourceManager. However, we cannot add the point directly to the resource. Instead, we add it to an ElementGraphicsLayer, which is in turn added to the resource. An ElementGraphicsLayer is a simple type of graphics layer. If we want more complex interaction with the graphics, we could create a FeatureGraphicsLayer instead. A FeatureGraphicsLayer behaves similarly to a map layer. For now, we will use the simpler ElementGraphicsLayer.

      We retrieve the ElementGraphicsLayer from the map resource. The first time we add a point we need to create the ElementGraphicsLayer. Add this code immediately after the previous code:

      [C#] 
          ESRI.ArcGIS.ADF.Web.DataSources.Graphics.MapResource gResource = null;

    // Find the GraphicsLayer resource added to the MapResourceManager
    foreach (IGISFunctionality gFunc in map.GetFunctionalities())
	{
        if (gFunc.Resource is ESRI.ArcGIS.ADF.Web.DataSources.Graphics.MapResource)
        {
            gResource = (MapResource)gFunc.Resource;
        }
    }

    // Find the ElementGraphicsLayer in the graphics resource just found
    ElementGraphicsLayer gLayer = null;
    foreach (System.Data.DataTable dt in gResource.Graphics.Tables)
    {
        if (dt is ElementGraphicsLayer}
        {
            gLayer = (ElementGraphicsLayer)dt;
        }
    }

    // ElementGraphicsLayer will not exist first time a point is added--create it now
    if (gLayer == null) 
    {
	    gLayer = new ElementGraphicsLayer();
        gResource.Graphics.Tables.Add(gLayer);
    }
      [VB] 
          Dim gResource As ESRI.ArcGIS.ADF.Web.DataSources.Graphics.MapResource = Nothing

    ' Find the GraphicsLayer resource added to the MapResourceManager
    For Each gFunc As igisfunctionality In map.GetFunctionalities()

        If TypeOf gFunc.Resource Is ESRI.ArcGIS.ADF.Web.DataSources.Graphics.MapResource Then
            gResource = CType(gFunc.Resource, MapResource)
        End If
    Next

    ' Find the ElementGraphicsLayer in the graphics resource just found
    Dim gLayer As ElementGraphicsLayer = Nothing
    For Each dt As System.Data.DataTable In gResource.Graphics.Tables
        If TypeOf dt Is ElementGraphicsLayer Then
            gLayer = CType(dt, ElementGraphicsLayer)
        End If
    Next

    ' ElementGraphicsLayer will not exist first time a point is added--create it now
    If gLayer Is Nothing Then
	    gLayer = New ElementGraphicsLayer()
        gResource.Graphics.Tables.Add(gLayer)
    End If

      Notice that the ElementGraphicsLayer inherits from the standard .NET DataTable class. It extends DataTable by adding geometry attributes and more capabilities.
    7. Now that we have the graphics layer object, we can add the point to it. We do this by creating symbology for the point, and creating a GraphicElement to hold the point's geometry and symbology. Then we add the GraphicElement to the graphic layer:

      [C#] 
          // Create the symbology for the point
    SimpleMarkerSymbol sms = new SimpleMarkerSymbol(Drawing.Color.Red, 20, MarkerSymbolType.Cross);

    // Create a graphic element to hold the point and its symbology
    GraphicElement ge = new GraphicElement(point, sms);

    // Add the graphic element to the graphics layer
    gLayer.Add(ge);
      [VB] 
          ' Create the symbology for the point
    Dim sms As New SimpleMarkerSymbol(Drawing.Color.Red, 20, MarkerSymbolType.Cross)

    ' Create a graphic element to hold the point and its symbology
    Dim ge As New GraphicElement(point, sms)

    ' Add the graphic element to the graphics layer
    gLayer.Add(ge)
    8. Finally, we refresh the map in order to show the new point. Note that by using the built-in client callback approach for tools, the map will redraw without refreshing the entire web page. The code below takes this one step further: if the browser client is handling the images of the graphics layer and the map separately (which is the map control default), we only need to refresh the graphics layer image. This way, the map does not need to be redrawn when we are only adding the graphic point.

      [C#] 
          if (map.ImageBlendingMode == ImageBlendingMode.Browser)
    {
        map.RefreshResource(gResource.Name);
    }
    else
    {
        map.Refresh();
    }
      [VB] 
          If map.ImageBlendingMode = ImageBlendingMode.Browser Then
        map.RefreshResource(gResource.Name)
    Else
        map.Refresh()
    End If

      Save the class library file.
  6. Now we can add the tool to the toolbar. We use the toolbar designer to add the tool, and point to the class we just created as the server-side action of the tool.
    1. With the website open in Visual Studio 2005 (or Visual Web Developer Express), open or switch to the Default.aspx page. Switch the view to Design view if necessary.
    2. For the images for the tool, you can use icons included with the developer kit, typically installed at C:\Program Files\ArcGIS\DeveloperKit\SamplesNET\Server\data\icons. Copy these icons into your website by right-clicking on the image folder and choosing Add Existing Item. Use the add-item dialog to navigate to the sample image folder and add these images: select_point_1.gif, select_point_1U.gif, and select_point_1D.gif. Clck OK to add these images to the images folder in your website.
    3. Click on the Toolbar control to select it. In the Properties window of Visual Studio, click in the value of the ToolbarItems property, which displays the ellipsis (...) button. Click this button to open the ToolbarCollectionEditorForm.
    4. In the ToolbarCollectionEditorForm, click the Tool item in the left-hand Toolbar Items list. Then click the Add button to add a new tool to the toolbar.
    5. With the new tool highlighted on the right side of the dialog, click the Properties arrow-button in the lower right. This expands the dialog to display the properties of the tool.
    6. Set the properties of the tool as follows (you can use the browse buttons to set the images):
      • DefaultImage = ~/images/select_point_1.gif
      • HoverImage = ~/images/select_point_1U.gif
      • SelectedImage = ~/images/select_point_1D.gif
      • Text = Add Point
      • ClientAction = Point
      • ServerActionAssembly = App_Code
      • ServerActionClass = GraphicPointTool
      The ClientAction determines how the user interacts with the map before the request is sent to the server. "Point" means the when user clicks on the map, the location is immediately sent to the server. If you created a tool that required a line or polygon you could choose one of those options.

      The ServerActionAssembly is set to App_Code when we include the tool class within the App_Code folder of the web application. If you created a tool in a separate project and added the reference to the current website project, you would use its assembly name instead.

      The ServerActionClass is the class within the ServerActionAssembly that implements the IMapServerToolAction interface. When using the App_Code option, the drop-down list will not find the class--you must type it in manually.

      Your toolbar properties should resemble this graphic:
      Toolbar properties

      Click OK to close the toolbar designer.
    7. Save the Default.aspx page.
  7. View the page in a browser by choosing File-->View in Browser. Test the tool by clicking the Add Point tool in the toolbar and clicking on the map to add graphic points to the map.

The flow in this custom tool is summarized in the graphic below. For more information on callback processing, see AJAX and the ASP.NET 2.0 Callback Framework.

  1. The user activates the Add Point tool in the toolbar, and clicks on the map. The browser captures the click location.
  2. The browser's client ADF code sets up the request to the server via a client callback (not a full page postback).
  3. The browser uses its built-in XMLHTTP object to send the request to the server without submitting the full page.
  4. On the server, the map control receives the callback request and sends the click location to the custom tool via its ServerAction method. The custom tool code adds the point to the graphic layer of the map's resources. The response is generated for the client, which includes information about updating the map control.
  5. The client processes the callback result to update its display.
  6. The map control's client-side script determines if any further action is needed (A-B-C), such as requesting map tiles around the current map, which may be necessary if the map operation involved moving the map (this is not required in our particular example of adding a point).

Custom tool flow

 

For more examples of adding graphics to the map page, see the samples Common_AddGraphics and ArcGIS_AddGraphics in the developer kit samples.