Interactive Maps Application
 | Create interactive maps easily, share locations and associate structured data with areas |
| Type | XAR |
| Category | Application |
| Developed by | Fawad Ali, Stéphane Laurière |
| Active Installs | 10 |
| Rating | |
| License | GNU Lesser General Public License 2.1 |
Description
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.
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,
- On the create page, choose Map Point as the template and create the page.
- After clicking create, a map with several options will be shown. Select a location on the map or specify the latitude and longitude.
- Specify the other properties.
- The Options field takes CartoCSS to specify several options for Point e.g. opacity: 0.5; icon-url: "https://iconurl.com/icon.png";.
Supported options are: icon-url, title, alt, z-index-offset, opacity, rise-offset, rise-on-hover, attribution - 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.
- On the create page, choose Map Path as the template and create the page.
- On the path edit page, define the points through which a path is to be generated.
- Click Save & View.
Creating a shape
An interactive map preview with tools is provided for easily creating shapes. For creating shapes.
- On the create page, choose Map Shape as the template and create the page.
- On the shape edit page, a preview map will be shown with tools at the bottom left to create different shapes.
- Choose any tool and create your desired shape.
- Specify other options.
- The Style field takes CartoCSS to specify all the styles of shape e.g. fill-color: green;.
- 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 2>: ...
For example,
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,
- Go to the space where you want to create the map and click the Create button.
- Choose Map from the available templates and create the page.
- 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. - Click Save & View to view the map.
Configurable map options
| Field | Description | Example Value |
|---|---|---|
| INCLUDE LOCATION SEARCH | If 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 BUTTON | If 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 |
| QUERY | 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 POPUPS | If 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 SCALE | If 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 ZOOM | The zoom to which the map will open to. | 14 |
| DEFAULT LOCATION | The location to which the map will open to if there is no map item. | 48.8566, 2.3522 or Paris, France |
| LOCATION CLASSES | 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: | Maps.Code.PointClass: latitude, longitude |
| TILES | Background tiles of the map. | https://maps.heigit.org/openmapsurfer/tiles/roads/webmercator/{z}/{x}/{y}.png |
| MAP SIZE | Width 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 or 100%, 300px |
| INCLUDE FACETS | If facets (Refine your search section) are to be included or not. | Checked or unchecked |
| FACET FIELDS | Facet 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 |
| ATTRIBUTION | Attribution that appears at the bottom right corner of the map. It can be used to specify the identity of an entity or organization. | © <a href="https://www.openstreetmap.org/">OpenStreetMap</a> | <a href="https://www.xwiki.org">XWiki</a> |
| CUSTOM LOCATION PROPERTIES | This 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. | property.XWiki.XWikiUsers.address|property.TestClass.location_property |
Features
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,
- Go to Maps.MapEditor.
- Create map items using tools provided at the bottom left of the map preview.
- 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.
- 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.
Fullscreen
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.
- 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: "https://img.icons8.com/dusk/64/000000/city.png";
- 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.
- 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.
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 https://query.wikidata.org/ 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:
- Log in the wiki with a user having Administration rights
- Go to the Administration page and select the Import category
- Follow the on-screen instructions to upload the downloaded XAR
- Click on the uploaded XAR and follow the instructions
- You'll also need to install all dependent Extensions that are not already installed in your wiki
Release Notes
v1.2
v1.1
v1.0
Dependencies
Dependencies for this extension (org.xwiki.contrib:application-interactive-maps-ui 1.2):
- org.xwiki.platform:xwiki-platform-search-solr-ui 10.11
- org.xwiki.platform:xwiki-platform-appwithinminutes-ui 10.11
- org.webjars.npm:leaflet 1.5.1
- org.webjars.npm:github-com-Leaflet-Leaflet-Editable 1.1.0
- org.webjars.bowergithub.leaflet:path.drag.js 0.0.6
- org.webjars.bowergithub.9inpachi:leaflet-indoor 1.0.0
