Developing Web Applications with the Web ADF - Web controls  

FindAddressTask control



The FindAddressTask control utilizes resources in the GeocodeResourceManager to perform geocode operations. Geocoding is the process of converting a description of a location, such as an address, to a x,y map coordinate. The user input form is created dynamically at runtime based on the inputs required by the geocode resource. The match or address candidate results are provided as an ADO.NET DataSet, and are typically displayed in a TaskResults control.  If the geocoded locations are displayed in a TaskResults control which is buddied to a Map control, each point will be represented as a graphic in the Map. 

Assembly: ESRI.ArcGIS.ADF.Tasks.dll
Class: ESRI.ArcGIS.ADF.Tasks.FindAddressTask

Using the FindAddressTask control
  1. Add supporting controls to the page

    In order to take full advantage of the FindAddressTask control, a number of supporting controls must be available.  Set up a Web application with MapResourceManager, GeocodeResourceManager, and Map controls using their discussion topics as a guide. Be sure to point the GeocodeResourceManager to an available geocoding resource. Add a TaskResults control using that control's discussion topic as a guide.  At runtime, the TaskResults control displays the results of the FindAddressTask.  Through the TaskReslts control, geocode results are displayed as interactive client-side graphics with map tips (by default).  Users can then interact with the results to change map extent, display selected features, or re-execute the task. TaskResults also displays a message to the user while the task executes.

    The GeocodeResourceManager determines the behavior of the geocoding, including minimum score and whether to find all candidates or just the best one. See that control's discussion for information on setting those properties.

    To hide the find address panel at website startup, set the FindAddressTask.Visible property to false.  To allow the user to call up the form from a link on the page, add a Menu control from the standard ASP.NET Navigation tools, and then add a TaskManager from the ArcGIS Web Controls toolbox group.   Set the BuddyControl property of the TaskManager to the Menu control you added.  If you want to display the address form immediately upon application startup, make sure the FindAddressTask.Visible property is set to true.  Note, a TaskManager and ASP.NET Navigation control are not required to use the FindAddressTask, they are merely designed to assist when using the task at runtime.  

    Also set the Map property of the TaskResults control to the Map control you added if you want users to see results highlighted on the map when selected.
  2. Add a FindAddressTask control

    In Visual Studio, display the prepared Web form in design mode, select the Toolbox, and expand the ArcGIS Web Controls tab.  Drag and drop a FindAddressTask control into the TaskManager control (or if you did not add a TaskManager control, just drag the FindAddressTask onto the page). Your page might resemble the following layout, arranged using a table:

    Visual Studio design page with FindAddressTask

  3. Set the properties for the FindAddressTask control

    In design mode, click on the FindAddressTask. The Properties window displays properties for the FindAddressTask.

    FindAddressTask properties 
    1. Set the TaskResults container

      Click the first item in the smart tag menu to choose the Task Results container, or click the TaskResultsContainers property button in the Properties window. This brings up the BuddyControl collection editor. Click Add to add an item to the collection. With the TaskResults1 item selected, in the right side of the dialog, click the drop-down list and select the TaskResults control you added earlier. This is where the FindPlaceTask displays results that are found when the user executes a query.

      QueryAttributesTask result container dialog 
    2. Set the task and query results properties

      Using the smart tag on the FindAddressTask, select the "Configure Task" option.  One dialog with two tabs will be displayed. 

      The General tab will enable you to set the GeocodeResourceManager and GeocodeResource you want to use with the FindAddressTask.    You can also set the runtime name of the task (as it appears in the ASP.NET Navigation control), the text of the button in the task to initiate the execute the task, and a help tip to provide end users with some assistance at runtime when the mouse cursor hovers over the FindAddressTask panel (e.g. provide address examples to illustrate input format).

      FindAddressTask properties


      The Results tab enables you to set the render properties of match candidates returned from executing the FindAddressTask.  A TaskResults control is required and must be configured as a task results container for the FindAddressTask (see additional property setting discussion below).  The TaskResults control must be buddied with a Map control to view the FindAddressTask results in the Map.  The Results tab contains two buttons to set the default renderer and highlight renderer of address match results.   At runtime, match candidate locations will be displayed in a map as graphic features using these renderers.  When hovering over a result in the TaskResults control or a match location graphic feature in the map, the respective highlight renderer will be displayed.  The "Show MapTips" check box will enable MapTips on each match location graphic feature and display the match fields returned for each candidate. 

      FindAddressTask properties

      Optionally, you can set some of these properties via the properties dialog in Visual Studio.         
    3. Set the GeocodeResourceManager property to the control added earlier, using the drop-down list.
    4. Set the GeocodeResource property to one of the available geocode resources in the drop-down list. If none appears in the drop-down list, ensure that the GeocodeResourceManager property is set, and that the GeocodeResourceManager control on the page has been set up with at least one geocoding resource.
    5. For the TaskResultsContainers (in the Task property group), add the TaskResults control added earlier. Click the ellipsis button in the property's value box to open the BuddyControl Collection Editor. Add an item to the buddy control list, and then set its Name to the TaskResults control by using the drop-down list. If this is not set, no results will display on the Web page.  Optionally
    6. If you have added a Menu control and buddied it to the TaskManager control, and want to hide the find-address input form until the user clicks the link for finding addresses, then set the Visible property to False.
  4. Setting the position of the address input form

    By default, the FindAddressTask form appears in a floating window, which the user may drag to a new position within the web page. The opening position does not necessarily correspond to its position on the web page design form. If preferred, the task panel displayed at runtime may be fixed at a specific position.

    To fix the position of the form at a specific location, set the position style of the FindAddressTask or a containing control or DIV. To set the style, switch the Web page from Design view to HTML view in Visual Studio. Find the FindAddressTask in the page listing. Insert a style attribute within the control tag, and set its position properties to specific values. Use "position:absolute" to set the query form at an exact position on the page. Use "position:relative" to fix the position relative to its placement to other controls. In the following example, relative placement is used to ensure the query window is placed within a table cell:

    <td>
      <esriTasks:FindAddressTask style="position:relative;top:5px;left:0px;" 
        ID="FindAddressTask1" runat="server" ...>
      </esriTasks:FindAddressTask >
    <td>

    When fixing the position of the query window, you may want to set the CloseButton, Draggable, ExpandCollapseButton, HeightResizable and WidthResizable properties to false to disallow modifying the query form. Setting Draggable to false disallows moving the query window.

    Optionally, in design view you can right click on the task control and set the position property.  The design time location of the task control will not change.  At runtime, the task panel used to provide input and execute the task will be displayed in the position defined for the task at design time. 
  5. Other properties for FindAddressTask

    Some of the properties that you may wish to modify for your application include:
    • Title: Displayed to the user at the top of the address input form. You should change this from the default, which is the ID of the control. Choose a title that describes what the task does. An example would be "Find an address".
    • ButtonText: Text for the button the user clicks to execute the task
    • FeatureSelectionColor: After the query results display, and the user checks the box next to a feature, the feature is highlighted with this color on the map.
    • ShowDetailsInTable: Whether to display feature attributes in the query results for each feature
  6. Using the FindAddressTask at runtime

    Using the FindAddressTask is similar to using other tasks. The number and name of input text boxes are determined dynamically at runtime from the geocode resource. Typically the inputs include street address and other fields. An example of the query form the user might see would be:

    FindAddressTask at runtime

    The user enters values for each form item, then clicks the find button. The results are displayed in the TaskResults control output. See TaskResults for a discussion and examples of using the results from a query.
Members

Properties 

  The following table provides a list of properties of interest.  For complete reference information, see the FindAddressTask control in the library reference section.

Property Name  Type Description
ButtonText string The text which appears on the button to executes the task.
FeatureSelectionColor Color The Color of selected features.
GeocodeResource string  Name of the geocode resource used by this task.
GeocodeResourceManager string Name of the geocode resource manager from which the geocode resource is retrieved.
GroupResultsByTable bool Whether the results of this task will have the results grouped by layers.
NavigationPath string The path to the task as it would appear in a hierarchical data control buddied to the task's TaskManager.
ShowFieldAttributes bool Whether the results of this task will have the field attributes.
ShowLegend bool Whether the results of this task will have a legend. Legend is only available if GroupResultsByTable is true.
TaskResultsContainers BuddyControl Collection The controls in which results from this task are displayed.