mukil / Leaflet.annotate

Leaflet.annnotate

An extension of the LeafletJS (0.7.x) standard API facilitating the publication of information in geographical web maps with advanced accessibility. Employing Leaflet.annotate, in the end, will allow you to markup elements in your map with the Schema.org vocabulary and thus publish them as independent and (potentially) addressable items of information ("Things").

Once you annotate your items, Leaflet.annotate automatically translates all semantic and spatial attributes as information readable in the web of data. It frees you to write markup that is compliant with the latest of Living HTML, SVG Standard 1.1. 2nd Edition while integrating general resource descriptions vocabularies like Schema.org and the Dublin Core Metadata Element Set.

Furthermore (as it defines an API) it allows developers to build all kinds of crazy things, e.g. assistive dialogs to read and analyse the contents of your map, re-usable across all LeafletJS based geographical web maps. And no, this is not intended to help you annotate elements of your next "statistical geovisual analytics" or your next "big data geoweb map" app. It is intended to support web map making as an information organization practice.

Overview: This Leaflet plugin consists of two components

1. Schema.org Microdata Syntax Implementation

Advances the markup of your geographic web map according to standards and the geospatial domain present in the public Schema.org vocabulary. This makes your web map accessible. This implementation hooks into the standard LeafletJS API enabling you to improve your markup when using Marker, CircleMarker or GeoJSON elements from Leaflet. To use it include the following script tag in your HTML document:

<script src="Leaflet.annotate.Microdata-0.3.0_en_US.min.js"></script>

To annotate single map elements please check out the API documentation below. Basically your LeafletJS standard options object now can handle a simple itemtype. The plugin expects the value of such an itemtype be the name of a Schema.org type, e.g. City, or Organisation. All itemtypes which allow (by their type definition) you the expression of a property with a geographical extent or location as their value/s, are supported.

2. Markup Viewer - A new Leaflet Control

The AnnotationViewer is a new user dialog aimed at improving the experience for users who want to reading and interpretate the contents of your geographic web map systematically.

The following script included in this repository ships it (Icon: ?) to your document:

<script src="Leaflet.annotate.Viewer-0.3.0.min.js"></script>

And to use this control you must explicitly add it to your map, like any other custom Leaflet Control.

map.addControl(L.control.annotationViewer())

Feedback and contributions are very welcome.
Cheers!

API

The following API options are available on standard Leaflet Marker, CircleMarker, ImageOverlay, Popup and at least a GeoJSON Layer. All these three type of overlays can be annotated in valid standard markup trough passing one or all of the following key:value pairs as additional `options' to the object during creation:

Note: Contrary to the standard specification an option (key) can be annotated just once. For example currently this API does not enable you two specify two alternateNames for your map element.

Examples - Building anotations using the API

Include the following script from this repository in your HTML file:

<script src="Leaflet.annotate.Microdata-0.3.0_en_US.min.js"></script>

After that, if you pass itemtype as an option to your map element during creation, it is configured for annotation. Annnotation will happen if you add the map element to your Leaflet map object.

Example1: Annotating a Marker as map element representing a City looks like this:

var marker = L.marker([40.573112, -73.980740], { itemtype: 'City', title: 'New York City'})

This also exposes your markers location values as machine readable GeoCoordinates values in HTML.

Example2: Annotating a Circle Marker (SVG) to represent a Creative Work, a virtual Poem.

var circleMarker = L.circleMarker([40.573112, -73.980740], {
	itemtype: 'CreativeWork', geoprop: 'locationCreated'
    title: 'The circle marker stating where this meta poem was created.'
})

This too exposes this markers location value as machine readable GeoCoordinates but more specifically, it exposes the location as the Place where the poem was written (locationCreated).

Example3: Annotating a group of geometries (SVG) which all represent the boundaries of one Country, in this case the (formal) boundaries of the "Estados Unidos":

var statesBoundaries = L.geoJson(response, { itemtype: 'Country',
    title: 'Estados Unidos'
}).addTo(map)
// Note: Here we must call annotate() explicitly on geographical Overlays such as this GeoJSON Layer
statesBoundaries.annotate()

Note: Here an additional and explicit call of annotate() is necessary.
This exposes the polygons location values (all GeoCoordinates of the boundaries) as a machine readable GeoShape.

Background

Answers to the following questions are implemented in this extension:

• Which standard HTML Elements (Tags) match best to structure HTML documents of composite nature, esp. regarding to many contributions from many people? - That depends, of course, but relying on div should "be the last resort" so iused article.
• Which standad HTML Elements (Tags) match best for annotating core elements of a geographic web map (like Marker, Layer, Popup, etc.)? - Depends, but for Markers and Popups and the current microdata implementation i chose article.
• Where and how to represent multiple authors in a single HTML document? - Either completely relying on class names (suggestion of HTML Standard) or through using an markup extenension mechanism and relying on terms of an already established metadata vocabulary., e.g. using meta elements within article elements or trough integrating metadata in the microdata syntax.
• Where and how to represent datetime on variously authored fragements in HTML? - W3CDTF
• Which HTML Markup Extension Syntax to implement? - Microdata, because the metadata is rendered inline.
• Which metadata vocabularies are widely used and therefore could be considererd "well supported"? - Schema.org, Dublin Core Metadata Element Set
• Which metadata vocabulary is open and extensible for us? - Schema.org

Implementation Notes

To annotate SVG Elements we introduce a metadata Element next to the respective path. In practice both are often grouped within a g element. All Schema.org and Dublin Core based annotation values are attributes of a meta element.

Maps annotated with this plugin are currently just tested to work with Internet Explorer 11 (Windows 7), Chromium 52.0.2743.x (Ubuntu 14.04, 64 Bit) and Firefox 49.0 (Ubuntu 14.04, 64 Bit). Most other versions of these browser should therefore work too. Safari is yet untested but should work fine too.

HTML canvas based rendering is also not supported, in fact, a canvas based approach for rendering geographic we maps is exactly the opposite of how Leaflet.annotate tries to representing geographical web maps in HTML.

Important: If you use JavaScript frameworks which manage the DOM for you, such as for example AngularJS, you (most probably) can not make use of this Leaflet extension.

Release History

0.3, Upcoming

0.3-RC, Aug 24, 2016 (Release Candidate)

• Annotatable Leaflet Items: UI Layers (Marker, Popup), Vector Layers (CircleMarker), Other Layers (GeoJSON, ImageOverlay)
• Compatible with the latest stable LeafletJS Release: 0.7.7
• Most probably also compatible from at least all versions of 0.7.3 and upwards

License: FreeBSD License

Author:
(C) Malte Reißig (2016)