QueryAttributesTask control

In this topic

• About the QueryAttributesTask control
• Using the control
• Members

About the QueryAttributesTask control

Using the control

1. To use the QueryAttributesTask control, add supporting controls to the page. Set up a Web application with MapResourceManager and Map controls, then add a TaskResults control. At runtime, the TaskResults control shows the results of the QueryAttributesTask. You can then interact with the results to the change map extent, display selected features, or re-execute the task. TaskResults also show a message when the query executes.
   
   To hide the query form when the application starts, and to allow you to access the form from a link on the page, add a Menu control from the standard ASP.NET Navigation tools, then add a TaskManager from the ArcGIS Web Controls toolbox. If you want to show the query form immediately upon application startup, you can skip adding these controls.
   
   Be sure to set the BuddyControl property of the TaskManager to the previously added Menu control. Set the Map property of the TaskResults control to the previously added Map control, if you want to see results highlighted on the map when selected.
2. To add a QueryAttributesTask control, in Visual Studio, open the prepared Web form in design mode, select the Toolbox panel, and expand the ArcGIS Web Controls tab. Drag and drop a QueryAttributesTask control into the TaskManager control (if you did not add a TaskManager control, drag the QueryAttributesTask onto the page). See the following screen shot that shows the controls on the page in Visual Studio:
   
   
   
3. To set the required properties for the QueryAttributesTask control, in design mode, select the QueryAttributesTask, which shows the smart tag arrow in the upper-right corner of the control. Click the smart tag arrow to display the smart tag menu, which shows common properties that you can set; however, other properties are available in the Properties window for the control. See the following screen shot that shows the smart tag menu:
   
   
   
1. Click Choose Task Results container on the smart tag menu or click the TaskResultsContainers property button on the Properties window. The BuddyControl Collection Editor dialog box appears. Click Add to add an item to the collection. With the TaskResults1 item selected, on the right side of the dialog box, click the drop-down list and select the previously added TaskResults control. This is where the QueryAttributesTask places results when a query is executed. See the following screen shot that shows the BuddyControl Collection Editor dialog box:
   
   
   
2. Click Configure Task on the smart tag menu to edit query attributes properties. The Query Attributes Properties dialog box appears displaying three tabs (General, Settings, and Results) where you can change the visible content on the task at runtime, edit the query parameters, and customize the display of results. 
• General tab—Use to change the task control name that displays by an ASP.NET Navigation control (for example, Menu) and the text on the button to execute the task. 
  
  See the following screen shot that shows the Query Attributes Properties dialog box with the General tab selected:
  
  
  
• Settings tab—Use to set the layer you want to query and the attribute query parameters. The Layer section on the dialog box enables you to set the MapResourceManager, MapResourceItem, and Layer on which you want to perform a query. Once these properties are set, you can edit the attribute query parameters. 
  
  See the following screen shot that shows the Query Attributes Properties dialog box with the Settings tab selected: 
  
  
  
  
• Query Entries—Use this section on the preceding Query Attributes Properties dialog box to construct a predefined query filter on a field. Click the Add button to create a predefined query using the Form Entry Editor dialog box. See the following screen shot showing the Form Entry Editor dialog box:
  
  
  
• Label Text—Type the text to show for this query item. 
• Associated Field—Select the associated field from the drop-down list. This is the field that is queried in this query item.
• Operator—Choose an operator that compares the value you enter to the field values. If you select the "like" operator, no wildcard character is added by default to the user's value and partial text values are not matched. Modify the where expression with the Custom Where Expression option.
• Default Value—Optionally, you can set a default value or create a pick list to choose from. The default value displays in the input box. You can accept or change this value. If you select the Show Pick List check box, specify a list of items, then choose from among these values in a drop-down list. You cannot enter an arbitrary value if you select the Show Pick List check box. You can enter values manually in the pick list or click the Get Sample Values button to retrieve the unique values of the field from the layer (this can retrieve a very large number of values).
• Input Validation—Validate your input for a better user experience and for filtering out malicious input. ASP.NET Validation controls are used to evaluate your input before it is sent to the server. You can choose between Range and Regular Expression validation. Range validation enables you to constrain the input range of values. Regular expression provides a mechanism for evaluating the pattern of user input. On the preceding Form Entry Editor dialog box, the regular expression validates a name (in this case, city name), allows up to 40 upper or lower case characters, and a few special characters common for names. For more information, see the Microsoft Developer Network (MSDN) topic, How to use regular expressions to constrain input in ASP.NET. In both cases, a custom error message can be defined to provide information on the expected format of the input for the query. 
• When finished setting up the form entry item, click OK to close the dialog box. The form entry item will be added to the Query Entries section on the Query Attributes Properties dialog box.
• If you want to create a compound query with multiple criteria, click Add on the previous Query Attributes Properties dialog box to add additional query entries. For each entry added, you are prompted to enter a value.
• By default, multiple form entry items are queried with "and" criteria. In the previous example, only cities that match both the name AND the population values entered by the user will be found. To change the concatenation rules to use OR, modify the query by selecting the Custom Where Expression check box under the Settings tab on the Query Attributes Properties dialog box.
• Custom Where Expression—Use to create or modify the selection expression. To use this option, select the check box on the Query Attributes Properties dialog box and type or modify the expression in the expression text box. Click Insert Field to add a field from the layer selected for the query or click Insert User Input Placeholder to add placeholders (for example, "{0}") for text that you can enter.
  
  The following screen shot shows the where expression being modified, which allows a wildcard (%) to be used to compare your value with names in the Layer field on the Query Attributes Properties dialog box. In this example, names that begin with the entered value are matched.
   
  
  
