Extension:Semantic Layers

DOCUMENTATION IN PROGRESS...MORE TO COME

What can this extension do?
This extension lets users put interactive OpenLayers maps into MediaWiki pages, and allows users to easily place "markers" (and define a subset of other layer types) on those maps using Semantic MediaWiki attributes and relations. It also takes advantage of the Semantic MediaWiki framework to provide basic, but powerful map-based query capabilities using its Semantic Search syntax.

Usually, OpenLayers and this extension would be used for displaying and interacting with traditional geographic data sets. This extension is of course well suited for such purposes, but OpenLayers is more flexible than that. It allows you to make a "map" out of a simple image, which means that you can use this extension to make rich, interactive, annotated illustrations from any image. This can be useful for such varied applications as annotated video game level maps/walkthroughs, marking up medical diagrams or images, architectural diagrams, or even things like chess diagrams.

Background
Before trying to use the extension, it is important to understand a few things.

Where does the data/imagery come from?
In short, OpenLayers (and hence Semantic Layers) is a BYOD (Bring Your Own Data) system. OpenLayers is a strictly Javascript based piece of software and has no server side component at all. Semantic Layers is simply "glue" code that connects OpenLayers to MediaWiki and Semantic MediaWiki. Neither software provides nifty satellite pictures or road maps to look at.

This can be both good and bad. On the plus side, since OpenLayers is not just the client part of any client-server software suite, it supports a very wide variety of data sources and formats, and is designed to be easily extensible to support more. On the down side, it's not very useful without any data or imagery.

The good news is, there are plenty of data sources available, if you know where to look. For tiled imagery, the data protocol usually used with OpenLayers is Web Map Service, or WMS. MetaCarta, the original developer and corporate sponsor of OpenLayers, provides two imagery datasets via WMS: a simple world map with land, water bodies, and country borders, as well as a mirror of NASA's Blue Marble imagery. Both of these datasets are preconfigured and available by default in Semantic Layers, in the Layers.js file. You can also look at, which maintains a catalog of publicly available WMS datasets.

The other good news is, if you want to publish your own geographic data, there are plenty of ways to do that using free open source software. Check out UMN MapServer or read about GML, which is an XML format for representing vector data that you can create by hand or with any web scripting language.

What is a "Layer"?
A Layer is, generically, any dataset that you want to display on a map. This could include:


 * Tiled imagery, e.g. a set of rectangular images that fit together to show satellite images of the earth
 * A set of "markers", each consisting of a single coordinate pair that denotes the location of something
 * A single image with geographic or Cartesian coordinates for a "bounding box" that indicates where in the map the image should be displayed

or many other kinds of data, but these three types are those primarily supported by the current version of the extension.

A map can (and usually does) contain multiple layers, which can be turned on or off by the user viewing the map so that they can see as much or as little data as they want.

Layers are stacked on the map, one on top of the other, so order matters. For example, you generally wouldn't put a tiled imagery layer "on top of" a markers layer because it would both visually obscure the markers and also (even if the imagery layer is transparent) prevent the user from clicking on the marker icon. Partly for this reason, in OpenLayers and Semantic Layers, some layers can be designated as "Base Layers", which always appear on the "bottom" of the layer stack, and only one base layer can be viewed at a time.

Usage
NOTE: It is difficult to cover the usage of this extension in a linear fashion. You may need to skip around to different sections to get a good idea of how to use it, depending on what you're trying to do.

Adding a map
A map is added to a wiki page with the &lt;slmap&gt;&lt;/slmap&gt; tag (there is also the parser function, but that should be considered unstable for now). After installing Semantic Layers, a simple map can be added to a wiki page by adding the following:



Of course that is not a very useful map, as it has only the default layer displayed and defaults to showing the whole world. The slmap tag accepts the following arguments, which can help to make the map more interesting:

Other arguments are also available that pertain to semantic searches, but those will be covered further down.

Of course, in a default installation of Semantic Layers with no wikidata added yet, you can only create maps with two not particularly useful layers: World_Map and Satellite. You will need to add additional layers to your wiki to do more useful things.

Defining Layers
There are two ways to define layers. One is by using the Layer namespace and Semantic MediaWiki annotations. The other is by adding Javascript code to Layers.js, but this second method is covered further down, as it requires access to the Semantic Layers extension installation files.

NOTE: If you are not already familiar with them, you should learn about Semantic MediaWiki annotations before continuing.

Semantic Layers lets you define some types of layers directly in the wiki, by using the Layer namespace. For example, if you had an article named Layer:Sample WMS with the following contents, it would be a duplicate of the included World_Map layer defined in Layers.js:

Layer label:=World Map Layer class:=WMS Layer data source:=http://labs.metacarta.com/wms-c/Basic.py? Layer class option:=layers=basic Layer class option:=format=image/png

Unfortunately, to really understand all of that, you have to be familiar with the OpenLayers.Layer.WMS class, which is outside the scope of this document. But if you're familiar with Javascript, you can probably figure most of it out by looking at the OpenLayers examples.

In the current version of Semantic Layers, three "Layer class" options are supported:


 * Markers (the default)
 * WMS
 * Image

There are a number of attributes and relations that are used in defining Layers. Each layer class takes a different combination of definition annotations. The following table lists all the attributes and relations used by Semantic Layers. Note that all attribute and relation names are defined as MediaWiki messages. Therefore, if they conflict with existing annotations in your wiki or are unsuitable for some other reason, it should be possible to change them by editing the message in Special:Allmessages--but this is strongly discouraged as well as untested.

IMPORTANT: The extension does not automatically define these annotations. They (the attributes, at least) must be defined manually in the wiki with the appropriate types. Also note that this should be done before they are used to create any layers, otherwise Semantic MediaWiki may not recognize the annotations  and queries will not function properly.

DOCUMENTATION IN PROGRESS...MORE TO COME

Installation
The current version requires Semantic MediaWiki version 0.7 (it will not work with version 1.0-pre-alpha). It is planned to eventually allow Semantic Layers to offer some rather limited functionality without Semantic MediaWiki, but you will want Semantic MediaWiki anyway to take full advantage of Semantic Layers' capabilities.

Parameters
There are a few settings that can be changed, but they should be changed in the file includes/SL_Settings.php (a better configuration mechanism will be eventually forthcoming). The SL_Settings.php file contains descriptions of the available settings. You should not have to edit this file to get initially up and running, but it can be used in more advanced setups.

Changes to LocalSettings.php
Add the following line to LocalSettings.php to enable Semantic Layers. It must appear after the line that installs Semantic MediaWiki.

require_once("$IP/extensions/SemanticLayers/includes/SL_Settings.php");

Defining layers in Layers.js
You can add any layer type supported by OpenLayers by adding the Javascript layer definition to the file js/Layers.js. When doing so, try to mimic the syntax used in the included Layers.js file as closely as possible--Semantic Layers uses a somewhat crude parser to extract the available layers from the Javascript file, so there's a chance that a valid Javascript definition of the layer wouldn't get recognized by the extension code.

DOCUMENTATION IN PROGRESS...MORE TO COME