User:Wauteurz/Dynmaps

Need a map that will dynamically update as listings are added, updated and removed? This page tells how.

This tutorial is structured in four parts. The first explains the essential workings of dynamic maps and how to add them into articles. The second handles point-based data (individual markers on a map), the third deals with polygons (enclosed shapes on a map), and the last explains line-based data (elements on a map going from A to B).

Dynamic maps are added using {{Mapframe}}. Its preferred location within regular destination articles is at the top of the Get around-paragraph. If there are already WV:Listings in the article, simply adding {{Mapframe}} will automatically configure the map.

48°12′59″N 16°22′50″E

A custom Mapframe of Vienna, Austria.

Most instances of a dynamic map do not need a lot of defined parameters. In theory, every parameter of the template can be left empty, granted that listings in the article have coordinates. The following paragraphs will explain how to make a dynamic map on a step-by-step basis.

Centering the map

To make the map center on a single region such as a city centre, add the latitude and longitude on which you wish to center the map to {{Mapframe}}. These coordinates are best obtained by using the Geomap tool. By setting the Geomap to Mapframe in the menu on the left, the Mapframe syntax will be generated for you. A Mapframe with a centered location should have a syntax akin to this:

{{Mapframe | 48.21650 | 16.38063}} 

Note that the latitude and longitude parameters are unnamed parameters. These should always be put in front of all other parameters, but defining |lat= and |long= is not needed.

Defining a zoom level

Adding a zoom level is entirely optional. The advantage of defining a zoom level, is that it locks down the map's default zoom. This way you can exclude listings that are further afield and therefore force a mapframe without a defined zoom level to be very cluttered with many listings overlapping each other in a central location.

Zoom levels are defined as a number. The smaller that number is, the further the mapframe is zoomed out. The furthest the map can be zoomed in, is 18. The Geomap tool automatically chooses a zoom level based on how zoomed in you are in the tool. You may wish to redefine this number, or remove it altogether. Adding a zoom level, our syntax now looks like this:

{{Mapframe | 48.21650 | 16.38063 | zoom=11}} 

Custom sizes

{{Mapframe}} has a height and width parameter, which lets you define the amount of pixels the mapframe should be tall and wide. Do not define these with "px" behind them. Simply insert the number of pixels. In most cases, the default size should not be overwritten. In some cases though, such as when pairing a dynamic map with {{Regionlist}}, you might wish to use a larger size for improved legibility.

Defining the size of our Vienna map, its syntax now should something like this:

{{Mapframe | 48.21650 | 16.38063 | zoom=11 | height=500 | width=600}} 

Naming your map

To wrap up our simple, large map of Vienna, we want to give it a name. This name defaults to "Map of your article", but you might want to name this differently for a variety of reasons. Simply add a name parameter to achieve this. You can use Wikitext formatting within this name to link to other articles or include a template. Generally, these Wikitext features aren't applied in articles. Our map is now finalised as the example on the right. Its syntax is as follows:

{{Mapframe | 48.21650 | 16.38063 | zoom=11 | height=500 | width=600 |name=A custom Mapframe of {{flag|Vienna}} [[Vienna]], Austria.}} 

Altering alignment

Similar to images, {{Mapframe}} supports defining to which side of the article's boundaries it aligns. To do this, define |align= direction. By default this is set to right, and there are very few cases in which this alignment should be altered. It can, however, be changed to align to the left or center if desired.

Adding a static map

If a static map exists of the destination, then you can add this below the mapframe. To add the static map of Vienna, for example, use |staticmap= Vienna Wikivoyage Map.png, which will insert File:Vienna Wikivoyage Map.png below the dynamic map.

Adding a custom district map

If you or another editor has previously made a custom district map and uploaded this to as a .map-file, you can insert this map by adding {{Mapshape|type=page|wikicommons=Vienna Districts.map}}. In Vienna's case, this map is found at Commons:Data:Vienna Districts.map.

Showing certain layers

