Integration Module

The Integration Module implements the ability to open other applications from within an HTML5 viewer. For example, integrating Bing Maps with an HTML5 viewer enables users to open Bing Maps alongside the viewer. In the screen capture below, three mapping applications are open. Two of the applications are docked to the viewer and one is undocked.

Mapping applications integrated with an HTML5 viewer

You are responsible for ensuring that you have the required licenses for the applications that you integrate.

The Handheld user interface does not support integration.

Internet Explorer's Enterprise mode does not support integration—Enterprise mode emulates Internet Explorer 8, which does not support integration.

To integrate an application with an HTML5 viewer, you configure an external component for the application in the viewer. The external component's configuration can either specify the web application to integrate, or it can specify a web page that points to the web application to integrate.

The simplest configuration points directly to a public web application (or website). In this case, the application displays in an integration pane without any additional controls beyond what the application itself offers. To configure this, all you have to do is configure the external component to point to the web application. End users will be able to open the application from the viewer and use the application's controls.

You may want to provide additional controls for interacting with an integrated application. For example, when you integrate a mapping application, you may want users to be able to center the integrated map on the viewer's map. In this case, you host a web page that points to the application that you want to integrate and you build the additional controls into the web page. You must also provide any supporting files that the web page references, such as CSS and JavaScript files. When you configure the external component in the viewer, you specify the web page that points to the application, instead of the application itself.

If the application is licensed, you may need to host a web page that provides the licensing information, instead of pointing directly to the application.

The HTML5 Viewer ships with integration samples for Bing Maps and Pictometry that you can use. See Example 1 - Integrate with Bing Maps and Example 2 - Integrate with Pictometry for instructions. As well, the VertiGIS Studio Support's Code Gallery includes a sample that integrates Google Street View.

Integration with Mapping Applications

Effective with version 2.9 of the HTML5 Viewer, Internet Explorer version 11.0 and later is required for third-party mapping applications.

When an integrated map is open, the viewer's map displays a marker that indicates the center of the integrated map. Dragging the marker pans the integrated map so that the map stays centered at the center of the marker's body.

Dragging the marker () pans the integrated map () so it stays centered on the marker

You can pan and zoom the viewer's map and integrated maps independently of each other by using the standard map controls for panning and zooming. If you pan or zoom an integrated map, the marker stays synchronized with the map.

You can configure a different marker for each integrated map . Using different markers enables users to distinguish one map's marker from another's when there is more than one integrated map open.

The HTML5 Viewer ships with integration samples for Bing Maps and Pictometry. The sample web pages contain tools for managing the integrated map and its pane independently of any other integrated applications that are open. The tools are:

Viewpoint Indicator - Shows the marker that is used for this integrated map. The Viewpoint Indicator is for information only—it is not clickable. The Viewpoint Indicator is configured in the CSS file that is provided with the sample. If you change a map's marker in the Integration Module, you must also update the Viewpoint Indicator in the CSS.

Center - Moves the integrated map's marker to the center of the viewer's map and rescales the integrated map to match the viewer's map as closely as possible.

Dock/Undock - (Desktop interface only) Allows the user to dock and undock the integrated map from the viewer. Depending on the browser settings, the map may undock to a new tab or to a new window. The Tablet interface does not support undocking integration panes.

Close - Allows the user to close the current integration pane without closing any other panes that are open.

Open an Application from an HTML5 Viewer

The Integration Module has one view—ExternalComponentView. By default, ExternalComponentView is not visible, so you must provide a way for users to activate the view. The HTML5 Viewer provides a Linked Maps button that you can add to the toolbar. Alternatively, you could add an I Want To menu item or a hyperlink that runs one of the activation commands. You can also use these commands in workflows.

The commands that activate ExternalComponentView are ShowExternalComponentView, DisplayDockedExternalComponentById, and DisplayUndockedExternalComponentById.

By default, the Linked Maps button uses the ShowExternalComponentView command. ShowExternalComponentView opens each default component (defaultComponents) that is configured. Each component opens in its own pane. If there are no defaultComponents configured, ShowExternalComponentView opens the first component that is configured in externalComponents.

The DisplayDockedExternalComponentById and DisplayUndockedExternalComponentById commands open the component that you specify as the command's parameter.

Configuration Properties

Module

Views

View Models

Configure Cross-Domain Access for an Integrated Application

Configuring cross-domain access enables the viewer and integration pane to communicate with each other. You must configure cross-domain access if all of the following conditions are met:

