diff --git a/Docs/Making_Your_Own_Theme.md b/Docs/Making_Your_Own_Theme.md index 10faf35fc3..6483f49631 100644 --- a/Docs/Making_Your_Own_Theme.md +++ b/Docs/Making_Your_Own_Theme.md @@ -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#`. - -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=` - -_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: diff --git a/Docs/theme-template.json b/Docs/theme-template.json deleted file mode 100644 index aeb6658907..0000000000 --- a/Docs/theme-template.json +++ /dev/null @@ -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" - ] - } - ] - } - ] - } - ] -}