Every kind of listing falls into a certain layer. These layers correspond to the listing types (eat, sleep, see, do, et cetera). By adding |layer= see,do to the mapframe's syntax, you will exclude every layer except the see and do-layer.

Using groups

When using multiple dynamic maps in one article, you might want to control which listings appear on which maps. For these, add |group= name to all listings you want to appear in the dynamic map. For the mapframe itself, use |show= name. Naturally, the name defined in group and show should be the same.

* {{Listing | type =    | name     = | alt =    | lat      = | long =    | url      = | email =    | address  = | directions =    | image    = | wikidata = | wikipedia =    | phone    = | tollfree = | fax =    | hours    = | price = | checkin = | checkout =    | content  =    | lastedit = }} 

Listings are entries for the individual sights and locations at a destination. They include contact information, geocoding, links and other valuable information that a reader may require.

Listings is both a stand-alone template ({{Listing}} and a group of purpose-made derivatives of that template. These are all named after the article section they go in: {{See}}, {{Do}}, {{Eat}}, {{Drink}}, {{Buy}}, {{Sleep}} and {{Go}}. In articles, use the proper derivative instead of {{Template}}. This tutorial will use the Peace Palace in The Hague, The Netherlands as an example listing. This means that the derivative template {{See}} is used. All of the steps detailed in this section, however, will apply to all listing derivatives.

Naming the listing

The name which is used in English promotion and general usage, should be defined as the default name using |name= Peace Palace. In case the listing is better known by a former name, or has a different name in its native language or script, this should be added as well using |name= Vredespaleis.

Defining coordinates

As with mapframes, coordinates are easiest to obtain using the Geomap tool. Its default lat|long mode suffices, but you might want to switch the displayed map over to Mapnik using the layer icon in the top right.

To get the coordinates, simply navigate to the location of the listing, click on the place where there listing should be, and copy the "lat=xx.xxx | long=xx.xxx" text from the bubble that appears. These can then be pasted directly into the wikitext syntax.

When using the listing editor, it's more convenient to copy the raw coordinates from the Geomap tool individually, and insert those into the corresponding fields of the listing editor.

Addresses and directions

Addresses are fairly straightforward. Simply add the street name and house number to |address=. When adding an article containing multiple towns, define the town's name as well: address=Street 23, Town. Never add post codes and other identifiers if not strictly necessary.

Directions can be defined pretty broadly. Usually, it's the best practice to define directions relative to some easy-to-get-to location, such as a public transit stop. Since our example, the Peace Palace, has a dedicated tram stop, we need only mention this. This can be done in plain text, but can also be done using templates such as {{Station}}.

Using the directions above, we've created the following listing and syntax:

• 52.08654.29521 Peace Palace (Vredespaleis), Carnegieplein 2 (Vredespaleis  1 ).  

* {{See |name= Peace Palace |alt= Vredespaleis |lat= 52.0865 |long= 4.2952 |address= Carnegieplein 2 |directions= {{Station|Vredespaleis|city=denhaag|1}} }} 

Websites, emails addresses, phone and fax numbers.

If available, all of the above can be added using |url= website, |email= [email protected], |tel= +xx xxx xxx xxx and |fax= +xx xxx xxx xxx. Phone and fax number should always include the international dialling code (+xx). If a toll-free number is available, please use |tollfree= instead.

Opening hours

Opening hours are defined in the local clock times. The US, for example, uses 1-12 AM/PM, while most of Europe uses a 24-hour notation. Days are listed as M/Tu/W/Th/F/Sa/Su. For the Peace Palace, we can define these as |hours= W-Su 12:00-16:00, M-Tu closed.

Prices and price ranges

Prices are listed in the local currency. It is encouraged to use the dedicated template for that currency so that readers unfamiliar with the currency's exchange rate can get a better idea of what it'll cost them. Since The Netherlands use the Euro, the Peace Palace's listing is as follows: |price= {{EUR|16.50}}

Descriptions

Descriptions can be added using |content=. Simply write an interesting description of a couple of sentences at most, but preferably keep it to a single sentence. You don't need to repeat the whole Wikipedia article - just link it instead so that those that want to can find their way to the Wikipedia article. If the listing is so important to the destination itself that it warrants adding more information, write more about it in a dedicated subparagraph in the corresponding paragraph.

Using the directions above, we now have a pretty much complete listing for the Peace Palace:

• 52.08654.29522 Peace Palace (Vredespaleis), Carnegielaan 2 (Vredespaleis  1 ), ☏ +31 703 024 242. W-Su 12:00-16:00, M-Tu closed. The Peace Palace is the home of the International Criminal Court, Permanent Court of Arbitration and other law-related organisations. The building was opened in 1913 following the Hague Convention of 1899, which instructed for the creation of the court. The palace sits on the Carnegielaan, named for the Scottish-American main financier of the building's construction. €16.50.  

* {{see | name=Peace Palace | alt=Vredespaleis | url=https://www.vredespaleis.nl/?lang=en | email= | address=Carnegielaan 2 | lat= 52.0865 | long= 4.2952 | directions={{Station|Vredespaleis|city=denhaag|1}} | phone=+31 703 024 242 | hours=W-Su 12:00-16:00, M-Tu closed | price={{EUR|16.50}} | content=The Peace Palace is the home of the International Criminal Court, Permanent Court of Arbitration and other law-related organisations. The building was opened in 1913 following the Hague Convention of 1899, which instructed for the creation of the court. The palace sits on the Carnegielaan, named for the Scottish-American main financier of the building's construction. }} 

Linking other Wikimedia projects

Using other Wikimedia projects, some of these steps above can be omitted altogether. Defining a Wikidata ID (Q####) in the |wikidata= field will give you the option to fetch URLs, contact information, coordinates and images from Wikidata, provided that the listing has an entry on Wikidata. In the case of the Peace Palace, this ID is Q834448. Make sure that you get the Wikidata of the actual listing, instead of something similarly named. Major attractions tend to have things named after them. One way to ensure that you get the right Wikidata ID, is to navigate to the listing's Wikipedia article, and click "Wikidata item" in the Tools-sidebar on the right.

Adding images

This is done using the |image= parameter, or using the image field in the listing editor. Simply paste the file name used on without the File:-prefix. In the editor, click the result that appears before saving. This then allows for an image to appear whenever the listing is clicked on the dynamic map. If linking the Wikidata item gives you an ugly image, either overwrite it locally using the |image= parameter, or replace the image (P18) assigned to the Wikidata item.

Hotel check-in and check-out times

For {{Sleep}}, a |checkin= and |checkout= parameter is available. If you know when the accommodation is willing to welcome you, or expects you to have left your room, then insert these times here using the local time notation.

Inline usage

If you want the listing to appear in-line with the text itself, instead of in a list, you can enable the inline mode by adding |inline= true to the wikitext syntax. This option is not available in the listing editor.

Editing the listing number

Using |counter= ##, the listing number can be forced into being a specific number. Simply define the parameter as the desired number. This option is not available in the listing editor.

Polygons come in different shapes and sizes, and use several somewhat confusingly named templates. There is also more than one way to getting these to appear on a dynamic map. The quickest way to achieve this, is through Wikidata. A more reliable method, however, is to manually create the shape instead.

52°22′8″N 4°53′27″E

A map of Amsterdam's Canal District, defined using custom coordinates. Though using {{Mapmask}}, the result is identical to the result that {{Mapshape}} would produce.

Using Wikidata

The more straight-forward method to add masks onto a dynamic map, is to use Wikidata. A map mask for Amsterdam, for example, can simply be added by using {{Mapshape}} and defining the Wikidata ID of Amsterdam (Q9899). This gives the following syntax:

{{Mapshape|wikidata=Q9899}} 

Using custom-made masks

Not everything has a polygon available on Wikidata, nor is {{Mapshape}} perfectly stable. Therefore, you might want to use an alternative. In cases like that, you can create a polygon in a GeoJSON editor. Several of these exist online, but free software such as QGIS can also be used for this purpose. The main requirement here, is that the GeoJSON code can be exported or copied across to another tool. Useful online solutions include geojson.io, geoman.io, vector.rocks and krata. On GitHub, several instances of these can be found as well.

When downloaded onto your computer, open the .json file in a text editor such as Notepad. Some tools also allow you to copy the raw GeoJSON code as well. Copy the raw GeoJSON code across to the Mapmask ↔ GeoJSON converter. This tool will convert GeoJSON code to a {{Mapmask}}-compatible code. Run the tool, and use the resulting syntax in the article where you wish to insert the mask.

Using Wikidata

Be aware that Wikidata-based region maps tend to be somewhat unstable. It is advisable that instead of Wikidata, you use GeoJSON as a basis for region maps for that reason.

Assuming that all the subdivisions of the region have Wikidata items with associated shapes, you can build a dynamic map to accompany a {{Regionlist}}. For this, use {{Mapshape}}. For each subregion that requires a colour, fill in the following syntax:

{{Mapshape |type= geoshape |wikidata= | fill= {{StdColor|T2}} |title= }} 

For |wikidata=, enter the Wikidata ID of the subregion. If the subregion consists of multiple Wikidata IDs, separate them using a comma. |fill= requires a valid web color or RGB hex, but it is advised that you use of Wikivoyage's standardised colours instead. Lastly, |title= is the text that appears when clicking on the region on the dynamic map. Make this be a link to the subregion.

Using GeoJSON

GeoJSON-based maps can be worth making as they are more reliable than Wikidata-based maps. They do, however, demand more effort to make. You can either choose to build your region map using open data, or choose to draw it from scratch. In the case of the latter, you will need a GeoJSON editor that will allow you to snap polygons together, such as Krata or Geoman.io. Of course, a program such as QGIS can work as well. Simply start tracing the shapes of the regions you wish to display on your region map. For each, add the following parameters:

Optionally, a stroke-opacity can be added as well.

Once you've defined these parameters for all your regions on the map, you can export the raw GeoJSON to Commons. The map needs to be stored in the Data:-namespace, with the file name ending in .map. For example: Data:Luxembourg WV.map. Add onto the raw GeoJSON code you have with Commons-specific parameters, and fiddle a bit with the default map extent to make sure it displays the full map. Should anything go wrong, refer to other GeoJSON-based region maps to see where they differ from yours. The editor on Commons will also flag potential errors - make sure the map you're uploading has no errors.

Open data can be imported into QGIS, at which point you might have to merge or alter some polygons. It's recommended to use EPSG:3857 - WSG 84 / Pseudo-Mercator as the project's CRS. This generally speaking, is a faster process than drawing regions from scratch. After importing and merging, add and define the above parameters, after which the shapes can be exported to GeoJSON and uploaded to Commons in much the same process. Since GeoJSON files can be heavy on QGIS, it's recommended to instead create the polygons in a GeoPackage layer. To create a new one, use Ctrl + Shift + N. The prompt that pops up will ask you for several settings:

• Database: Where on your PC you wish to store the GeoPackage.
• Table name: The name of the layer within the GeoPackage that you will be defining. Simply name this something like "Wikivoyage regions".
• Geometry type: The kind of geometry you will be drawing on this layer. Set this to MultiPolygon. As opposed to Polygon, MultiPolygon plays nice with enclaves and exclaves.
• New field: Each field should correspond to one of the parameters on the right. All fields should be set to Text (string), while fill-opacity, stroke-opacity and stroke-width should be set to Decimal (double). You do not need to define the length of these fields.

You can reuse this GeoPackage to draw multiple region map shapes if you wish. When exporting, select the shapes needed on a single region map, right click on the GeoPackage in the Layers menu, and click Export → Save Features As.... In the prompt that follows, define where to save the file, setting the format to GeoJSON, and using the project's CRS. Also click the "Save only selected features checkbox before exporting. The resulting file, you can upload to Commons.

Some dynamic maps will display some public transport, mostly tramlines and metrolines, and some others display routes. These all utilise {{Mapshapes}}. The template's documentation contains an in-depth tutorial on how to set up these map elements.