JMap Web Development

Introduction
General Information
1. Brief Overview of JMap Web’s Design
2. Third-party JavaScript Libraries Used
3. JMap Javascript Libraries and Their Architecture
JMap Web Public API
JMap Web’s Initialization Process
1. JMap.initialize(map, options)
2. After the Initialization Process
3. URL Parameters

Introduction

This section details how to develop for JMap Web as well as how to integrate JMap Web into other web applications.

JMap Web is a web application that uses technologies such as HTML5, JavaScript, CSS and JSON. The JMap Web application is built on top of third-party JavaScript libraries including OpenLayers, jQuery and many others.

General Information

Brief Overview of JMap Web’s Design

JMap Web provides a web application capable of interacting with JMap Server. Its user interface is primarily intended for use on laptop and desktop web browsers.

The key elements of a deployed JMap Web application are the following:

The client: Can be described as a single-page application (index.jsp). The client is considered the web page as it is rendered in the user’s web browser.
A Web Map Service: Provides access to the map’s tiles.
The AJAX Dispatcher: A web service to which HTTP requests are sent. The AJAX Dispatcher then dispatches the request to the appropriate “Action Handler”. This will be further discussed in the Sending Server Requests and Custom Actions section of this document.

Third-party JavaScript Libraries Used

At the time of writing this document, JMap Web currently uses the following third-party Javascript libraries. Your extensions may leverage these libraries without any additional configuration. The following table includes a brief description of how JMap Web uses these libraries.

Bibliothèque

Description

DataTables (v1.10.13)

jQuery plugin that easily enables the creation of powerful HTML tables for data representation. This is primarily used to display search results.

fancyBox (v2.1.5)

Displays content in a “lightbox” style interface. JMap Web uses fancyBox to display the full size version of documents included in mouseover popups.

Google Maps (v3)

Necessary to access Google Maps’s Roadmap, Terrain, Satellite and Hybrid base layers.

jQuery (v2.2.4)

jQuery is a fast, small, and feature-rich JavaScript library. It makes things like HTML document traversal and manipulation, event handling, animation, and Ajax much simpler with an easy-to-use API that works across a multitude of browsers.

jQuery-ui (v1.12.1)

Library of user interface components relying on the jQuery framework. Currently, JMap Web uses a custom build that includes only the autocomplete component.

moment.js (v2.18.1)

Library used to parse, validate, manipulate, and display dates in JavaScript.

malihu-custom-scrollbar-plugin(v3.1.5)

Styles the appearance of scroll bars for overflowing mouseover popups. Its primary function is to allow a more consistent appearance in various browsers.

OpenLayers (v4.1.1)

This is JMap Web’s most important library. OpenLayers allows JMap Web to display a map and manage the vast majority the user’s interaction with it.

Ol3-Google-Maps (0.14.0)

This library powered by Mapgears facilitates the use of Google Maps in OpenLayers 3.

Proj4js (v2.4.3)

Proj4js is a library that’s used to translate geographic coordinates from one map projection system to another. Proj4js is used by OpenLayers, but isn’t included with it.In order to perform transformations for named projections (ex: “EPSG:3857”), projections must be defined in Proj4js. By default, only a small number of projections are defined. JMap Web includes a Proj4js projection definition file for each projection that’s supported by JMap Server. Those projection definitions will be loaded into memory as they are required.

Bootstrap (3.3.7)

«Front-end framework» used to create user interface elements

Bootswatch (3.3.7)

“Paper” theme for Bootstrap

bootstrap-datetimepicker(v4.15.35)

Date/time picker widget based on Twitter Bootstrap.

bootstrap-multiselect (v0.9.13)

JQuery multiselect plugin based on Twitter Bootstrap.

JMap Javascript Libraries and Their Architecture

In addition to the libraries previously mentioned, JMap Web also includes its own libraries based on OpenLayers’s Class base type. This allows JMap Web to benefit from object oriented programming paradigms in a Javascript context (which usually favors a more prototypal and functionnal approach).

A JMap Javascript library essentially consists of a collection of Javascript files, styles sheets (CSS) and resources (images, sounds, etc.).

JMap Javascript libraries have been designed for use in different application templates of the “JMap Web” deployment type. By spreading the code across several libraries, code reuse is possible in various environments such as JMap Web. JMap Javascript libraries define unique behavior for specific contexts.

JMap Web uses the following JMap Javascript libraries:

core
desktop_ui

Reusable model classes are usually defined in the core library. As such, it is frequently used and is included in the vast majority of “JMap Web” application templates.

The core library is written in JavaScript ES5. In addition to JMap model classes, it includes custom OpenLayers controls and layers, HTML5 functionality wrappers and more. The core library is JMap Web lowest level Javascript library. It handles general tasks such as the initialization process of the map. All other library is then loaded on top of it as an extension.

