Potlatch 2/Developer Documentation/Map Features
 | Potlach 2 is no longer maintained |
Potlatch 2 has been deprecated and replaced by Potlatch 3.
The tag presets presented in Potlatch 2's 'Simple' view are defined in a file called map_features.xml. This page explains how it works and how you can change it.
About this documentation
This documentation is principally intended for those setting up their own custom instances of Potlatch 2. It is not a guide on how to edit the file used by the Potlatch 2 instance on openstreetmap.org. The UI of the openstreetmap.org instance is rigorously edited by the developers to avoid bloat and cruft, and the subset of tags presented is part of this. Decisions will be made on existing usage, on "fulfilling a need", and on quality. If you are interested in seeing new tags in the P2 instance on osm.org, please talk to the developers via the potlatch-dev mailing list. Thanks.
This documents the file format, not the code that interprets it. For the latter, please see the Potlatch 2 asdocs.
File organisation
Potlatch 2 loads a preset file called map_features.xml.
Other files can be nested in this by use of an <include> tag:
<include file="map_features/barriers.xml" />
(Nested files should also be valid XML, which means they should have a single root element - by convention, <featureGroup/>.)
A future version of Potlatch 2 will enable users to load arbitrary preset files via the UI.
Overview
A feature is the distinct, recognisable type that will be presented to the user as "what this is". For example: trunk road, school, reservoir.
A feature category groups features together. For example: Roads, Paths, Accommodation, Sport and Leisure.
An input is a single editing control for a single tag. For example: a drop-down menu with yes/no options, or a free-text field for a name.
An input set is a group of inputs. It can be reused anywhere in the file, and nested in other input sets. For example: a bridge-type drop-down (bridge tag) and a layer slider (layer tag) could together form one input set.
How they fit together
A basic workflow for creating a tag editor would be:
- Create the feature (e.g. "trunk road")
- Say what category it is (e.g. "roads").
- Say what type of entity it applies to (e.g. lines and areas).
- Add the tags that define this feature (e.g. highway=trunk). When a user clicks on an entity with these tags, this feature will be displayed; conversely, when the user chooses this feature from a menu, these tags will be applied to the entity.
- Add the inputs that the user can edit for this feature (e.g. road name (name tag) and number (ref tag).)
A more complex workflow would involve input sets (e.g. those inputs shared by all road features), and input categories for each input (so that they're grouped together under tabs).
Features
A feature is the distinct, recognisable type that will be presented to the user as "what this is". For example:
<feature name="Service road">
<category>roads</category>
<icon image="features/highway__service.png">${name}</icon>
<help>https://wiki.openstreetmap.org/wiki/Tag:highway%3Dservice</help>
<line/>
<tag k="highway" v="service"/>
<inputSet ref="minorRoad"/>
<input type="choice" presence="always" name="Type of service road" key="service" category="">
<choice value="alley" text="Alleyway/laneway"/>
<choice value="parking_aisle" text="Parking aisle" description="The path that cars drive on through a parking lot."/>
<choice value="driveway" text="Driveway"/>
<choice value="drive-through" text="Drive-through" description="For drive-through restaurants, bottle shops etc."/>
<choice value="emergency_access" text="Emergency access" description="For firefighters and other emergency services."/>
</input>
<inputSet ref="common"/>
</feature>
The line, area, point and relation elements define what entity type this feature can be. For example, a trunk road could be <line/> or <area/> (for roundabouts); a supermarket could be <area/> or <point/>; a football pitch could only be <area/>.
The tag elements define all the tags that identify this feature.
The name attribute defines the name displayed in drop-down menus from which the user can choose.
The category element defines the feature category (see below) in which this feature is be grouped.
The help element defines a URL providing more information about this feature.
The input elements define editing controls available for this feature (see below).
The inputSet elements reference input sets (groups of editing controls) available for this feature. Their ref attribute relates to the id of an inputSet defined elsewhere in the file (see below).
The icon element defines a feature's graphical appearance within the tag panel.
tag element syntax
The tag elements define all the tags that identify this feature. Often this will just be a single tag (for example, highway=trunk) but you may also specify more than one element (e.g. amenity=public_building; building=yes).
For each one, its k attribute defines the key to match, and its v attribute defines the value to match. These tags will be applied to the object when the user chooses this feature from the drop-down menu.
The optional vmatch attribute allows you to specify values which are matched, but not applied. This is useful for compatibility with legacy or minority tagging schemes. The attribute is parsed as a regular expression (the special value "*" means "any value"). For example:
<tag k="route" v="hiking" vmatch="hiking|foot"/>
icon element syntax
The icon element defines a feature's graphical appearance within the tag panel. It is usually found within a <feature/>, but the same format is also used for route relation inputs (see below).
Its image attribute is the URL of an image to be shown when the feature is selected, and when the drop-down menu is open.
Its dnd attribute is the URL of an image to be shown in the drag-and-drop icon panel (default: same as image attribute).
Its background and foreground attributes are the colours in which the HTML fragment will be displayed.
Its content is an HTML fragment displayed next to the image when the feature is selected. Tag values (such as name and ref) may be embedded by using the ${key} syntax.
within element syntax
The within element adds the constraint of what the entity is contained "within". These constraint relationships make sense:
- point within line, area or relation
- line or area within relation
A current example is a turn restriction (other examples are pedestrian crossings, and level crossings):
<feature> <point/> <within entity="way" k="highway" minimum="2"/> <inputSet ref="junctionNode"/> <inputSet ref="common"/> </feature>
- entity
- (required) the kind of thing this thing must be within
- k
- (required) the key of the containing entity
- v
- (optional) the value of the containing entity
- minimum
- (optional) the number of similar containing entities that must be present. In the above example, there must be at least 2 "highway=*" ways containing this node.
- role
- (optional) the role that the containing entity (if a relation) must be.
Feature categories
A feature category groups features together. For example: Roads, Paths, Accommodation, Sport and Leisure. They appear in these categories in the main drop-down feature menu.
You define a feature category like this:
<category name="Roads" id="roads"/>
To assign a feature to that category, use the <category> tag within the <feature> element. For example:
<category>roads</category>
Inputs
An input is a single editing control for a single tag. It is usually an element within a <feature/>. To allow inputs to be shared between features, it can also form part of an <inputSet/> (see below).
The simplest form of input is a freetext input:
<input type="freetext" presence="always" category="Naming" name="Ref" key="ref" description="Reference number of the road"/>
The key attribute defines which OSM key will be edited (for example, "highway").
The name attribute defines a label shown by the control.
The description attribute defines a tooltip shown on mouse-over.
The layout attribute defines whether the control's layout will be 'horizontal' or 'vertical' (default).
The category attribute defines the name of the tab that the input will be shown under.
The subcategory attribute (optional) defines a subgroup under that tab (intended for lesser-used tags).
The presence attribute defines whether this input should be shown on the 'Basic' tab:
- =always - always show
- =onTagMatch - only show if the tag is set
- =withCategory - don't show on the Basic tab
The priority attribute controls ordering within the tab. Inputs with priority='highest' will be shown before ='high', ='normal' (the default), ='low' and ='lowest'.
The type attribute defines what control this is. Available controls are listed below.
type='freetext'
A simple text editor.
The absenceText attribute defines text to be shown if the value is not set.
type='choice'
A drop-down menu. <choice/> elements are used to define the options available (like <option/> in an HTML </select> element). For example:
<input type="choice" presence="always" category="" name="Religion" key="religion" description="The religion worshipped here.">
<choice value="christian" text="Christianity (church)"/>
<choice value="jewish" text="Judaism (synagogue)"/>
<choice value="muslim" text="Islam (mosque)"/>
</input>
You can list a series of synonym values, with a preferred option. For example for the sidewalk tag, you can use both and yes to mean the same thing (however you shouldn't currently need to specify both in the match [1]):
<choice value="both" text="Both" description="There is a sidewalk on both sides of the road." match="both|yes"/>
type='checkbox'
A checkbox used to set the tag value to 'yes' or 'no'. (Values of "1", "0", "true" and "false" are recognised but not set.)
type='slider'
A slider allowing any numeric value to be chosen between two extremes. For example:
<input type="slider" presence="onTagMatch"
name="Layer" category="Physical" description="Relative vertical positions (-5 lowest, +5 highest)"
key="layer" minimum="-5" maximum="5" default="0" snapInterval="1" labels="Lowest,Ground,Highest"
defaultName="Ground"/>
The minimum and maximum attributes define the range of values allowed (default 0,100).
The snapInterval attribute defines the minimum increment between these values (default 1).
The default attribute defines the default numeric value if not set (default 0).
The labels attribute is a comma-separated list of labels to be laid out at equal intervals from minimum to maximum values.
type='number'
A numeric entry textfield with additional "up" and "down" nudge buttons beside it. For example:
<input type="number" minimum="0" maximum="99999" stepSize="1"
presence="always" category="Parking" name="Capacity" key="capacity" description="The number of cars that can be parked in the car park"/>
The minimum and maximum attributes define the range of values allowed by the nudge buttons (default 0, 100).
The stepSize attribute defines the increment of clicking on an up/down nudge button (default 1).
The absenceText attribute defines text to be shown if the value is not set.
The notValidText attribute defines text to be shown if the value is not a number, or outside the minimum/maximum values.
type='speed'
A dedicated speed-limit editor.
type='route'
A dedicated route relation editor, showing route relations of which this entity is a member, and allowing the user to add it to other route relations. For example:
<input type="route" name="National Cycle Routes" description="A signposted route in a National Cycle Network, or nearest equivalent." category="Cycle" priority="low">
<match k="type" v="route"/>
<match k="route" v="bicycle"/>
<match k="network" v="ncn"/>
<icon image="features/route__ncn.png" background="#ff6f7a" foreground="white">${ref} ${name}</icon>
</input>
The match elements define the tags required for a parent relation to match.
The icon element defines the appearance of the control shown for a matching relation (same syntax as an <icon/> within a <feature/>).
type='turn'
A dedicated turn restriction editor, showing turn restrictions of which this entity is a member, and allowing the user to add it to other turn restrictions. For example:
<input type="turn" name="Turn restriction" description="Turn restriction" category="Turn" priority="normal" presence="onTagMatch">
<match k="type" v="restriction"/>
<role role="via"/>
</input>
The match elements define the tags required for a parent relation to match.
The role element defines the member role required for a parent relation to match.
Input sets
An input set is a group of inputs. It can be reused by any feature.
It contains <input/> elements as per above. For example:
<inputSet id="roadRefs"> <input type="freetext" presence="always" name="Reference" category="Naming" priority="high" key="ref" /> <input type="freetext" presence="onTagMatch" name="International Reference" category="Naming" key="int_ref" /> <input type="freetext" presence="onTagMatch" name="Old Reference" category="Naming" priority="low" key="old_ref" /> </inputSet>
An inputSet can also contain other, nested inputSet elements:
<inputSet id="common"> <inputSet ref="source"/> <inputSet ref="designation"/> </inputSet>