ArcGIS Server Geoportal extension - Geoportal Search Widget for Flex

How to Use

The ArcGIS API for Flex allows for the creation of Rich Internet applications on top of ArcGIS Server. It is based on the free Adobe Flex framework. ESRI provides a sample viewer application that can be integrated with the Geoportal extension, using the Geoportal Search Widget for Flex. For instructions on how to add the Geoportal Search Widget to your existing sample viewer, see the section below on How to Add the Geoportal Widget to an Existing Flex Viewer.

The Geoportal extension ships with an example viewer that is preconfigured with the Geoportal Search Widget. To launch the example viewer, go to the examples page (http://server_name/geoportal/widgets/example.jsp) and launch the Flex Viewer from the link on the page. The Find Data window will automatically be opened when the application is launched; this Find Data window is the Geoportal Search Widget for Flex.

How to search

Notice that the Find Data window has one input field, a Search button, and three radio buttons. The input field accepts any lucene search query. You can type in a simple query, such as just one keyword to search, or you can develop more complex queries using the Lucene syntax. Furthermore, you can limit search results to a certain spatial extent. Select the appropriate radio button: Anywhere means no spatial filter will be applied, Intersecting will retrieve records that touch or overlap the spatial extent currently shown in the Flex Viewer, and Fully Within will retrieve records where the spatial extent falls fully within the extent currently shown in the Flex Viewer.

Once you have entered the search criteria, click the Search button.

Search results matching your criteria are returned. Doubleclick on one of the records, and the interface zooms to the spatial extent of the resource. Another window appears, showing information for that search result resource and links that provide the same functionality that you'd see on the geoportal search page. You will notice that no Preview link is generated, and instead an Add to Map link appears for Live Data. That is because in this Flex application, users preview the service when they chose to add it to the map with the Add to Map link.

Other tools in the Find Data window

At the top right side of the Find Data window, there are four icons. The first is a set of binoculars, and the second is a square chart. These two buttons allow for toggling between the search interface and the list of resources. Click on the binoculars to define a search; click on the chart to see the results from the previous search. The third and fourth buttons define the behavior of the window itself. Click on the green arrow to minimize the window. Click on the X button to close it.

If you close the window, but want to open it again, hover the pointer over the cube Tools icon in the viewer's main menu, and you will see the Find Data tool displayed in the list of available tools. Click on it to restore it to the Find Data user interface.

Viewing a service in the interface

The example Flex Viewer provided with the Geoportal extension supports ArcIMS, ArcGIS Server REST services, OGC WMS, and GeoRSS. If a service is not running or is of an unsupported service type, it will not appear on the map interface even though an Add to Map link is displayed with the search result.

How to navigate the Flex Viewer map

Documentation for how to use the Flex Viewer is specific to its implementing organization, and will be defined in the Flex Viewer's help by the organization hosting the viewer.

How to Add the Geoportal Widget to an Existing Flex Viewer

The Flex Viewer that ships with the Geoportal extension is a sample. If you are hosting your own ESRI Flex Sample Viewer and would like to add the Geoportal Search Widget to that application, follow the steps below. In these instructions, the [Geoportal Install Directory] refers to the directory created when the Geoportal Distribution setup.exe was run. By default, this directory is C:\ESRI\Geoportal Extension 10. The [Your ESRI Flex Sample Viewer Root Directory] refers to the root directory where your own ESRI Flex Sample Viewer has been deployed. The Geoportal Widget swf and swc files have been built with flex version 3.1.0.

You can add the Geoportal Search Widget to your ESRI Flex Sample Viewer without recompiling, or you can add it to the actual ESRI Flex Sample Viewer code.
- If you want to copy the widget to your ESRI Flex Sample Viewer without compiling, then do this first step: Navigate to the [Geoportal Install Directory]/Widgets/FlexExample/swf/com/esri directory and copy the gpt folder. Paste this gpt folder into the [Your ESRI Flex Sample Viewer Root Directory]/com/esri folder.
- If you want to copy the widget to your ESRI Flex Sample Viewer code, then you will need to do two initial steps: 1) Navigate to the [Geoportal Install Directory]/Widgets/swc/ directory and copy the GeoportalSearchWidget.swc file. Paste this file into the [Your ESRI Flex Sample Viewer Root Directory]/libs directory. 2) Navigate to the [Geoportal Install Directory]/Widgets/swc/com/esri directory and copy the gpt folder. Paste this gpt folder into the [Your ESRI Flex Sample Viewer Root Directory]/src/com/esri directory.

Navigate to the [Your ESRI Flex Sample Viewer Root Directory] folder and open the config.xml file in a text editor. Add the following block of code under the <widgets> element:

<widget label="Find Data" 
preload="maximized" 
icon="com/esri/solutions/flexviewer/assets/images/icons/i_search.png" 
menu="menuWidgets" 
config="com/esri/gpt/flexviewer/widgets/GeoportalSearchWidget.xml"> 
com/esri/gpt/flexviewer/widgets/AGSGptRSSWidget.swf</widget>

Navigate to the [Your ESRI Flex Sample Viewer Root Directory]/com/esri/gpt/flexviewer/widgets folder, and open the GeoportalSearchWidget.xml file in a text editor. This file contains a number of settings you can specify to customize your Geoportal Search Widget. Most of these settings are optional, and are listed in the table below. Before configuring the optional settings, you must do the following:
- Find the section shown below, and comment it out so it reads as follows:
```

```
- Now, copy the next gptEndpoint element that describes the GEOSS portal URL, and paste it just below your commented text:
```
<gptEndpoint url="http://geoss.esri.com/geoportal/rest/find/document" 
name="GEOSS"/>
```
- Edit the copied gptEndpoint element by changing the URL to point to your geoportal, and updating the name attribute with the name of your geoportal. This will allow users to select your geoportal from the list of default sites to search. You can remove the GEOSS or GOS portals from the list by removing their gptEndpoint entries.

If you desire to change the look and feel of your search widget or how it behaves, configure any of the following optional elements. Elements not listed in this table should not be altered:

Element Name	Description	Accepted Values
<label>	refers to labels in the Search Widget. The value attribute is what the user sees. Do not change the name attribute.	value should be a string
<searchTimeout>	max time in seconds a search will be allowed to run before it times out	integer
<addLayerTimeout>	max time in seconds adding a layer will be allowed to run before it times out	integer
<iconSearch>	filepath to the search icon in the Search Widget interface	string
<iconResult>	filepath to the table icon in the Search Widget interface	string
<iconHelp>	filepath to the help icon in the Search Widget interface	string
<zoomFactor>	how much buffer to add to the view of the extent so that the borders of the extent and some surrounding area can be seen when you choose Zoom to Extent for a search result	integer
<urlHelp>	URL to the help webpage. You can update this to point to a file hosted by your organization. The default is the Geoportal extension's Search Widget help	URL string
<color id="mainBboxesPlain">	defines look and feel for bounding boxes showing the extent of returned search results	variable - several parameters are defined here
<color id="mainBboxesHighlight"	defines look and feel for a highlighted bounding box showing the extent of a selected search result	variable - several parameters are defined here

The Adobe Flash player will not allow the ESRI Flex Sample Viewer (or any Flash program) to access another site for information unless that site has a crossdomain.xml that defines access policy. To get around this Flash restriction, the Geoportal Search Widget for Flex can use a proxy. If the proxy is not used, then all of the search and the map service endpoint domains must have a crossdomain.xml file explicitly allowing access from the domain the ESRI Flex Sample Viewer runs on. If the ESRI Flex Sample Viewer and the map services found are going to be on the same domain then a crossdomain file and/or a proxy is not needed and you can skip this step.
Different builds of the ESRI Flex Sample Viewer may have different ways of configuring the proxy. Below are two examples that can work for the Flex Viewer on builds 05.22.09 to 06.12.09, if your ESRI Flex Sample Viewer is deployed within a Java Application Server such as Tomcat. To find the build number, open the WHATSNEW.txt file from your ESRI Flex Sample Viewer root directory and read the first few lines.
- Example A: Replace proxy.jsp with the proxy.jsp from the Geoportal Example Flex Viewer
  - Overwrite the proxy.jsp file in your Flex Viewer root directory with the proxy.jsp file from the [Geoportal Install Directory]/Widgets folder.
- Example B: Reference proxy.jsp
  - Copy the the proxy.jsp file from the [Geoportal Install Directory]/Widgets folder into one of your Java web applications.
  - Verify that your Flex Viewer is in the same domain as where you are hosting this proxy.jsp.
  - Open the GeoportalSearchWidget.xml file (from [Your Flex Viewer Root Directory]/com/esri/gpt/flexviewer/widgets folder) and update the <useProxy> element's proxyUrl attribute with the following URL: "http://yourdomain/yourcontext/proxy.jsp?url=" . The updated element is shown below:
```
<useProxy
proxyUrl="http://yourdomain/yourcontext/proxy.jsp?url="></useProxy>
```
  - Change "yourdomain" to reference the server hosting your Flex Viewer, and change "yourcontext" to the web application hosting your proxy.jsp file.
  - Save the GeoportalSearchWidget.xml file.
Launch your ESRI Flex Sample Viewer and try out the Geoportal Search Widget.

8/6/2012