Geomajas Editing plug-in guide

In order to use this plug-in in combination with the GWT face, the following Maven dependency is required:

<dependency>
    <groupId>org.geomajas.plugin</groupId>
    <artifactId>geomajas-plugin-editing-gwt</artifactId>
</dependency>

Before going deeper into the inner workings of the different services and how they work together, we need to explain the GeometryEditor. This is the top level editing object that makes all of the other services work together. It has a GeometryEditService, a renderer for the map, a SnapService, and a registry for controller on the map.

This is where you start when trying to edit geometries within the GWT. Because the rendering is face specific, this object too is face specific. A GeometryEditor can simply be constructed using a map:

GeometryEditor editor = new GeometryEditor(mapWidget);

Central service for all operations concerning the geometry editing process. This process should work together with a set of controllers on the map that execute methods from this service after which events are fired for a renderer to act upon. This service makes use of the GeometryIndexService to identify sub-geometries, vertices and edges. All operations work on a set of such indices. This allows for great flexibility in the operations that can be performed on geometries.

The editing plug-in has support for snapping while inserting or dragging. The controllers are equipped with a SnapService which can convert the mouse event locations into snapped locations, before they are passed to the GeometryEditService for operation execution.

The SnapService works through a series of rules that need to be active. Without any snapping rules, the SnapService will no snap. Adding snapping rules, goes through the "addSnappingRule" method, and requires the following parameters:

The JavaScript counterpart of the GeometryEditService is basically a wrapper around the GWT version. It therefore has the same methods, and works the same way.

The snapping options in JavaScript are not as rich as they are in GWT. No separate SnappingService is available. What can be done, is configuring snapping options in the XML configuration of the vector layers, and using that configuration directly. The JavaScript "GeometryEditor" has methods for activating those snapping rules during editing.

On top of that, the GeometryEditor also has the ability to turn snapping on and off while inserting vertices or while dragging vertices. As with the GWT snapping you need at least one snapping rule for snapping to occur.

The JavaScript counterpart of the GeometryMergeService is basically a wrapper around the GWT version. It therefore has the same methods, and works the same way.

The JavaScript counterpart of the GeometrySplitService is basically a wrapper around the GWT version. It therefore has the same methods, and works the same way.

This section describes how to let the user draw a new geometry of some pre-defined type. The idea is that the user can click on the map to insert vertices into the geometry. This requires three steps:

The following code has to be executed:

GeometryEditor editor = new GeometryEditorImpl(map); // (1)
Geometry polygon = new Geometry(Geometry.POLYGON, 0, 0);  // (2)
editor.getEditService().start(polygon); // (2)
try {
    GeometryIndex index = editor.getEditService().addEmptyChild(); // (3)
    editor.getEditService().setInsertIndex(editor.getEditService().getIndexService().addChildren(index, GeometryIndexType.TYPE_VERTEX, 0)); // (3)
    editor.getEditService().setEditingState(GeometryEditState.INSERTING); // (3)
} catch (GeometryOperationFailedException e) {
    editor.getEditService().stop();
    Window.alert("Exception during editing: " + e.getMessage());
}

From there on, the user can take over. Depending on the use case, the editing service could be stopped by letting the user click outside the finished geometry

editor.getBaseController().setClickToStop(true);

or by explicitly stopping the service:

editor.getEditService().stop();

The editing happens on the same object that was originally passed to the service.

The following steps have to be taken:

The following code assumes that the polygon being edited already has an exterior ring:

   try {
        GeometryEditService service = editor.getEditService();
        GeometryIndex ringIndex = service.addEmptyChild(); // (1)
        // Free drawing means inserting mode. First create a new empty child, than point the insert
        // index to the child's first vertex:
        service.setInsertIndex(service.getIndexService().addChildren(ringIndex,GeometryIndexType.TYPE_VERTEX, 0));// (2)
        service.setEditingState(GeometryEditState.INSERTING);// (2)
    } catch (GeometryOperationFailedException e) {
        Window.alert("Error during editing: " + e.getMessage());
    }

The following steps have to be taken:

The following code deletes the first interior ring if the polygon has one:

