.. contents:: Contents
.. section-numbering::

.. _`HordeMap`: https://wiki.horde.org/HordeMap?referrer=HordeMap

==========
 `HordeMap`_
==========

Provides a javascript api for interacting with ajax "slippy" maps.

.. _`HordeMap`: https://wiki.horde.org/HordeMap?referrer=HordeMap

------
 Bugs
------

--------
 People
--------

`Michael Rubinsky`_

.. _`Michael Rubinsky`: https://wiki.horde.org/MichaelRubinsky?referrer=HordeMap

-------------
 Description
-------------

Abstraction for in-line map support. Horde ships with a driver for `OpenLayers`_ which provides support for Google, Yahoo, Bing, and OpenStreetMaps out of the box. Other mapping providers can be added by either adding support to the existing OpenLayers driver or by writing a new custom map driver.

.. _`OpenLayers`: http://openlayers.org

Building OpenLayers for Horde
==============================

Horde come bundled with a custom OpenLayers build. In Horde 4 and Horde 5.0, this is based on OpenLayers 2.11. We perform significant modification to the base OpenLayers code to better fit it into the Horde Framework, and to significantly reduce the size of the resulting file. We build a custom version of the file, and split out other parts of it into our own classes. This takes the size of the file from somewhere around 3MB to slightly less the 1MB uncompressed (around 280k compressed).  This section is meant as an overview of how to build this Horde specific file.

* Download the full OL distribution

* While not necessary, I usually edit the *lib/OpenLayers.js* file before I run the build to remove all code to check if we are in a single file build or not. This is not necessary since we know we are always a single file build, and it shaves a good bit of code off.

* Create a custom build cfg file. The file used to build the current file distributed in Horde is attached.

* Build the file by executing the *build.py* file in the openlayers build directory. Copy the resulting OpenLayers.js file to the hordemap directory.

* Next we deal with the commercial mapping layers. Take the *full* contents of the *OpenLayers/Layer/{mapprovider}.js* files that you want to support, and add append it to the *hordemap/{mapprovider}.js* file, replacing the existing openlayer code already in that file. For example - take the contents of *OpenLayers/Layer/Google.js* and append it to the end of *hordemap/google.js* being sure to replace the exising openlayer code. This is all the code outside of the HordeMap.Google and HordeMap.Geocoder.Google classes.

* Language files. This is probably the section with the most work. Since OpenLayers does not maintain any consistency in the style of locale naming, we have to edit almost every language file. OpenLayers sometimes names locales like EN_US, and sometimes like EN-US and sometimes just like EN. First, copy all the language files (except the en.js file - that should be built in the openlayers.js file) to the *hordemap/lang* directory. They should *all* be named in the de_DE.js format.  Next, you have to open each file and rename the key into the Lang array to match the filename.

* Until OpenLayers 3.0 is released, we need to remove a hack that OpenLayers has in place to allow some of their old example code to function. The following code in Openlayers.js should be removed:

::

 // FIXME: Remove this in 3.0. In 3.0, Event.stop will no longer be provided
 // by OpenLayers.
 if (window.Event) {
     OpenLayers.Util.applyDefaults(window.Event, OpenLayers.Event);
 } else {
     var Event = OpenLayers.Event;
 }

How to use (Horde 4 example).
=============================

