A Leaflet plugin to create web mapping documents

Plugin compatible with Leaflet 0.7

Introduction

On the representation of geographical web maps in HTML

Current development in HTML allows of course the integration of various domain specific vocabularies to represent concepts of map making at runtime in the DOM. The idea of archiving complex documents up into their state that a web map becomes persistent, like an immutable data store. The DOM changes over time as does the web map, of course modern maps vary per browser session. So to constructively discuss interactive, participatory, adaptice and collaborative web maps means to develop a more fine grained understanding of modern map making practices as we completely change the format of our research data for this particular type of document: a map. I tell you twenty type of maps, all just written in a different, domain specific, vocabulary. The universal map format does not only express the textual (instance) but also the conceptual, relational but also the visual aspects in self-contained document format, allowing for the integration of many different semantic vocabularies, networks of concepts to not call them ontologies. DMX is right there, in retrospective I must say that my specific hypertext like understanding of geographic web maps comes from my understanding of computers through deepamehta, or DMX, how it is now called.

The kick comes in when one understands how we currently teach kids map reading nowadays. Critical, reflective, reflexive map reading comes from context information about each single information in the middle of the complex system called map. This intersection of concepts of critical cartography, post-reprsentational map theory, pedagocal practices to theories of human knowledge over time and space. Harley suggests us to read maps as texts, that is where our ideas of map reading come from. But the foundations of our digital maps do not leverage this knowledge a single bit.

Proof of Concept, Part 1: A Leaflet plugin integrating Schema.org und Dublin Core in Microdata Syntax to annotate Leaflet concepts in your geographic web map machine readable.

Developers README

Extending LeafletJS (0.7.x) standard API with Leaflet.annotate facilitates 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 HTMLSVG 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.

Documentation

The plugin extends the options for the LeafletJS Standard API elements MarkerCircleMarkerPopupImageOverlay and GeoJSON so you can publish these map elements in HTML semantically annotated ‐ and therewith machine readable web maps. While there is quite some effort already around the development of new geospatial data catalogs (which are awesome) this plugin turns the focus onto geographic web maps. Acknowleding that, de-facto, some maps already are data catalogs themselves, they are just not that well represented in HTML so that other programs can extract and re-use the information people collect in them.

Using this plugin you will contribute to research on digital cartography through allowing search engines and other applications (a) understand what is your map about, (b) what elements it is made of and (c) which parts of the world it explicitly deals with. Everything from just analyzing your maps representation in HTML.

Leaflet.annotate started as a plugin overriding the original HTML representation shipped by the open source web mapping library LeafletJS. It is a proof of concept implemtantion which effectively turned Leaflet into a semantic authoring environment for spatial data on the web. The hack turned out to integrate geospatial domain specific vocabulary into HTML creating advanced web mapping documents using the Microdata syntax, Dublin Core and Schema.org. 

Your web map elements when published with semantic markup can become geo-referenced "resource descriptions", which in turn are:

  • identifiable and addressable for others,
  • discoverable for users through search engines,
  • interoperable items for other application developers,
  • collections of linked data and therewith and
  • potentially multilingual without much additional effort.

Therefore we wrote this small script, integrating freeing you of caring much about the necessary syntax details.

Your feedback or contributions are very welcome. Please use this issue tracker to report any issues you experienced with it.

Overview & installation

The source code released contains two different components, one (the core) for generating the semantic markup and the other (an example) for reading and making the markup usable for visitors who want to systematically read and explore the map

  1. The core file is the semantic markup generating Leaflet Plugin in

    Leaflet.annotate.Microdata-0.3.0_en_US.min.js

    After loading this script you can start annotating Marker, CircleMarker, Popup, ImageOverlay and GeoJSON elements.

  2. The first add-on is a custom L.control which uses the semantic markup generated by the core, it can be installed through loading the files

    util/Leaflet.annotate.Viewer-0.3.0.min.js and 
    css/viewer-style.css

    Using this add-on you can add a text based search control to your map allowing readers of it to magically listsearch and focus all your annotated web map elements.