As for desktop_ui, it mostly contains classes that focus on user interface elements. It directly makes use of the DataTables, jQuery and Twitter Bootstrap Javascript libraries. All visual elements that are not managed by OpenLayers are defined within desktop_ui.

JMap Web Public API

Included in JMap 7 is JMap Web’s public API which allows developers to easily integrate with JMap functionalities.

A generated JSdoc documentation of the javascript API is available online at http://dev.k2geospatial.com/jmap/web/api/7.0/.

JMap Web’s Initialization Process

Before moving onto the creation of a JMap Web extension, this section will explain JMap Web’s initialization process.

Note : This section refers to the JMap Web application template as it is included when JMap Server is installed. The process, as briefly described here, differs when you choose to embed a JMap deployment within your existing web application. For more details, consult the Embedding a JMap Deployment Into Your own Application section of this document.

The JMap Web application template’s files are located in $JMAP_HOME$ /applications/templates/html/web/index.jsp

This is the web document that will be served by JMap Server as the application is being requested by the user. Open this file in a text editor application. As you can notice, both jQuery and a jmap.min.js are loaded in the head portion of the document.

Further down, the map is initialized once the document is ready for manipulation.

var options = {

url: '$APPLICATION_PROTOCOL$://$APPLICATION_HOST$:$APPLICATION_WEBPORT$$PATH$',

language: '$LANGUAGE_CODE$',

embedded: true,

mapConfig: {

// Configuration properties

},

onMapInit: function() {

console.log('Map was initialized.');

}

};

$(document).ready(function() {

JMap.initialize(document.getElementById('map'), options);

});

JMap.initialize(map, options)

The JMap.initialize function is defined in the jmap.min.js file. It loads all necessary dependencies and will then initialize all of the application’s required objects. Among those objects are the globally available JMap.app and JMap.app.map.

The JMap.app object is an instance of the core library’s Application class. The JMap.app.map object is an instance of the ol.Map class.

Argument

Description

map

Required {DOMElement|String} The element or id of an existing element in your page that will contain the map.

options

Required {Object} Should at least provide a jmapUrl {String} property. Supports the following property keys: • url: Required. {String} The url of your JMap deployment. • language: {String} Set a language between French (fr), Spanish (es) or English (en), the default choice is English • mapConfig: {Object} Additional map configuration options. • embedded: {true} Makes some JMap Web components behave better visually. • onMapInit: {Function} Handler to be called once the map initialisation process is completed. Useful to add new OpenLayers.Controls once the OpenLayers library is loaded.

The mapConfig object may include the following properties to customize the application. The default value is identified in bold.

mapConfig properties

Description

Map Options

displayUnits

null | ’m’ | ’km’ | ’ft’ | ’mi’ | ’in’ | ’°’ {String} The map unit. Defaults to the JMap project’s value.

initialZoom

null {Array} Map coordinates that describe bounds: [left, bottom, right, top]

mapUnits

null | ’m’ | ’km’ | ’ft’ | ’mi’ | ’in’ | ’°’ {String} The map unit. Defaults to the JMap project’s value.

maximumExtent

null {Array} Map coordinates that describe bounds: [left, bottom, right, top]

projection

null {Object} If supplied, it must contain a string code property that corresponds to an EPSG code

Additional Map Layers

addShowPositionLayer

true | false

Services on Launch

activateGeolocationServiceOnLaunch

true | false

loadGoogleMapsApiOnLaunch

true | false - Will automatically be set to true if the deployment contains at least one Google layer or if any of the following is true: addGoogleDirections, addGoogleGeocoding, addGoogleStreetView.

Map and Navigation Options

addGeolocateButton

true | false

addCoordinateZoomButton

true | false

addInitialViewButton

true | false

addRewindViewButton

true | false

addMapOverview

true | false

isMapOverviewMaximized

true | false

addMousePosition

true | false

addScaleBar

true | false

addZoomButtons

true | false

JMap Tools

addInfoReportTool

true | false

addMeasureTools

true | false

addMeasureAreaTool

true | false

addMeasureDistanceTool

true | false

addMeasureCircularAreaTool

true | false

addMouseOverTool

true | false

addAnnotations

true | false

JMap Edition Functionalities

addEditionTools

true | false

addEditionCreateElementTool

true | false - The addEditionTools property must also be set to true for this to take effect.

addEditionModifyElementTool

true | false - The addEditionTools property must also be set to true for this to take effect.

addEditionShowElementFormButton

true | false - The addEditionTools property must also be set to true for this to take effect.

JMap Selection Functionalities

addSelectionTools

true | false - The addSelectionTools property must also be set to true for this to take effect.

addCircleSelectionTool