README

1. software
2. ikiwiki-osm

Installing

Copy the osm.pm script in your Plugin directory, see http://ikiwiki.info/plugins/install/ for more information.

You will need the XML::Writer perl module to write KML files, which is the default mode of operation. GeoJSON files can also be generated if the JSON perl module is installed.

Configuring

Here are the configuration options you can put in your setup file:

# the default zoon when you click on the map link
osm_default_zoom: 15
# the icon showed on links
osm_default_icon: img/osm.png
# the alt tag of links, defaults to empty
osm_alt: 
# tag to icon mapping
osm_tag_icons:
  test: img/test.png
  trailer: img/trailer.png
# the output format for waypoints, can be KML, GeoJSON or CSV (one or many, comma-separated)
osm_format: KML

How to use

[[!osm ]]
[[!waypoint  lat="45°30N" lon="73°40W" name="My city" tag="city"]]

The osm directive will display the actual map, while the waypoint directive adds waypoints to the map. Those two can be put in separate pages.

The above can also be shortened as:

[[!waypoint  lat="45°30N" lon="73°40W" name="My city" tag="city" embed]]

The tag is also taken from the tags elsewhere in the page, so the above is equivalent to:

[[!waypoint  lat="45°30N" lon="73°40W" name="My city" embed]]

The icon is also taken from the tag if attached to the tag page as icon.png (default, modifiable)..

Map display

• map - map to display, defaults to the current page name in fullscreen mode, "map" otherwise
• zoom - the level to zoom to on the OSM map
• loc - lattitude and longitude of the map center
• lat - lattitude
• lon - longitude
• fullscreen - make the map take the whole screen through CSS
• right - float the map right, ignored for fullscreen
• left - float the map left (default unless fullscreen)
• width - width of the map, ignored for fullscreen
• height - height of the map, ignored for fullscreen

Waypoints

Waypoints can be added to any page. By default the waypoint takes the name of the page, which allows you to easily tag pages and make them appear on the central map.

Waypoints, by default, show up as a image (the icon parameter) link to the main map (or the map parameter provided). That markup can be hidden with the hidden parameter.

• name - the name of this point, defaults to the page name must be unique, otherwise later incantation will overwrite previous ones.
• map - the map to add the point to (defaults to "map")
• desc - description to embed in the map
• loc - lattitude and longitude
• lat - lattitude
• lon - longitude
• tag - the type of points, maps to an icon in the osm_types array
• hidden - do not display the link to the map (will not affect embed)
• icon - URL to the icon to show in the link to the map and within the map
• embed - embed the map display alongside the point, in which case the regular arguments to the map display can be used

Links

If two pages with waypoints have a link between them, that link will magically show up on the map. Now how awesome is that?

Todo

• spit the javascript in a .js file, may require:
• integrate in core ikiwiki
• make more options to the osm directive to add OpenLayers controls and styles to the map
• allow links to be explicited in the waypoint
• use dictionnary values from the page instead of parameters, this requires refactoring the markdown parser