apprt-integration

This bundle provides a way to control an embedded map.apps app from its surrounding web page.

Usage

No configuration is required, default values are used.

Motivation

The focus of this bundle is to provide the necessary infrastructure to:

  1. Allow a web page to get access to an application API provided by map.apps
  2. Enable developers to extend/define the available commands of the application API provided by map.apps

This makes it possible for you to create focused APIs to integrate map.apps applications into Content Relationship Management systems (CRM).

The apprt-integration bundle itself contains no functions to control the application. It only provides the necessary infrastructure. Some default map control functions are provided by the bundle integration-map.

Use cases

How to access the Integration API of an app from an iframe

To embed the application inside an iframe into a web page, create a custom app.html file and set the iframe's src attribute to that file. To ensure the app is not blocked by any access control restrictions, the app.html file needs to be published under the same origin as the web page. This means that it must be accessed through the same protocol, host, and port.

The app.html needs to register the Integration API in its global window object to expose it to the surrounding web page:

<!DOCTYPE html>
<html>
<head>
    <script type="text/javascript" src="/path-to/apprt-boot/<version>/boot.js"></script>
    <script type="text/javascript">
        $apprt.startApp({
            app: "myapp",
            configLocation: "builderapps"
        }, function (framework) {
            // register the API as global object
            window.integrationAPI = framework.integrationAPI;

            // inform possible 'wait' callback that API is now available
            var callback = window.integrationAPIAvailable;
            if (callback){
                callback(window.integrationAPI);
            }
        });
    </script>
</head>
<body></body>
</html>

From the web page containing the iframe you can now access the integration API as follows:

<!DOCTYPE html>
<html>
<head>
    <script type="text/javascript">
        var appAPI;
        window.addEventListener("load", function(event) {
            var iframe = document.getElementById("app-iframe");
            var iframeWindow = iframe.contentWindow;
            appAPI = iframeWindow.integrationAPI;
            if (!appAPI){
                // register callback to be informed about API availability
                iframeWindow.integrationAPIAvailable = function(integrationAPI){
                    appAPI = integrationAPI;
                }
            }
        }, false);

        function zoom(){
            if (appAPI){
                // zoom to a special point on the map
                appAPI.zoomTo({x: 52, y : 7});
            }
        }
    </script>
</head>
<body>
    <iframe id="app-iframe" src="app.html"></iframe>
    <button onclick="zoom()">Zoom</button>
</body>
</html>

How to access the Integration API from a surrounding web page

To access the Integration API from a surrounding HTML page, add the integration-map bundle to your app and embed the app as in the following sample:

<!DOCTYPE html>
<html>
<head>
    <style>
        #mapapps-app {
            position: relative;
            margin: 0;
            padding: 0;
            width: 800px;
            height: 800px;
        }
    </style>
    <script type="text/javascript" src="/path-to/apprt-boot/<version>/boot.js"></script>
    <script type="text/javascript">
        $apprt.startApp({
            app: "myapp",
            domId: "mapapps-app",
            configLocation: "builderapps"
        }, function (framework) {

            // this property is only available if the
            // bundle "apprt-integration" is part of the app
            var appAPI = framework.integrationAPI;

            // the following methods are only available if
            // the bundle "integration-map" is part of the app

            // wait until the map is ready
            appAPI.whenMapReady(function () {
                // zoom to a special point on the map
                appAPI.zoomTo({x: 7, y : 52});
            });

        });
    </script>
</head>
<body>
    <h1>Hello World</h1>
    <div id="mapapps-app"></div>
</body>
</html>

NOTE: We recommend the use of iframe to integrate map.apps applications. The iframe integration ensures that the JavaScript and CSS of map.apps does not interfere with the JavaScript or CSS on your page.

How to implement an Integration API extension

To develop custom functions that interact with map.apps from a surrounding web page, create a new bundle. The bundle integration-map is an example of such an extension bundle and you can utilize it as a template for your custom bundles.

In your bundle's manifest.json file create a component that provides the service apprt-integration.Extension:

"components": [
        {
            "name": "IntegrationExtension",
            "provides": ["apprt-integration.Extension"],
            "references": [
                {
                    "name": "_mapWidgetModel",
                    "providing": "map-widget.MapWidgetModel"
                }
            ]
        }
    ]

The IntegrationExtension component is implemented by an ordinary class. All its methods that are considered as public are registered as extension methods of the Integration API and are accessible from the embedding page.

The following methods are not treated as public and are not exposed:

Here's an example of a custom IntegrationExtension:

export default class IntegrationExtension {

    zoomOut() {
        this._mapWidgetModel.view.goTo({zoom: ++this._mapWidgetModel.zoom});
    }

    zoomIn() {
        this._mapWidgetModel.view.goTo({zoom: --this._mapWidgetModel.zoom});
    }
}

It adds the methods zoomOut and zoomIn to the Integration API and enable you to control the map zoom from the embedding web page.