====== 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.

===== Add/Remove Plugins =====

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 32x32 pixels).

===== Implementing Plugins =====

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()''

==== geocode() ====

Signature : ''geocode(query,handleResult,handleFault)''.

<code javascript>
/**
 * 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) 
{
   // ...
}  	
</code>

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.