Docs: update 'make your own theme'-page
This commit is contained in:
parent
da68d365fe
commit
550c60ab7f
2 changed files with 6 additions and 230 deletions
|
|
@ -24,6 +24,11 @@ Please, do reach out to the MapComplete community channel
|
||||||
on [Telegram](https://t.me/MapComplete)
|
on [Telegram](https://t.me/MapComplete)
|
||||||
or [Matrix](https://app.element.io/#/room/#MapComplete:matrix.org).
|
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?
|
What is a good theme?
|
||||||
---------------------
|
---------------------
|
||||||
|
|
@ -227,49 +232,7 @@ The entire tagRendering will thus be:
|
||||||
```
|
```
|
||||||
|
|
||||||
|
|
||||||
The template
|
## Make it official
|
||||||
------------
|
|
||||||
|
|
||||||
[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:
|
|
||||||
|
|
||||||
Did you make an awesome theme that you want to share with the OpenStreetMap community? Have it included in the main
|
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:
|
application. This makes sure that:
|
||||||
|
|
|
||||||
|
|
@ -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"
|
|
||||||
]
|
|
||||||
}
|
|
||||||
]
|
|
||||||
}
|
|
||||||
]
|
|
||||||
}
|
|
||||||
]
|
|
||||||
}
|
|
||||||
Loading…
Add table
Add a link
Reference in a new issue