JMap Server SDK

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 lost if you update the deployment or its template’s files.

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 copy that file to a separate web server in order to confirm that Cross-Origin Resource Sharing and the X-frame-options were properly enabled.

Embedding a map in an iframe:

To display JMap Web in an iframe, simply add the iframe with the “scr” attribute pointing to the JMap Web deployment.

<!-- Add this if you use google maps features in your deployment --> <iframe height="450px" width="600px" src="https://jmap7.jmaponline.net/montreal_web"></iframe>

You can also pass a sessionId, see the embed_example page on how to retreive a session Id from the REST API.

<!-- Add this if you use google maps features in your deployment --> <iframe height="450px" width="600px" src="https://jmap7.jmaponline.net/montreal_web?sessionId=123456789"></iframe>

You will most likely be displaying the map from another origin, to allow the application to be displayed from another origin, the next step is to update your deployment and add your allowed origins in the advanced options.

If you encounter this message in the web console, make sure you allow the origin in the X-frame-options with options “Any” or “Allow-from”:

Refused to display 'https://jmap7.jmaponline.net/montreal_web/' in a frame because it set 'X-Frame-Options' to 'sameorigin'.

Embedding a map in a Div

To have the application code ready you will need to add the following lines in the <head> portion of the document where you wish to embed your deployment.

*Note that the code in /jmap is available without login because it is allowed in the bypass filter of your deployment.

<!-- Add this if you use google maps features in your deployment --> <script type="text/javascript" src="https://maps.googleapis.com/maps/api/js?v=3.36&key=YOURGOOGLEMAPKEY"></script> <link rel="stylesheet" href="[YourDeploymentAdress]/jmap/css/jmap.min.css"> <script type="text/JavaScript" src="[YourDeploymentAdress]/jmap/jmap.min.js"></script>

  • You might need to adjust the relative path mentioned above.•Including JQuery is not necessary if you already use it. JMap Web requires a minimum version of 2.2.4 to assure most functionalities

  • Be aware that this will replace your JQuery librairy, if you need to keep a specific version, consider using an iframe instead.

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>

Note the JMap Web tool bar takes a static height of 45 pixels.

Include the following Javascript to trigger map initialization without Authorization.

// <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.    url: '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.

Dealing with Authentication in a Div

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 = {      
url: 'http://192.168.0.80:8080/web_deployment'      
mapConfig: {},      
onMapInit: function() {       
console.log('Map was initialized.');      
}     
};       
JMap.initialize(document.getElementById('map'), options);    
});   
}); 
</script>

Dealing with CORS (Cross-Origin Resource Sharing)

If your map is located within the div of a page that is hosted on a different Origin that of your JMap Server, you will need to modify the Cors filter options of your web.xml file.

Check the Tomcat documentation here

Instantiate and map the CORS filter, start by activating the Cross-Origin Ressource Sharing option in the Advanced Options of the Deployment’s Wizard and skip to the end.

Open the web.xml and look for the CorsFilter settings.

<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>

Example for a map embedded without Authorization requirements, needs to allow anonymous login.

<filter>

<filter-name>JMapLoginFilter_index</filter-name>

<!-- ... -->

<init-param>

<param-name>httpauthentication</param-name>

<param-value>false</param-value>

</init-param>

</filter>

<!-- ... -->

<filter>

<filter-name>CorsFilter</filter-name>

<filter-class>org.apache.catalina.filters.CorsFilter</filter-class>

<init-param>

<param-name>cors.allowed.origins</param-name>

<param-value>*</param-value>

</init-param>

<init-param>

<param-name>cors.allowed.headers</param-name>

<param-value>Content-Type,X-Requested-With,Origin,Cookie</param-value>

</init-param>

<init-param> <param-name>cors.exposed.headers</param-name>

<param-value>sessionId</param-value>

</init-param>

</filter>

<filter-mapping>

<filter-name>CorsFilter</filter-name>

<url-pattern>/*</url-pattern>

</filter-mapping>

Example for a map embedded with Authorization requirement

Note that the wildcard (*) mark is not allowed in the origins list when you require authentication with Access-Control-Request-Headers, and credientials support must be set to true.

<filter>

<filter-name>JMapLoginFilter_index</filter-name>

<!-- ... -->

<init-param>

<param-name>httpauthentication</param-name>

<param-value>true</param-value>

</init-param>

</filter>

<!-- ... -->

<filter>

<filter-name>CorsFilter</filter-name>

<filter-class>org.apache.catalina.filters.CorsFilter</filter-class>

<init-param>

<param-name>cors.allowed.origins</param-name>

<param-value>http://192.168.0.37:8081,https://www.google.com</param-value>

</init-param>

<init-param>

<param-name>cors.allowed.methods</param-name>

<param-value>GET,POST,HEAD,OPTIONS,PUT,DELETE</param-value>

</init-param>

<init-param>

<param-name>cors.allowed.headers</param-name>

<param-value>Content-Type,X-Requested-With,accept,Authorization,Origin,Access-Control-Request-Method,Access-Control-Request-Headers,x-auth-token,Cookie</param-value>

</init-param>

<init-param>

<param-name>cors.exposed.headers</param-name>

<param-value>Access-Control-Allow-Origin,Access-Control-Allow-Credentials,sessionId</param-value>

</init-param>

<init-param>

<param-name>cors.support.credentials</param-name>

<param-value>true</param-value>

</init-param>

</filter>

<filter-mapping>

<filter-name>CorsFilter</filter-name>

<url-pattern>/*</url-pattern>

</filter-mapping>

PrécédentDeploying JMap Web Extensions

Dernière mise à jour

K2 Geospatial 2022