mapcomplete/Docs/Making_Your_Own_Theme.md

Making your own theme

In MapComplete, it is relatively simple to make your own theme. This guide will give some information on how you can do this.

Requirements

Before you start, you should have the following qualifications:

• You are a longtime contributor and do know the OpenStreetMap tagging scheme very well.
• You are not afraid of editing a .JSON-file
• You're theme will add well-understood tags (aka: the tags have a wiki page, are not controversial and are objective)
• You are in contact with your local OpenStreetMap community and do know some other members to discuss tagging and to help testing

If you do not have those qualifications, reach out to the MapComplete community channel on Telegram

The custom theme generator

The custom theme generator is a special page of MapComplete, where one can create their own theme. It makes it easier to get started.

However, the custom theme generator is extremely buggy and built before some updates. This means that some features are not available through the custom theme generator. The custom theme generator is good to get the basics of the theme set up, but you will have to edit the raw JSON-file anyway afterwards.

A quick tutorial for the custom theme generator can be found here.

Loading your theme

If you have your .json file, there are three ways to distribute your theme:

• Take the entire JSON-file and base64 encode it. Then open up the url https://mapcomplete.osm.be?userlayout=true#<base64-encoded-json-here>. Yes, this URL will be huge; and updates are difficult to distribute as you have to send a new URL to everyone. This is however excellent to have a 'quick and dirty' test version up and running as these links can be generated from the customThemeGenerator and can be quickly shared with a few other contributors.
• Host the JSON file on a publicly accessible webserver (e.g. github) and open up https://mapcomplete.osm.be?userlayout=<url-to-the-raw.json>
• Ask to have your theme included into the official MapComplete - requirements below

Getting your theme included into the official mapcomplete

Did you make an awesome theme that you want to share with the OpenStreetMap community? Have it included in the main application, which makes it more discoverable.

Your theme has to be:

0. Make sure the theme has an English version. This makes it easier for me to understand what is going on. The more other languages, the better of course!
1. Make sure your theme has good tagging
2. Make sure there are somewhat decent icons. Note that there is no styleguide at the moment though.

The preferred way to add your theme is via a Pull Request. A Pull Request is less work for the maintainer (which makes it really easy and for me to add it) and your name will be included in the git history (so you'll be listed as contributor). If that is not possible, send the .Json-file and assets, e.g. as a zip in an issue, per email, ...

Via a pull request:

1. Fork this repository
2. Go to assets/themes and create a new directory yourtheme
3. Create a new file yourtheme.json, paste the theme configuration in there. You can find your theme configuration in the customThemeBuilder (the tab with the Floppy disk icon)
4. Copy all the images into this new directory: external assets can suddenly break and leak privacy
   • Make sure the license is suitable, preferable a Creative Commons license. Attribution can be added at the bottom of this document
   • If an SVG version is available, use the SVG version
   • Make sure all the links in yourtheme.json are updated. You can use ./assets/themes/yourtheme/yourimage.svg instead of the HTML link
5. Add your theme to the code base:
   • Open AllKnownLayouts.ts
   • Add an import statement, e.g. import * as yourtheme from "../assets/themes/yourtheme/yourthemes.json";
   • Add your theme to the LayoutsList, by adding a line new LayoutConfig(yourtheme)
6. Test your theme: run the project as described above
7. Happy with your theme? Time to open a Pull Request!
8. Thanks a lot for improving MapComplete!

The .JSON-format

There are three important levels in the .JSON-file:

• The toplevel describes the metadata of the entire theme. It contains the title, description, icon... of the theme. The most important object is layers, which is a list of objects describing layers.
• A layer describes a layer. It contains the name, icon, tags of objects to download from overpass, and especially the icon and a way to ask dynamically render tags and ask questions. A lot of those fields (icon, title, ...) are actually a TagRendering
• A TagRendering is an object describing a relationship between what should be shown on screen and the OSM-tagging. It works in two ways: if the correct tag is known, the appropriate text will be shown. If the tag is missing (and a question is defined), the question will be shown.

Every field is documented in the source code itself - you can find them here:

• The top level LayoutConfig
• A layer object LayerConfig
• The TagRendering
• At last, the exact semantics of tags is documented here

MetaTags

There are few tags available that are calculated for convenience - e.g. the country an object is located at. An overview of all these metatags is available here

Some hints

Everything is HTML

All the texts are actually HTML-snippets, so you can use <b> to add bold, or <img src=...> to add images to mappings or tagrenderings.

Some remarks:

• links are disabled when answering a question (e.g. a link in a mapping) as it should trigger the answer - not trigger to open the link.
• If you include images, e.g. to clarify a type, make sure these are icons or diagrams - not actual pictures! If users see a picture, they think it is a picture of that actual object, not a type to clarify the type. An icon is however perceived as something more abstract.

Some pitfalls

Not publishing

Not publishing because 'it is not good enough'. Share your theme, even if it is still not great, let the community help it improve

Thinking in terms of a question

Making a tagrendering as if it were a question only. If you have a question such as: Does this bench have a backrest?, it is very tempting to have as options yes for backrest=yes and no for backrest=no. However, when this data is known, it will simply show a lone yes or no which is very unclear.

The correct way to handle this is to use This bench does have a backrest and This bench does not have a backrest as answers.

One has to think first in terms of what is shown to the user if it is known, only then in terms of what is the question I want to ask

Forgetting the casual/noob mapper

MapComplete is in the first place a tool to help non-technical people visualize their interest and contribute to it. In order to maximize contribution:

1. Use simple language. Avoid difficult words and explain jargon
2. Put the simple questions first and the difficult ones on the back. The contributor can then stop at a difficult point and go to the next POI
3. Use symbols and images, also in the mappings on questions
4. Make sure the icons (on the map and in the questions) are big enough, clear enough and contrast enough with the background map

Using layers to distinguish on attributes

One layer should portray one kind of physical object, e.g. "benches" or "restaurants". It should contain all of them, disregarding other properties.

One should not make one layer for benches with a backrest and one layer for benches without. This is confusing for users and poses problems: what if the backrest status is unknown? What if it is some weird value? Also, it isn't possible to 'move' an attribute to another layer.

Instead, make one layer for one kind of object and change the icon based on attributes.

Using layers as filters

Using layers as filters - this doesn't work!

All data is downloaded in one go and cached locally first. The layer selection (bottom left of the live app) then selects anything that matches the criteria. This match is then passed of to the rendering layer, which selects the layer independently. This means that a feature can show up, even if it's layer is unselected!

For example, in the cyclofix-theme, there is the layer with bike-wash for do it yourself bikecleaning - points marked with service:bicycle:cleaning. However, a bicycle repair shop can offer this service too!

If all the layers are deselected except the bike wash layer, a shop having this tag will still match and will still show up as shop.

Not reading the .JSON-specs

There are a few advanced features to do fancy stuff available, which are documented only in the spec above - for example, reusing background images and substituting the colours or HTML-rendering. If you need advanced stuff, read it through!