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.
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.
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!
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.
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.
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
divshould "be the last resort" so iusedarticle. - 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
metaelements withinarticleelements or trough integrating metadata in themicrodatasyntax. - Where and how to represent
datetimeon 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
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.
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)