leaflet-editable

# Leaflet.Editable

Make geometries editable in Leaflet.

This is not a plug and play UI, and will not. This is a minimal, lightweight, and fully extendable API to control editing of geometries. So you can easily build your own UI with your own needs and choices.

See the demo UI, an more examples below. This is also the drawing engine behind uMap.

Design keys:

• only the core needs
• no UI, instead hooks everywhere needed
• everything programatically controlable
• MultiPolygon/MultiPolyline support
• Polygons' holes support
• touch support
• tests

Note: only geojson features are supported for now: Marker, Polyline, Polygon, and MultiPolygon/MultiPolylines (no Rectangle, Circle…)

## Install

You need Leaflet >= 0.7.3, and then include src/Leaflet.Editable.js.

## Quick start

Allow Leaflet.Editable in the map options:

var map = L.map('map', {editable: true});

Then, to start editing an existing feature, call the enableEdit method on it:

var polyline = L.polyline([[43.1, 1.2], [43.2, 1.3],[43.3, 1.2]]).addTo(map);
polyline.enableEdit();

If you want to draw a new line:

map.editTools.startPolyline();  // map.editTools has been created
                                // by passing editable: true option to the map

If you want to continue an existing line:

polyline.editor.continueForward();
// or
polyline.editor.continueBackward();

## Examples

• Basic controls
• Continue line by ctrl-clicking on first/last point
• Create hole in a polygon by ctrl-clicking on it
• Change line colour on editing
• Display a tooltip near cursor while drawing
• Example of Leaflet.Snap integration to enable snapping

## API

Leaflet.Editable is made to be fully extendable. You have three ways to customize the behaviour: using options, listening to events, or extending.

### L.Map

Leaflet.Editable add options and events to the L.Map object.

#### Options

option name	default	usage
editable	false	Whether to create a L.Editable instance at map init or not.
editOptions	{}	Options to pass to L.Editable when instanciating.

Events

event name	properties	usage
editable:created	layer	Fired when a new feature (Marker, Polyline…) has been created.
editable:enable	layer	Fired when an existing feature is ready to be edited
editable:disable	layer	Fired when an existing feature is not ready anymore to be edited
editable:editing	layer	Fired as soon as any change is made to the feature geometry
editable:drawing:start	layer	Fired when a feature is to be drawn
editable:drawing:end	layer	Fired when a feature is not drawn anymore
editable:drawing:cancel	layer	Fired when user cancel drawing while a feature is being drawn
editable:drawing:commit	layer	Fired when user finish drawing a feature
editable:drawing:click	layer	Fired when user click while drawing
editable:vertex:ctrlclick	originalEvent, latlng, vertex, layer	Fired when a click having ctrlKey is issued on a vertex
editable:vertex:shiftclick	originalEvent, latlng, vertex, layer	Fired when a click having shiftKey is issued on a vertex
editable:vertex:altclick	originalEvent, latlng, vertex, layer	Fired when a click having altKey is issued on a vertex
editable:vertex:contextmenu	originalEvent, latlng, vertex, layer	Fired when a contextmenu is issued on a vertex
editable:vertex:deleted	originalEvent, latlng, vertex, layer	Fired after a vertex has been deleted by user
editable:vertex:deleted	originalEvent, latlng, vertex, layer	Fired after a vertex has been deleted by user
editable:vertex:drag	originalEvent, latlng, vertex, layer	Fired when a vertex is dragged by user
editable:vertex:dragstart	originalEvent, latlng, vertex, layer	Fired before a vertex is dragged by user
editable:vertex:dragend	originalEvent, latlng, vertex, layer	Fired after a vertex is dragged by user

L.Editable

You will usually have only one instance of L.Editable, and generally the one created automatically at map init: map.editTools. It's the toolbox you will use to create new features, and also the object you will configure with options. Let's see them.

Options

Note: you can pass them when creating a map using the editOptions key.

option name	default	usage
polylineClass	L.Polyline	Class to be used when creating a new Polyline
polygonClass	L.Polygon	Class to be used when creating a new Polygon
markerClass	L.Marker	Class to be used when creating a new Marker
drawingCSSClass	leaflet-editable-drawing	CSS class to be added to the map container while drawing
editLayer	new L.LayerGroup()	Layer used to store edit tools (vertex, line guide…)
featuresLayer	new L.LayerGroup()	Default layer used to store drawn features (marker, polyline…)
vertexMarkerClass	L.Editable.VertexMarker	Class to be used as vertex, for path editing
middleMarkerClass	L.Editable.MiddleMarker	Class to be used as middle vertex, pulled by the user to create a new point in the middle of a path
polylineEditorClass	L.Editable.PolylineEditor	Class to be used as Polyline editor
polygonEditorClass	L.Editable.PolygonEditor	Class to be used as Polygon editor
markerEditorClass	L.Editable.MarkerEditor	Class to be used as Marker editor
lineGuideOptions	{}	Options to be passed to the line guides
skipMiddleMarkers	null	Set this to true if you don't want middle markers

