Javascrip based components

Creating a component using a 3rd Party JavaScript library

The JBStrap framework allows you to create your own components, based on third-party libraries, that you can use the same way as if they were default JBStrap component. This could be a different Combobox, a map component, etc.

To begin the development of your Component, you need to access the JavaScript library. You can access it locally, or remotely, but it is recommended that you use it locally, in case of a version change, or if the server where the library is normally found cannot be accessed, your components can still work.

In this section, a simplified map component will be created. The component will display a zoomable map on the user interface. In this example, we use the Leaflet JavaScript library . The library offers much deeper functionality, but we will try to keep it simple in this example.

Implementation

As a first step, download the library and it’s CSS class. Place these in the project’s WebContent folder. After this, the library will be accessible.

The next step is registering the style sheet, so that it is automatically downloaded when a client connects.

  Registering the CSS file. We recommend that you do this in the Startup class:  
        
JBStrap.addStyleSheet("leaflet.css");

In order to be able to use your component easily, create a JavaScript package, in which the needed functions are implemented. These are responsible for interpreting (wrapper method) instructions for the map API and storing the needed data on the client-side.

  Source code of the file, containing the Leaflet map API and the JavaScript responsible for interpreting instructiosn between the API and component:  
        
/**
* Initializing map and storing map object in the DOM element
*/
function leafletInit(componentId) {
	var map = L.map(componentId).setView([0,0], 1);
	L.tileLayer('http://{s}.tile.osm.org/{z}/{x}/{y}.png', {
		attribution: '© <a href="http://osm.org/copyright">OpenStreetMap</a> contributors'
	}).addTo(map);
	$('#' + componentId).data('_map', map);
}
/**
* Add new POI to the map
*/
function addPoi(componentId, latitude, longitude, title, city, country) {
	var map = $('#' + componentId).data('_map');
	marker = L.marker([latitude, longitude]).addTo(map);
	marker.bindPopup('<b>' + title + '</b><br>' + country + ' / ' + city);
	var markers = $('#' + componentId).data("_markers");
	if (markers == undefined) {
		markers = [];
	}
	markers.push({marker : marker, coord: [latitude, longitude]});
	$('#' + componentId).data('_markers', markers);
}
/**
* Show POI on the map: move map center to the POI and zoom in on the POI
*/
function showPOI(componentid, index) {
	var map = $('#' + componentid).data('_map');
	var markers = $('#' + componentid).data('_markers');
	if (markers.length > index && index >= 0) {
		var poi = markers[index];
		map.setView(poi.coord, 16);
		poi.marker.openPopup();
	}
}
/**
* Reset the map to the initializing state
*/
function reset(componentId) {
	var map = $('#' + componentId).data('_map');
	var markers = $('#' + componentId).data('_markers');
	if (markers != undefined) {
		for (i = 0; i < markers.length; i++) {
			markers[i].marker.closePopup();
		}
	}
	map.setView([0,0], 1);
}

Save this JavaScript file to the project’s WebContent folder, as map.js . The code in this file is responsible for the component is initialization, adding POIs to the map, and resetting the map to its default state.

If this is done, implement the component, that is, create the Java code. You must extend a class from the Component class, in which you will implement the new component itself. You must call the init method in this class, as this method loads the needed JavaScript packages to the client, in case they are not loaded.

  Java source code of the Map component:  
        
package com.example.employee.components;

import java.io.StringWriter;
import java.util.ArrayList;
import java.util.List;
import java.util.Optional;

import com.jbstrap.core.Parameters;
import com.jbstrap.core.websocket.JavaScriptLoadError;
import com.jbstrap.ui.Component;

public class Map extends Component<Map> {
	
	private final List<Parameters> POIs = new ArrayList<>();
	
	/**
	 * Create a new Map component
	 */
	public Map(final String width, final String height) {
		super(null);
		setStyle("width", width);
		setStyle("height", height);
	}
	
	/**
	 * Initialize the Map component after it is drawn on the client.
	 * The method loads the required JavaScript files and show added POIs on the map
	 */
	@Override
	public void init() throws JavaScriptLoadError {
		// Load Leaflet JavaScript API
		getClient().loadJavaScript("leaflet.min.js");
		// Load map wrapper JavaScript
		getClient().loadJavaScript("map.js");
		// Initialize the component
		getClient().runJavaScript("leafletInit(" + getId() + ");");
		// placing POIs on the map
		if (!POIs.isEmpty()) {
			POIs.forEach(poi -> runJavaScript("addPoi('" + getId() + "', " + poi.getAsDouble("lattitude") + ", " + poi.getAsDouble("longitude") + ", '" + poi.getAsString("title") + "', '" + poi.getAsString("city") + "', '" + poi.getAsString("country") + "');"));
		}
		super.init();
	}
	
