mapCreate interactive maps easily, share locations and associate structured data with areas
Developed by

Fawad Ali, Stéphane Laurière

Active Installs23
1 Votes
LicenseGNU Lesser General Public License 2.1

Installable with the Extension Manager


Create interactive maps easily, share locations and associate structured data with areas.

A feature rich map application that will allow you to easily create interactive maps within XWiki. Using this application, you can present items of interest on a map in a variety of ways. Data can be associated with each item of interest so users can get more information about the item. Furthermore, using simple to advanced search and filter capabilities, users can easily look for the location they are interested in. Bundled with a lot of customization options to create the map that best suits your context.

Solr search query called map query is used to get data to be displayed on the map.

Creation of map items

Map items are object pages that can be included in the map. There are several kind of map items namely Point, Path, Shape and Indoor Structure.

Creating a point

For creating a point that is to be included inside the map,

  1. On the create page, choose Map Point as the template and create the page.
  2. After clicking create, a map with several options will be shown. Select a location on the map or specify the latitude and longitude.
  3. Specify the other properties.
  4. The Options field takes CartoCSS to specify several options for Point e.g. opacity: 0.5; icon-url: "";.
    Supported options are: icon-url, title, alt, z-index-offset, opacity, rise-offset, rise-on-hover, attribution
  5. Save & View to view the newly created Point map item.

Creating a path

Paths are generated between a number of points. For creating paths, first create the points through which you want to create a path.
Now that the points are created.

  1. On the create page, choose Map Path as the template and create the page.
  2. On the path edit page, define the points through which a path is to be generated.
  3. Click Save & View.

Paths are generated using Open Source Routing Machine (OSRM). The servers used to generate the paths are sometimes busy so the paths might not be generated showing an error on the map page.

Creating a shape

An interactive map preview with tools is provided for easily creating shapes. For creating shapes.

  1. On the create page, choose Map Shape as the template and create the page.
  2. On the shape edit page, a preview map will be shown with tools at the bottom left to create different shapes.
  3. Choose any tool and create your desired shape.
  4. Specify other options.
  5. The Style field takes CartoCSS to specify the all the styles of shape e.g. fill-color: green;.
  6. Save & View to view the newly created shape.

Creating an indoor structure

A well defined text is used to gather data for an indoor structure. Levels are defined with shapes and points to be shown on each level.


The structure for levels with shapes and points should be:

<level 1>: <shape 1 fullname>, <shape 2 fullname>, <point 1 fullname> ... <shape/point n fullname>
<level 2>: ...

For example,

0: Sandbox.Indoor.ComputerDept.Dept, Sandbox.Indoor.ComputerDept.Faculty Offices, Sandbox.Indoor.ComputerDept.Class Rooms
1: Sandbox.Indoor.SoftwareDept.Dept, Sandbox.Indoor.SoftwareDept.Faculty Offices, Sandbox.Indoor.SoftwareDept.Class Rooms

Levels can be both positive and negative numbers.
When added to a map, an indoor structure will look like this with level control available at the bottom right.

Creation of a map

For including map items inside a map, map query is used to gather the map items.

Creating the map

Maps can be simply created from the map template. For creating a map,

  1. Go to the space where you want to create the map and click the Create button.
  2. Choose Map from the available templates and create the page.
  3. A list of configurable options will appear. If you leave a field empty, its default value will be used.
    A detailed description of each configurable option is given at the end of this section.
  4. Click Save & View to view the map.

Configurable map options

FieldDescriptionExample Value
INCLUDE LOCATION SEARCHIf location search is to be included or not. Location search refers to being able to search any location on the map even if it is not a point of interest.Checked or unchecked
INCLUDE CURRENT LOCATION BUTTONIf current location button is to be included or not. Current location button moves the map to the user's current location on click.Checked or unchecked

This specifies the map query. It is a solr query that is used to collect data to be displayed on the map. Using the query specified, all the pages that satisfy the query and have a map item object (e.g. Maps.Code.ShapeClass) are gathered so they can be added to the map.

See Solr Search Syntax for a quick overview.

