Discussion thread about the project on the XWiki devs mailing-list:



This project is about the development of interactive maps in XWiki. Its goal is to create an XWiki application that will allow users to easily generate interactive maps supporting collaboration so that locations can be shared, and areas can be associated with structured data. This application will open several possibilities that can be utilized within XWiki and broaden the overall scope by allowing rich wiki maps where locations and areas can be presented in a way that will increase the understandability of data.

Use cases

Town hall use case

As an employee of a town hall, I can create with my colleagues an interactive map displaying the main city points and areas of interest: museums, gardens, libraries, swimming pools, shops, transports, ... I can do by harnessing existing data that I have at I my disposal either already in a wiki, or that can I can import into one. For example, I have a database of all city monuments with their geographical coordinates, a geographical database of metro and bus lines, and some touristic paths across the city. I want to represent this data on a map in order to promote it and ease its usage.

I need to be able to configure the map visually: associate icons to specific elements (e.g. one icon for monuments), choose colors of paths and shapes, choose the available map background(s). For example, if real imagery of the world is required for pointing out a location, a satellite-based background can be chosen, or if the infrastructure must be emphasized, background which better represent paths can be used .

  • Step 1: I import the available data into a wiki.
  • Step 2: I enrich the data collaboratively via the wiki: I provide more detailed information about each monument, I add images, videos. I also edit individual points, paths or shapes in order to add missing geographical information or in order to refine the data or fix it.
  • Step 3: I create a map configuration that lets me represent this data interactively, define a visual theme, configure filters and the way contextual information can be retrieved and displayed.

Encyclopedia use case

This use case is functionaly very similar to the town hall use case, however it provides a slightly different perspective,. It highlights the facts that 1) the user will want to avoid twisting the data just for the purpose of representing it on a map: existing content will be simply enriched for map representation, 2) it may make sense to use Solr QL and Solr facets as the primary way to configure and filter map elements.

As the contributor to an existing encyclopedia, beside presenting content as articles with images and videos, I want to represent the existing content on a map. Among other things, my encyclopedia contains in particular pages related to places or events. I want to enrich the existing pages so that they can be represented on a map. For example, I want to represent all HLS places related to archeologia on a map.

  • Step 1: I enrich the existing pages so that they can be represented on a map. To do so, I can either launch a service that computes the geo coordinates / shapes from existing data, if any, or I can manually add geographical information to each relevant page. For instance, if a page relates to a battle, the key locations where the battle took place would be added.
  • Step 2: configure one or several maps for representing the enriched information. For instance:
    • Map representing all places that relate to archeologia
    • Map representing all the battles that took place in the 17th century
    • Map representing all monuments in a country

Indoor map use case

As the organizer of a fair, I have a database of all fair exhibitors description and of their booth location. I want to represent this data on an interactive plan.

Indoor maps will be able to describe the internal structure or fair plan of a building or structure. They can be used to guide users in a big building and locate point of interests. Users will be able to insert an image as background describing the structure of the building and then add custom shapes, markers atop the image and associate relevant popups with them. Support will be added so that multi level of buildings can be represented.


Data Model

  • Map: represents a map configuration. In particular it provides either directly or via distinct classes:
    •  A way to define the target data that is used to render the map: it can be either all the geographical data that contained in the wiki, or just a part of it. It is important to agree on the best way to define this query. This could be either a database list, hence defined in HQL, or a Solr query. Solr could be more powerful to cover in particular the encyclopedia use case. To be discussed.
    • Map theme: visual configuration aspects: map background, marker icons, entity colors, ...
  • Point: a geographical point defined by its latitude and longitude (or just by abstract spatial coordinates in the case of indoor maps, to be discussed in the future)
  • Shape: a polygon, circle, etc.
  • Path: a segment linking two points
  • Content: this is the content to be displayed contextually when clicking on a map element. Typically in the case of an encyclopedia, the content could be each article itself, or the first paragraph of it, or any configurable block(s) (including images). This requires a dedicated discussion in order to let the behaviour be as generic as possible, without the need, if possible, to duplicate information just for map rendering (the content is interesting beyond the map representation, it would be cumbersome to have to twist the existing content for a specific representation).

Once the logical data model will be defined, we will need to choose the most appropriate way to implement it as XWiki classes. In particular, there's the need to choose what query language will be used. We need also to choose if we represent the geographical entities as individual classes (one class for Point, one for Path, one for Shape, or we define a generic entity such "SpatialEntity" or "GeographicalEntity" than can either represent a point, a path, a shape. We need also to define how the content will be associated with each entity. It's important also to specify how the visual elements will be made configurable, possibly via a map theme.


Each geographical entity should be viewable and editable individually.  For instance, I should be able add geographical information to an article related to a battle, and to view this information. In particular, the sheet allows to visualize and edit point markers, shapes, paths (a segment between two points), tracks (a set of paths), ... How the content itself will be made editable remains to be discussed and specified.
Custom shapes can be used to highlight a specific area for representation. The content associated with these shapes can give useful information about the area. For these kind of maps, the user will be able to draw a shape of his choice with the tools made available and optionally attach popups.

User Interface Widgets

Filter Widget

This widget is a user interface that lets the user refine the list of places he wants to display on the map. To start with it can be a plain text input. It can evolve into a more avanced widget that will expose data filters / facets.


Filtered List

This widget allows the user to search for a specific kind of place (e.g. restaurants) and get a list of locations to choose from. Through the content available and binded to a location, the user will be able to learn some aspects of the location.

Location Search Widget

This widget allows to search any location on the map by coordinates or name. A search icon will always appear on the map which on selection will display a search form through which a location will be searched and the map will move to that location.


Query Service

The query service is a web service that returns dynamically the data to be represented on a map. It takes as input a query, and it returns a JSON file containing the data to be represented on the map. The content itself that is associated with each entity could be returned via subsequent ajax calls, so that the returned GeoJSON remains small enough.

Tile Service

This service allows to convert a large image such as a high-resolution fair plan into tiles so that the plan can be represented as an interactive map.

Data Import Service

This service eases the integration of existing data into a wiki. The primary input formats should be CSV and GeoJSON. It will be useful also for designing and testing the application, beside being useful to the users. The input data can be already geolocalized or not. If not, the batch geolocalization service could be used.


  • The BatchImport application can be used to import data from CSV or XLS files. The application should ease the access to such operations.
  • OpenStreetMap provides API endpoints providing content in GeoJSON that can be used for generating data to be imported:

Geo Location Service

The location service allows to convert one address or several ones to coordinates. It hinges on existing geolocation services such as OpenStreetMap Nominatim.

Other aspects

Maps on Mobile

Special design arrangements will be made for easy viewing of maps and availing all the features of the application on mobile devices.

Data samples

In order to implement the use cases described above, at some point that will be useful to work with a significant amount of data. This paragraph is about gathering such data. This step can come later in the process, once the basic structure is implemented and a workable prototype is working with data entered manually.


List of memorials


Choose a large city, enter the query below, then export it into GeoJSON:


Other data sources




Get Connected