Getting Started

Getting Started with Java Leaflet

This guide will help you get up and running with Java Leaflet in minutes, whether you're building a JavaFX desktop application or a Vaadin web application.

Table of Contents

• Installation
  • JavaFX Setup
  • Vaadin Setup
• Creating Your First Map
  • JavaFX Example
  • Vaadin Example
• Basic Concepts
• Next Steps

---

Installation

Prerequisites

• Java 17 or higher
• Maven 3.6+ or Gradle 7+
• For JavaFX: JavaFX SDK 19+
• For Vaadin: Node.js 16+ (for frontend compilation)

JavaFX Setup

Add the JavaFX dependency to your pom.xml:

<dependencies>
    <!-- Java Leaflet for JavaFX -->
    <dependency>
        <groupId>io.github.makbn</groupId>
        <artifactId>jlmap-fx</artifactId>
        <version>2.0.0</version>
    </dependency>
</dependencies>

If using Gradle:

dependencies {
    implementation 'io.github.makbn:jlmap-fx:2.0.0'
}

Vaadin Setup

For Vaadin applications, add the Vaadin dependency:

<dependencies>
    <!-- Java Leaflet for Vaadin -->
    <dependency>
        <groupId>io.github.makbn</groupId>
        <artifactId>jlmap-vaadin</artifactId>
        <version>2.0.0</version>
    </dependency>

    <!-- Vaadin Spring Boot Starter (if using Spring Boot) -->
    <dependency>
        <groupId>com.vaadin</groupId>
        <artifactId>vaadin-spring-boot-starter</artifactId>
        <version>24.8.6</version>
    </dependency>
</dependencies>

---

Creating Your First Map

JavaFX Example

Create a simple JavaFX application with an interactive map:

package com.example;

import io.github.makbn.jlmap.fx.JLMapView;
import io.github.makbn.jlmap.map.JLMapProvider;
import io.github.makbn.jlmap.model.JLLatLng;
import javafx.application.Application;
import javafx.scene.Scene;
import javafx.scene.layout.BorderPane;
import javafx.stage.Stage;

public class MyFirstMap extends Application {

    @Override
    public void start(Stage primaryStage) {
        // Create the map view
        JLMapView mapView = JLMapView.builder()
                .jlMapProvider(JLMapProvider.OSM_MAPNIK.build())
                .startCoordinate(new JLLatLng(51.505, -0.09)) // London
                .showZoomController(true)
                .build();

        // Create the scene
        BorderPane root = new BorderPane(mapView);
        Scene scene = new Scene(root, 800, 600);

        // Configure the stage
        primaryStage.setTitle("My First Java Leaflet Map");
        primaryStage.setScene(scene);
        primaryStage.show();
    }

    public static void main(String[] args) {
        launch(args);
    }
}

Run the application:

mvn javafx:run

Vaadin Example

Create a Vaadin view with an interactive map:

package com.example.views;

import com.vaadin.flow.component.orderedlayout.VerticalLayout;
import com.vaadin.flow.router.Route;
import io.github.makbn.jlmap.map.JLMapProvider;
import io.github.makbn.jlmap.model.JLLatLng;
import io.github.makbn.jlmap.vaadin.JLMapView;

@Route("")
public class MainView extends VerticalLayout {

    public MainView() {
        setSizeFull();
        setPadding(false);

        // Create the map view
        JLMapView mapView = JLMapView.builder()
                .jlMapProvider(JLMapProvider.OSM_MAPNIK.build())
                .startCoordinate(new JLLatLng(48.864716, 2.349014)) // Paris
                .showZoomController(true)
                .build();

        mapView.setSizeFull();
        add(mapView);
    }
}

Run the application:

mvn spring-boot:run

Then open http://localhost:8080 in your browser.

---

Basic Concepts

1. Map Providers

Java Leaflet supports multiple tile providers:

// OpenStreetMap Mapnik (default)
JLMapProvider.OSM_MAPNIK.build()

// MapTiler (requires API key)
JLMapProvider.MAP_TILER
    .parameter(new JLMapOption.Parameter("key", "YOUR_API_KEY"))
    .build()

// Water Color
JLMapProvider.WATER_COLOR
    .parameter(new JLMapOption.Parameter("key", "YOUR_API_KEY"))
    .build()

2. Adding Markers

Add interactive markers to your map:

// After map is loaded
mapView.getUiLayer().addMarker(
    new JLLatLng(51.505, -0.09),
    "Hello London!",
    true  // draggable
);

3. Layer System

Java Leaflet organizes functionality into four main layers:

// UI Layer - markers, popups, images
mapView.getUiLayer().addMarker(...);

// Vector Layer - polygons, polylines, circles
mapView.getVectorLayer().addCircle(...);

// Control Layer - zoom, pan, bounds
mapView.getControlLayer().setZoom(12);

// GeoJSON Layer - GeoJSON data
mapView.getGeoJsonLayer().addFromFile(...);

4. Event Handling

Respond to user interactions:

JLMarker marker = mapView.getUiLayer().addMarker(...);

marker.setOnActionListener((source, event) -> {
    if (event instanceof ClickEvent clickEvent) {
        System.out.println("Marker clicked at: " + clickEvent.center());
    }
});

---

Adding More Features

Adding a Popup

JLPopup popup = mapView.getUiLayer().addPopup(
    new JLLatLng(51.5, -0.09),
    "<h3>Hello!</h3><p>This is a popup</p>"
);

Drawing Shapes

// Draw a circle
mapView.getVectorLayer().addCircle(
    new JLLatLng(51.508, -0.11),
    500,  // radius in meters
    JLOptions.builder()
        .color(JLColor.BLUE)
        .fillColor(JLColor.BLUE)
        .fillOpacity(0.3)
        .build()
);

// Draw a polygon
JLLatLng[] vertices = {
    new JLLatLng(51.509, -0.08),
    new JLLatLng(51.503, -0.06),
    new JLLatLng(51.51, -0.047)
};

mapView.getVectorLayer().addPolygon(
    new JLLatLng[][][] { new JLLatLng[][] { vertices } },
    JLOptions.builder()
        .color(JLColor.RED)
        .build()
);

Controlling the View

// Pan to a location
mapView.getControlLayer().panTo(new JLLatLng(51.505, -0.09));

// Animate to a location
mapView.getControlLayer().flyTo(new JLLatLng(48.8566, 2.3522), 10);

// Zoom
mapView.getControlLayer().zoomIn(2);
mapView.getControlLayer().setZoom(12);

// Fit bounds
JLBounds bounds = JLBounds.builder()
    .southWest(new JLLatLng(51.5, -0.1))
    .northEast(new JLLatLng(51.52, -0.08))
    .build();
mapView.getControlLayer().fitBounds(bounds);

---

Complete Example

Here's a more complete example showing multiple features:

import io.github.makbn.jlmap.fx.JLMapView;
import io.github.makbn.jlmap.map.JLMapProvider;
import io.github.makbn.jlmap.model.*;
import io.github.makbn.jlmap.listener.event.ClickEvent;
import javafx.application.Application;
import javafx.scene.Scene;
import javafx.scene.layout.BorderPane;
import javafx.stage.Stage;

public class ComprehensiveExample extends Application {

    @Override
    public void start(Stage primaryStage) {
        // Create map
        JLMapView mapView = JLMapView.builder()
                .jlMapProvider(JLMapProvider.OSM_MAPNIK.build())
                .startCoordinate(new JLLatLng(51.505, -0.09))
                .showZoomController(true)
                .build();

        // Add a marker with popup
        JLMarker marker = mapView.getUiLayer().addMarker(
            new JLLatLng(51.505, -0.09),
            "Click me!",
            true
        );

        // Add click listener
        marker.setOnActionListener((source, event) -> {
            if (event instanceof ClickEvent) {
                System.out.println("Marker clicked!");
            }
        });

        // Draw a circle around the marker
        mapView.getVectorLayer().addCircle(
            new JLLatLng(51.505, -0.09),
            500,
            JLOptions.builder()
                .color(JLColor.BLUE)
                .fillOpacity(0.2)
                .build()
        );

        // Create scene
        BorderPane root = new BorderPane(mapView);
        Scene scene = new Scene(root, 1000, 700);

        primaryStage.setTitle("Java Leaflet - Comprehensive Example");
        primaryStage.setScene(scene);
        primaryStage.show();
    }

    public static void main(String[] args) {
        launch(args);
    }
}

---

Troubleshooting

JavaFX: Map Not Showing

If the map doesn't appear:

1. Check JavaFX modules - Ensure JavaFX modules are in your module path
2. Wait for map load - The map loads asynchronously. Use event listeners if needed
3. Check console - Look for JavaScript errors in the console

Vaadin: Compilation Errors

If you get frontend compilation errors:

1. Install Node.js - Vaadin requires Node.js for frontend compilation
2. Run mvn clean install - This will download and install frontend dependencies
3. Check Vaadin version - Ensure you're using Vaadin 24+

Module Path Issues

If you encounter module issues:

module com.example.myapp {
    requires io.github.makbn.jlmap.fx;  // For JavaFX
    // OR
    requires io.github.makbn.jlmap.vaadin;  // For Vaadin

    requires javafx.controls;  // For JavaFX
    requires javafx.web;       // For JavaFX
}

---

Next Steps

Now that you have a basic map running, explore more features:

1. Context Menus - Add right-click menus to map objects
2. Journey System - Create animated journeys
3. API Reference - Explore the complete API
4. Examples & Tutorials - Learn from more examples
5. Architecture - Understand the internals

---

Additional Resources

• JavaFX Documentation - Learn more about JavaFX
• Vaadin Documentation - Learn more about Vaadin
• Leaflet.js - Original JavaScript library
• GitHub Repository - Source code and examples

---

Previous: ← Home | Next: Architecture Overview →