::

 <?php
 /**
  * Example script for producing a HordeMap
  *
  * @author Michael J Rubinsky
  */
 
 // Init Horde
 define('HORDE_BASE', '/private/var/www/html/horde');
 require_once HORDE_BASE . '/lib/core.php';
 Horde_Registry::appInit(
     'horde',
      array(
         'authentication' => 'none',
         'session_control' => 'none'));
 
 // Hordemap parameters.
 $params = array(
     // Always "Horde" for horde's map driver.
     'driver' => 'Horde',
     // Provider layers that we want displayed
     'providers' => array('Yahoo', 'Google', 'Public', 'Mytopo'),
     // Geocoder to use.
     'geocoder' => 'Google'
 );
 // JSON encode for output in the javascript
 $providerJson = json_encode($params['providers']);
 
 // Setup translations
 $language = str_replace('_', '-', $GLOBALS['language']);
 $language = $GLOBALS['language'];
 if (!file_exists($GLOBALS['registry']->get('jsfs', 'horde') . '/map/' . $language . '.js')) {
     $language = 'en-US';
 }
 
 // Additional configurations.
 $params['conf'] = array(
     // If using a marker image
     //'markerImage' => (string)Horde_Themes::img('map/marker.png'),
     //'markerBackground' => (string)Horde_Themes::img('map/marker-shadow.png'),
     //'useMarkerLayer' => true,
     // Use this language for translations if available.
     'language' => $language,
 );
 
 // API keys for those layers that require them.
 foreach ($params['providers'] as $layer) {
     switch ($layer) {
     case 'Google':
         // No longer required for v3.
         //$params['conf']['apikeys']['google'] = $GLOBALS['conf']['api']['googlemaps'];
         break;
     case 'Yahoo':
         $params['conf']['apikeys']['yahoo'] = $GLOBALS['conf']['api']['yahoomaps'];
         break;
     case 'Cloudmade':
         $params['conf']['apikeys']['cloudmade'] = $GLOBALS['conf']['api']['cloudmade'];
         break;
     case 'Mytopo':
         $params['conf']['apikeys']['mytopo'] = $GLOBALS['conf']['api']['mytopo'];
         break;
     }
 }
 
 // Geocoding
 if (!empty($params['geocoder'])) {
     switch ($params['geocoder']) {
     case 'Google':
         //$params['conf']['apikeys']['google'] = $GLOBALS['conf']['api']['googlemaps'];
         break;
     case 'Yahoo':
         $params['conf']['apikeys']['yahoo'] = $GLOBALS['conf']['api']['yahoomaps'];
         break;
     case 'Cloudmade':
         $params['conf']['apikeys']['cloudmade'] = $GLOBALS['conf']['api']['cloudmade'];
         break;
     }
 }
 
 // Include the Hordemap bootstrap file, and initialize the Hordemap.
 $params['jsuri'] = $GLOBALS['registry']->get('jsuri', 'horde') . '/map/';
 Horde::addScriptFile('map/map.js', 'horde');
 $js = 'HordeMap.initialize(' . Horde_Serialize::serialize($params, HORDE_SERIALIZE::JSON) . ');';
 Horde::addinlineScript($js);
 
 // Start output
 require HORDE_BASE . '/templates/common-header.inc';
 ?>
 <script type="text/javascript">
 // Basic initialization code to run on dom:loaded to init and display the map
 document.observe("dom:loaded", function() {
     // These are the same as configured above
     var providers = <?php echo $providerJson ?>;//['Google', 'Yahoo', 'Public'];
     layers = [];
     providers.each(function(l) {
        var p = new HordeMap[l]();
        $H(p.getLayers()).values().each(function(e) {layers.push(e);});
     });
     map = new HordeMap.Map['Horde']({
     elt: $('mapdiv'),
         // If delayed is set to true, the map will not display until map.display()
         // is called (see below).
         //delayed:true,
         layers: layers,
         markerDragEnd: function(r) {alert('markerdragend');},
         mapClick: function(r) {alert('mapclick')}
     });
     // Must call map.display() when you want the map to display when the
     // delayed property is set to true.
     //map.display();
 });
 </script>
 <h2>HordeMap Example</h2>
 <div id="mapdiv" style="height:300px;width:700px;"></div>

-----------
 Resources
-----------

http://openlayers.org
http://gis.ibbeck.de/ginfo/apps/OLExamples/Index/index.html

----

Back to the `Project List`_

.. _`Project List`: https://wiki.horde.org/Project?referrer=HordeMap