array.html

<!-- $Id$ -->

<p>A GMap array is used to define and render a map inside PHP code. This is useful
for things like creating a map based on a database query, or doing things that you
can't do with a macro.</p>

<p>Defaults for map attributes can be set on the <a href="base_url:admin/settings/gmap">GMap settings page</a>.</p>

<h2>TOP LEVEL ATTRIBUTES</h2>

<p>These are all of the (by default) recognized keys for a map array. You usually will only use a subset of them.</p>
<pre>
  $map = array(
    '<a href="#tl-id"      >id</a>' =>                  // "Map ID" -- used to associate a map with other controls.
    '<a href="#tl-width"   >width</a>' =>               // Map width as a CSS dimension.
    '<a href="#tl-height"  >height</a>' =>              // Map height as a CSS dimension (usually px).
    '<a href="#tl-lat"     >latitude</a>' =>            // Map center latitude.
    '<a href="#tl-lon"     >longitude</a>' =>           // Map center longitude.
    '<a href="#tl-zoom"    >zoom</a>' =>                // Zoom level.
    '<a href="#tl-mz"      >maxzoom</a>' =>             // Maximum zoom level for autozoom.
    '<a href="#tl-extent"  >extent</a> =>               // Map bounds.
    '<a href="#tl-mt"      >maptype</a>' =>             // Initial baselayer type.
    '<a href="#tl-ct"      >controltype</a>' =>         // Size of map controls.
    '<a href="#tl-align"   >align</a>' =>               // CSS alignment for map div.
    '<a href="#tl-mtc"     >mtc</a>' =>                 // Map type control.
    '<a href="#tl-bl"      >baselayers</a>' => array(), // Enabled map baselayers.
    '<a href="#tl-styles"  >styles</a>' => array(),     // Shape style definitions.
    '<a href="#tl-behavior">behavior</a>' => array(),   // Various map behavior flags.
    '<a href="#tl-rmtcb"   >rmtcallback</a>' =>         // Remote callback for ahah info windows.
    '<a href="#tl-iwq"     >iwq</a>' =>                 // Info window DOM query.
    '<a href="#tl-markers" >markers</a>' => array(),    // Array of markers to place on the map.
    '<a href="#tl-shapes"  >shapes</a>' => array(),     // Array of shapes to place on the map.
  );
</pre>

<p>Here is a description of the top level keys of the map array.</p>
<ul>

<li><a name="tl-id">id</a>
<dl>
<dt>Values:</dt>
<dd>Identifier (String)</dd>
<dt>Description:</dt>
<dd>A unique identifier, used to distinguish a map from other maps on the page, and as a key to tie controls to a map.</dd>
<dt>Example:</dt>
<dd>
  "mymap"
</dd>
<dt>Notes:</dt>
<dd>
  Assign this if you are planning on using external controls with a map.
  One will be automatically assigned if you don't specify an id.
</dd>
</dl>
</li>

<li><a name="tl-width">width</a>
<dl>
<dt>Values:</dt>
<dd>CSS Dimension (String)</dd>
<dt>Description:</dt>
<dd>Width of map div, in valid css dimensions (generally pixels or percent).</dd>
<dt>Example:</dt>
<dd>"100%"</dd>
</dl>
</li>

<li><a name="tl-height">height</a>
<dl>
<dt>Values:</dt>
<dd>CSS Dimension (String)</dd>
<dt>Description:</dt>
<dd>Height of map div, in valid css dimensions (generally pixels).</dd>
<dt>Example:</dt>
<dd>"400px"</dd>
<dt>Notes:</dt>
<dd>
  Using a percentage for height will most likely lead to a buggy map. Google's javascript
  must be able to determine the actual height of the map div for proper operation.
</dd>
</dl>
</li>

<li><a name="tl-lat">latitude</a>
<dl>
<dt>Values:</dt>
<dd>Latitude of map center in degrees decimal format. (Float)</dd>
<dt>Description:</dt>
<dd>Map center point latitude, as a signed float.</dd>
<dt>Example:</dt>
<dd>39.36827914916013</dd>
<dt>Notes:</dt>
<dd>
  Cast to float if you are unsure what type your latitude variable is; some parts of
  Google Maps do not operate correctly if latitude is passed as a string.
  See "extent" if you wish to provide a bounding rectangle instead.
</dd>
</dl>
</li>

