midgard/MapComplete
1
0
Fork 0
forked from MapComplete/MapComplete
Code Pull requests Activity

Docs: update 'make your own theme'-page

Browse source
This commit is contained in:
Pieter Vander Vennet 2023-11-29 02:51:25 +01:00
parent da68d365fe
commit 550c60ab7f
2 changed files with 6 additions and 230 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

49
Docs/Making_Your_Own_Theme.md
View file

@ -24,6 +24,11 @@ Please, do reach out to the MapComplete community channel
on [Telegram](https://t.me/MapComplete)
or [Matrix](https://app.element.io/#/room/#MapComplete:matrix.org).
Get started
-----------
You can create your own theme at https://mapcomplete.org/studio
What is a good theme?
---------------------
@ -227,49 +232,7 @@ The entire tagRendering will thus be:
```
The template
------------
[A basic template is available here](https://github.com/pietervdvn/MapComplete/blob/develop/Docs/theme-template.json).
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](https://www.youtube.com/watch?v=nVbFrNVPxPw).
Loading your theme
------------------
If you have your JSON file, there are three ways to distribute your theme:
### a. base64 the JSON file
Take the entire JSON file and [base64](https://www.base64encode.org/) encode it.
Then open up the URL `https://mapcomplete.org?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.
You can use the community maintained [ThemeHelper](https://github.com/tordans/MapComplete-ThemeHelper) to make this process easier. This uses `lzString.compressToBase64` which is the counterpart to how MapComplete decompresses the base64 input.
### b. Host the JSON file
Host the JSON file on a publicly accessible webserver (e.g. GitHub) and open up `https://mapcomplete.org?userlayout=<url-to-the-raw.json>`
_Gotcha:_ Make sure the server that hosts your JSON has liberal caching settings. Otherwise one version of the file might get cached in the users' browser cache for a long time and updates are not destributed for this user.
### c. Make it official
Get your theme included into the official MapComplete:
## Make it official
Did you make an awesome theme that you want to share with the OpenStreetMap community? Have it included in the main
application. This makes sure that:

187
Docs/theme-template.json
View file

@ -1,187 +0,0 @@
{
"#1": "This JSON file is a small template to get you started developing a theme",
"#2": "All lines starting with '#' are comments and can be removed in the theme if you don't need the explanation anymore",
"#3": "Make sure to join our chat channel at https://app.element.io/#/room/#MapComplete:matrix.org for questions, sharing your theme, ...",
"#4": "To actually load your theme: on linux: run a local webserver (e.g. `webfsd`) and go to https://mapcomplete.org/theme?userlayout=http://127.0.0.1:8080/path-to-your-theme.json",
"#5": "If you don't know how to run a webserver: go to https://www.base64encode.org/ , copy paste this entire document in the 'encode' field and encode it;",
"#6": "Then, go to https://mapcomplete.org/theme?userlayout=true#your-base64-encoded-file",
"id": "template",
"credits": "Write your name here (or remove everything)",
"title": {
"en": "Title of your theme",
"#1": "You can add extra languages here (and in all translation blocks), but make sure 'en' is everywhere"
},
"description": {
"en": "The welcome message goes here"
},
"icon": "/path/to/icon.svg OR path to an online svg, such as https://upload.wikimedia.org/wikipedia/commons/9/9f/Missing_Maps_Icon.svg",
"startZoom": 0,
"startLat": 0,
"startLon": 0,
"#7": "For more options and configuration, see the documentation in LayoutConfig.json",
"#8": "`layers` is where most of the content will be. Either reuse an already existing layer by simply calling it's ID or define a whole new layer. An overview of builtin layers is at https://github.com/pietervdvn/MapComplete/blob/develop/Docs/BuiltinLayers.md#normal-layers",
"layers": [
{
"id": "a singular noun describing the feature, in english",
"source": {
"osmTags": {
"#1": "For a description on which tags are possible, see https://github.com/pietervdvn/MapComplete/blob/develop/Docs/Tags_format.md",
"and": [
"key0=value0",
"key1=value1",
{
"or": [
"key2!=value3",
"key3=",
"key4~*",
"key5~some.[regex]*"
]
}
]
}
},
"#4": "Minzoom: only download and show if zoom >= minzoom",
"minzoom": 12,
"name": {
"en": "Name of the layer, as shown in the layer selection"
},
"title": {
"render": {
"en": "Title in a popup when a feature is clicked"
},
"mappings": [
{
"if": "name~*",
"then": {
"#1": "If name is given, use name instead as popup title. Note that the translation here uses '*' instead of 'en', which'll be shown in every language",
"*": "{name}"
}
}
],
"#1": "Note that this is a tagRendering, but doesn't have a question field"
},
"allowMove": true,
"deletion": {
"softDeletionTags": {
"and": [
"razed:tourism=artwork",
"tourism="
]
},
"neededChangesets": 5
},
"#2": "The maprenderings describe how a feature is shown on the map",
"mapRendering": [
{
"#1": "Rendering block of a mapping which is shown for points AND at the center point of a line/area",
"location": [
"point",
"centroid"
],
"icon": "circle:white;URL or path to icon.svg",
"iconSize": "30,30,center",
"#2": "Note: all these values can be tagrenderings too, e.g.:",
"label": {
"render": {
"en": "Item"
},
"mappings": [
{
"if": "name~*",
"then": {
"*": "{name}"
}
}
]
}
},
{
"#1": "Rendering of a line",
"color": "#ff0",
"width": 5
}
],
"#3": "Presets describe which new items can be added on click. Delete this block if adding a new point is not relevant",
"presets": [
{
"title": {
"en": "lowercase item"
},
"tags": [
"somekey=somevalue",
"otherkey=othervalue"
],
"description": "A thorough definition of what the item is, usefull if people add stuff wrongly. This is optional",
"exampleImages": [
"optionally add images here",
"an image.jpg",
"another example image of the feature.jpg"
]
}
],
"#1": "The tagrenderings are everything that must be shown and/or asked. Use a full tag-rendering section OR a single string to call a builtin tagrendering (see https://github.com/pietervdvn/MapComplete/blob/develop/Docs/BuiltinQuestions.md)",
"tagRenderings": [
{
"render": {
"en": "This is a simple tagrendering without a question. It will always show this text as is"
}
},
"images",
"website",
"phone",
"opening_hours",
"email",
"reviews",
{
"render": {
"en": "This is a simple tagrendering without a question. It will always show this text as is"
}
},
{
"render": {
"en": "The value of some_osm_key is {some_osm_key} in this advanced tagrendering"
},
"question": {
"en": "What is XYZ?"
},
"freeform": {
"key": "some_osm_key",
"#1": "Types can be found at https://github.com/pietervdvn/MapComplete/blob/develop/Docs/SpecialInputElements.md",
"type": "nat"
},
"mappings": [
{
"if": "somekey=some_value",
"then": {
"en": "Text on radio button which also is shown if somekey=some_value is present on the object"
},
"#1": "If this option is picked as answer, these tags will be added additionally. However, if 'somekey=some_value' is present, the above rendering will be shown",
"addExtraTags": [
"extrakey=extravalue"
]
}
]
},
{
"mappings": [
{
"if": "somekey=some_value",
"then": {
"en": "Text on radio button which also is shown if somekey=some_value is present on the object"
},
"icon": {
"path": "/path/to/extra-icon.svg OR url",
"class": "medium",
"#1": "An extra icon supporting this option"
},
"#1": "If this option is picked as answer, these tags will be added additionally. However, if 'somekey=some_value' is present, the above rendering will be shown",
"addExtraTags": [
"extrakey=extravalue"
]
}
]
}
]
}
]
}