To assist you in the creation of valid semantic markup you can find existing JavaScript objects which help you to map user input to valid Schema.org type names (=Leaflet.annotate's itemtype option). These type names also allow you to map a label in your language to the schema.org type name.

  • util/Leaflet.annotate.types_en_US.js
  • util/Leaflet.annotate.types_de_DE.js

Example: Photos of sculptures in Paris

Browse this example showing public sculptures in Paris.

This map is a good example of a so called "map mashup". In it you'll just find geo-referenced pictures representing public sculptures in the city of Paris. All web map elements are annotated as representing a Photographs depicting a specific contentLocation.

Here is the Leaflet code which produces the semantic markup explorable in the example. Bold elements are interpreted by the annotate plugin to produce proper markup.

L.circleMarker(coordinates, { weight: 2, opacity: 0.6, fillColor: "#a9a9a9",
  fillOpacity: 0.2, lineCap: 'square', color : "#8f1414",
  alt: "Photo of a sculpture named " + popupTitle,
  itemtype: 'Photograph',   geoprop: 'contentLocation',
  url: photoURL, title: 'Picture of ' + popupTitle
}).setRadius(3)

If you copy & paste the generated markup into Googles Structured Data Testing Tool you will find out that it can identify/recognize ~400pictures were composed in this map.

The data for this map is fetched live with SPARQL from query.wikidata.org. Sculptures are shown when they are located in Paris (or one of its districts) and have a publicly licensed picture associated in wikmedia commons. The semantic annotation of the CircleMarker elements here happens in the SVG fragment created by Leaflet and, according to the standard, in a metadataelement.

Example: Annotated GeoJSON-Layer

Browse this example to see the USA with "charmingly inaccurate" boundaries.

Usage

Automatic Annotation

Annotation happens automatically whenever you add a MarkerCircleMarkerPopup or ImageOverlay to your L.map and pass them a valid itemtype value as an option to Leaflets Standard API:

L.marker(coordinates, {
  title: 'Madison Square Garden', itemtype: 'CivicStructure'
})

Valid itemtype values are currently all the names of Schema.org terms which allow for at least one Place as one of their properties. Regarding the schema.org type you use you might be required to explicitly specify the desired geoprop option

L.circleMarker(coordinates, { title: 'The Catcher in the Rye', itemtype: 'Book', geoprop: 'locationCreated', sameAs: 'https://www.wikidata.org/wiki/Q183883' })

For example when mapping CreativeWorks you can express a geographical dimension for the location it was created (locationCreated) or for the location it depicts (contentLocation) using the respective property names.

Here is another, more comple example, annotating an ImageOverlay:

L.imageOverlay(imageUrl, imageBounds, {
  "itemtype": "CreativeWork", "geoprop": "contentLocation",
  "publisher": "The University of Texas",
  "source": "https://www.lib.utexas.edu/maps/new_jersey.html",
  "created": "Thu Jan 01 1920 01:00:00 GMT+0100 (CET)",
  "title": "Automobile Blue Book"
}).addTo(map)

Manual Annotation

On a GeoJSON element annotation happens whenever you call the .annotate() method on the GeoJSON layer and pass a valid code>itemtype value as an option:

L.geoJson(geojsonData, { title: 'Uganda',   itemtype: 'Country',   sameAs: 'https://www.wikidata.org/wiki/Q1036' }).annotate()

This will markup the GeoJSON document as a map overlay representing the area for the Republic of Uganda. In Wikidata the URI for the concept/entity representing this country is https://www.wikidata.org/wiki/Q1036.

Another example of a semantically annotated GeoJSON overlay where the options used by Leaflet.annnotate to generate the semantic markup are highlighted in bold:

// 1. Markup your GeoJSON
var statesBoundaries = L.geoJson(geoJsonData, {
  title: 'Charmingly Inaccurate - USA', itemtype: 'Country',
  description: 'A caricature of the lower 48 United States, this linework 
    set is recognizable and friendly, but not concerned with accuracy. It’s
      that friend you have who’s always embellishing his stories.
         You never mind his lying, though, because the exaggerations make
           things more fun. Go ahead, enjoy the story your map is telling.
             (Version 1.1)',
  creator: 'Daniel P. Huffmann', publisher: 'Daniel P. Huffmann',
  published: '10/04/2013', modified: '10/04/2013', created: '3/24/2013',
  rights: 'Public Domain',
  derivedFrom: 'Derived from a 1920 broadside map entitled “The Rights of 
    the People—Women are People: Suffrage Victory Map. Equal Suffrage
      League of Virginia Papers, Acc. 22002,Library of Virginia.'
}).addTo(map)

// 2. Render annotations into the DOM
statesBoundaries.annotate()

API Documentation

You can find all options with which the Leaflet.annotate plugins extends the Standard API documented in the API section of the projects README.

http://mukil.github.io/Leaflet.annotate/