Methods

Those are the public methods. You will generally access them by the map.editTools instance:

map.editTools.startPolyline();

method name	params	return	usage
startPolyline	latlng*	created L.Polyline instance	Start drawing a polyline. If latlng is given, a first point will be added. In any case, continuing on user click.
startPolygon	latlng*	created L.Polygon instance	Start drawing a polygon. If latlng is given, a first point will be added. In any case, continuing on user click.
startMarker	latlng*	created L.Marker instance	Start adding a marker. If latlng is given, the marker will be shown first at this point. In any case, it will follow the user mouse, and will have a final latlng on next click (or touch).
stopDrawing	—	—	When you need to stop any ongoing drawing, without needing to know which editor is active.

Events

Same as L.Map.

L.Editable.VertexMarker

The marker used to handle path vertex. You will usually interact with a VertexMarker instance when listening for events like editable:vertex:ctrlclick.

Those are its public methods.

method name	params	return	usage
delete	—	—	Delete a vertex and the related latlng.
getIndex	—	int	Get the index of the current vertex among others of the same LatLngs group.
getLastIndex	—	int	Get last vertex index of the LatLngs group of the current vertex.
getPrevious	—	VertexMarker instance	Get the previous VertexMarker in the same LatLngs group.
getNext	—	VertexMarker instance	Get the next VertexMarker in the same LatLngs group.

L.Editable.BaseEditor

When editing a feature (marker, polyline…), an editor is attached to it. This editor basically knows how to handle the edition.

It has some public methods:

method name	params	return	usage
enable	—	this	Set up the drawing tools for the feature to be editable.
disable	—	this	Remove editing tools.

L.Editable.MarkerEditor

Inherit from L.Editable.BaseEditor.

L.Editable.PathEditor

Inherit from L.Editable.BaseEditor.

Inherited by L.Editable.PolylineEditor and L.Editable.PolygonEditor.

Interesting new method:

method name	params	return	usage
reset	—	—	Rebuild edit elements (vertex, middlemarker, etc.)

### L.Editable.PolylineEditor

Inherit from L.Editable.PathEditor.

Useful specific methods:

method name	params	return	usage
continueForward	—	—	Set up drawing tools to continue the line forward
continueBackward	—	—	Set up drawing tools to continue the line backward

### L.Editable.PolygonEditor

Inherit from L.Editable.PathEditor.

method name	params	return	usage
newHole	latlng*	—	Set up drawing tools for creating a new hole on the polygon. If the latlng param is given, a first point is created.

EditableMixin

EditableMixin is included to L.Polyline, L.Polygon and L.Marker. It adds the following methods to them.

When editing is enabled, the editor is accessible on the instance with the editor property.

#### Methods

method name	params	return	usage
enableEdit	—	related editor instance	Enable editing, by creating an editor if not existing, and then calling enable on it
disableEdit	—	—	Disable editing, also remove the editor property reference.
toggleEdit	—	—	Enable or disable editing, according to current status.
editEnabled	—	boolean	Return true if current instance has an editor attached, and this editor is enabled.

Events

Some events are also fired on the feature itself.

event name	properties	usage
editable:drawing:start	layer	Fired when a feature is to be drawn
editable:drawing:end	layer	Fired when a feature is not drawn anymore
editable:drawing:cancel	layer	Fired when user cancel drawing while a feature is being drawn
editable:drawing:commit	layer	Fired when user finish drawing a feature
editable:drawing:click	layer	Fired when user click while drawing
editable:vertex:ctrlclick	originalEvent, latlng, vertex, layer	Fired when a click having ctrlKey is issued on a vertex
editable:vertex:shiftclick	originalEvent, latlng, vertex, layer	Fired when a click having shiftKey is issued on a vertex
editable:vertex:altclick	originalEvent, latlng, vertex, layer	Fired when a click having altKey is issued on a vertex
editable:vertex:contextmenu	originalEvent, latlng, vertex, layer	Fired when a contextmenu is issued on a vertex
editable:vertex:deleted	originalEvent, latlng, vertex, layer	Fired after a vertex has been deleted by user

## Licence

Leaflet.Editable is released under the WTFPL licence.