Embedding a JMap Web Deployment Into Your own Application

 

JMap Web's design allows the embedding of JMap Web deployments into your own web applications. This section details the necessary steps to enable application embedding.

Copying the JMap Web Libraries and Dependencies to Your Web Server

Your deployed JMap Web applications, as they are now being served by JMap's embedded Tomcat instance, contain the libraries and web services required for application embedding. Your application's files are located in the /applications/deployed directory of your JMap Server.

Among those files is the jmap directory. It contains all necessary resources required to embed your JMap deployment. This directory and its contents must be copied to your web server and be accessible by your web application's pages.

JMap Web's dependencies will be loaded as part of the initialization process prior to displaying the map. For more details regarding the initialization process refer to the JMap Web's Initialization Process section of this document.

•JQuery is required during the map initialization process and as such must be present in your application's document.
•Including JMap Web's dependencies's stylesheets will alter the styles of your document. Currently, there is unfortunately no way to avoid this.

Authorizing Cross-Origin Resource Sharing

In order to allow JMap Web Deployments to be embedded, a few tweaks to your deployment's web.xml files are necessary.

•Modifying the deployment's web.xml file will require you to unload/load your deployment. This can be done in JMap Admin's deployment section.
•All modifications to your deployment's files will be loss if you update the deployment or its template's files.

 

1. Enable HTTP Authentication for the JMapLoginFilter_index filter.

<filter>
  <filter-name>JMapLoginFilter_index</filter-name>
  <!-- ... -->
  <init-param>
    <param-name>httpauthentication</param-name>
    <param-value>true</param-value>
  </init-param>
</filter>

 

2. Instanciate and map the CORS filter. Add the following declarations before the first ByPassFilter mapping.

<filter>
<filter-name>CorsFilter</filter-name>
<filter-class>org.apache.catalina.filters.CorsFilter</filter-class>
<init-param>
  <param-name>cors.allowed.headers</param-name>
  <param-value>Content-Type,X-Requested-With,accept,Origin,Access-Control-Request-Method,Access-Control-Request-Headers,Authorization,Cookie</param-value>
</init-param>
<init-param>
  <param-name>cors.exposed.headers</param-name>
  <param-value>Access-Control-Allow-Origin,Access-Control-Allow-Credentials</param-value>
</init-param>
</filter>
<filter-mapping>
<filter-name>CorsFilter</filter-name>
<url-pattern>/*</url-pattern>
</filter-mapping>

Embedding a map

Once the jmap directory is copied to your web server, you will need to add the following script references in the <head> portion of the document where you wish to embed your deployment:

<script type="text/JavaScript" src="jmap/vendor/jquery-1.9.1.min.js"></script>
<script type="text/JavaScript" src="jmap/jmap.min.js"></script>
•You might need to adjust the relative paths mentioned above.
•Including JQuery is not necessary if you already use it. JMap Web requires a minimum version of 1.9.1 to assure most functionalities.

To initialize the map, you will need to provide an empty div into which the map will be created.

<div id="map" style="height: 600px; width: 600px;"></div>

Tip: Don't see the map? Make sure your div is properly sized.

Include the following Javascript to trigger map initialization.

<script type="text/JavaScript">
 $(document).ready(function() {
  var options = {
    // The URL of your deployed application. This must be an address that your users may access.
     jmapUrl: 'http://192.168.0.80:8080/web_deployment'
   };
 
   JMap.initialize(document.getElementById('map'), options);
 });
</script>

The JMap.initialize function that is called above is the same as the one that was detailed previously here. You may customize the embedded application by specifying those same configuration properties in a mapConfig object literal supplied in the options argument.

 

embed_example.html

Included in your deployed application's directory is an embed_example.html file. It serves as an example of a JMap Web embedded application. Open that file in a text editor to see how application embedding is done.

You can also copy that file and the jmap directory to a seperate web server in order to confirm that Cross-Origin Resource Sharing was properly enabled.

Dealing with Authentication

If you enabled controlled access on your JMap Web deployment, you will need to authenticate as a JMap User prior to initializing the map.

The following is provided as an example and IS NOT a recommended way of authenticating yourself to JMap Server:

<script type="text/JavaScript">
   $(document).ready(function() {
     $.ajaxSetup({
       xhrFields: {
         withCredentials: true
       }
     });
 
     $.ajax('http://192.168.0.80:8080/web_deployment/ajaxdispatch', {
       data: {
         action: 'ping'
       },
       beforeSend: function(xhr) {
        // Replace 'USERNAME:PASSWORD' with a valid string value.
         xhr.setRequestHeader('Authorization', 'Basic ' + btoa('USERNAME:PASSWORD'));
       },
     }).done(function(data, textStatus, jqXHR) {
      var options = {
         jmapUrl: 'http://192.168.0.80:8080/web_deployment'
         mapConfig: {},
         onMapInit: function() {
           console.log('Map was initialized.');
         }
       };
 
       JMap.initialize(document.getElementById('map'), options);
     });
   });
</script>