$Id: API.txt,v 1.6.4.10 2008-06-13 18:14:16 bdragon Exp $

# *GMAP API DOCUMENTATION* #

The GMap API is a simple way to create Google Maps from a macro or PHP code.

**NOTE**: This is a work in progress!

CONCEPTS
--------

* Baselayer

  The actual map (Street map, topological map, satellite imagery, etc.) that everything is being displayed upon.

* Macro

  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.

* Map Type

  See Baselayer.

* Overlay

  A transparent layer drawn on top of the baselayer.

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.

###Macro###

**NOTE**: This section is downright wrong at the moment.

The macro is straight with each variable 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 +
  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).

###GMap Array###

The main map array is quite complex. Most of the features have a macro equivilent,
but some of the more powerful constructs do not.

####Style subsection####

Some places in the array accept a style array. A style array is an array with
3 or 5 elements, used to define fill and stroke parameters.

    <?php
    // A style description.
    $style = array(
      '00dd00', // STROKE COLOR: The hex color of the line or border ('#RRGGBB'), without the leading #.
      5,        // STROKE WEIGHT: The weight of the line or border. Defined as width, in pixels.
      80,       // STROKE OPACITY: The opacity of the line or border. Defined as % out of 100.
      'ff00ff', // FILL COLOR: The hex color of the polygon fill ('#RRGGBB'), without the leading #. (if applicable.)
      60,       // FILL OPACITY: The opacity of the fill. Defined as % out of 100. Use 0 for no fill. (if applicable.)
    );
    ?>

Google Maps does not currently support named colors properly. (@@@ verify this?)

@@@ Describe changes to style array for 5?

####Marker subsection####

####Shape subsection####

Shapes are parsed by gmap_shapes.js and loaded by shapeloader_static.js.

#####Line#####

    <?php
    $shape = array(
      // 'line' will be drawn as a GPolyline.
      'type' => 'line',
      // points is an array of arrays containing [latitude, longitude] pairs.
      // There must be at least two points.
      'points' => array(array(0.000, 0.000), array(0.000, 0.000)),
      // Optional. Will use the 'line_default' style if not defined.
      'style' => $style,
    );
    $map['shapes'][] = $shape;
    ?>

#####Polygon#####

    <?php
    $shape = array(
      // 'polygon' will be drawn as a GPolygon.
      'type' => 'polygon',
      // points is an array of arrays containing [latitude, longitude] pairs.
      // The first and last point should have the same coordinate, and there
      // should be at least three points.
      'points' => array(array(0.000, 0.000), array(0.000, 0.000), array(0.000, 0.000)),
      // Optional. Will use the 'poly_default' style if not defined.
      'style' => $style,
    );
    $map['shapes'][] = $shape;
    ?>

#####Circle#####

Circle is a special case of Polygon, except the points will be calculated
on the fly.

    <?php
    $shape = array(
      // 'circle' will be drawn as a GPolygon.
      'type' => 'circle',
      // Center coordinate of the circle.
      'center' => array(0.000, 0.000),
      // Radius of the circle, specified in kilometers.
      'radius' => 100,
      // Optional. Will use the 'poly_default' style if not defined.
      'style' => $style,
    );
    $map['shapes'][] = $shape;
    ?>

#####RPolygon#####

RPolygon is similar to Circle, except that one of the vertexes will be *point2*.

    <?php
    $shape = array(
      // 'rpolygon' will be drawn as a GPolygon.
      'type' => 'rpolygon',
      // Center coordinate of the regular polygon.
      'center' => array(0.000, 0.000),
      // A point on the rim of the regular polygon.
      'point2' => array(0.000, 0.000),
      // Optional. Will use the 'poly_default' style if not defined.
      'style' => $style,
    );
    $map['shapes'][] = $shape;
    ?>


**NOTE**: This rest of this section is inaccurate.

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

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);

gmap_draw_map($mymap);

GMAP VIEWS API
--------------

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 fields contain 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.

------- STUFF ABOVE THIS POINT HAS NOT BEEN REVIEWED YET!-------
------- PLEASE DO NOT TRUST THIS DOCUMENTATION!----------

(Misc. documentation, up to date from this point down.)

<?php

// A style description.
$style = array(
  '00dd00', // STROKE COLOR: The hex color of the line or border ('#RRGGBB'), without the leading #.
  5,        // STROKE WEIGHT: The weight of the line or border. Defined as width, in pixels.
  80,       // STROKE OPACITY: The opacity of the line or border. Defined as % out of 100.
  'ff00ff', // FILL COLOR: The hex color of the polygon fill ('#RRGGBB'), without the leading #. (if applicable.)
  60,       // FILL OPACITY: The opacity of the fill. Defined as % out of 100. Use 0 for no fill. (if applicable.)
);

// Backwards compatibility note:
// There were originally more style options, but they were for xmaps only, and
// as xmaps is not compatible with google maps anymore, they are now ignored.
//
// '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)


