A Leaflet plugin integrating schema.org to markup items in your geographic web map machine readable.
Switch branches/tags
Nothing to show
Clone or download
Fetching latest commit…
Cannot retrieve the latest commit at this time.
Permalink
Type Name Latest commit message Commit time
Failed to load latest commit information.
dist
docs
src
.gitignore
Gruntfile.js
LICENSE
README.md
package.json

README.md

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:

Option Key Expected Value Metadata Element Key and Definition
itemtype (Mandatory) Text Nearly any Schema.org type with a "spatial property" (allowing for stating a Geo Coordinate, Geo Shape or Place) in its definition. For example you could use City or State here. If you declare a schema type which is no subtype of Place, like e.g. Organization, CreativeWork, Article or Comment please make sure you set the geoprop option. Please see schema.org type definitions to find out about all possible types and let me know if your case is not supported yet.
geoprop (Optional) Text Name of Schema.org property to use for the geographical expression. Default is "geo", which is valid for Place and all its subtypes. Other valid values consequently would be "location" (for Organisation) or "contentLocation" and "locationCreated" (for CreativeWork).
title
(Optional)
Text name (Thing), "The name of the item."
description (Optional) Text description (Thing), "A short description of the item."
alternateName (Optional) Text alternateName (Thing), "An alias for the item."
image
(Optional)
Text image (Thing), "An image of the item." Currently this should be an URL.
sameAs (Optional) Text sameAs (Thing), "URL of a reference Web page that unambiguously indicates the item's identity. E.g. the URL of the item's Wikipedia page, Freebase page, or official website."
url
(Optional)
Text url (Thing), "URL of the item."
identifier (Optional) Text identifier (Dublin Core), "An unambiguous reference to the resource within a given context. Recommended best practice is to identify the resource by means of a string conforming to a formal identification system."
domId (Optional) Text Allows you to set the DOM ID for the annotation container element (either article, or metadata). Note: Leaflet must translate some geodata, esp. MultiPolygon GeoJSON files into multiple HTML elements. On such map elements you must not use/set this property as it would invalidate the HTML document.
creator (Optional) Text creator (Dublin Core), "An entity primarily responsible for making the resource. Typically, the name of a Creator should be used to indicate the entity (e.g. person, organisation or service)."
contributor (Optional) Text contributor (Dublin Core), "An entity responsible for making contributions to the resource. Typically, the name of a Contributor should be used to indicate the entity (e.g. person, organisation or service)."
publisher (Optional) Text publisher (Dublin Core), "An entity responsible for making the resource available. Typically, the name of a Contributor should be used to indicate the entity (e.g. person, organisation or service)."
rights (Optional) Text rights (Dublin Core), "Information about rights held in and over the resource. Typically, rights information includes a statement about various property rights associated with the resource, including intellectual property rights."
derivedFrom (Optional) Text source (Dublin Core), "A related resource from which the described resource is derived. The described resource may be derived from the related resource in whole or in part. Recommended best practice is to identify the related resource by means of a string conforming to a formal identification system."
format (Optional) Text format (Dublin Core), "The file format, physical medium, or dimensions of the resource. Recommended best practice is to use a controlled vocabulary such as the list of Internet Media Types MIME."
language (Optional) Text language (Dublin Core), "A language of the resource. Recommended best practice is to use a controlled vocabulary such as RFC 4646 RFC4646."
created (Optional) Text and Integers created (Dublin Core Term), "Date of creation of the resource. Recommended best practice is to use an encoding scheme, such as the W3CDTF profile of ISO 8601."
modified (Optional) Text and Integers modified (Dublin Core Term), "Date on which the resource was changed.. Recommended best practice is to use an encoding scheme, such as the W3CDTF profile of ISO 8601."
published (Optional) Text and Integers date (Dublin Core), "A point or period of time. May be used to express temporal information at any level of granularity. Recommended best practice is to use an encoding scheme, such as the W3CDTF profile of ISO 8601."

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)