Notes on Geocoding Plugins

When using the Orbit WebClient using the Javascript API you can make use of a client-side “Geocode Plugin”. These plugins can be used to let the user of a Publication reverse geocode a location.

Geocode plugins are stored here :

/server/program/services/publisher/publication_geocode_plugins

Adding or removing plugins on the Publisher server is as easy as adding or removing files from this folder. Each geocoding plugins is defined by this set of files :

• <plugin-name>.js : The javascript implementation.
• <plugin-name>.png : The icon (must be 32×32 pixels).

When implementing a geocoding plugin, you can expect this object to exist :

• orbit.webclient.GeocodePlugin

Your implementation should provide the following objects :

• Object : orbit.webclient.GeocodePlugin.<plugin-name>
• Function : orbit.webclient.GeocodePlugin.<plugin-name>.geocode()

Signature : geocode(query,handleResult,handleFault).

/**
 * Implements the geocoding request.
 * @param query the user query string.
 * @param handleResult the function to call when geocoding results arrive.
 * @param handleFault the function to call when an error occurs.
 */
orbit.webclient.GeocodePlugins.<plugin-name>.geocode = function(query,handleResult,handleFault) 
{
   // ...
}  	

When a geocoding result is found, the plugin should call handleResult(results) :

• results : An array of result objects.
  Each item in the array should have these properties :
  • coordinate : object with x and y properties defining a coordinate. (x=longitude, y=latitude).
  • crs : the crs code (the epsg code, for example 4326 for Lat/Lon).
  • boundingbox : the bounding box (optional)
    • minx
    • miny
    • maxx
    • maxy

When an error occurs, the plugin should call handleFault(error) :

• error : An object with error details.
  The 'error' object has these properties :
  • code : a code defining the error.
    Possible values :
    • query_limit_reached : the service returned that a limitation of some kind prevents it from returning results.
    • network_error : an error occurred on the network-level.
    • no_permission : the service returned that a permission problem occurred.
    • service_error : an error occurred on the server side.
    • plugin_error : an error occurred on the plugin side.
  • message : a message describing the error in more detail in english.