<li><a name="tl-lon">longitude</a>
<dl>
<dt>Values:</dt>
<dd>Longitude of map center in degrees decimal format. (Float)</dd>
<dt>Description:</dt>
<dd>Map center point longitude, as a signed float.</dd>
<dt>Example:</dt>
<dd>-81.5625</dd>
<dt>Notes:</dt>
<dd>
  Cast to float if you are unsure what type your latitude variable is; some parts of
  Google Maps do not operate correctly if latitude is passed as a string.
  See "extent" if you wish to provide a bounding rectangle instead.
</dd>
</dl>
</li>

<li><a name="tl-zoom">zoom</a>
<dl>
<dt>Values:</dt>
<dd>0-17 (Integer)</dd>
<dt>Description:</dt>
<dd>Initial map zoom level. (This may be modified after map load by the user / autozoom / etc.)</dd>
<dt>Example:</dt>
<dd>7</dd>
<dt>Notes:</dt>
<dd>
  0 is the furthest out zoom level, 17 is the closest up zoom level (but is subject to change.)
  Some areas do not have satellite data all the way to 17, you may want to stay zoomed out a few clicks.
  See "extent" if you wish to provide a bounding rectangle instead.
</dd>
</dl>
</li>

<li><a name="tl-mz">maxzoom</a>
<dl>
<dt>Values:</dt>
<dd>0-17 (Integer)</dd>
<dt>Description:</dt>
<dd>
  Sets the maximum level of zoom the 'autozoom' behavior flag will zoom to.
  Useful to prevent single-marker maps from zooming in too far.
</dd>
<dt>Example:</dt>
<dd>7</dd>
<dt>Notes:</dt>
<dd></dd>
</dl>
</li>

<li><a name="tl-extent">extent</a>
<dl>
<dt>Values:</dt>
<dd>array(array(float, float), array(float, float))</dd>
<dt>Description:</dt>
<dd>
  Initial bounding box for map. The first inner array is the southwest corner,
  the second inner array is the northeast corner.
  All units are degrees decimal.
  Make sure to cast coordinate components to float as needed.
</dd>
<dt>Example:</dt>
<dd>array(array(43.19, -104.06), array(46.01, -96.76))</dd>
<dt>Notes:</dt>
<dd>
  Setting extent will cause the map to disregard latitude, longitude, and zoom.
  The actual map extent may vary slightly from the requested extent due to the
  tiled zoom level based nature of Google Maps.
</dd>
</dl>
</li>

<li><a name="tl-mt">maptype</a>
<dl>
<dt>Values:</dt>
<dd>"Map", "Satellite", "Hybrid", "Terrain", ... (String)</dd>
<dt>Description:</dt>
<dd>
  Initial baselayer of map. The set of allowable baselayers can be extended,
  see the gmap_extrabaselayers in the gmap_addons project for examples of how to
  add additional baselayers.
</dd>
<dt>Example:</dt>
<dd>"Map"</dd>
<dt>Notes:</dt>
<dd>
  The most common values are "Map" and "Hybrid". Addon modules that add additional
  baselayers must use identfiers that won't conflict with other modules. (The
  four "core" maptypes are poorly named due to legacy macros.)
</dd>
</dl>
</li>

<li><a name="tl-ct">controltype</a>
<dl>
<dt>Values:</dt>
<dd>"None", "Micro", "Small", "Large" (String)</dd>
<dt>Description:</dt>
<dd>Set the pan/zoom control type.</dd>
<dt>Example:</dt>
<dd>"Small"</dd>
<dt>Notes:</dt>
<dd>"Micro" corresponds to GSmallZoomControl, which only provides zoom control.</dd>
</dl>
</li>

<li><a name="tl-align">align</a>
<dl>
<dt>Values:</dt>
<dd>"Right", "Left", "Center" (String)</dd>
<dt>Description:</dt>
<dd>Sets the css alignment of the map div, using classes provided by gmap.css.</dd>
<dt>Example:</dt>
<dd>"Center"</dd>
<dt>Notes:</dt>
<dd>
  The limited flexibility of align is a holdover from the early days. If you
  need to position a map div more accurately, consider using a mapid and targeting
  the div yourself with css.
</dd>
</dl>
</li>

