GWT-OpenLayers -

User Reference

This page is devided in 2 sections. First is a brief guide for working with GWT-OpenLayers in your GWT application.

Second is a step by step guide using Eclipse.

Brief Guide

Add the jar to your eclipse lib path, or the dependency to your maven pom.xml.
You will need to add the following to your gwt.xml file (see the showcase for a working example):
```
<inherits name='org.gwtopenmaps.openlayers.OpenLayers'/>
```
You will need to add the OpenLayers javascript to your html head - YOU MUST DO THIS.
```
<script src="http://www.openlayers.org/api/OpenLayers.js"></script>
```
Then you can go cut some code. Take a look at the showcase for reference. Start by looking at some basic examples (search for basic in the search box), and looking at the code using the 'View source' button.

Eclipse step by step guide

In this guide we will give a step by step overview of how to create your fist project using GWT-Openlayers. This guide will use Eclipse as an IDE, but you can use any IDE you want for developing GWT-Openlayers. Also this guide will manually download binary jars and include them in your project, it is however also possible to use maven for auto dependency (see the Brief Guide above).

Install the Eclipse GWT plugin

If you haven't done so allready start by installing the GWT plugin for Eclipse. Go to the GWT website for detailed instructions on how to do this

GWT Eclipse plugin

Creating a new project and adding the needed GWT-Openlayers dependencies

Creating a new GWT project

Start Eclipse. Go to the File menu, select New and finally select Other... In the popup type web and select Web Application Project (under Google)

Clicking the Next button will show the following popup.
Just choose a project name and a package name. Also uncheck Use Google App Engine as we are not going to host our project on Google App Engine (this however is possible).
Finally click the Finish button to let the GWT plugin create an example GWT project.

Add GWT-Openlayers dependencies to our project

First go to your .gwt.xml project definition file. In my example this file is found under src/be/frank/gwtol/Gwtoltest.gwt.xml
In this file you will find a line that says Other module inherits
Under this line add
```
<inherits name='org.gwtopenmaps.openlayers.OpenLayers'/>
```
Now we will add the Openlayers javascript files to our project.
Since we will use OpenStreetMap maps in this test project we are also adding the OpenStreetMap javascript to our project. For this we open the .html file of our project. In my example this file is found under war/Gwtoltest.html
Now add the following lines to the head tag of this document. First line is for OpenLayers, second line is for OpenStreetMap
```
<script src="http://www.openlayers.org/api/OpenLayers.js"></script>
<script src="http://www.openstreetmap.org/openlayers/OpenStreetMap.js"></script>
```
Since we now have our html file open we can also directly clean up unneeded stuff generated by the GWT Eclipse plugin.\n Just remove all lines in the body tag as these are not needed in our project.
The last thing we need to add to our project is the gwtopenlayers jar file. For now we only need the client jar file. The server jar file is only needed if you have cross-origin problems.
Download the the jar at GWT-Openlayers 1.0 Snapshot client binary jar.

Place the jar war/WEB-INF/lib.
Now add the jar file to the build path of the project.
In Eclipse open the menu Project, then select Properties, and in the popup select Java Build Path on the right. Click the Add jars... button and select the jar you just placed in the war/WEB-INF/lib directory. Finally click the OK button.

Code our project

Now everything is setup to use OpenLayers in combination with OpenStreetMap it is time to create some code. The project we are going to build will display an OpenStreetMap as a base layer. The user has the option to display normal OpenStreetMap, or the cycle OpenStreetMap layer. On this map we will display a marker. The marker we draw will actually be a Point drawn in an overlay Vector layer. We will style the Point to look as a nice marker.

Displaying an OpenStreetMap layer in OpenLayers.

The first thing we are going to do is just display a simple OpenStreetMap layer in our project.\