• Results tab—Use to define how the results of a query are returned and shown to the client. The settings under this tab work explicitly with the capabilities of a TaskResults control.  
• Limit search results to—Use to set the maximum number of records returned in the result. If more records are returned from the query, paging is enabled on the records rendered in the TaskResults container.  
• Group results by layer name in Results Panel—Select this check box to group results from a query in the TaskResults. If selected (the default), query results are contained in a parent node to display in the TaskResults. The parent node will have the same name as the queried layer and the number of records returned. If the check box is not selected, each result record is added to the TaskResults control independently. 
• Show attributes in Results Panel—Select this check box to show attributes for each returned record. If selected (the default), attributes for each returned record from a query display in the TaskResults control. If this check box is not selected, only the primary display field shows for each record node.
• Show MapTips—Select this check box to show MapTips on the results shown on the map. If selected (the default), callouts for MapTips are available for graphic results on the map.
• Display Results Using—Choose one of the following formats to display results:
• Layer formatting—Defined for the map resource item that contains the queried layer is used by default. 
• Customize formatting—You can choose to customize the format (symbology, fields, and attribute display) of results. 
• Symbols tab—Use to define the default and highlight symbol for results generated by the query. Click the Draw with or Highlight with button to change the symbol. When results are generated from the query layer at runtime, features will render in the Web browser using the default (Draw with) symbol. When the mouse cursor hovers over a feature, the highlight symbol (Highlight with) appears. The layer's feature type determines the options to change the symbol.
 
See the following screen shot that shows the Query Attributes Properties dialog box with the Results and Symbols tab selected:



• Fields tab—Shows the fields in the query layer. Click the Primary display field drop-down arrow to select the primary display field for attribute tables. This area can be used to describe the contents of a record and is set to a field that contains an intuitive, preferably unique value to identify an attribute. Select a check box next to each field to set the field's visibility. You can also edit the text in the Alias field if you do not want to use the original field name. Results generated from querying a layer contains only visible fields and uses field aliases to define column names. 
  
  The Primary display field will be used to define the node text for each record shown 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 this field is not found, the first string field is used. If there are no string fields, the first numeric field is used.
  
  See the following screen shot that shows the Fields tab:
  
  
  
• Records tab—Displays the tabular format of results shown in the Web browser at runtime. Record display properties for the query layer can be used to show results in 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 record display, click the Custom formatting radio button. The Title and Contents sections on the dialog box are now editable. The Contents section provides a rich text editor to modify font style and color, or to add fields, hyperlinks, tables, or images. Edits are stored as Hypertext Markup Language (HTML) style content to render in the Web browser at runtime. To view the HTML content that will be used to format layer results, click the HTML radio button on the bottom of the dialog box. The raw HTML content displays in the Contents window. Any valid content to render in a Web browser can be added, including HTML, Cascading Style Sheets (CSS) definitions, and JavaScript.
  
  See the following screen shot that shows the Records tab:
  
  
  
4. By default, the QueryAttributesTask form appears in a floating window that can be dragged to a new position on the Web page. The opening position does not necessarily correspond to its position on the Web page design form. If preferred, the query window can be fixed at a specific position.
1. To fix the position of the query form at a specific location, set the position style of the QueryAttributesTask, or a containing control or DIV.
2. To set the style, switch the Web page from design view to HTML view in Visual Studio. Find the QueryAttributesTask on 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.
 

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

5. The following describes additional properties for the QueryAttributesTask control that you can use to modify your application:
• Title—Shows at the top of the query form. Change the default, which is the ID of the control. Choose a title that describes the query's function, for example, Find cities where.
• ButtonText—Text for the button, that when clicked, executes the query.
• MaxRecords—Maximum number of features found by the query (default is 50). This value can 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. Modify the MaxRecordCount property in the service configuration file (.cfg) to change this value. For more information, see Service configuration files. 
• FeatureSelectionColor—After query results display and the check box next to a feature is selected, the feature highlights with this color on the map.
• ShowFieldAttributes—Whether to display feature attributes in the query results for each feature.
6. Using the QueryAttributesTask is similar to using the SearchAttributesTask, except that you see more text clues for the form items and multiple entry form items can be added by the site designer.
• Type values for each form item and click Find. The results show in the TaskResults control output.
  
  The following screen shot shows an example query form:
  
  

Members

Property name	Type	Description
ButtonText	string	Text that shows on the button to execute the task.
FeatureSelectionColor	color	Color of selected features.
GroupResultsByTable	bool	Whether the results of this task are grouped by layers.
MaxRecords	int	Maximum number of records the task returns. This value can 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).
NavigationPath	string	Path to the task as it appears in a hierarchical data control buddied to the task's TaskManager.
PredefinedQuery	QueryAttributes	Defines the query to be executed, including map resource, layer, and where expression.
ShowFieldAttributes	bool	Whether the results of this task have the field attributes.
ShowLegend	bool	Whether the results of this task have a legend (only available if GroupResultsByTable is set to true).
TaskResultsContainers	BuddyControlCollection	Controls in which results from this task display.
Title	string	Text shown on the panel's title bar.

See Also:

• ESRI.ArcGIS.ADF.Tasks.dll