<li><a name="tl-mtc">mtc</a>
<dl>
<dt>Values:</dt>
<dd>"none", "standard", "hier", "menu" (String)</dd>
<dt>Description:</dt>
<dd>The "map type control" widget used to select different baselayers.</dd>
<dt>Example:</dt>
<dd>"standard"</dd>
<dt>Notes:</dt>
<dd>
  "standard" -- buttons ('GMapTypeControl' widget)<br />
  "hier"     -- buttons + dropdown menu ('GHierarchicalMapTypeControl' widget)<br />
  "menu"     -- dropdown menu ('GMenuMapTypeControl' widget)<br />
</dd>
</dl>
</li>

<li><a name="tl-bl">baselayers</a>
<dl>
<dt>Values:</dt>
<dd>array(string, ...)</dd>
<dt>Description:</dt>
<dd>Enabled baselayers.</dd>
<dt>Example:</dt>
<dd>array("Map", "Satellite", "Hybrid", "Terrain")</dd>
<dt>Notes:</dt>
<dd>
  The "traditional" set of baselayers is [Map, Satellite, Hybrid].
  Other modules, such as gmap_extrabaselayers (from gmap_addons) may provide
  additional possibilities.<br />
  The example shows the four "core" baselayers.
</dd>
</dl>
</li>

<li><a name="tl-styles">styles</a>
<dl>
<dt>Values:</dt>
<dd>array(string => array(...), ...)</dd>
<dt>Description:</dt>
<dd>An array of style names and definitions.</dd>
<dt>Example:</dt>
<dd>
<pre>
  array(
    'line_default' => array('0000ff',5,45,'',0,0),
    'poly_default' => array('000000',3,25,'ff0000',45),
    'green' => array('00ff00', 5, 100)
  );
</pre>
</dd>
<dt>Notes:</dt>
<dd>
  Currently, 'line_default' and 'poly_default' are predefined, and apply to lines and
  filled polygons that do not have style information assigned.
  You can override these two defaults on the map level if you wish.<br />
  See the <a href="#sh-style">shape style</a> definition for more information on styles.
</dd>
</dl>
</li>

<li><a name="tl-behavior">behavior</a>
<dl>
<dt>Values:</dt>
<dd>array(string, ...)</dd>
<dt>Description:</dt>
<dd>
  Map behavior flags.<br />
  Any that aren't set on the map level will be inherited from the defaults.
</dd>
<dt>Example:</dt>
<dd>array('autozoom', 'overview')</dd>
<dt>Notes:</dt>
<dd>
  <p>There are several behavior flags recognized by gmap.module, and other modules
  may choose to add their own behavior flags as well.</p>
  <p>All behavior flags recognized are documented on the <a href="base_url:admin/settings/gmap">GMap settings page</a>.</p>
  <em>Core behavior flags:</em>
    <dl>
    <dt>locpick</dt>      <dd>Puts the map into "locpick" mode, which is used to choose a coordinate using the map.</dd>
    <dt>nodrag</dt>       <dd>Disables map dragging. Also disables keyboard shortcuts.</dd>
    <dt>nokeyboard</dt>   <dd>Disables the keyboard handler (arrow keys, etc.)</dd>
    <dt>nomousezoom</dt>  <dd>Disables the ability to zoom with the mouse wheel.</dd>
    <dt>autozoom</dt>     <dd>Enables automatic map bounds calculation, based on the markers added to the map.</dd>
    <dt>dynmarkers</dt>   <dd>Ensures the marker system is loaded. Use this if you will be dynamically adding markers
      to an empty map.</dd>
    <dt>overview</dt>     <dd>Enables the miniature overview map in the bottom right corner.</dd>
    <dt>collapsehack</dt> <dd>Attempts to work around a resize bug when placing maps inside collapsible fieldsets.<br />
      This does not work in all themes.</dd>
    <dt>scale</dt>        <dd>Adds a map scale legend to the map.</dd>
    <dt>fatmarkers</dt>   <dd>If enabled on a View, this will cause the gmap_views code to
      serialize the views fields and pass it through the map object. This is useful
      if you wish to use custom marker handling code.  Since you can't currently
      use map arrays with GMap Views (only macros), there's usually no point in setting it.</dd>
    </dl>
</dd>
</dl>
</li>

<li><a name="tl-rmtcb">rmtcallback</a>
<dl>
<dt>Values:</dt>
<dd>Base url of callback path. (String)</dd>
<dt>Description:</dt>
<dd>
  This specifies the location that GMap needs to call the Drupal site back at to
  retrieve the contents of an ahah info window.