GeometryEditService service = editor.getEditService();
Geometry geometry = service.getGeometry();
if(geometry.getGeometries().length > 1) {
    GeometryIndex ringIndex = service.create(GeometryIndexType.TYPE_GEOMETRY, 1); // (1)
    service.remove(Collections.singletonList(ringIndex)); // (2)
}

This section describes how to let the user draw a new geometry of some pre-defined type. The idea is that the user can click on the map to insert vertices into the geometry. This requires three steps:

The following code has to be executed (onGeomajasLoad() is called automatically on page load):

var map; // The map object.
var editor; // Geometry editor. Holds the central editing service, the renderer, the styling information...
var service; // The central editing service.

function onGeomajasLoad() {
 map = Geomajas().createMap("app", "mapMain", "js-map-element");
 editor = new org.geomajas.plugin.editing.GeometryEditor(); // (1)
 editor.setMap(map); // (1)
 service = editor.getService();
}

function drawPolygon() {
  var geometry = new org.geomajas.jsapi.spatial.Geometry("Polygon", 0, 0); // (2)
  service.start(geometry);// (2)
  service.addEmptyChild(); // (3)
  var index = service.getIndexService().create("vertex", [0, 0]); // (3)
  service.setInsertIndex(index); // (3)
  service.setEditingState("inserting"); // (3)
}

From there on, the user can take over. Depending on the use case, the editing service could be stopped by letting the user click outside the finished geometry

editor.getBaseController().setClickToStop(true);

or by explicitly stopping the service:

editor.getEditService().stop();

The editing happens on the same object that was originally passed to the service.

The following steps have to be taken:

The following code assumes that the polygon being edited already has an exterior ring:

function insertHole() {
  var geometry = service.getGeometry();
  var ringIndex = service.addEmptyChild(); // (1)
  var indexValue = ringIndex.getValue();
  var index = service.getIndexService().create("vertex", [indexValue, 0]); // (2)
  service.setInsertIndex(index); // (2)
  service.setEditingState("inserting"); // (2)
}

The following steps have to be taken:

The following code deletes the first interior ring if the polygon has one:

function deletefirstHole() {
    var geometry = service.getGeometry();
    if(geometry.getGeometries().length > 1) {
        var index = service.getIndexService().create("geometry", [1]); // (1)
        service.remove([index]); // (2)
    }
}

Geometry handlers are necessary to apply custom editing actions when certain mouse events occur. The concept is similar to normal map controllers, but geometry handlers add information about the geometry index of the part of the geometry on which the mouse event occurs. To register a geometry handler, the following steps have to be taken:

The following code illustrates such registration in the case of a custom handler for deletion of interior rings.

function registerDeleteHole() {
    factory = new org.geomajas.plugin.editing.handler.GeometryHandlerFactory(); // (1)
    factory.setUpHandler(function(event) {   // (2)
        var index = factory.getIndex();
        if (service.getIndexStateService().isMarkedForDeletion(index)) {
            try {
                service.remove([index]);
            } catch (e) {
                alert("Error occurred while deleting the inner ring: " + e.getMessage());
            }
        }
    });
    factory.setMouseOverHandler(function(event) {  // (2)
        var index = factory.getIndex();
        var geometryType = service.getIndexService().getGeometryType(service.getGeometry(), index);
        if (geometryType == "LinearRing") {
            if (service.getIndexService().getValue(index) > 0) {
                // Only inner rings must be marked. The outer shell can remain as-is.
                service.getIndexStateService().markForDeletionBegin([index]);
            }
        }
    });
    factory.setMouseOutHandler(function(event) {  // (2)
        var index = factory.getIndex();
        if (service.getIndexStateService().isMarkedForDeletion(index)) {
            service.getIndexStateService().markForDeletionEnd([index]);
        }
    });
    EditingHandlerRegistry().addGeometryHandlerFactory(factory);  // (3)  
    editor.getRenderer().redraw();  // (4)  
}

function unRegisterDeleteHole() {
    if(factory) {
        EditingHandlerRegistry().removeGeometryHandlerFactory(factory); // (5)
        editor.getRenderer().redraw();  // (5)
    }
}