From 52403308518a16822b9d36bcd3ecb237f7281c04 Mon Sep 17 00:00:00 2001 From: Osmo Salomaa Date: Sat, 3 May 2014 15:43:25 +0300 Subject: [PATCH] Write router README file. --- TODO | 2 +- routers/README | 33 ++++++++++++++++++++++++++++++++- 2 files changed, 33 insertions(+), 2 deletions(-) diff --git a/TODO b/TODO index a0d4f02..e962743 100644 --- a/TODO +++ b/TODO @@ -13,7 +13,7 @@ Poor Maps 1.0 * Allow removing places from history (long tap, context menu) * Keep objects (POIs, routes) across sessions? * Add narration of routing manoeuvers - * Add a message box and allow tapping on markers + * Allow tapping on markers * Add a better cover? * Add about page? * Allow landscape for the map page when gestures work right diff --git a/routers/README b/routers/README index 1bbcd3e..0adfad5 100644 --- a/routers/README +++ b/routers/README @@ -1,4 +1,35 @@ Implementing a Router ===================== -TODO (APIs are still in motion.) +To implement a router you need to write a JSON metadata file, a Python +file that implements the 'route' function and one or two QML files. +The route function should given two points return properties of the +found route. The from and to points given as arguments can be either +strings (addresses, landmarks, etc.) or two-element tuples of (x,y) +coordinates. The return value format is up to you, since you handle that +in your router-specific QML. However, a dictionary of route properties +is a good idea, or a list of dictionaries if returning multiple routes. + +Of the two QML files, the settings file ('*_settings.qml') is optional; +it can be used to provide a column of router-specific settings, which +are shown in Poor's routing page below the endpoint selectors. If using +settings, you should use a 'CONF_DEFAULTS' attribute to specify default +values, which are passed to poor.conf and saved across sessions, see +'mapquest_open' for an example. + +The second QML file ('*_results.qml') is mandatory and used to specify a +result page. The routers shipped with Poor provide a minimal page which +shows a busy indicator and handles route display and notification if no +results found. For a minimal router that returns one route, you can copy +and possibly adapt that. If writing a router that returns several routes +that the user can choose from and/or allows a closer examination of the +route properties before showing it on a map, you can use this page to +display whatever is best suitable given your router and domain. For +example, a public transportation router could show departure times, +vehicle icons, platform numbers, etc. + +To download data you should always use 'poor.util.request_url' in order +to use Poor's user-agent and the default timeout from poor.conf. If your +routing provider cannot handle addresses, but requires coordinates, +consider geocoding using 'mapquest_nominatim', which is shipped with +Poor. See 'mapquest_open' and 'osrm' for examples.