</dd>
<dt>Example:</dt>
<dd>check_url(url('my/callback'))</dd>
<dt>Notes:</dt>
<dd>
  Each marker can have a <a href="#ma-rmt">rmt</a> parameter that determines what
  is appended to the path when making the callback. This should be used to pass
  a unique identifier to your callback so you can retrieve the correct data.
</dd>
</dl>
</li>

<li><a name="tl-iwq">iwq</a>
<dl>
<dt>Values:</dt>
<dd>jQuery query for matching DOM elements. (String)</dd>
<dt>Description:</dt>
<dd>
  <p>Info Window Query (default).</p>
  <p>This specifies the query to use to match existing DOM elements to use for
  info window contents. You can use this in combination with
  <a href="#ma-iwo">iwo</a> on markers to make info windows copied from data
  already on the page. Additionally, <a href="#ma-iwq">iwq</a> can also be
  specified directly on a marker.</p>
</dd>
<dt>Example:</dt>
<dd>.markerdata&gt;.marker</dd>
<dt>Notes:</dt>
<dd>
  Each marker that has <a href="#ma-iwo">iwo</a> set and does not have 
  <a href="#ma-iwq">iwq</a> set will use the default iwq from the map.

  A marker with neither set will not use the iwq method of providing info
  window content. This allows mixing methods of providing info window
  content on a single map.
</dd>
</dl>
</li>

<li><a name="tl-markers">markers</a>
<dl>
<dt>Values:</dt>
<dd>array(array(...), ...)</dd>
<dt>Description:</dt>
<dd>An array of marker arrays to place on the map.</dd>
<dt>Example:</dt>
<dd>
<pre>
array(
  array(
    'options' => array(),
    'text' => 'start',
    'longitude' => 12.196,
    'latitude' => -58.13,
    'markername' => 'route',
    'offset' => 0,
  ),
  array(
    'options' => array(),
    'text' => 'finish',
    'longitude' => 12.196,
    'latitude' => -58.523,
    'markername' => 'route',
    'offset' => 1,
  ),
);
</pre>
</dd>
<dt>Notes:</dt>
<dd>
  <p>There are three types of overlays you can place on a map: markers, shapes, and feeds.
  Each of these classes is represented by a sub-array in the GMap array.</p>

  <p>This is not the only way to put markers on the map. It is, however, the easiest
  way. The markers specified here are loaded through the "static marker loader."</p>

  <p>You can also set arbitrary keys in the array. They will be passed to the javascript
  side automatically.</p>
</dd>
</dl>
</li>

<li><a name="tl-shapes">shapes</a>
<dl>
<dt>Values:</dt>
<dd>array(array(...), ...)</dd>
<dt>Description:</dt>
<dd>
  <p>An array of shapes to place on the map.</p>
  <p>The format of the shape arrays depends on the type.</p>
</dd>
<dt>Example:</dt>
<dd>
<pre>
  array(
    array(
      'type' => 'line',
      'points' => array(
        array(0.000, 0.000),            // First point.
        array(0.000, 0.000),            // Second point.
        array(0.000, 0.000),            // Third point.
      ),
      'style' => array("00ff00", 5, 80),
    )
    array(
      'type' => 'polygon',
      'points' => array(
        array(0.000, 0.000),            // First point.
        array(0.000, 0.000),            // Second point.
        array(0.000, 0.000),            // Third point.
      ),
      'style' => array("ff0000", 5, 80, "00ff00", 60),
    ),
    array(
      'type' => 'circle',
      'center' => array(0.000, 0.000),  // Center coordinate of the circle.
      'radius' => 100,                  // Radius of the circle in kilometers.
      'style' => array(),               // Style to use.
    ),
    array(
      'type' => 'rpolygon',
      'center' => array(0.000, 0.000),  // Center coordinate of the regular polygon.
      'numpoints' => 4,                 // Number of vertices the polygon should have.
      'point2' => array(0.000, 0.000),  // One of the vertex coordinates.
      'style' => array(),               // Style to use.
    ),
    array(
      'type' => 'encoded_line',
      'points' => 'icx~FfigvOt~CsnB~Vo`G~aDqnBp`@chB',  // a series of points, encoded
      'levels' => 'BBBBB',                              // zoom level for each point, encoded
      'numLevels' => 18,                                // derived from the encoding algorithm
      'zoomFactor' => 2,                                // derived from the encoding algorithm
      'style' => array(),
    ),
    array(
      'type' => 'encoded_polygon',
      'polylines' => array(
        array(
          'points' => 's{r~FnwcvO`zB{qHa}Fa`E~aC|rN',
          'levels' => 'BBBB',
          'numLevels' => 18,
          'zoomFactor' => 2,
        ),
      ),
      'style' => array(),
    ),
  );