You do not need to configure cross-domain access if the viewer and web page are deployed to the same domain, or if you are pointing the viewer configuration directly to the application, or if you are pointing the viewer to a web page that does not use any HTML5 Viewer commands.

To configure cross-domain access for an integrated application:

Step 1: Configure the web page's origin in the Integration Module

  1. Run an XML editor or text editor as an administrator.

  2. Open one of the viewer configuration files, Desktop.json.js or Tablet.json.js, in the editor.

    By default, the configuration files are here:

    C:\Program Files (x86)\Latitude Geographics\Geocortex Essentials\[instance]\REST Elements\Sites\[site]\Viewers\[viewer]\VirtualDirectory\Resources\Config\Default\

  3. Add the web page's origin to the Integration Module's allowedOrigins property.

    For example, if the web page is deployed to http://mymaps.mydomain.com:

    {
       "moduleName": "Integration",
       "moduleType": "geocortex.essentialsHtmlViewer.mapping.modules.integration.IntegrationModule",
       "configuration": {
          "allowedOrigins": ["http://mymaps.mydomain.com"]
       }
       ...

    The origin that you configure in the allowedOrigins property must be identical to the URL that you configure in the externalComponent's uri property. If the web page, webpage.html, is deployed to http://mymaps.mydomain.com, then the uri property for the external component looks like this:

    "externalComponents": [
       {
          ...
          "uri": "http://mymaps.mydomain.com/maps/webpage.html",
          ...
       }
    ]
  4. Save the file.

  5. Repeat these steps for the other configuration file.

Step 2: Configure the viewer's origin in ThirdPartyMap.js

  1. Run an HTML or text editor as an administrator.

  2. Open ThirdPartyMap.js in the editor.

    In the default deployment, the file is here:

    C:\inetpub\wwwroot\Html5Viewer\Resources\3rdPartyMaps\ThirdPartyMap.js

  3. Find the following line:

    this.allowedOrigins = [];
  4. Type or paste the viewer's origin in the array, within quotation marks:

    this.allowedOrigins = ["http://myviewers.mydomain.com"];

    The origin that you configure in the ThirdPartyMap.js's allowedOrigins must be identical to the viewer's origin as it appears in the browser. Note that http://myviewers does not match http://myviewers.mydomain.com, even though they map to the same machine.

  5. Save the file.

Configure Access to a Secured Site by an Integrated Application

If the site that the viewer belongs to is secured and SSL is enforced (in other words, the Enforce SSL setting is enabled in the Security Settings), then you must ensure that the web page uses SSL to access the integrated application.

At a minimum, you must specify https in the URL that the web page uses to connect to the application. Depending on the application, you may also have to include a URL parameter for SSL. Refer to the application's documentation for information about secure access.

Example 1 - Integrate with Bing Maps

This example shows how to integrate Bing Maps into an HTML5 viewer using the sample Bing Maps web page that ships with the Viewer.

In this example, the integration pane (ExternalComponentView) is closed by default and the toolbar includes the Linked Maps button. When the user clicks the button, Bing Maps opens in an integration pane with a header.

The main steps to adapt the Bing Maps sample are:

  1. Adapt the sample Bing Maps web page:

    1. Configure your Bing Maps key.
    2. If the viewer belongs to a secured site and SSL is enforced, adapt the Bing Maps URL to use SSL.
  2. Add an external component for Bing Maps to the Integration Module.

  3. Configure cross-domain access.

    You only need to do this if the sample Bing Maps web page is deployed to a different domain than the viewer.

  4. Add the Linked Maps button to the toolbar.

The instructions assume that the Bing Maps web page is hosted at http://mymaps.mydomain.com/maps and the HTML5 Viewer is hosted at http://myviewers.mydomain.com/Html5Viewer. Replace these URLs with the URLs for your installation.

Step 1: Adapt the sample Bing Maps web page

  1. Run an HTML editor or text editor as an administrator.

  2. Locate BingMaps.html where it is deployed in IIS.

    In the default deployment, the file is here:

    C:\inetpub\wwwroot\Html5Viewer\Resources\3rdPartyMaps\BingMaps.html

  3. Open BingMaps.html in the editor.

  4. Configure your Bing Maps key:

    1. Find the following line:

      var bingApiKey = "";
    2. Type or paste your Bing Maps key between the quotation marks.

  5. Find the following line that sets the type of map to display:

    var mapTypeId = "birdseye";

    Set the mapTypeId value to the type of map you want to display. For possible values, see Microsoft's MapTypeID Enumeration documentation.

  6. Save the file.

Step 2: Add an external component for Bing Maps to the Integration Module

If you already have one or more externalComponents configured when you add the Bing Maps external component, remember to separate the components using commas. You may also want to configure the defaultComponent if you have more than one external component configured.

  1. Run an XML editor or text editor as an administrator.

  2. Open one of the viewer configuration files, Desktop.json.js or Tablet.json.js, in the editor.

    By default, the configuration files are here:

    C:\Program Files (x86)\Latitude Geographics\Geocortex Essentials\[instance]\REST Elements\Sites\[site]\Viewers\[viewer]\VirtualDirectory\Resources\Config\Default\

  3. Add an external component for Bing Maps to the Integration Module's externalComponents property:

    {
      "moduleName": "Integration",
      ...
      "viewModels": [
        {
          ...
          "configuration": {
            ...
            "externalComponents": [
              {
                "id": "bingMaps",
                "displayName": "Bing Maps",
                "uri": "Resources/3rdPartyMaps/BingMaps.html",
                "viewpointIndicatorUri": "Resources/Images/Icons/location-direction-red-32.png"
              }
            ]
          ...

    The example markup given above assumes that the web page and the viewer are deployed to the same domain. If they are deployed to different domains, you must specify the full URL, for example, http://mymaps.mydomain.com/maps/Resources/3rdPartyMaps/BingMaps.html.

     

  4. Save the file.

  5. Repeat these steps for the other configuration file.

Step 3: Configure cross-domain access

If the Bing Maps web page is deployed to a different domain than the viewer, then you must configure cross-domain access so the viewer and integration pane can communicate with each other. If the web page and viewer are deployed to the same domain, skip this step.

  1. Configure the web page's origin:

    1. In one of the viewer's configuration files, add the web page's origin to the Integration Module's allowedOrigins property:

      {
         "moduleName": "Integration",
         "moduleType": "geocortex.essentialsHtmlViewer.mapping.modules.integration.IntegrationModule",
         "configuration": {
            "allowedOrigins": ["http://mymaps.mydomain.com"]
         }
         ...

      The origin that you configure in the allowedOrigins property must be identical to the URL that you configure in the externalComponent's uri property.

    2. Save the file.

    3. Repeat these steps for the other configuration file.

  2. Configure the viewer's origin:

    1. Open ThirdPartyMap.js.

      In the default deployment, the file is here:

      C:\inetpub\wwwroot\Html5Viewer\Resources\3rdPartyMaps\ThirdPartyMap.js

    2. Find the following line:

      this.allowedOrigins = [];
    3. Type or paste the viewer's origin in the array, within quotation marks:

      this.allowedOrigins = ["http://myviewers.mydomain.com"];

      The origin that you configure in ThirdPartyMap.js's allowedOrigins property must be identical to the viewer's origin as it appears in the browser. Note that http://myviewers does not match http://myviewers.mydomain.com, even though they map to the same machine.

    4. Save the file.

Step 4: Add the Linked Maps button to the toolbar

  1. In Geocortex Essentials Manager, edit the viewer that you want to configure—edit the site that the viewer belongs to, click Viewers in the side panel, and then click the Edit icon beside the viewer.

  2. Click Toolbar in the side panel.

  3. In the Available Tools column, find the Linked Maps tool and drag it to the desired position in the Configured Toolbar column.

  4. Click Apply Changes.

  5. Click Save Site.

Example 2 - Integrate with Pictometry

This example shows how to integrate Pictometry into an HTML5 viewer using the sample Pictometry web page that ships with the Viewer.

In this example, the integration pane (ExternalComponentView) is closed by default and the toolbar includes the Linked Maps button. When the user clicks the button, Pictometry opens in an integration pane with a header.

The main steps to adapt the Pictometry sample are:

  1. Adapt the sample Pictometry web page:

    1. Configure your Pictometry keys.

    2. If the viewer belongs to a secured site and SSL is enforced, adapt the Pictometry URLs to use SSL.

  2. Add an external component for Pictometry to the Integration Module.

  3. Configure cross-domain access.

    You only need to do this if the sample Pictometry web page is deployed to a different domain than the viewer.

  4. Add the Linked Maps button to the toolbar.

Step 1: Adapt the sample Pictometry web page

  1. Run a text editor as an administrator.

  2. Locate Pictometry.aspx in the viewer's 3rdPartyMaps folder in IIS.

    In the default deployment, the file is here:

    C:\inetpub\wwwroot\Html5Viewer\Resources\3rdPartyMaps\Pictometry.aspx

  3. Open Pictometry.aspx in the editor.

  4. Configure your Pictometry keys:

    1. Find the following lines:

      protected static string ApiKey = "";
      protected static string SecretKey = "";
    2. Type or paste your Pictometry keys:

      1. Put the API Key between the ApiKey quotation marks.

      2. Put the Secret Key between the SecretKey quotation marks.

      The API Key and Secret Key are provided by Pictometry.

  5. If the viewer belongs to a secured site and SSL is enforced:

    1. Find the following lines:

      public string IpaLoadUrl = "http://pol.pictometry.com/ipa/v1/load.php";
      public string IpaJsLibUrl = "http://pol.pictometry.com/ipa/v1/embed/host.php?apikey=" + ApiKey;
    2. Change the protocols to https:

      public string IpaLoadUrl = "https://pol.pictometry.com/ipa/v1/load.php";
      public string IpaJsLibUrl = "https://pol.pictometry.com/ipa/v1/embed/host.php?apikey=" + ApiKey;
  6. Save the file.

Step 2: Add an external component for Pictometry to the Integration Module

If you already have one or more externalComponents configured when you add the Pictometry external component, remember to separate the components using commas. You may also want to configure the defaultComponent if you have more than one external component configured.

  1. Run an XML editor or text editor as an administrator.

  2. Open one of the viewer configuration files, Desktop.json.js or Tablet.json.js, in the editor.

    By default, the configuration files are here:

    C:\Program Files (x86)\Latitude Geographics\Geocortex Essentials\[instance]\REST Elements\Sites\[site]\Viewers\[viewer]\VirtualDirectory\Resources\Config\Default\

  3. Add an external component for Pictometry to the Integration Module's externalComponents property:

    {
      "moduleName": "Integration",
      ...
      "viewModels": [
        {
          ...
          "configuration": {
            ...
            "externalComponents": [
              {
                "id": "pictometry",
                "displayName": "Pictometry",
                "uri": "Resources/3rdPartyMaps/Pictometry.aspx",
                "viewpointIndicatorUri": "Resources/Images/Icons/location-direction-purple-32.png"
              }
            ]
          ...

    The example markup given above assumes that the web page and the viewer are deployed to the same domain. If they are deployed to different domains, you must specify the full URL, for example, http://mymaps.mydomain.com/maps/Resources/3rdPartyMaps/Pictometry.aspx.

     

  4. Save the file.

  5. Repeat these steps for the other configuration file.

Step 3: Configure cross-domain access

If the Pictometry web page is deployed to a different domain than the viewer, then you must configure cross-domain access so the viewer and integration pane can communicate with each other. If the web page and viewer are deployed to the same domain, skip this step.

  1. Configure the web page's origin:

    1. In one of the viewer's configuration files, add the web page's origin to the Integration Module's allowedOrigins property:

      {
         "moduleName": "Integration",
         "moduleType": "geocortex.essentialsHtmlViewer.mapping.modules.integration.IntegrationModule",
         "configuration": {
            "allowedOrigins": ["http://mymaps.mydomain.com"]
         }
         ...

      The origin that you configure in the allowedOrigins property must be identical to the URL that you configure in the externalComponent's uri property.

    2. Save the file.

    3. Repeat these steps for the other configuration file.

  2. Configure the viewer's origin:

    1. Open ThirdPartyMap.js.

      In the default deployment, the file is here:

      C:\inetpub\wwwroot\Html5Viewer\Resources\3rdPartyMaps\ThirdPartyMap.js

    2. Find the following line:

      this.allowedOrigins = [];
    3. Type or paste the viewer's origin in the array, within quotation marks:

      this.allowedOrigins = ["http://myviewers.mydomain.com"];

      The origin that you configure in the ThirdPartyMap.jsallowedOrigins must be identical to the viewer's origin as it appears in the browser. Note that http://myviewers does not match http://myviewers.mydomain.com, even though they map to the same machine.

    4. Save the file.

Step 4: Add the Linked Maps button to the toolbar

  1. In Geocortex Essentials Manager, edit the viewer that you want to configure—edit the site that the viewer belongs to, click Viewers in the side panel, and then click the Edit icon beside the viewer.

  2. Click Toolbar in the side panel.

  3. In the Available Tools column, find the Linked Maps tool and drag it to the desired position in the Configured Toolbar column.

  4. Click Apply Changes.

  5. Click Save Site.