	/**
	 * Add new POI to the map
	 * @param lattitude The POI latitude
	 * @param longitude The POI longitude
	 * @param title The POI name. This name is shown in the POI popup window
	 * @param city The city in which the POI is located
	 * @param country The country in which the POI is located
	 */
	public Map addPOI(final double latitude, final double longitude, final String title, final String city, final String country) {
		final Parameters poi = new Parameters()
				.add("latitude ", latitude)
				.add("longitude", longitude)
				.add("title", title)
				.add("city", city)
				.add("country", country);
		POIs.add(poi);
		// Send POI data to the component. The JavaScript statement will only run if the component is
		//already drawn, that is, if the POI is added to the map after the component has been drawn.
		runJavaScript("addPoi('" + getId() + "', " + latitude + ", " + longitude + ", '" + title + "', '" + city + "', '" + country + "');");
		return this;
	}
	
	/**
	 * Reset the map view to the base position
	 */
	public Map reset() {
		runJavaScript("reset('" + getId() + "');");
		return this;
	}
	
	/**
	 * Show POI on the map. Move map center to the POI and zoom in
	 * @param index The index of the POI to display. The POI of the first one added is 0. If a non-POI index is specified, the method does nothing
	 */
	public Map showPOI(final int index) {
		if (index >= 0 && index < POIs.size()) {
			runJavaScript("showPOI('" + getId() + "', " + index + ");");
		}
		return this;
	}
	
	/**
	 * Get a POI by its name
	 * @return The POI corresponding to the given name. If there is no correct POI, then null
	 */
	public Parameters getPOIByTitle(final String title) {
		if (title != null) {
			final Optional<Parameters> poi = POIs.stream().filter(p -> title.equals(p.getAsString("title"))).findFirst();
			return poi.isPresent() ? poi.get() : null;
		}
		return null;
	}
	
	/**
	 * Writer component HTML to the page
	 */
	@Override
	public void writeHTML(final StringWriter writer) {
		writer.write(openTag("div"));
		writer.write(closeTag("div"));
	}
	
}

In the above code, a new component was created. You need to specify how big the map should be on the user interface. This can be defined by using CSS, following the CSS3 standard. The component has four methods, these are used to create, display or get POIs and you can reset the component to be in its default state. When any of the methods are called, the changes are applied instantly on both the client and server-side, without redrawing the component, if the map is already displayed.

In the source code, there are two more special methods, inherited from the Component class. The first is the init method. You have to implement the client-side component initialization. You don’t have to do this for every component, but if the component uses a JavaScript library, it is mandatory. The method is called after the component has been drawn, so every related HTML DOM object already exists during the component initialization. In this method, in the case of this map component, 4 things are happening:

Loading the Leaflet JavaScript API, if it is not yet loaded on the client
Loading the self-made JavaScript wrapper, if it is not yet loaded
Initializing the map on the interface, displaying the map
If you add a POI before the component is displayed, those will be placed on the map during initialization

With this, the component will be displayed according to the server-side settings. If you add a new POI after this, the addPOI method will be used to place a POI on the client-side map.

The other special method is the writeHTML method, which is responsible for drawing the component. Every component must implement this, as the Component ancestor class has this as an abstract method. You have to implement the drawing of the HTML content, with the help of the StringWriter object. In this case this means that you are placing a div tag in the HTML DOM, which marks the placement of the map itself. The map will be displayed in this div tag, meaning that the size of the map can be modified by altering the size of the div tag.

After this, the component can be used anywhere freely in the JBStrap framework. You can place it on a component or page. Next, let’s see how to place the Map component on to a page. In the following example, the Map component will be placed on a page, and there will be a toolbar with 4 buttons above the map. Three of these buttons will display three POIs on the map, (The London Eye, The Leaning Tower of Pisa and The Statue of Liberty). The fourth button will reset the map to its default state.

  Source code of the page displaying the map:  
        
public class MapTestPage extends BasePage {

    private final Button london = new Button(Icon.DIAMOND, "London Eye", ButtonType.PRIMARY, ButtonSize.SMALL);
	private final Button pisa = new Button(Icon.DIAMOND, "Leaning Tower of Pisa", ButtonType.PRIMARY, ButtonSize.SMALL);
	private final Button nyc = new Button(Icon.DIAMOND, "Statue of Liberty National Monument", ButtonType.PRIMARY, ButtonSize.SMALL);
	private final Button reset = new Button(Icon.STAR, "Reset the map", ButtonType.DANGER, ButtonSize.SMALL);

	@Override
	public void build() {
		final Map map = new Map("640px", "480px")
				.addPOI(51.5033240,  -0.119500, "London Eye", "London", "Great Britain")
				.addPOI(43.7230000,  10.396620, "Leaning Tower of Pisa", "Pisa", "Italy")
				.addPOI(40.6892494, -74.044553, "Statue of Liberty National Monument", "New York", "USA");
		london.addClickHandler(event -> map.showPOI(0));
		pisa.addClickHandler(event -> map.showPOI(1));
		nyc.addClickHandler(event -> map.showPOI(3));
		reset.addClickHandler(event -> map.reset());
		addComponents(
				new Toolbar().addButtons(london, pisa, nyc, reset),
				map
				);
	}
}