</pre>
</dd>
<dt>Notes:</dt>
<dd><p>For both <strong>encoded_line</strong> and <strong>encoded_polyline</strong>, the 'points', 'levels', 'numLevels', and 'zoomFactor' should be generated using the <em>gmap_polyutil_polyline()</em> function in <em>gmap_polyutil.inc</em>. To use this, pass an array of points into the function:</p>
<pre>$points = array(
  array(41.90625, -87.67634),
  array(41.91226, -87.65643),
  array(41.91021, -87.65059),
  array(41.90753, -87.64956),
);
$gmap_encoding = gmap_polyutil_polyline($points);
</pre>
<p>results in:</p>
<pre>Array
(
    [points] => ayw~FbhcvOqd@m{BxKoc@vOmE
    [levels] => PGFP
    [numLevels] => 18
    [zoomFactor] => 2
)
</pre></dd>
</dl>
</li>

<!--
<li><a name="tl-foo">foo</a>
<dl>
<dt>Values:</dt>
<dd></dd>
<dt>Description:</dt>
<dd></dd>
<dt>Example:</dt>
<dd></dd>
<dt>Notes:</dt>
<dd></dd>
</dl>
</li>
-->

</ul>

<h2>OVERLAYS</h2>

<p>There are three types of overlays you can place on a map by default: markers, shapes, and feeds.
Each of these classes is represented by a sub-array in the GMap array.
Addon modules can add more types of overlays.
</p>


<h3>MARKERS</h3>

<p>Markers are point features on a map. They are placed somewhere on the globe and can
optionally be programmed to show an information window when clicked.</p>

<p>Any additional keys / values you put in a marker array will be passed to the
javascript side automatically. This is very useful when writing custom code.</p>

<pre>
  $marker = array(
    '<a href="#ma-lat"    >latitude</a>' => 0.000,            // Marker latitude.
    '<a href="#ma-lon"    >longitude</a>' => 0.000,           // Marker longitude.
    '<a href="#ma-mn"     >markername</a>' => 'smileyface',   // Name of marker set to use.
    '<a href="#ma-offset" >offset</a>' => 0,                  // Offset in marker set.
    '<a href="#ma-text"   >text</a>' => 'popup text',         // GInfoWindow contents.
    '<a href="#ma-tabs"   >tabs</a>' => array(),              // Tabbed GInfoWindow contents.
    '<a href="#ma-link"   >link</a>' => 'http://google.com',  // Use marker as hyperlink.
    '<a href="#ma-rmt"    >rmt</a>' => '',                    // Argument to pass for rmt
    '<a href="#ma-iwq"    >iwq</a>' => '',                    // Info window query
    '<a href="#ma-iwo"    >iwo</a>' => 0,                     // Info window offset
    '<a href="#ma-opts"   >opts</a>' => array(),              // Use custom GMarkerOptions.
    '<a href="#ma-options">options</a>' => array(),           // Misc. behavior modifications.
  );
</pre>

<p>Here is a description of the keys of a marker array.</p>
<ul>

<li><a name="ma-lat">latitude</a>
<dl>
<dt>Values:</dt>
<dd>Latitude of point in degrees decimal format. (Float)</dd>
<dt>Description:</dt>
<dd>Marker latitude, as a signed float</dd>
<dt>Example:</dt>
<dd>39.36827914916013</dd>
<dt>Notes:</dt>
<dd>
    Cast to float if you are unsure what type your latitude variable is; some parts of
    Google Maps do not operate correctly if latitude is passed as a string.
</dd>
</dl>
</li>

<li><a name="ma-lon">longitude</a>
<dl>
<dt>Values:</dt>
<dd>Longitude of point in degrees decimal format. (Float)</dd>
<dt>Description:</dt>
<dd>Marker longitude, as a signed float.</dd>
<dt>Example:</dt>
<dd>-81.5625</dd>
<dt>Notes:</dt>
<dd>
    Cast to float if you are unsure what type your latitude variable is; some parts of
    Google Maps do not operate correctly if latitude is passed as a string.
</dd>
</dl>
</li>

<li><a name="ma-mn">markername</a>
<dl>
<dt>Values:</dt>
<dd>The name of the icon set to use (String)</dd>
<dt>Description:</dt>
<dd>
    Marker icons are located in the GMap module's 'markers' directory.
    GMap reads the .ini files to find available markers.
</dd>
<dt>Example:</dt>
<dd>"Light Blue"</dd>
<dt>Notes:</dt>
<dd>Some markers have multiple icons. Use <a href="#ma-offset">offset</a> to choose which one to show.</dd>
</dl>
</li>

<li><a name="ma-offset">offset</a>
<dl>
<dt>Values:</dt>
<dd>The index of the marker to use (Integer)</dd>
<dt>Description:</dt>
<dd>For markernames with multiple icons, you can choose which one to use.</dd>
<dt>Example:</dt>
<dd>0</dd>
<dt>Notes:</dt>
<dd>
  <p>The code will automatically wrap around if you simply increment offset every marker.</p>
  <p>You do not need to know how many icons are actually assigned to the marker set.</p>
</dd>
</dl>
</li>

<li><a name="ma-text">text</a>
<dl>
<dt>Values:</dt>
<dd>HTML or Text to show in info window on marker click (String)</dd>
<dt>Description:</dt>
<dd>
  <p>This will set up an info window popup when you click the marker.</p>
  <p>If you specify as a string, it will make a regular GInfoWindow.</p>
  <p>If you specify as an array, it will make a tabbed GInfoWindow, where the
  array keys are the tab titles, and the array values are the contents of the
  tabs.</p>
</dd>
<dt>Example:</dt>
<dd>"Point A"</dd>
<dt>Notes:</dt>
<dd>
  Anything put in here will be sent inline to the javascript side, so if you are
  planning on using complex popups, you may want to consider using <a href="ma-rmt">rmt</a> instead.
</dd>
</dl>
</li>

<li><a name="ma-tabs">tabs</a>
<dl>
<dt>Values:</dt>
<dd>array('' => '',...)</dd>
<dt>Description:</dt>
<dd>
  Tab titles and HTML or text to show in info window on marker click.
</dd>
<dt>Example:</dt>
<dd>
<pre>
  array(
    'Name' => '&lt;em&gt;United States&lt;/em&gt;',
    'Currency' => 'United States Dollar',
  );
</pre>
</dd>
<dt>Notes:</dt>
<dd>
  Anything put in here will be sent inline to the javascript side.
</dd>
</dl>
</li>

<li><a name="ma-link">link</a>
<dl>
<dt>Values:</dt>
<dd>A url to go to when the marker is clicked. (String)</dd>
<dt>Description:</dt>
<dd>
  This will program the marker to act like a hyperlink.
</dd>
<dt>Example:</dt>
<dd>"http://google.com/"</dd>
<dt>Notes:</dt>
<dd>
  It is pointless to specify <a href="#ma-text">text</a> or <a href="#ma-tabs">tabs</a>
  at the same time as link, as link causes immediate navigation away from the map.
</dd>
</dl>
</li>

<li><a name="ma-rmt">rmt</a>
<dl>
<dt>Values:</dt>
<dd>Path to append to the rmtcallback. (String)</dd>
<dt>Description:</dt>
<dd>
  When using ahah markers, this should be set to the identifiers expected by
  your callback.
</dd>
<dt>Example:</dt>
<dd>"15/0"</dd>
<dt>Notes:</dt>
<dd>
  If you need to pass multiple identifiers, just seperate them with slashes.
</dd>
</dl>
</li>

<li><a name="ma-iwq">iwq</a>
<dl>
<dt>Values:</dt>
<dd>jQuery query for matching DOM elements. (String)</dd>
<dt>Description:</dt>
<dd>
  <p>Info Window Query.</p>
  <p>This specifies the query to use to match existing DOM elements to use for
  info window contents. You can also specify a default <a href="#tl-iwq">iwq</a>
  at the top level.</p>
</dd>
<dt>Example:</dt>
<dd>.markerdata&gt;.marker</dd>
<dt>Notes:</dt>
<dd>
  When iwq is set on the marker, <a href="#ma-iwo">iwo</a> will default to 0.
  Otherwise, you must set iwo if you want the default iwq to be used.
</dd>
</dl>
</li>

<li><a name="ma-iwo">iwo</a>
<dl>
<dt>Values:</dt>
<dd>Zero based index to choose a single match from the iwq query. (Integer)</dd>
<dt>Description:</dt>
<dd>
  <p>Info Window offset.</p>
  <p>When using iwq, iwo will select which of the matches to use for the info
  window.</p>
</dd>
<dt>Example:</dt>
<dd>0</dd>
<dt>Notes:</dt>
<dd>
  If using the default <a href="#tl-iwq">iwq</a>, you must set iwo even if you
  are using offset 0. This is to allow mixing methods of showing info windows
  within the same map.
</dd>
</dl>
</li>

<li><a name="ma-opts">opts</a>
<dl>
<dt>Values:</dt>
<dd>array('' => ...,...)</dd>
<dt>Description:</dt>
<dd>
  <p>Filling out this parameter will allow you to override the <em>GMarkerOptions</em>
  that a marker is initialized with.</p>
  <p>The <em>icon</em> key is automatically filled in, you can't set it here.</p>
</dd>
<dt>Example:</dt>
<dd>
<pre>
  array(
    'bouncy' => TRUE,
  );
</pre>
</dd>
<dt>Notes:</dt>
<dd>
  The documentation for <em>GMarkerOptions</em> can be found <a href="http://code.google.com/apis/maps/documentation/reference.html#GMarkerOptions">here</a>.
</dd>
</dl>
</li>

<li><a name="ma-options">options</a>
<dl>
<dt>Values:</dt>
<dd>
  array('',...)
</dd>
<dt>Description:</dt>
<dd>
  This is used similar to how <a href="#tl-behavior">behavior</a> works at the map level.
</dd>
<dt>Example:</dt>
<dd>
<pre>
  array('autoclick');
</pre>
</dd>
<dt>Notes:</dt>
<dd>
  Available options:
  <dl>
  <dt>autoclick</dt> <dd>Automatically causes a click event on this marker.
    Useful when you want to automatically show an info window.</dd>
  </dl>
</dd>
</dl>
</li>

<!--
<li><a name="ma-foo">foo</a>
<dl>
<dt>Values:</dt>
<dd></dd>
<dt>Description:</dt>
<dd></dd>
<dt>Example:</dt>
<dd></dd>
<dt>Notes:</dt>
<dd></dd>
</dl>
</li>
-->

</ul>

<h3>SHAPES</h3>

<p>Shapes are the non point features on the map.</p>

<pre>
  $shape = array(
    '<a href="#sh-type"  >type</a>' => '',
    '<a href="#sh-points">points</a>' => array(),
    '<a href="#sh-center">center</a>' => array(0,0),
    '<a href="#sh-radius">radius</a>' => 0,
    '<a href="#sh-point2">point2</a>' => array(0,0),
    '<a href="#sh-numpt" >numpoints</a>' => 10,
    '<a href="#sh-style" >style</a>' => array(),
  );
</pre>

<ul>

<li><a name="sh-type">type</a>
<dl>
<dt>Values:</dt>
<dd>"circle", "polygon", "rpolygon", "line" (String)</dd>
<dt>Description:</dt>
<dd>
  Determines how the shape is processed. Circles and rpolygons are converted into
  lines with javascript math.
</dd>
<dt>Example:</dt>
<dd>"circle"</dd>
<dt>Notes:</dt>
<dd>
  "line" is drawn as a GPolyline.<br />
  "polygon" is drawn as a GPolygon.<br />
  "circle" and "rpolygon" (regular polygon) are special cases of "polygon".
</dd>
</dl>
</li>

<li><a name="sh-points">points</a>
<dl>
<dt>Values:</dt>
<dd>array(array(lat1, lon1), array(lat2, lon2), ... , array(latN, lonN))</dd>
<dt>Description:</dt>
<dd>
  <p>An array of points defining the shape.</p>
  <p>Used by the <em>line</em> and <em>polygon</em> types.</p>
</dd>
<dt>Example:</dt>
<dd>
<pre>
  array(
    array(44.205835001, -70.3674316406),
    array(44.3159879052, -68.6096191406),
  ),
</pre>
</dd>
<dt>Notes:</dt>
<dd>
  <p>Each point itself is an array with two elements (latitude, longitude). The different shapes have different requirements with respect to points.</p>
  <p>"line" must have at least two points. It is best to break up long lines into shorter segments, because long lines can be buggy--sometimes beginning and ending points are switched.</p>
  <p>"polygon" should have at least three points; the first and last points should have the same coordinates.</p>
</dd>
</dl>
</li>

<li><a name="sh-center">center</a>
<dl>
<dt>Values:</dt>
<dd>array(lat, lon)</dd>
<dt>Description:</dt>
<dd>Center point of <em>circle</em> or <em>rpolygon</em>.</dd>
<dt>Example:</dt>
<dd>array(44.213, -96.411)</dd>
<dt>Notes:</dt>
<dd></dd>
</dl>
</li>

<li><a name="sh-radius">radius</a>
<dl>
<dt>Values:</dt>
<dd>Float</dd>
<dt>Description:</dt>
<dd>
  <p>The radius of the circle, in km.</p>
  <p>Only used for the <em>circle</em> type.</p>
</dd>
<dt>Example:</dt>
<dd>100</dd>
<dt>Notes:</dt>
<dd>
  Big circles look more like ovals. This is due to the mercator projection
  used by Google Maps.
</dd>
</dl>
</li>

<li><a name="sh-point2">point2</a>
<dl>
<dt>Values:</dt>
<dd>array(lat, lon)</dd>
<dt>Description:</dt>
<dd>
  <p>The coordinate of a vertex on the rim of the <em>rpolygon</em>.</p>
  <p>Only used for the <em>rpolygon</em> type.</p>
</dd>
<dt>Example:</dt>
<dd>array(12.66, -55.23)</dd>
<dt>Notes:</dt>
<dd>
  Changing both the latitude and longitude in respect to the center point will make the
  polygon "rotate."
</dd>
</dl>
</li>

<li><a name="sh-numpt">numpoints</a>
<dl>
<dt>Values:</dt>
<dd>Integer</dd>
<dt>Description:</dt>
<dd>
  <p>Sets the number of points used to draw the <em>circle</em> or <em>rpolygon</em>.</p>
  <p>Only used for the <em>circle</em> and <em>rpolygon</em> types.</p>
</dd>
<dt>Example:</dt>
<dd>20</dd>
<dt>Notes:</dt>
<dd>
  Don't use a very large number, it will slow down the map drawing.
</dd>
</dl>
</li>

<li><a name="sh-style">style</a>
<dl>
<dt>Values:</dt>
<dd>array(stroke color, stroke weight, stroke opacity, fill color, fill opacity) OR String</dd>
<dt>Description:</dt>
<dd>
  <p>A <em>style array</em>, or a key to the <a href="#tl-styles">styles array on the map</a>.</p>
  <p>This is the same format used for the map level styles array.</p>
</dd>
<dt>Example:</dt>
<dd>array("ff0000", 5, 80, "00ff00", 60)</dd>
<dt>Notes:</dt>
<dd>
  <p>The elements of this array MUST be in the specified order.</p>
  <p>Stroke and fill colors should be hex color codes (without the leading "#"); Google Maps does not accept named colors.</p>
  <p>The stroke weight is the width of the line or polygon border in pixels.</p>
  <p>Stroke and fill opacities should be a percentage between 0 and 100.</p>
  <p>Fill color and fill opacity are not used for type "line".</p>
  <p>If shapes of type "line" don't have styles defined, the 'line_default' style will be used; shapes of type "polygon", "circle", and "rpolygon" will use 'poly_defalt'.</p>
  <p>In previous versions of GMap (Specifically, all Drupal 4.6 and 4.7 versions), opacity was specified as a number between 0 and 1. It is now a number between 0 and 100.</p>
  <p>On backwards compatibility: there were originally more style options, but they were dependant on xmaps; xmaps is no longer compatible with Google Maps, so these options are now ignored. They are: 'pattern', 'text', 'fillcolor', 'fillopacity'; all except for 'pattern' are now available with different syntax.</p>
</dd>
</dl>
</li>

<!--
<li><a name="sh-foo">foo</a>
<dl>
<dt>Values:</dt>
<dd></dd>
<dt>Description:</dt>
<dd></dd>
<dt>Example:</dt>
<dd></dd>
<dt>Notes:</dt>
<dd></dd>
</dl>
</li>
-->

</ul>

<h2>USING A MAP ARRAY</h2>

<pre>
$map = array(...); // Set up your map array.
$element = array( // GMap in Drupal 7 uses drupal_render().
  '#type' => 'gmap',
  '#gmap_settings' => $map,
);
$output = drupal_render($element);
</pre>