loviuz/MapComplete
1
0
Fork 0
forked from MapComplete/MapComplete
Code Pull requests Activity
MapComplete/Docs/SpecialRenderings.md

52 KiB
Raw Blame History

Special tag renderings

In a tagrendering, some special values are substituted by an advanced UI-element. This allows advanced features and visualizations to be reused by custom themes or even to query third-party API's.

General usage is {func_name()}, {func_name(arg, someotherarg)} or {func_name(args):cssClasses}. Note that you do not need to use quotes around your arguments, the comma is enough to separate them. This also implies you cannot use a comma in your args

Table of contents

+ [Using expanded syntax](#using-expanded-syntax)
  1. default
  1. favourites
  1. images
  1. notes
  1. reviews
  1. settings
  1. Unclassified elements

Using expanded syntax

Instead of using {"render": {"en": "{some_special_visualisation(some_arg, some other really long message, more args)} , "nl": "{some_special_visualisation(some_arg, een boodschap in een andere taal, more args)}}, one can also write

{
  "render": {
    "special": {
      "type": "some_special_visualisation",
      "argname": "some_arg",
      "message": {
        "en": "some other really long message",
        "nl": "een boodschap in een andere taal"
      },
      "other_arg_name": "more args"
    },
    "before": {
      "en": "Some text to prefix before the special element (e.g. a title)",
      "nl": "Een tekst om voor het element te zetten (bv. een titel)"
    },
    "after": {
      "en": "Some text to put after the element, e.g. a footer"
    }
  }
}

In other words: use { "before": ..., "after": ..., "special": {"type": ..., "argname": ...argvalue...}. The args are in the special block; an argvalue can be a string, a translation or another value. (Refer to class RewriteSpecial in case of problems)

default

These special visualisations are interactive components that most elements get by default. You'll normally won't need them in custom layers

delete_button

Adds a button which allows to delete the object at this location. The config will be read from the layer config

Example usage of delete_button

{delete_button()}

if_nothing_known

Shows a 'nothing is currently known-message if there is at least one unanswered question and no known (answerable) question

name default description
text undefined Text to show
cssClasses undefined Classes to apply onto the text

Example usage of if_nothing_known

{if_nothing_known(,)}

minimap

A small map showing the selected feature.

name default description
zoomlevel 18 The (maximum) zoomlevel: the target zoomlevel after fitting the entire feature. The minimap will fit the entire feature, then zoom out to this zoom level. The higher, the more zoomed in with 1 being the entire world and 19 being really close
idKey id (Matches all resting arguments) This argument should be the key of a property of the feature. The corresponding value is interpreted as either the id or the a list of ID's. The features with these ID's will be shown on this minimap. (Note: if the key is 'id', list interpration is disabled)

Example usage of minimap

{minimap()}, {minimap(17, id, _list_of_embedded_feature_ids_calculated_by_calculated_tag):height:10rem; border: 2px solid black}

move_button

Adds a button which allows to move the object to another location. The config will be read from the layer config

Example usage of move_button

{move_button()}

qr_code

Generates a QR-code to share the selected object

Example usage of qr_code

{qr_code()}

share_link

Creates a link that (attempts to) open the native 'share'-screen

name default description
url undefined The url to share (default: current URL)
text undefined The text to show on the button. If none is given, will act as a titleIcon

Example usage of share_link

{share_link()} to share the current page, {share_link(<some_url>)} to share the given url

split_button

Adds a button which allows to split a way

Example usage of split_button

{split_button()}

favourites

Elements relating to marking an object as favourite (giving it a heart). Default element

favourite_icon

A small button that allows a (logged in) contributor to mark a location as a favourite location, sized to fit a title-icon

Example usage of favourite_icon

{favourite_icon()}

favourite_status

A button that allows a (logged in) contributor to mark a location as a favourite location

Example usage of favourite_status

{favourite_status()}

images

Elements related to adding or manipulating images. Normally also added by default, but in some cases a tweaked version is needed

image_carousel

Creates an image carousel for the given sources. An attempt will be made to guess what source is used. Supported: Wikidata identifiers, Wikipedia pages, Wikimedia categories, IMGUR (with attribution, direct links)

name default description
image_key image,mapillary,image,wikidata,wikimedia_commons,image,panoramax,image The keys given to the images, e.g. if image is given, the first picture URL will be added as image, the second as image:0, the third as image:1, etc... Multiple values are allowed if ';'-separated

Example usage of image_carousel

{image_carousel(image,mapillary,image,wikidata,wikimedia_commons,image,panoramax,image)}

image_upload

Creates a button where a user can upload an image to IMGUR

name default description
image-key undefined Image tag to add the URL to (or image-tag:0, image-tag:1 when multiple images are added)
label undefined The text to show on the button
disable_blur undefined If set to 'true' or 'yes', then face blurring will be disabled. To be used sparingly

Example usage of image_upload

{image_upload(,,)}

notes

Elements relating to OpenStreetMap-notes, e.g. the component to close and/or add a comment

add_image_to_note

Adds an image to a node

name default description
Id-key id The property name where the ID of the note to close can be found

Example usage of add_image_to_note

{add_image_to_note(id)}

open_note

Creates a new map note on the given location. This options is placed in the 'last_click'-popup automatically if the 'notes'-layer is enabled

Example usage of open_note

{open_note()}

reviews

Elements relating to seeing and adding ratings and reviews with Mangrove.reviews

create_review

Invites the contributor to leave a review. Somewhat small UI-element until interacted

name default description
subjectKey name The key to use to determine the subject. If specified, the subject will be tags[subjectKey]
fallback undefined The identifier to use, if tags[subjectKey] as specified above is not available. This is effectively a fallback value
question undefined The question to ask during the review

Example usage of create_review

{create_review(name,,)}

list_reviews

Adds an overview of the mangrove-reviews of this object. Mangrove.Reviews needs - in order to identify the reviewed object - a coordinate and a name. By default, the name of the object is given, but this can be overwritten

name default description
subjectKey name The key to use to determine the subject. If specified, the subject will be tags[subjectKey]
fallback undefined The identifier to use, if tags[subjectKey] as specified above is not available. This is effectively a fallback value

Example usage of list_reviews

{list_reviews(name,)}

rating

Shows stars which represent the average rating on mangrove.

name default description
subjectKey name The key to use to determine the subject. If the value is specified, the subject will be tags[subjectKey] and will use this to filter the reviews.
fallback undefined The identifier to use, if tags[subjectKey] as specified above is not available. This is effectively a fallback value

Example usage of rating

{rating(name,)}

reviews

A pragmatic combination of create_review and list_reviews

name default description
subjectKey name The key to use to determine the subject. If specified, the subject will be tags[subjectKey]
fallback undefined The identifier to use, if tags[subjectKey] as specified above is not available. This is effectively a fallback value
question undefined The question to ask in the review form. Optional

Example usage of reviews

{reviews()} for a vanilla review, {reviews(name, play_forest)} to review a play forest. If a name is known, the name will be used as identifier, otherwise 'play_forest' is used

settings

Elements part of the usersettings-ui

clear_caches

A button which clears the locally downloaded data and the service worker. Login status etc will be kept

name default description
text undefined The text to show on the button

Example usage of clear_caches

{clear_caches()}

disabled_questions

Shows which questions are disabled for every layer. Used in 'settings'

Example usage of disabled_questions

{disabled_questions()}

gps_all_tags

Shows the current tags of the GPS-representing object, used for debugging

Example usage of gps_all_tags

{gps_all_tags()}

gyroscope_all_tags

Shows the current tags of the GPS-representing object, used for debugging

Example usage of gyroscope_all_tags

{gyroscope_all_tags()}

import_mangrove_key

Only makes sense in the usersettings. Allows to import a mangrove public key and to use this to make reviews

name default description
text undefined The text that is shown on the button

Example usage of import_mangrove_key

{import_mangrove_key()}

login_button

Show a login button

Example usage of login_button

{login_button()}

logout

Shows a button where the user can log out

Example usage of logout

{logout()}

Unclassified elements

Various elements

add_new_point

An element which allows to add a new point on the 'last_click'-location. Only makes sense in the layer last_click

Example usage of add_new_point

{add_new_point()}

add_note_comment

A textfield to add a comment to a node (with the option to close the note).

name default description
Id-key id The property name where the ID of the note to close can be found

Example usage of add_note_comment

{add_note_comment(id)}

all_tags

Prints all key-value pairs of the object - used for debugging

Example usage of all_tags

{all_tags()}

auto_apply

    A button to run many actions for many features at once.
    To effectively use this button, you'll need some ingredients:

    1. A target layer with features for which an action is defined in a tag rendering. The following special visualisations support an autoAction: tag_apply, import_way_button, conflate_button
    2. A host feature to place the auto-action on. This can be a big outline (such as a city). Another good option for this is the layer [current_view](./BuiltinLayers.md#current_view)
    3. Then, use a calculated tag on the host feature to determine the overlapping object ids
    4. At last, add this component
name default description
target_layer undefined The layer that the target features will reside in
target_feature_ids undefined The key, of which the value contains a list of ids
tag_rendering_id undefined The ID of the tagRendering containing the autoAction. This tagrendering will be calculated. The embedded actions will be executed
text undefined The text to show on the button
icon ./assets/svg/robot.svg The icon to show on the button

Example usage of auto_apply

{auto_apply(,,,,./assets/svg/robot.svg)}

braced

Show a literal text within braces

name default description
text undefined The value to show

Example usage of braced

{braced()}

canonical

Converts a short, canonical value into the long, translated text including the unit. This only works if a unit is defined for the corresponding value. The unit specification will be included in the text.

name default description
key undefined The key of the tag to give the canonical text for

Example usage of canonical

If the object has length=42, then {canonical(length)} will be shown as 42 meter (in english), 42 metre (in french), ...

clear_location_history

A button to remove the travelled track information from the device

Example usage of clear_location_history

{clear_location_history()}

close_note

Button to close a note. A predefined text can be defined to close the note with. If the note is already closed, will show a small text.

name default description
text undefined Text to show on this button
icon checkmark.svg Icon to show
idkey id The property name where the ID of the note to close can be found
comment undefined Text to add onto the note when closing
minZoom undefined If set, only show the closenote button if zoomed in enough
zoomButton undefined Text to show if not zoomed in enough

Example usage of close_note

{close_note(,checkmark.svg,id,,,)}

compare_data

Gives an interactive element which shows a tag comparison between the OSM-object and the upstream object. This allows to copy some or all tags into OSM

name default description
url undefined The attribute containing the url where to fetch more data
host undefined The domain name(s) where data might be fetched from - this is needed to set the CSP. A domain must include 'https', e.g. 'https://example.com'. For multiple domains, separate them with ';'. If you don't know the possible domains, use '*'.
readonly undefined If 'yes', will not show 'apply'-buttons

Example usage of compare_data

{compare_data(,,)}

conflate_button

This button will modify the geometry of an existing OSM way to match the specified geometry. This can conflate OSM-ways with LineStrings and Polygons (only simple polygons with one single ring). An attempt is made to move points with special values to a decent new location (e.g. entrances)

Note that the contributor must zoom to at least zoomlevel 18 to be able to use this functionality. It is only functional in official themes, but can be tested in unoffical themes.

Specifying which tags to copy or add

The argument `tags` of the import button takes a `;`-seperated list of tags to add (or the name of a property which contains a JSON-list of properties).

These can either be a tag to add, such as amenity=fast_food or can use a substitution, e.g. addr:housenumber=$number. This new point will then have the tags amenity=fast_food and addr:housenumber with the value that was saved in number in the original feature.

If a value to substitute is undefined, empty string will be used instead.

This supports multiple values, e.g. ref=$source:geometry:type/$source:geometry:ref

Remark that the syntax is slightly different then expected; it uses '$' to note a value to copy, followed by a name (matched with [a-zA-Z0-9_:]*). Sadly, delimiting with {} as these already mark the boundaries of the special rendering...

Note that these values can be prepare with javascript in the theme by using a calculatedTag

Importing a dataset into OpenStreetMap: requirements

If you want to import a dataset, make sure that:

  1. The dataset to import has a suitable license
  2. The community has been informed of the import
  3. All other requirements of the import guidelines have been followed

There are also some technicalities in your theme to keep in mind:

  1. The new feature will be added and will flow through the program as any other new point as if it came from OSM. This means that there should be a layer which will match the new tags and which will display it.
  2. The original feature from your geojson layer will gain the tag '_imported=yes'. This should be used to change the appearance or even to hide it (eg by changing the icon size to zero)
  3. There should be a way for the theme to detect previously imported points, even after reloading. A reference number to the original dataset is an excellent way to do this
  4. When importing ways, the theme creator is also responsible of avoiding overlapping ways.

Disabled in unofficial themes

The import button can be tested in an unofficial theme by adding test=true or backend=osm-test as URL-paramter. The import button will show up then. If in testmode, you can read the changeset-XML directly in the web console. In the case that MapComplete is pointed to the testing grounds, the edit will be made on https://master.apis.dev.openstreetmap.org

name default description
targetLayer undefined The id of the layer where this point should end up. This is not very strict, it will simply result in checking that this layer is shown preventing possible duplicate elements
tags undefined The tags to add onto the new object - see specification above. If this is a key (a single word occuring in the properties of the object), the corresponding value is taken and expanded instead
text Import this data into OpenStreetMap The text to show on the button
icon ./assets/svg/addSmall.svg A nice icon to show in the button
way_to_conflate undefined The key, of which the corresponding value is the id of the OSM-way that must be conflated; typically a calculatedTag

Example usage of conflate_button

{conflate_button(,,Import this data into OpenStreetMap,./assets/svg/addSmall.svg,)}

direction_absolute

Converts compass degrees (with 0° being north, 90° being east, ...) into a human readable, translated direction such as 'north', 'northeast'

name default description
key _direction:centerpoint The attribute containing the degrees

Example usage of direction_absolute

{direction_absolute(_direction:centerpoint)}

direction_indicator

Gives a distance indicator and a compass pointing towards the location from your GPS-location. If clicked, centers the map on the object

Example usage of direction_indicator

{direction_indicator()}

export_as_geojson

Exports the selected feature as GeoJson-file

Example usage of export_as_geojson

{export_as_geojson()}

export_as_gpx

Exports the selected feature as GPX-file

Example usage of export_as_gpx

{export_as_gpx()}

fediverse_link

Converts a fediverse username or link into a clickable link

name default description
key undefined The attribute-name containing the link

Example usage of fediverse_link

{fediverse_link()}

group

A collapsable group (accordion)

name default description
header undefined The identifier of a single tagRendering. This will be used as header
labels undefined A ;-separated list of either identifiers or label names. All tagRenderings matching this value will be shown in the accordion

Example usage of group

{group(,)}

histogram

Create a histogram for a list of given values, read from the properties.

name default description
key undefined The key to be read and to generate a histogram from
title empty string This text will be placed above the texts (in the first column of the visulasition)
countHeader empty string This text will be placed above the bars
colors* undefined (Matches all resting arguments - optional) Matches a regex onto a color value, e.g. 3[a-zA-Z+-]*:#33cc33

Example usage of histogram

{histogram('some_key')} with properties being `{some_key: ["a","b","a","c"]} to create a histogram

import_button

This button will copy the point from an external dataset into OpenStreetMap

Note that the contributor must zoom to at least zoomlevel 18 to be able to use this functionality. It is only functional in official themes, but can be tested in unoffical themes.

Specifying which tags to copy or add

The argument `tags` of the import button takes a `;`-seperated list of tags to add (or the name of a property which contains a JSON-list of properties).

These can either be a tag to add, such as amenity=fast_food or can use a substitution, e.g. addr:housenumber=$number. This new point will then have the tags amenity=fast_food and addr:housenumber with the value that was saved in number in the original feature.

If a value to substitute is undefined, empty string will be used instead.

This supports multiple values, e.g. ref=$source:geometry:type/$source:geometry:ref

Remark that the syntax is slightly different then expected; it uses '$' to note a value to copy, followed by a name (matched with [a-zA-Z0-9_:]*). Sadly, delimiting with {} as these already mark the boundaries of the special rendering...

Note that these values can be prepare with javascript in the theme by using a calculatedTag

Importing a dataset into OpenStreetMap: requirements

If you want to import a dataset, make sure that:

  1. The dataset to import has a suitable license
  2. The community has been informed of the import
  3. All other requirements of the import guidelines have been followed

There are also some technicalities in your theme to keep in mind:

  1. The new feature will be added and will flow through the program as any other new point as if it came from OSM. This means that there should be a layer which will match the new tags and which will display it.
  2. The original feature from your geojson layer will gain the tag '_imported=yes'. This should be used to change the appearance or even to hide it (eg by changing the icon size to zero)
  3. There should be a way for the theme to detect previously imported points, even after reloading. A reference number to the original dataset is an excellent way to do this
  4. When importing ways, the theme creator is also responsible of avoiding overlapping ways.

Disabled in unofficial themes

The import button can be tested in an unofficial theme by adding test=true or backend=osm-test as URL-paramter. The import button will show up then. If in testmode, you can read the changeset-XML directly in the web console. In the case that MapComplete is pointed to the testing grounds, the edit will be made on https://master.apis.dev.openstreetmap.org

name default description
targetLayer undefined The id of the layer where this point should end up. This is not very strict, it will simply result in checking that this layer is shown preventing possible duplicate elements
tags undefined The tags to add onto the new object - see specification above. If this is a key (a single word occuring in the properties of the object), the corresponding value is taken and expanded instead
text Import this data into OpenStreetMap The text to show on the button
icon ./assets/svg/addSmall.svg A nice icon to show in the button
snap_onto_layers undefined If a way of the given layer(s) is closeby, will snap the new point onto this way (similar as preset might snap). To show multiple layers to snap onto, use a ;-seperated list
max_snap_distance 5 The maximum distance that the imported point will be moved to snap onto a way in an already existing layer (in meters). This is previewed to the contributor, similar to the 'add new point'-action of MapComplete
note_id undefined If given, this key will be read. The corresponding note on OSM will be closed, stating 'imported'
maproulette_id undefined The property name of the maproulette_id - this is probably mr_taskId. If given, the maproulette challenge will be marked as fixed. Only use this if part of a maproulette-layer.
to_point undefined If set, a feature will be converted to a centerpoint

Example usage of import_button

{import_button(,,Import this data into OpenStreetMap,./assets/svg/addSmall.svg,,5,,,)}

import_way_button

This button will copy the data from an external dataset into OpenStreetMap, copying the geometry and adding it as a 'line'

Note that the contributor must zoom to at least zoomlevel 18 to be able to use this functionality. It is only functional in official themes, but can be tested in unoffical themes.

Specifying which tags to copy or add

The argument `tags` of the import button takes a `;`-seperated list of tags to add (or the name of a property which contains a JSON-list of properties).

These can either be a tag to add, such as amenity=fast_food or can use a substitution, e.g. addr:housenumber=$number. This new point will then have the tags amenity=fast_food and addr:housenumber with the value that was saved in number in the original feature.

If a value to substitute is undefined, empty string will be used instead.

This supports multiple values, e.g. ref=$source:geometry:type/$source:geometry:ref

Remark that the syntax is slightly different then expected; it uses '$' to note a value to copy, followed by a name (matched with [a-zA-Z0-9_:]*). Sadly, delimiting with {} as these already mark the boundaries of the special rendering...

Note that these values can be prepare with javascript in the theme by using a calculatedTag

Importing a dataset into OpenStreetMap: requirements

If you want to import a dataset, make sure that:

  1. The dataset to import has a suitable license
  2. The community has been informed of the import
  3. All other requirements of the import guidelines have been followed

There are also some technicalities in your theme to keep in mind:

  1. The new feature will be added and will flow through the program as any other new point as if it came from OSM. This means that there should be a layer which will match the new tags and which will display it.
  2. The original feature from your geojson layer will gain the tag '_imported=yes'. This should be used to change the appearance or even to hide it (eg by changing the icon size to zero)
  3. There should be a way for the theme to detect previously imported points, even after reloading. A reference number to the original dataset is an excellent way to do this
  4. When importing ways, the theme creator is also responsible of avoiding overlapping ways.

Disabled in unofficial themes

The import button can be tested in an unofficial theme by adding test=true or backend=osm-test as URL-paramter. The import button will show up then. If in testmode, you can read the changeset-XML directly in the web console. In the case that MapComplete is pointed to the testing grounds, the edit will be made on https://master.apis.dev.openstreetmap.org

name default description
targetLayer undefined The id of the layer where this point should end up. This is not very strict, it will simply result in checking that this layer is shown preventing possible duplicate elements
tags undefined The tags to add onto the new object - see specification above. If this is a key (a single word occuring in the properties of the object), the corresponding value is taken and expanded instead
text Import this data into OpenStreetMap The text to show on the button
icon ./assets/svg/addSmall.svg A nice icon to show in the button
snap_to_point_if undefined Points with the given tags will be snapped to or moved
max_snap_distance 0.05 If the imported object is a LineString or (Multi)Polygon, already existing OSM-points will be reused to construct the geometry of the newly imported way
move_osm_point_if undefined Moves the OSM-point to the newly imported point if these conditions are met
max_move_distance 0.05 If an OSM-point is moved, the maximum amount of meters it is moved. Capped on 20m
snap_onto_layers undefined If no existing nearby point exists, but a line of a specified layer is closeby, snap to this layer instead
snap_to_layer_max_distance 0.1 Distance to distort the geometry to snap to this layer

Example usage of import_way_button

{import_way_button(,,Import this data into OpenStreetMap,./assets/svg/addSmall.svg,,0.05,,0.05,,0.1)}

language_chooser

The language element allows to show and pick all known (modern) languages. The key can be set

name default description
key undefined What key to use, e.g. language, tactile_writing:braille:language, ... If a language is supported, the language code will be appended to this key, resulting in language:nl=yes if nl is picked
question undefined What to ask if no questions are known
render_list_item {language()} How a single language will be shown in the list of languages. Use {language} to indicate the language (which it must contain).
render_single_language undefined What will be shown if the feature only supports a single language
render_all {list()} The full rendering. Use {list} to show where the list of languages must come. Optional if mode=single
no_known_languages undefined The text that is shown if no languages are known for this key. If this text is omitted, the languages will be prompted instead

Example usage of language_chooser

{language_chooser(,,{language()},,{list()},)}

language_picker

A component to set the language of the user interface

Example usage of language_picker

{language_picker()}

link

Construct a link. By using the 'special' visualisation notation, translations should be easier

name default description
text undefined Text to be shown
href undefined The URL to link to. Note that this will be URI-encoded before
class undefined CSS-classes to add to the element
download undefined Expects a string which denotes the filename to download the contents of href into. If set, this link will act as a download-button.
arialabel undefined If set, this text will be used as aria-label
icon undefined If set, show this icon next to the link. You might want to combine this with class: button

Example usage of link

{link(,,,,,)}

linked_data_from_website

Attempts to load (via a proxy) the specified website and parsed ld+json from there. Suitable data will be offered to import into OSM

name default description
key website Attempt to load ld+json from the specified URL. This can be in an embedded