$map = array(
  // The identifier used to tell the map apart from other maps on the page.
  // Any controls that are to be synced with the map use the same map id.
  // Usually required.
  'id' => 'example',

  // Choose the default baselayer.
  // Core options: 'Map', 'Satellite', 'Hybrid', 'Physical'.
  // Additional options are available with gmap_extrabaselayers.module
  // and other addon modules.
  // Legacy names: 'type'.
  'maptype' => 'Terrain',

  // Width of the map as a CSS dimension.
  'width' => '400px',

  // Height of the map as a CSS dimension.
  'height' => '400px',

  // The initial center point of the map.
  'latitude' => 12.345,
  'longitude' => 12.345,

  // The initial zoom of the map.
  'zoom' => 4,

  // Map div alignment.
  // Options: 'left', 'right', 'center'.
  'align' => 'left',

  // Pan/zoom control type.
  // Options: 'None', 'Small', 'Large'.
  // Legacy names: 'control'.
  'controltype' => 'Small',

  // Map Type control. (aka layer selector)
  // Options: 'none', 'standard', 'hier', 'menu'.
  // Replaces and extends the old 'tcontrol' param.
  'mtc' => 'standard',

  // Behavior flags.
  // Flags set to TRUE are forced on.
  // Flags set to FALSE are forced off.
  // Missing flags inherit from the defaults.
  'behavior' => array(
    // Sets the map up for being used to select a coordinate.
    // Use in combination with latitude, longitude, or latlon fields.
    'locpick' => FALSE,

    // Disable dragging. If dragging is disabled, keyboard shortcuts will
    // also be disabled.
    // FALSE: Allow dragging as usual.
    // TRUE: Inhibit dragging.
    // Replaces the old 'drag' param.
    'nodrag' => FALSE,

    // Disable keyboard shortcuts.
    // FALSE: Allow keyboard shortcuts.
    // TRUE: Inhibit keyboard shortcuts.
    'nokeyboard' => TRUE,

    // nomousezoom

    // autozoom

    // dynmarkers

    // Enable overview map control in the bottom right corner.
    'overview' => TRUE,

    // collapsehack

    // Map scale indicator visibility.
    // FALSE: Hide map scale.
    // TRUE: Show map scale.
    // Replaces the old 'scontrol' param.
    'scale' => TRUE,

    // fatmarkers

  ),

  // Static markers.
  // 'markers' is an array of marker arrays.
  // The contents of a marker array are specified seperately below for clarity.
  'markers' => array(),

  // Static shapes.
  // 'shapes' is an array of shape arrays.
  // The contents of a shape array are specified seperately below for clarity.
  'shapes' => array(),

  'feeds' => array(),

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


);

$map['markers'][] = array(


);

$map['feeds'][] = array(
  'url' => 'http://earthquake.usgs.gov/eqcenter/catalogs/eqs7day-M5.xml',
  'markername' => 'red',
);

    // Each marker is
    array(

    ),
    // ...
  ),



$output = theme('gmap', array('#settings' => $map));













HOOK_GMAP
---------

*hook_gmap()* is a general hook for easily extending GMap.

    function hook_gmap($op, &$map)

###$op 'macro'###

Test test test

###$op 'pre_theme_map'###

Test test test

###$op 'macro_multiple'###

Test test test

###$op 'behaviors'###

Test test test

GMAP_VIEWS EXTENSIONS
---------------------

In Views 1.x, you need to use the "argument handling code" box to apply settings to a map view.

You can set a custom macro with $view->gmap_macro.

    $view->gmap_macro = '[gmap |behavior=+autozoom]';

You can set the map object directly with $view->gmap_map.

    $view->gmap_map = $map;

Extensions to core map object:

    $map = array(
      '#settings' => array(
        'behavior' => array(
          // Fatmarkers is used to pass the raw views data in as markers.
          // This is useful if you are doing custom processing on the javascript side.
          'fatmarkers' => FALSE,
        ),
        'gmap_views' => array( // @@@ TODO: Actually *implement* this functionality!
          // Set all markers to the same thing.
          'forcemarkername' => 'drupal',

          // Lookup table for marker names.
          // Use in combination with markername.
          'markername_map' => array(
            'blog' => 'blue',
            'story' => 'green',
            'page' => 'pink',
          ),
          // OR
          //
          'markername_map' => 'my_custom_map_function',

          // Views fields
          // ============

          // The field to use to determine the marker name.
          // Use in combination with markername_map if the field doesn't contain
          // marker names.
          'markername' => 'my_custom_field',

          // The field to use to determine the marker offset.
          // If not set, it will be automatically tracked.
          'markeroffset' => 'my_custom_field',

          // Latitude and longitude.
          'lat' => 'my_custom_field',
          'lon' => 'my_custom_field',

          'popup_theme' => 'my_custom_popup',
        ),
      ),
    );


(parse macro header, integrate back into docs.)
/**
 *
 * Returns a variable based on .
 *
 * @param $instring
 * A string with the settings of gmap insertion in the format var=setting|var2=setting2
 *  The possible variables are
 *  id - the id of the map every map on a page must have a unique id
 *  width - width of the map
 *  height - height of the map
 *  center - a string of the longitude and latitude 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'
 *  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 +
 *  The following shape types require XMaps:
 *  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
 *
 *  Each of the shapes types can optionally have charecteristics of colour,
 *  width, opacity, pattern, text, fill colour, fill opacity.  Pattern, text
 *  and fill are all only used by xmaps.
 *      color - hexadecimal for the colour include the '#'
 *
 *
 * @return
 * A string with the google map ready to be inserted into a node.
 *
 */


@@@ Describe style changes for 1.0 final!

UPDATING OLD MACROS
-------------------

This section still needs written.