Start by opening you client java file (in my example this is found under src/be/frank/gwtol/client/Gwtoltest.java).
* First thing we are going to do is clean up this file as a lot of code was added by the GWT plugin when we created this project. Just cleanup all code, all we need for now is an empty onModuleLoad method.
(note that you can also delete the GreetingService.java, GreetingServiceAsync.java and the shared and server folders as these are not needed for our small project).
First thing we will create is a MapWidget. This is a GWT Widget that will display our map.
Since the MapWidget needs MapOptions we will need to create these first.
(Don't forget the needed imports : import org.gwtopenmaps.openlayers.client.MapOptions; and import org.gwtopenmaps.openlayers.client.MapWidget;)
```
MapOptions defaultMapOptions = new MapOptions();
MapWidget mapWidget = new MapWidget("500px", "500px", defaultMapOptions);
```
Now our MapWidget is ready it is time to add some base layers (base layers can be seen as background layers).
We are going to add 2 base layers so the user can swap between these 2. We will add the normal (Mapnik) OpenStreetMap layer, and we will add the cycle OpenStreetMap layer.
Below is the code for creating these layers.
First to lines initialize the layers.
Following to lines are used to specify that these layers are base layers.
Last 2 lines add the layers to our map.

(Don't forget the import import org.gwtopenmaps.openlayers.client.layer.OSM;)
```
OSM osmMapnik = OSM.Mapnik("Mapnik");
OSM osmCycle = OSM.CycleMap("CycleMap");

osmMapnik.setIsBaseLayer(true);
osmCycle.setIsBaseLayer(true);

mapWidget.getMap().addLayer(osmMapnik);
mapWidget.getMap().addLayer(osmCycle);
```
The code so far can be seen in the screenshot below
Next step is center the map on a location so we display something. We just give a coordinate, and let the map center on it with a zoomlevel of 12. \Note that the needed import for this step is import org.gwtopenmaps.openlayers.client.LonLat;
```
LonLat lonLat = new LonLat(6.95, 50.94);
lonLat.transform("EPSG:4326", mapWidget.getMap().getProjection()); //transform lonlat (provided in EPSG:4326) to OSM coordinate system (the map projection)
mapWidget.getMap().setCenter(lonLat, 12);
```
Now our project actaully contains enough code to run. Only thing we need to add is adding the mapWidget to the RootLayoutPanel.
Don't forget the import : import com.google.gwt.user.client.ui.RootLayoutPanel;
```
RootLayoutPanel.get().add(mapWidget);
```
So this is the code up until now.
Now lets try this code out and run our project.
In Eclipse go the the Run menu, and select Run As, Web Application Project

Now the project will run, and Eclipse will display a Development Mode tab displaying an URL. Just double click this URL.
Now your browser will open and display our project (if your browser asks to install the GWT plugin, confirm and install).

So now you see a nice OpenStreetMap map, which you can pan and zoom. But we currently we can only see one layer, although we added 2 layers.
To be able to switch between our 2 layers we will need to add a LayerSwitcher to our code. Just add the following line (also add import org.gwtopenmaps.openlayers.client.control.LayerSwitcher;)
```
mapWidget.getMap().addControl(new LayerSwitcher());
```
Now just refresh your browser and you will see a blue + in the upperright corner of the map. Click it to open the layer switcher and switch layers.

Adding a Vector layer displaying a marker

Next step we will do is adding a marker on the map, we will place the marker at the same location we centered the map on.
To achieve this we will actually add a Vector layer on top of the base layers. And add a Point to this Vector layer. Finally we will style this Point to look as an actual marker (needed imports are : import org.gwtopenmaps.openlayers.client.layer.Vector;, import org.gwtopenmaps.openlayers.client.geometry.Point;, import org.gwtopenmaps.openlayers.client.Style; and import org.gwtopenmaps.openlayers.client.feature.VectorFeature;

final Vector vectorLayer = new Vector("Vectorlayer");

Point point = new Point(lonLat.lon(), lonLat.lat());

Style pointStyle = new Style();
pointStyle.setExternalGraphic("http://demo.gwt-openlayers.org/gwt_ol_showcase/kangaroomarker.png");
pointStyle.setGraphicSize(32, 37);
pointStyle.setGraphicOffset(-16, -37); //anchor on bottom center
pointStyle.setFillOpacity(1.0);
        
VectorFeature pointFeature = new VectorFeature(point, pointStyle);

vectorLayer.addFeature(pointFeature);
mapWidget.getMap().addLayer(vectorLayer);

Now just refresh your browser and the marker will be displayed. In the LayerSwitcher you will see a overlay layer was added an can be switched off/on using the LayerSwitcher.
You can add as many items as you want to each Vector layer, and you can add as many layers as you want.

For reference here is a complete overview of the created code.

package be.frank.gwtol.client;

import org.gwtopenmaps.openlayers.client.LonLat;
import org.gwtopenmaps.openlayers.client.MapOptions;
import org.gwtopenmaps.openlayers.client.MapWidget;
import org.gwtopenmaps.openlayers.client.control.LayerSwitcher;
import org.gwtopenmaps.openlayers.client.feature.VectorFeature;
import org.gwtopenmaps.openlayers.client.geometry.Point;
import org.gwtopenmaps.openlayers.client.layer.OSM;
import org.gwtopenmaps.openlayers.client.layer.Vector;
import org.gwtopenmaps.openlayers.client.Style;

import com.google.gwt.core.client.EntryPoint;
import com.google.gwt.user.client.ui.RootLayoutPanel;

/**
 * Entry point classes define <code>onModuleLoad()</code>.
 */
public class Gwtoltest implements EntryPoint
{
    /**
     * This is the entry point method.
     */
    @Override
    public void onModuleLoad()
    {
        MapOptions defaultMapOptions = new MapOptions();
        MapWidget mapWidget = new MapWidget("500px", "500px", defaultMapOptions);

        OSM osmMapnik = OSM.Mapnik("Mapnik");
        OSM osmCycle = OSM.CycleMap("CycleMap");

        osmMapnik.setIsBaseLayer(true);
        osmCycle.setIsBaseLayer(true);

        mapWidget.getMap().addLayer(osmMapnik);
        mapWidget.getMap().addLayer(osmCycle);

        LonLat lonLat = new LonLat(6.95, 50.94);
        lonLat.transform("EPSG:4326", mapWidget.getMap().getProjection()); //transform lonlat (provided in EPSG:4326) to OSM coordinate system (the map projection)
        mapWidget.getMap().setCenter(lonLat, 12);

        final Vector vectorLayer = new Vector("Vectorlayer");

        Point point = new Point(lonLat.lon(), lonLat.lat());

        Style pointStyle = new Style();
        pointStyle.setExternalGraphic("http://demo.gwt-openlayers.org/gwt_ol_showcase/kangaroomarker.png");
        pointStyle.setGraphicSize(32, 37);
        pointStyle.setGraphicOffset(-16, -37); //anchor on bottom center
        pointStyle.setFillOpacity(1.0);

        VectorFeature pointFeature = new VectorFeature(point, pointStyle);

        vectorLayer.addFeature(pointFeature);
        mapWidget.getMap().addLayer(vectorLayer);

        mapWidget.getMap().addControl(new LayerSwitcher());

        RootLayoutPanel.get().add(mapWidget);
    }
}

Note that this example just is shows a very small portion of what is possible using GWT-OpenLayers.
You can also display Google, Bing, your own WMS, your own WFS, ... layers. Besides this Gwt-OpenLayers can also be used to edit Geographical data and save changes back to the backend. In short : You can use GWT-Openlayers to create any GIS project you want.

Going further and requesting for help

The next thing you can do is have a look at our own Showcase. This displayes a lot of possibilities of GWT-OpenLayers together with the needed sourcecode. You can find the showcase at http://demo.gwt-openlayers.org

Another source of interest is our own javadoc http://www.gwt-openlayers.org/apidocs/index.html

Finally you can also look at the showcase of the normal OpenLayers (http://openlayers.org/dev/examples/). In most cases it isn't too hard to map those examples to GWT-Openlayers.
Also the official OpenLayers api can help you out in some cases (http://dev.openlayers.org/apidocs/files/OpenLayers-js.html).

If you get stuck and need help there are a number of ways to get into contact with us, or other people willing to help.
In order of our preference:

Ask your question on StackOverflow.
If you ask your question on http://stackoverflow.com/, and tag your question with gwt-openlayers we (the main GWt-Openlayers developers) will get notified of this question, and will reply as soon as possible (please note that we develop GWT-Openlayers in our spare time).
Ask your question on Google+.
Join our Google+ group at Google+ and ask your question.
Visit our IRC channel (hint: say someones name who is online, so they get a notification someone is asking something)
- Server: irc.freenode.net
- Channel: #gwt-openlayers

Overview

Developer

Project Documentation