The GMap API is a simple way to create Google Maps from a macro or PHP code. It allows other modules to integrate Google Maps into their Drupal site. Among other things, the GMap API can be used by theme developers to integrate Google maps into portions of their theme, or by developers to insert a map into any block of PHP.

CONCEPTS

Baselayer

The actual map (Street map, topological map, satellite imagery, etc.) that everything is being displayed upon. This may also be referred to as the "map type".

GMap macro

A GMap-specific text-based representation of a Google Map.

Overlay

A transparent layer drawn on top of the baselayer.

PROGRAMMING API

Macros

Each attribute of a macro is separated by a "|" and uses an "=" to define that attribute. Possible attributes are center, width, height, zoom, type, control, align, id, markers, feed, line, circle, polygon, and rpolygon.

**See the MACRO-DICTIONARY.txt for an explaination of each of these attributes.

You can convert a macro into a GMap array with the function gmap_parse_macro(). If you need to parse a macro generated with an old version of GMap where the point format was longitude, latitude, set $version to 1: gmap_parse_macro($my_macro, 1); otherwise, you may omit it.

/**
 * function gmap_parse_macro()
 * Convert a macro string into a GMap array.
 *
 * @param $macro_text
 *   Macro to process.
 * @param $version
 *   Version to treat macro as.
 *   Set to 1 when processing very old macros, otherwise leave as is.
 * @return
 *   A GMap array.
 */

  // usage
  $macro_text = "[gmap zoom=7 |center=41.9023,-87.5391 |width=600px |height=400px |control=Small |type=Map]";
  $map_array = gmap_parse_macro($macro_text);

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. The map array is processed and converted to a javascript object. Shapes are parsed by gmap_shapes.js and loaded by shapeloader_static.js.

Using the GMap Array

Once you build a GMap array, you can render it as a map using a theme function provided by GMap. Anything left out of your GMap array will be filled in with the default map settings, which can be changed on the GMap settings page.

**See GMAP-ARRAY-DICTIONARY.txt for explainations of each of the GMap array options.

  // a simple GMap array
  $map_array1 = array(
    'id' => "my-map",         // id attribute for the map
    'width' => "100%",        // map width in pixels or %
    'height' => "400px",      // map height in pixels
    'latitude' => 41.9023,    // map center latitude
    'longitude' => -87.5391,  // map center longitude
    'zoom' => 7,              // zoom level
    'maptype' => "Map",       // baselayer type
    'controltype' => "Small"  // size of map controls
  );
  $element1 = array(
    '#type' => 'gmap',
    '#gmap_settings' => $map_array1,
  );
  $output1 = drupal_render($element1);

  // a more elaborate example
  $map_array2 = array(
    'id' => 'example',
    'maptype' => 'Terrain',
    'width' => '400px',
    'height' => '400px',
    'latitude' => 12.345,
    'longitude' => 12.345,
    'zoom' => 4,
    'align' => 'left',
    'controltype' => 'Small',
    'mtc' => 'standard',

    'behavior' => array(
      'locpick' => FALSE,
      'nodrag' => FALSE,
      'nokeyboard' => TRUE,
      'overview' => TRUE,
      'scale' => TRUE,
    ),

    'markers' => array(
      array(
        'text' => 'First Marker',
        'longitude' => 39.3739522204,
        'latitude' => -81.5681648254,
        'markername' => 'lblue',
      ),
      array(
        'text' => 'Second Marker',
        'longitude' => 44.205835001,
        'latitude' => -70.3674316406,
        'markername' => 'orange',
      ),
    ),

    'shapes' => array(
      array(
        'type' => "polygon",
        'style' => array("000000", 3, 25, "ffff00", 45),
        'points' => array(
          array(43.667871610117494,-70.675048828125),
          array(43.43696596521823,-70.0927734375),
          array(43.9058083561574,-69.202880859375),
          array(44.512176171071054,-69.796142578125),
          array(43.667871610117494,-70.675048828125),
        ),
      ),
      array(
        'type' => "circle",
        'style' => array("000000", 3, 25, "ffff00", 45),
        'radius' => 0.7622248729082767,
        'center' => array(39.3739522204, -81.5681648254),
      ),
    ),

    'feeds' => array(
      array(
        'url' => 'http://earthquake.usgs.gov/eqcenter/catalogs/eqs7day-M5.xml',
        'markername' => 'red',
      ),
    ),
  );
  $element2 = array(
    '#type' => 'gmap',
    '#gmap_settings' => $map_array2,
  );
  $output2 = drupal_render($element2);