space:Maps.Demo.XWikiSAS AND title:Romania
INCLUDE POPUPSIf popups are to be associated with the map items or not. No map items will have popups if this option is unchecked. If checked, then the individual configuration of a map item will be considered.Checked or unchecked
INCLUDE MAP SCALEIf the distance scale is to be included in the map or not. The map distance scale appears at the bottom left corner of the map. It specifies the corresponding distance on the ground.Checked or unchecked
DEFAULT ZOOMThe zoom to which the map will open to.14
DEFAULT LOCATIONThe location to which the map will open to if there is no map item.48.8566, 2.3522
Paris, France

This specifies classes which will be used to get point objects. The default class for points is Maps.Code.PointClass. However, if a user wants to use a custom class or classes to gather latitude and longitude of a point, then he can specify these classes as well.

The structure for defining a custom class should be:
<class name>: <latitude property name>, <longitude property name>
<class name 2>: ...

Maps.Code.PointClass: latitude, longitude
TestSpace.TestClass: lat, lon

TILESBackground tiles of the map.{z}/{x}/{y}.png
MAP SIZEWidth and height of the map. Can accept both percentage and pixel values. Width and height are separated by comma with value before comma as width and value after comma as height (width, height).300px, 300px
100%, 300px
INCLUDE FACETSIf facets (Refine your search section) are to be included or not.Checked or unchecked
FACET FIELDSFacet fields are used for specifying solr filters that appear in the Refine your search section. Anything that can work as a filter in solr can be used. It is a list so multiple fields can be defined.space_facet|property.XWiki.TagClass.tags_string
ATTRIBUTIONAttribution that appears at the bottom right corner of the map. It can be used to specify the identity of an entity or organization.&copy; <a href="">OpenStreetMap</a> | <a href="">XWiki</a>
CUSTOM LOCATION PROPERTIESThis specifies class properties that can serve as addresses for points. With this, a property of a class can be defined and it will be considered a potential point. One of the use cases could be to show locations of all XWiki users which can be gathered using property.XWiki.XWikiUsers.address|property.TestClass.location_property


This application includes a lot of customizable features which can be used to create maps of your choice.

Map editor

A complete tool is provided to easily create Point and Shape objects for the map. For using map editor,

  1. Go to Maps.MapEditor.
  2. Create map items using tools provided at the bottom left of the map preview.
  3. Click on a map item to define its properties namely title, content, add popup and style/options, and update them. Click on delete in the properties menu to delete a map item.
  4. Specify a space where map items are to be created and click Create Items and BAM!! All is done.

Search and filters

Search allows searching of map items or a location on the map. If search for a location is made, the map will move to that geographical location even if it is not a point of interest. Search for map item will narrow down the map items included in the map.


Filters specify solr search facets which define map item results that belong to a category.


Custom filters can be defined using the FACET FIELDS map option.


A map can easily be shifted to fullscreen mode for a more dedicated and wide view.


Custom marker icon

A custom image can be used in place of the default marker icon. For using a custom image as marker icon, there are two ways.

  1. Icon URL:
    • ​​​​​​​The icon-url CSS property can be defined in point's options field which takes URL of an image to be used as a marker icon. e.g. icon-url: "";
  2. Attachment:
    • Rename your image so that it starts with the word marker. For example, marker_paris.png or markerGermany.png. Names like germanyMarker.png that do not begin with marker are not accepted.
    • Attach the image to the point page.

Map data importer

Large amount of map items can be imported and included in the map using the map data importer. Import map data using SPARQL from as JSON in a specific wiki space and add it to a map using map query. More details are available on the page Maps.MapDataImporter of the application.

Sample maps

Prerequisites & Installation Instructions

We recommend using the Extension Manager to install this extension (Make sure that the text "Installable with the Extension Manager" is displayed at the top right location on this page to know if this extension can be installed with the Extension Manager). Note that installing Extensions when being offline is currently not supported and you'd need to use some complex manual method.

You can also use the following manual method, which is useful if this extension cannot be installed with the Extension Manager or if you're using an old version of XWiki that doesn't have the Extension Manager:

  1. Log in the wiki with a user having Administration rights
  2. Go to the Administration page and select the Import category
  3. Follow the on-screen instructions to upload the downloaded XAR
  4. Click on the uploaded XAR and follow the instructions
  5. You'll also need to install all dependent Extensions that are not already installed in your wiki

Release Notes





Dependencies for this extension (org.xwiki.contrib:application-interactive-maps-ui 1.2):

Created by Fawad Ali on 2019/07/16 19:03

Get Connected