en-ca 1999-12-31 $id:$ Doc_Builder DM Solutions Group Inc. chameleon@lists.maptools.org Christopher R. Thorne DM Solutions Group Inc. chameleon@lists.maptools.org Query TBD Navigation Widget 2.0 2005-01-10 TECHRELEASE Paul Spencer DM Solutions Group Inc. chameleon@lists.maptools.org The Query widget is used to query the map for information at a single point. If a visible feature (point, line, polygon, or raster) found in the map has accessible tabular information, the Query widget returns the query results in a popup window. This widget normally queries all visible layers that are specified as queryable in the map file or Context file. There are several things that must be done to make a map file layer queryable, as discussed in the MapServer documentation at http://mapserver.gis.umn.edu. The availability of tabular data to display to a user depends on how the MapServer map file (*.map) or OGC Context file (*.cml) are configured. In many cases, a Web-mapping application provides some specific queryable layers as well as some non-queryable layers (for base data). Both MapServer map files and OGC Context files have their own procedures for making a map data layer queryable. Refer to the MapServer documentation at http://mapserver.gis.umn.edu. A map widget must be present in the interface for this widget to find possible queryable map features. A map layer must be configured to be queryable. In the case of Context files, it is up to the WMS server to determine whether the client query request is allowed, regardless of what is specified in the Context file. The queryability of a WMS layer can be checked by getting the WMS server's Capabilities document. The Query widget tag has attributes from the Button Attributes and Popup Attributes Groups. This means the Query widget has access to the Style and PopUpCSS Shared Resources. To learn about them, please refer to the appropriate attribute group sections for details. The Query widget provides the capability to perform spatial queries on the map. A query retrieves metadata about a visible layer at a particular geographic location. To perform a query, select the Query tool and click on the map. A Query Results window will popup and display the results of querying each visible, queryable layer at the clicked location. Not all layers may be configured to be queryable - this is determined by the application. You must select the Query button to activate this tool before proceeding to the map. If the button is a part of a button toolset, then the functionality of this button remains active until another button is selected in the same toolset. The user can click the mouse cursor on a queryable map feature and view the result of the request in a separate popup window. If no map features are found within the query tolerance area then the query popup display a "no data found" message. <CWC2 TYPE="Query" ENABLED="[TRUE|FALSE]" FORMINDEX="[0 < integer]" VISIBLE="[TRUE|FALSE]" <!-- Query Attributes--> ALLOWRECTANGLE = "[TRUE|FALSE]" HIGHLIGHTRESULTS = "[TRUE|FALSE]" INCLUDEEMPTYRESULTS = "[TRUE|FALSE]" MAXFEATURES = "[1 < integer]" PERSISTENTRESULTS = "[TRUE|FALSE]" POPUPRESULTS = "[TRUE|FALSE]" RADIUS = "[1 < integer]" SUBMITPAGE = "[TRUE|FALSE]" <!-- Navigation Attributes --> CURSORTYPE="[string]" DEFAULT="[TRUE|FALSE]" MAPID="[string]" WIDGETSTYLE="[string]" <!-- Popup Attribute Group --> POPUPHEIGHT="[0 < integer]" POPUPWIDTH="[0 < integer]" MENUBAR="[TRUE|FALSE]" POPUPSTYLERESOURCE="[string]" RESIZABLE="[TRUE|FALSE]" SCROLLBARS="[TRUE|FALSE]" STATUS="[TRUE|FALSE]" TOOLBAR="[TRUE|FALSE]" <!-- Button Attribute Group--> BACKGROUNDIMAGE="[path]" DEFAULT="[TRUE|FALSE]" IMAGE="[path]" IMAGEHEIGHT="[integer]" IMAGETIP="[string]" IMAGEWIDTH="[integer]" LABELALIGN="[LEFT|CENTER|RIGHT]" LABELANTIALIAS="[TRUE|FALSE]" LABELCOLOR="[#RRGGBB]" LABELFONT="[string]" LABELFONTSIZE="[0 < integer]" ONCLICK="[string]" STYLERESOURCE="[string]" TEXTBUTTONBORDER="[path]" TEXTBUTTONBORDER_BOTTOM_IMAGE="[path]" TEXTBUTTONBORDER_BOTTOMLEFT_IMAGE="[path]" TEXTBUTTONBORDER_BOTTOMRIGHT_IMAGE="[path]" TEXTBUTTONBORDER_LEFT_IMAGE="[path]" TEXTBUTTONBORDER_RIGHT_IMAGE="[path]" TEXTBUTTONBORDER_TOP_IMAGE="[path]" TEXTBUTTONBORDER_TOPLEFT_IMAGE="[path]" TEXTBUTTONBORDER_TOPRIGHT_IMAGE="[path]" TEXTBUTTONCOLOR="[#RRGGBB]" TEXTBUTTONNUDGE="[integer]" TEXTBUTTONPADDING="[0 < integer]" TOOLSET="[string]" USETEXTBUTTONCACHE="[TRUE|FALSE]"> <!-- Button Subtag Group --> <IMAGE STATE="[NORMAL|SELECTED|HOVER|DISABLED]" IMAGE="[path]"/> </CWC2> The query radius in the following example is set to 3 pixels and the number of features to be displayed in the popup table results is set to 5. <cwc2 type="Query" visible="true" image="buttons/button_query_1.png" radius="3" maxfeatures="5"/> The following example shows how the Query widget uses a "TextButtons" Shared Resource called "NavigationButtons" with three possible image states. <cwc2 type="Query" visible="true" imagetip="Identify Feature" image="icons/query_icon.png" styleresource="NavigationButtons" popupwidth="500" popupheight="600" radius="3" maxfeatures="5"> <image state="normal" /> <image state="hover" /> <image state="selected" /> </cwc2> The following Query example shows how the widget could be defined without using a Shared Resource. Note that this tool is linked to a group of button-based navigation widgets using the toolset attribute. This means that if Query is selected, it remains active until another tool within that tool group is selected. <cwc2 type="Query" visible="true" imagetip="Identify Feature" toolset="Navigation" imagewidth="24" imageheight="24" popupwidth="500" popupheight="600" toolbar="false" status="false" menubar="false" radius="3" maxfeatures="5"> <image state="normal" image="buttons/button_query_1.png"/> <image state="hover" image="buttons/button_query_2.png"/> <image state="selected" image="buttons/button_query_3.png"/> </cwc2> Hawaii Demo www.mapsherpa.com/hawaii2/ The Hawaii Demo uses the latest 1.99 Chameleon version. Base Button NavTool Popup ALLOWRECTANGLE boolean Widget Only false true false Determine whether the query widget should support rectangular queries or point queries. WMS layers only accept point queries. Rectangular queries are not yet implemented, so this attribute is ignored. HIGHLIGHTRESULTS boolean Widget Only false true false Determine whether features identified in the query should be visually highlighted on the map or not. Feature highlighting may be temporary unless PERSISTENTRESULTS is set to "true". The visual style of the feature highlight is controlled by the QUERYMAP element of the map file. See http://mapserver.gis.umn.edu for details. INCLUDEEMPTYRESULTS boolean Widget Only false true false If set to "true", output a message when no search results are found for every layer that is queryable. In set to "false", then layers that are queryable but which have no results do not display any text. MAXFEATURES integer Widget Only 5 records 1 2147483647 The number of features to limit a GetFeatureInfo response to. This is the limit for each layer; it is not cumulative. This is a CubeWerx-specific extension to the WMS GetFeatureInfo request and may not be supported by all servers, although most should at least ignore it. PERSISTENTRESULTS boolean Widget Only false true false This controls the persistence of query results. Normally a query disappears on the next navigation by the user. With persistence turned on, highlighted results will be preserved until the user uses the ClearQueryResults widget or performs another query. Although POPUPRESULTS boolean Widget Only false true false Control the display of query results. Setting this to "false" causes the query results popup to be suppressed. This allows the building of custom query results functionality. RADIUS integer Widget Only 3 pixel width 1 2147483647 The number of pixels to search for features around the clicked location. This is a CubeWerx-specific extension to the current WMS GetFeatureInfo request and may not be supported by all servers, although most should at least ignore it. SUBMITPAGE boolean Widget Only false true false Determines whether the page is submitted when the user clicks on the map. Normally, the query widget does not submit the page. However, for custom query results, it may be desirable to change this behavior. NAV_CMD string The last command that was used to interact with the map. For the Query widget, this is set to QUERY. NAV_ALLOW_RECTANGLE boolean Track whether the current navigation tool uses a rubber-banding box or not. For the Query widget, this will be false. NavSetActiveTool Private Set the active navigation tool for a particular group of tools. oButton object true This is the JavaScript button object. aVals array true Array of parameters that defines the navigation tool. The first element is the tool number. The second element is the tool name. The third element is boolean and determines if rectangle mode is enabled or not. The fourth element controls automatic submission of the page after navigation. The fifth element is a string that define the cursor type. QueryWMouseClick Private Handle the user clicking the mouse on the map. e object true A JavaScript event object QueryWMouseMove Private Handle the user moving the mouse over the map. e object true A JavaScript event object