Hello! Bdragon here.
Benjamin Melançon suggested using a wiki page to rewrite gmap's API.txt for Drupal 5. I think it's a great idea.
Therefore, I'm asking for assistance with the rewrite. Please help rewrite and expand the document to describe how things actually work in 5, and I'll commit them to CVS.
===============NOTE!!!!=================== This is the 4.7 documentation, and has not been properly updated for 5.0 yet! Most of it is misleading or wrong! If you run into issues, the issue queue or IRC are usually the best places to go for help. ========================================== ------- STUFF BELOW THIS POINT HAS NOT BEEN REVIEWED YET!------- ------- PLEASE DO NOT TRUST THIS DOCUMENTATION!---------- ========================================== GMAP API DOCUMENTATION The GMap API is a simple way to create Google Maps from a macro or PHP code. ========================================== CONCEPTS The gmap API allows other modules to integrate Google Maps into their Drupal site. It can also be used by theme developers to integrate Google maps into portions of their theme. It can also be used to insert a map into any block of php. ========================================== PROGRAMMING API There are two different methods of inserting a Google Map using the gmap API. The first is using a macro as can be built from the macro creator included as part of this module. The second uses the gmap associative array to define the Google Map function. ========================================== I FIRST METHOD: Macro [Please note that there is discussion going on of moving away from filter/macro concept. (see here: http://groups.drupal.org/node/4323)] Macro is basically a short text tag, that you can insert into your node content. When the node is displayed then a Drupal's hook_filter() invokes GMap module and replaces this tag with Google map. There is GMap Macro Builder module in order to build macro tags easily. An example of Macro tag is: [gmap markers=small red::49.468124067331644,0.17578125 |zoom=5 |center=52.10650519075632,-0.8349609375 |width=580px |height=480px |control=Small |type=Map] The syntax of Macro is the following: the variables are separated by a "|" and then uses an "=" to define that variable. Possible parameters are: id - the id for the map. Each map on a page must have a unique id. center - The comma separated latitude and longitude of the centre of the map. width - width of the map height - height of the map zoom - the zoom factor of the google map align - the alignment of the map 'right', 'left' or 'center' control - the control shown on the map 'Large', 'Small', or 'None' type - 'Map', 'Hybrid' or 'Satellite' points/markers - a string of points to mark on the map with + between each point line - the line is defined by a set of points separated by a + track - Draws a line based on the points in the .plt file feed - the RSS feed with geo:lat information to be parsed by js The following shape types require XMaps: (xmaps is not currently functioning) circle - a circle based on a center point and a radius in km separated by a + and optionally can include the number of sizes. rpolygon - a regular polygon is defined by the center point and a point on the permiter separated by a + polygon - a polygon is defined by a set of points For a more detailed explanation on how to make complicated macros see: http://webgeer.com/gmapdemo You can convert a macro into a GMap array with the function gmap_parse_macro($instring,$ver=2) $ver is only required if you need to use a macro generated with an old version of gmap where the format was longitude, latitude (set to 1 in that case). The GMap Array is an associative array with the following definitions: id - the id of the map every map on a page must have a unique id width - width of the map should be either 'px' or '%' height - height of the map latitude - a string of the latitude of the centre of the map longitude - a string of the longitude of the centre of the map zoom - the zoom factor of the google map align - the alignment of the map 'right', 'left' or 'center' control - the control shown on the map 'Large', 'Small', or 'None' tcontrol - whether the type control is on the map or not: 'off' or 'on' scontrol - whether the scale control is on the map or not: 'off' or 'on' ocontrol - the 'width,height' of the overview map control type - 'Map', 'Hybrid' or 'Satellite' drag - 'yes' or 'no' map is draggable. Default is 'yes' markers - an array of marker arrays. Each marker array is an associative array with the following elements: 'latitude' - the latitude of the marker 'longitude' - the longitude of the marker 'markername' - the marker icon to use. For example if it is set to 'number', then the icons in the marker directory named 'number1.png', 'number2.png' etc. will be used. If these don't exist 'number.png' would be used. If that doesn't exist then the default marker will be used. (optional) 'text' - html text to be located in a pop-up window when you click on the marker. (@@@ Describe array tabs trick... --Bdragon) shapes - an array of shape arrays. Each shape array can have the following elements: 'type' - 'line', 'circle', 'rpolygon', or 'polygon' 'color' - the hex for the color to create the line (eg. '#00dd00') 'width' - the width of the line in px 'opacity' - between 0 and 1 for the opacity of the line 'pattern' - a broken line definition '20 5 10 5' would mean 20 px long line, 5x break, 10px line 5px break 20px line ... (xmaps objects only) 'text' - the text used in the line (xmaps only) 'fillcolor' - the fill color for filled objects (xmaps objects only) 'fillopacity' - the opacity of the filled objects (xmaps object only) tracks - an array of track arrays. Each track array can have the following elements: 'filename' - a filename for the track (.plt) file. Should be relative to the drupal base url. 'type', 'color', etc... same as the shape line. feeds - an array of feed arrays. Each feed array can have the following elements: 'url' - the url of the feed. 'markername' - the marker icon to use. same as for markers except that numbered markers are not supported. wmss - an array of WMS services arrays. Each WMS service array can have the following elements: 'name' - the name of the custom map (no spaces or special chars). 'url' - the url of the WMS service. 'format' - image format to retrieve. Depends of WMS service: 'image/gif','image/png','image/jpeg' 'layers' - a comma separated list of layers advertized by WMS service to show in this custom map. 'minresolution' - lowest zoom level of this custom map. 'maxresolution' - highest zoom level of this custom map. 'copyrights' - an array of copyrights to display. Each copyright array can have the following elements: 'minzoom' - lowest zoom level at which this information applies. 'bounds' - a comma separated list of coordinates defining a region to which this copyright information applies: 'S,W,N,E' 'text' - text of the copyright message. 'overlaywith' - (optional) overlay WMS layers with this Google layers: 'Map', 'Hybrid', 'Satellite' or 'None'(default) 'merczoomlevel' - (optional) zoom factor of the google map where WMS service should advertize layers in Transverse Mercator projection instead of WGS84 projection. See discussion of this topic here: http://johndeck.blogspot.com/#112679047816546118 'opacity' - (optional) Opacity level for this tile from 0.0 (transparent) to 1.0 (opaque) Note: * use the array you would have in previous versions of GMap passed to gmap_draw_map() as the value to the #settings key above, instead of calling gmap_parse_macro(). ========================================== II SECOND METHOD: gmap_simple_map function ---------------------- 1. Using gmap_simple_map to insert a map into a theme, the simple way: gmap_simple_map($latitude, $longitude, $markername = '', $info = '', $zoom = 'auto', $width = 'default', $height = 'default', $autoshow = FALSE, $map = array()) With variables as defined here: * * @param $latitude * Latitude of marker. * * @param $longitude * Longitude of marker. * * @param $markername * Marker to use. * '' will fall back to google's default marker. * * @param $info * What to show in the bubble when the marker is clicked. * Leave blank if you don't want a bubble. * * @param $zoom * Map zoom. * 'default' will use the default zoom from the settings page. * 3 is usually a good value to use. * * @param $width * Map width. * 'default' will use the default width from the settings page. * * @param $height * Map height. * 'default' will use the default height from the settings page. * * @param $autoshow * If set to TRUE, automatically show the marker bubble. * * @param $map * Override parts of the GMap array. * If you need to do much with this, you should probabaly be putting together * the map array manually. * * @return * A themed HTTP string with the google map code to be inserted onto the page. * ---------------------- 2. Insert a map into a theme, the complex way:========================================== GMAP HOOKS & FUNCTIONS There is one hook (hook_gmap) and some useful functions provided by gmap.module API: ---------------------- hook_gmap($op, $map=null); * * This is implementation of hook_gmap(). * * $op can be: * * 'behaviours' -- use this hook, if you need to affect the default behavior of the map. * * 'pre_theme_map' -- use this hook, if you need to load your own custom js. * * 'macro_multiple' -- use this hook, if your custom module needs to add/affect list of * elements that can appear multiple times in the map. * In default the hook_gmap('macro_multiple') returns array: * array('points', 'markers', 'feed', 'circle', 'rpolygon', 'polygon', 'line') * * 'macro' -- By default the hook returns array ( * points => array('multiple' => TRUE), * 'markers' => array('multiple' => TRUE), * 'feed' => array('multiple' => TRUE) * This method however is not used in current code, so probably you don't need this operation. * * 'parse_macro'. -- use this hook, if your custom module needs to add extra keys into * GMap array. They will be added as [key] => [value] ---------------------- gmap_set_location($map, &$form, $fields); * * Creates a map that can be interactively used to fill a form with a * location (latitude, longitude and zoom level) * * @param $map * Either a macro to use as the base map for setting a location, or an * already set map associative array. * * @param $form * A formset associative array. Cannot be more than one deep. * * @param $fields * An associative array for the field names. 'latitude', 'longitude'=>name of * respective array, 'address' is optional. * * @return * A string with the google map code to be inserted onto the page. * ---------------------- gmap_geocode($address, $tld = 'com'); * * Utility function to use the google maps geocoder server side. * This is an easy, quick way to geocode a single address. * Note: This is a REMOTE CALL TO GOOGLE. Do NOT use this where performance matters, * as it could possibly take several seconds for this function to return. * See http://www.google.com/apis/maps/documentation/reference.html#GGeoStatusCode * for a description of the possible status codes. * * @param $address * A string of address to be geocoded * * @param $tld * A string of domain naim ($tdl = 'com' yields into HTTP request of com domain: * 'http://maps.google.com' * * @return; * An array on geocoding results in the form of array('status', 'accuracy', 'latitude', 'longitude'). * On server error an array of 'status' => 500 is returned ---------------------- gmap_simple_map($latitude, $longitude, $markername = '', $info = '', $zoom = 'auto', $width = 'default', $height = 'default', $autoshow = FALSE, $map = array()); * * Simple way to draw a map from inside a theme. * * @param $latitude * Latitude of marker. * * @param $longitude * Longitude of marker. * * @param $markername * Marker to use. * '' will fall back to google's default marker. * * @param $info * What to show in the bubble when the marker is clicked. * Leave blank if you don't want a bubble. * * @param $zoom * Map zoom. * 'default' will use the default zoom from the settings page. * 3 is usually a good value to use. * * @param $width * Map width. * 'default' will use the default width from the settings page. * * @param $height * Map height. * 'default' will use the default height from the settings page. * * @param $autoshow * If set to TRUE, automatically show the marker bubble. * * @param $map * Override parts of the map array. * If you need to do much with this, you should probabaly be putting together * the map array manually. * * @return * A themed HTTP string with the google map code to be inserted onto the page. * ========================================== GMAP VIEWS API ---------------------- 1. Using views to provide additional overlay data to the produced map The gmap_views module also provides a small API for providing additional overlay data to the produced map. By defining: function hook_gmap_views_handle_field($phases, $data) You can tell gmap which column contains the geographic information it needs to plot the nodes on the map. There are two phases to the hook, 'discovery' and 'process'. During the discovery phase, your hook will be called once for each field in the view. If your module can transform this field into latitude and longitude coordinates, you should return a value. This value will be store and returned to you during the 'process' phase. This can be use- ful in caching information, such has how to process the data, etc. If your module cannot process this field, return NULL (the norm in most cases). In the 'process' phase, the $data arugment will contain two keys: - 'module' => this will hold the name of the field, the module that is being invoked (your module) and an 'extra' field, containing whatever you returned during the 'discovery' phase. - 'entry' => the views "entry" containing all the fields returned from the database/ From this data you should return an array with keys "lat" and "lon". Gmap_views will use this array to plot the node on the map. ---------------------- 2. Providing arguments to a GMap view Do not select an argument, instead expand the Advanced PHP Options textarea. Arguments can be provided in the form: $view->gmap_macro = '[gmap | center=30,10 | zoom=4]'; ben-agaric note: below example should use a more common module (i.e. not mine). For example, to retrieve information from a place-aware term on place panels: if (arg(0) == 'place' && is_numeric(arg(1))) { $place_term = taxonomy_location_get(arg(1)); $view->gmap_macro = '[gmap |center=' . $place_term['latitude'] . ',' . $place_term['longitude'] . ']'; return $view; }<?php
echo theme('gmap', array('#settings' => gmap_parse_macro('[gmap |id=map1 |width=120px .... ]')));
?>The gmap marker is converted to the javascript to display the map using the function gmap_draw_map($gmap, $javascript=''), where $gmap is a map variable and javascript is some javascript to be run when the map is loaded. Note that the string '{mapid}' in the javascript will be replaced with the mapid of the map being drawn. It should be noted that the default map settings provided on the admin/settings/gmap page will be used for any value that is not provided. An example of the gmap_draw_map function being used. $myshapes=array(array('color' => '#00dd00', 'type'=>'line', 'opacity' => '0.5', 'points' => array( array('latitude'=>'49.19011831503412','longitude'=>'-123.20737838745117'), array('latitude'=>'49.18506953036687','longitude'=>'-123.16274642944336'))), array('color' => '#00dd00', 'opacity' => '0.5', 'type'=>'line', 'points' => array(array('latitude'=>'49.20526157803394','longitude'=>'-123.19965362548828'), array('latitude'=>'49.20077516864678','longitude'=>'-123.16102981567383')))); $mymarkers=array(array('markername'=>'blue', 'label' => 'Terminal bus stop', 'latitude' =>'49.19236205396474', 'longitude'=>'-123.1790542602539'), array('markername'=>'green', 'label' => 'Service buildings bus stop', 'latitude' =>'49.19224986943509', 'longitude'=>'-123.1538200378418'), array('markername'=>'green', 'label' => 'Transer to Vancouver bus', 'latitude' =>'49.191801128772326', 'longitude'=>'-123.14231872558594')); $mymap=array('id' => 'mymap', 'latitude' => '49.19258642226091', 'longitude'=>' -123.17647933959961', 'zoom' => 13, 'width' => '100%', 'height' => '400px', 'type' => 'Satellite', 'shapes' => $shapes, 'markers' => $mymarkers); theme('gmap', array('#settings' => $mymap));
BDragon must have misunderstood– I'm an idea person ;-) - it's the Agaric way
To get this started here's the consolidated issues relating to this documentation. As each one is sucked dry of its knowledge, let's marke it off with the del tag.
API.txt:
theme('gmap, $map); example needs updating.
Update references to gmap_draw_map() which was removed.
(inline docs in issue?) Document marker keys.
README.txt:
(General request for updated docs)