Developing Web Applications with the Web ADF - Web controls  

SearchAttributesTask control



The SearchAttributesTask control enables you to select a set of fields, in feature layers provided by resources, and search for a user provided value.  At runtime, each field is queried for the occurrence of a value provided by the user.  Partial values are permitted.  Only feature layers in resources provided by a MapResourceManager can be used.  In addition, feature layers must have unique layer names to work with the SearchAttributesTask.  The results are provided as an ADO.NET DataSet to be displayed in a TaskResults control.  

Assembly: ESRI.ArcGIS.ADF.Tasks.dll
Class: ESRI.ArcGIS.ADF.Tasks.SearchAttributesTask
Using the SearchAttributesTask control
  1. Add supporting controls to the page

    In order to take full advantage of the SearchAttributesTask control, a number of supporting controls must be available.  Setup a Web application with a MapResourceManager and Map control using their discussion topics as a guide. Add a TaskManager, Menu, and TaskResults control using their discussion topics as a guide. At runtime, the TaskResults control displays the results of SearchAttributesTask.  You can then interact with the results to change map extent, display selected features, or re-execute the task. 
  2. Add the SearchAttributesTask control to the page

    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 SearchAttributesTask control into the TaskManager control.  You should now see the following in Visual Studio:


  3. Set the SearchAttributesTask control properties

    In design mode, click on the SearchAttributesTask control and display the verbs associated with the control.



    a. Buddy the task control with the TaskResults control.

    To display the results of a task, you must buddy the task control with the TaskResults control.  Select the Choose Task Results Container verb to modify the TaskResultsContainers property.  In the buddy control dialog, add a new item and select the id of the TaskResults control you want to display in the task results. 

     

    b.  Configure the task.

    Click the second item in the smart tag menu to edit search attributes properties.  A dialog with a set of tabs is displayed which enables you to change the visible content on the task at runtime, set the search fields, and customize the display of results.  

    General Tab: On the general tab, you can change the task control name which is displayed by an ASP.NET Navigation control (e.g. Menu) and the text on the button to execute the task. 

    QueryAttributesTask result container dialog

    Settings Tab: On the Settings tab you can choose the fields you want to search.  Select from a list of fields in feature layers in map resources.  Only string fields can be searched.  Each field in each layer is searched for the occurrence of a user provided string.    


    QueryAttributesTask result container dialog


    Results Tab:  This tab defines how the results of a query are returned and presented to the client.   It is designed to work with explicitly with the capabilities of a TaskResults control.  
    • Use the Limit search results to Textbox to set the maximum number of records returned in the result.  If more records are returned from a search, paging will be enabled on the records rendered in the TaskResults container.  
    • Choose to group results from a query in TaskResults.  If checked (the default) results from a query will be contained in a parent node for display in TaskResults.  The parent node will have the same name as the queried layer and the number of records returned.  If unchecked, each result record will be added to the TaskResults control independently. 
    • Choose to show attributes for each record returned.  If checked (the default) attributes for each record returned from a search will be displayed in the TaskResults control.  If unchecked, only the primary display field will be displayed for each record node.
    • Choose to show Map Tips on the results displayed in the map.  If checked (the default) Map Tips callouts will be enabled on graphic results in the map. 


    • Choose the format for displaying results.  Layer formatting defined for the map resource item that contains the queried layer is used by default.  See the MapResourceManager discussion on defining layer definitions for more information.   You can choose to customize the format (symbology, fields, and attribute display) of results.  The tabs in the MapResourceManager Layer Definitions dialog and Query Attributes Properties Results tab are the same: Symbols, Fields, Records.
    • The Symbols tab enables you to define the default and highlight symbol for results generated by the query.   Click on the button next to "Draw with:" or "Highlight with:" to change the symbol.   When results are generated from a search layers at runtime, features will be rendered in the browser using the default ("Draw with:") symbol.   When the mouse cursor hovers over a feature, the highlight symbol ("Highlight with:") will display.  The feature type of the layer will determine the options for changing the symbol.
    • The Fields tab displays the fields in the search layer.   The check box next to each field can be used to set the field visibility.   You can also edit the text in the Alias field if you do not want to use the original field name.  

      The primary display field is often used to describe the contents of a record.  In general, it is set to a field that contains an intuitive, preferrably unique value to identify an attribute.  You can select the primary display field using the drop down box next to "Primary display field".  



      Results generated from searching a layer will contain only visible fields and use field aliases to define column names.  The primary display field will be used to define the node text for each record displayed in a TaskResults control.      

      For data sources that do not provide field settings, all fields are visible by default and the alias is the same as the field name. The primary display field is set to the first string field with "name" in it.   If no such field is found, the first string field is used.   If there are no string fields, the first numeric field is used. 
    • The Records tab displays the tabular format of results as displayed within the browser at runtime.  Record display properties for the query layer can be used to display results within a TaskResults control or in a MapTips callout window.  By default, visible fields are included in the record display as name value pairs and the title is the primary display field.



      To customize the look and feel of record display, select the Custom Formatting radio button.  The Title and Contents sections of the dialog are now editable.  The Contents section provides a rich text editor to modify font style and color or add fields, hyperlinks, tables or images.  Edits are stored as HTML style content to be rendered in the browser at runtime.  To view the HTML content that will be used to format layer results, select the HTML radio button at the bottom of the dialog.  The raw HTML content will be displayed in the Content window.  Any valid content to be rendered in a browser can be added - this includes HTML, CSS definitions, and JavaScript.


      c.  Set the Visible property to false.

      So the SearchAttributesTask control does not immediately display at runtime, make sure it is not visible.  When the user clicks on the menu item generated by the output from TaskManager, the task control will display.

  4. Run the application and execute the task

    At runtime, click on the My Search Attributes Task menu item, and the SearchAttributesTask dialog should display.  Enter a string value you expect to be in the search fields selected and click the Find button.  In the following example, the task is searching the US States layer for state names that contain the text "New".  When a task is executed at runtime, the TaskResults control displays an animated gif to indicate that the task is working.  A Cancel link is also displayed to cancel the task before it completes.   The arrow indicates the location of the task execution indicator in the TaskResults control. 




  5. Navigate the results of a task

    When SearchAttributesTask execution completes, the results are returned in the TaskResults control in a TreeView.  A user can expand and collapse the branches of the results collection to view result items.  If attributes are returned, a user can expand its branch to view feature attribute values.   If the box next to a feature node is checked, the feature will be selected in the map (by default all are selected).  If you hover over the feature node in the TaskResults control or the feature itself in the map, the feature will be highlighted.  In the example, below the mouse cursor is hovering over the 'New Mexico' feature node in the TaskResults control which highlights the state of New Mexico in the map.


  6. Using the context menu on the result items

    A user can right-click to display the context menu on a result item and select from the following options:
    a) Zoom to - zoom to the result item in the map
    b) Pan to - pan the map to center on the result item
    c) Remove - remove the result item from the task results list 


  7. Using the context menu on the task results 

    A user can right-click to display the context menu on the task results collection to:
    a) Rerun task -  execute the same task again and update this task result collection
    c) Remove - remove this task results collection from the TaskResults control




     

Members

Properties

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

Property Name  Type Description
ButtonText string The text which appears on the button to executes the task.
DefaultValue string The default text search value. 
FindOption FindOption Whether to search all layers specified in the task (AllLayers), or only layers currently visible (VisibleLayers).  
FeatureSelectionColor Color The Color of selected features.
InputWidth Unit The width of the text box in which the user enters the value to search.
GroupResultsByTable bool Whether the results of this task will have the results grouped by layers.
LabelText string Text to display next to the input box, to indicate the nature of the value to enter.  
MaxRecords int The maximum number of records the task will return.  This value may be limited by the service underlying the map resource.  For example, by default ArcGIS Server map services are limited to returning 500 features at a time.  To change this value, modify the MaxRecordCount property in the service configuration file (.cfg).   For more information, see the Service configuration files topic in the ArcGIS Server administration help system. 
NavigationPath string The path to the task as it would appear in a hierarchical data control buddied to the task's TaskManager.
SearchFields string A list of map resource - layer - fields on which a search for a value will be made.
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.
Title string The text displayed in the title bar of the panel.