QueryAttributesTask control

The QueryAttributesTask control enables you to explicitly define the parameters used to query values in a field. This control enhances the basic query capability of the SearchAttributesTask. At runtime, the QueryAttributesTask query can provide a drop down list of preset choices or a textbox for general text entry. Each query can also utilize a validator to restrict the values entered. In addition, multiple queries can be grouped together to produce a single result. Only feature layers in resources provided by a MapResourceManager can be used. The results are provided as an ADO.NET DataSet to be displayed in a TaskResults control.

A QueryAttributesTask creates a single query on one map layer. The query may have compound criteria. For example, you can define a query on a cities layer that selects cities with a population greater than a value entered by the user, and with a name that begins with a value entered by the user.

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

Using the QueryAttributesTask control

Add supporting controls to the page

In order to take full advantage of the QueryAttributesTask control, a number of supporting controls must be available. Set up a Web application with MapResourceManager and Map controls using their discussion topic as a guide. Add a TaskResults control using that control's discussion topics as a guide. At runtime, the TaskResults control will display the results of QueryAttributesTask. 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 query executes.

To hide the query form when the application starts up, and 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. If you want to display 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 Menu control you added. 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.
Add a QueryAttributesTask 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 QueryAttributesTask control into the TaskManager control; or, if you did not add a TaskManager control, just drag the QueryAttributesTask onto the page. Your page might resemble the following:
Set the required properties for the QueryAttributesTask control

In design mode, click the QueryAttributesTask, which will display the smart tag arrow in the upper right of the control. Click on this arrow to display the smart tag menu. This menu displays common properties that you can set, though others are available in the Properties window for the control.

a. Task results 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 QueryAttributesTask will place results when the user executes a query.

b. Configure Task : Click the second item in the smart tag menu to edit query attributes properties. A dialog with a set of tabs is displayed which enables you to change the visible content on the task at runtime, edit the query parameters, 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.

Settings Tab: On the Settings tab you can set the layer you want to query and the attribute query parameters. The Layer section of the dialog enables you to set the MapResourceManger, MapResourceItem, and Layer on which you want to perform a query. Once these properties are set, you can edit the attribute query parameters.

The Query Entries section gives you the ability to construct a predefined query filter on a field. Click on the Add button to create a new predefined query using the Form Entry Editor dialog.
- In the Label Text box, enter the text that you want to display to the user for this query item. Next, select the Associated Field from the drop-down list. This is the field that is queried in this query item. Choose the Operator that compares the value entered by the user to the field values. Note that if using 'like', no wildcard character is added by default to the user's value, and partial text values are not matched. You need to modify the where expression with the Custom Where Expression option (see below).
- Optionally, you may set a default value or create a pick list for users to choose from. The default value displays in the input box. The user may accept this value or change it. If you choose the Show Pick List option, you need to specify a list of items. The user must choose from among these values in a drop-down list. The user cannot enter an arbitrary value if you choose the pick list option. You may 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. Be aware that this can retrieve a very large number of values.
- You may also choose to validate the user's input. This is recommended both for a better user experience and for filtering out malicious input. ASP.NET Validation controls are used to evaluate user 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. In the screenshot below, the regular expression validates a name (in this case, city name). It allows up to 40 upper or lower case characters and a few common special characters common for names. See the MSDN topic on constraining input using regular expressions in ASP.NET for more information. In both cases, a custom error message can be defined to provide the end user with 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. The form entry item will be added to the Query Entries in the Form Entry Editor.
- If you want to create a compound query with multiple criteria, click Add in the Form Entry Editor to add additional query entries. For each entry you add, the user is prompted to enter a value.
- By default, multiple form entry items are queried with "and" criteria. In the example above, 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, you must modify the query using the Custom Where Expression option.
Custom Where Expression: You can use the Custom Where Expression option to create or modify the selection expression. To use this option, check the box on the Query Attributes Properties form and then enter or modify the expression in the expression text box. You can use the Insert Field option to insert a field from the layer selected for the query. You can also use the "Insert User Input Placeholder" to add placeholders (e.g., "{0}") for text that users would enter.

In the example below, the where expression has been modified with the form entry editor so that a wildcard (%) is used to compare the user's value with names in the layer field. In this case, names that begin with the value entered by the user are matched.

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 the query, 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 query 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 the query layer 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 query 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 querying 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.
Setting the position of query form

By default, the QueryAttributesTask 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 query window may be fixed at a specific position.

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. To set the style, switch the web page from Design view to HTML view in Visual Studio. Find the QueryAttributesTask 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, we use relative placement is used to ensure the query window is placed within a table cell:
```
<td>
  <esriTasks:QueryAttributesTask style="position:relative;top:5px;left:0px;" 
    ID="QueryAttributesTask1" runat="server" ...>
  </esriTasks:QueryAttributesTask>
<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.
Other properties for QueryAttributesTask

Some of the properties you may wish to modify for your application include:
- Title: displayed at the top of the query form to the user. You should change this from the default, which is the ID of the control. Choose a title that describes what the query does. An example would be, "Find cities where...".
- ButtonText: text for the button the user clicks to execute the query.
- MaxRecords: maximum number of features found by the query. Default is 50. 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.
- FeatureSelectionColor: after 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.
Using the QueryAttributesTask at runtime

Using the QueryAttributesTask is similar to using the SearchAttributesTask, except that the user sees more text clues for the form items, and multiple entry form items can be added by the site designer. An example of the query form the user might see would be:

The user enters values for each form item, then clicks Find. 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 QueryAttributesTask 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.

GroupResultsByTable bool Whether the results of this task will have the results grouped by layers.

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.

PredefinedQuery QueryAttributes

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.

Property Name	Type	Description
ButtonText	string	The text which appears on the button to executes the task.
FeatureSelectionColor	Color	The Color of selected features.
GroupResultsByTable	bool	Whether the results of this task will have the results grouped by layers.
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.
PredefinedQuery	QueryAttributes
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.