Deploying the Voyager Search Widget Using Esri's Web Appbuilder

Owned by Heather Geyer
Last updated: Aug 09, 2022
3 min read

The Voyager Search widget can be used in deploying web map applications with the ArcGIS Portal product. There are two separate versions of the Voyager Search widget. The web application template is available for download to customers with a Voyager Pro license or a Voyager Basic license that includes the Voyager widget extension. If you have a license to run the Voyager widget please contact support@voyagersearch.com to download the widget installation files.

  • To deploy the widget using Esri's Web Appbuilder application, use the web-appBuilder folder and skip to the Prerequisites section below.

  • To deploy the widget in current versions of ArcGIS Portal or in situations where using the Web AppBuilder is not a suitable deployment option, use the use the web-app-template folder and follow the Deploying the Voyager Search Widget to Portal for ArcGIS help document.

This document describes how to use the Voyager Search widget with Esri's Web AppBuilder for ArcGIS.

Prerequisites

Web AppBuilder

  1. Download a copy of the Web AppBuilder from https://developers.arcgis.com/web-appbuilder/

  2. The directory that results from unzipping the downloaded file is referred to in the next section as install_directory

HTTPS

IMPORTANT: Web AppBuilder uses HTTPS by default.  Voyager must also be running in HTTPS mode or Web AppBuilder will not be able to communicate with it. See this article for information on configuring Voyager to use HTTPS.

Widget Installation

In the the web-appBuilder folder there is a folder named Voyager. This folder contains the following:

  1. Three folders: css, images and js

  2. Four files: config.json, manifest.json, Widget.js and Widget.html

  3. For this web application to work with your Voyager installation, several references to http://voyagerdemo.com  need to be updated in the following files in the Voyager folder with your Voyager Server URL. For example, if your Voyager Server URL is voyager.acmecompany.com then you would replace "http://voyagerdemo.com /web/solr/v0/select" with "voyager.acmecompany.com/<content path if one is set>/solr/v0/select". Also replace " /web/api/rest/i18n/field/format.json" with "voyager.acmecompany.com/<context path if one is set>/api/rest/i18n/field/format.json". NOTE: Content path is set by Voyager admins in the voyager.vmoptions file settings described here.

    • In the file /config.json on the "voyagerRoot" and "voyagerFormatLookup" properties (lines 3 and 5)

    • In the file /Widget.js on the "voyagerFormatLookup" and "voyagerRoot" properties (lines 23 and 24)

    • In the file js/Search.js the Voyager Server install_directory/data/meta folder will need to be published via a web server such as IIS on the voyagerRoot server and configured on subs.thumb (lines 317 and 319). The URL can reference any existing jpg file in your installation's meta folder e.g. \data\meta\0\0a8\00a83e02267bd06a2c9279208bd2dd02d52bef3b.thumb.jpg)

  4. The Web AppBuilder server expects widgets to live in a specific directory: install_directory/client/stemapp/widgets.

  5. Copy the Voyager folder to install_directory/client/stemapp/widgets.

Using the Widget in the Web Appbuilder

  1. Open and login to the Web AppBuilder (it should be running at http://localhost:3344/, provide the url to your org and App ID if prompted)

  2. Click Create New

  3. Provide a title and description for the app, click OK

  4. Set the Theme and Map for your web map in the first two tabs in the panel on the left side of the app. Ensure that you set the map extent to your area of interest. Don't use the default global extent. Note: There is a known issue where the Voyager Search widget doesn't return search results for web maps with the extents that cover the International Dateline.

  5. In the tab bar in the left panel, select Widgets

  6. Click Set the widgets in this controller 

  7. Click Click here to add widget

  8. In the dialog that opens, the last item in the list should be Voyager Search, click it then click OK

  9. A window will open that allows you to change the voyagerRoot URL to your own Voyager Server instance. Click OK once you're finished updating the voyagerRoot value if you haven't already done so in step 3 of the widget installation (read from install_directory/client/stemapp/widgets/Voyager/config.json).

  10. The Voyager Search widget is now included in the toolbar across the top of the app. To use it, click the Voyager icon in the upper-right and the Voyager Search widget will open in a panel on the right side of the screen.

  11. In the sidebar on the left, click Save

  12. Go back to the Web AppBuilder dashboard by clicking the Web AppBuilder for ArcGIS link in the upper-left.

  13. To test the app, click launch; this should take you to http://localhost:3344/webappbuilder/apps/ (if this is your first app with the Web AppBuilder, app-id will be 1).

  14. To run the app elsewhere, click the ellipsis to the right of Launch and select Download

  15. Move the resulting .zip file to a web server, unzip and the app is live.

Using the Widget in the Web App

  1. Open the web map in a browser.

  2. Click on the Voyager icon to open the widget if its not already open.

  3. Get search results simply by entering a keyword, or any text, into the widget's search box.

  4. Click on the blue button with a plus sign icon to add the item to the map.

  5. Once the item is added to the map the it will be listed at the top of the widget where you can turn the layer on/off and remove the layer from the map.