modules/ymap/ymap.module

<?php
//$Id: ymap.module,v 1.3 2006/12/15 21:05:54 dayre Exp $


/**
 * Implementation of hook_perm.
 */
function ymap_perm() {
  return array('view maps');
}

/**
 * Implementation of hook_help.
 */
function ymap_help($section) {
  switch ($section) {
    case 'admin/help#ymap':
      $output = '<p>'. t('Add some help text here for Yahoo Maps') .'</p>';
			return $output;
    case 'admin/modules#description':
      return t('Lets you show location data on Yahoo! map.');
    case 'admin/settings/ymap':
      return t('The ymap module allows the display of location data on a Yahoo! map.  Once an API key has been set, you can ' . 
               'enable maps and default map settings per ') . l(t('individual content type'), 'admin/settings/content-types') . '.';
  
  }
}


/**
* Implentation of hook_nodeapi
*/
function ymap_nodeapi(&$node, $op, $teaser = NULL, $page = NULL) {
  //if the node we're looking at is not supposed to display maps, just bail out here...
	if (!variable_get('ymap_'. $node->type, 0)) return;
  
	switch ($op) {
		//---------------------
		// V i e w
		//---------------------
		case 'view':
			//set the map size for teaser or large view...
			if (_ymap_location_is_mappable($node->location)) {
				($teaser && $node->location) ? 
					  $node->teaser .= theme('ymap_node', $node, 'teaser')
					:	$node->body .= theme('ymap_node', $node);
			}
		break;
	}
} 

/**
 * Returns TRUE if the given array of location data contains the
 * necessary data for a map to represent it.
 * 
 * @param $location
 *   A location data structure.
 */
function _ymap_location_is_mappable($location) {
	return $location && (
		$location['city'] ||
		$location['province'] ||
		$location['postal_code'] ||
		$location['country'] ||
		($location['latitude'] && $location['longitude']) );
}


/**
 * Implementation of hook_form_alter.
 */
function ymap_form_alter($form_id, &$form) {
	//If we are looking at the node settings page at admin/settings/content-types/[blog|page|story|etc...]>
	//then show the following form to toggle the map on and off for each content type.
	if (isset($form['type']) && $form['type']['#value'] .'_node_settings' == $form_id) {
    $type = $form['type']['#value'];
    $form['ymap'] = array(
      '#type' => 'fieldset',
      '#title' => t('Yahoo! map settings'),
      '#collapsible' => TRUE,
      '#collapsed' => TRUE,
      '#weight' => 0
    );
    $form['ymap']['ymap_'. $type] = array(
      '#type' => 'checkbox',
      '#title' => t('Display map'),
      '#return_value' => 1,
      '#default_value' => variable_get('ymap_'. $type, 0),
      '#description' => t('Show a Yahoo! map for nodes of this type that have location information associated with them.')
    );
    
    $form['ymap']['ymap_'. $type .'_detail_size'] = array(
	    '#type' => 'textfield',
	    '#title' => t('Default size of the map detailed view (width x height)'),
	    '#size' => 8,
	    '#maxlength' => 15,
	    '#default_value' => variable_get('ymap_'. $type .'_detail_size', '500 x 300'),
	    '#description' => t('Enter in the width and height of the detail view map in pixels.  This size will be used to display the map on the "details" page.'),
	  );
	  
	  $form['ymap']['ymap_'. $type .'_teaser_size'] = array(
	    '#type' => 'textfield',
	    '#title' => t('Default size of the map teaser view (width x height)'),
	    '#size' => 8,
	    '#maxlength' => 15,
	    '#default_value' => variable_get('ymap_'. $type .'_teaser_size', '300 x 200'),
	    '#description' => t('Enter in the width and height of the teaser view map in pixels.  This size will be used to display the map on the "teaser" page.'),
	  );
	
		$form['ymap']['ymap_'. $type .'_map_type'] = array(
			'#type' => 'radios',
			'#title' => t('Default map type'),
			'#default_value' => variable_get('ymap_'. $type .'_map_type', 0),
			'#options' => array(t('Regular'), t('Satellite'), t('Hybrid')),
		);
		
		$form['ymap']['ymap_'. $type .'_show_map_type_control'] = array(
			'#type' => 'radios',
			'#title' => t('Show map type control'),
			'#default_value' => variable_get('ymap_'. $type .'_show_map_type_control', 1),
			'#options' => array(t('Off'), t('On')),
		);
	
		$form['ymap']['ymap_'. $type .'_show_zoom_control'] = array(
			'#type' => 'radios',
			'#title' => t('Show zoom control'),
			'#default_value' => variable_get('ymap_'. $type .'_show_zoom_control', 1),
			'#options' => array(t('Off'), t('Short zoom control'), t('Long zoom control')),
		);
	
		$form['ymap']['ymap_'. $type .'_show_zoom_scale'] = array(
			'#type' => 'radios',
			'#title' => t('Show zoom scale indicator'),
			'#default_value' => variable_get('ymap_'. $type .'_show_zoom_scale', 1),
			'#options' => array(t('Off'), t('On')),
		);
	
		$form['ymap']['ymap_'. $type .'_show_pan_control'] = array(
			'#type' => 'radios',
			'#title' => t('Show pan control'),
			'#default_value' => variable_get('ymap_'. $type .'_show_pan_control', 0),
			'#options' => array(t('Off'), t('On')),
		);
	
		$form['ymap']['ymap_'. $type .'_enable_map_dragging'] = array(
			'#type' => 'radios',
			'#title' => t('Enable map dragging'),
			'#default_value' => variable_get('ymap_'. $type .'_enable_map_dragging', 1),
			'#options' => array(t('Off'), t('On')),
		);
		
		$form['ymap']['ymap_'. $type .'_enable_key_controls'] = array(
			'#type' => 'radios',
			'#title' => t('Enable key controls'),
			'#default_value' => variable_get('ymap_'. $type .'_enable_key_controls', 1),
			'#description' => t('Enables keyboard/mouse wheel zoom and pan controls shortcuts.'),
			'#options' => array(t('Off'), t('On')),
		);
		
		// we use the #validate form directive to call our validation
		// function for our content type specific form.
		$form['#validate']['ymap_form_validate'] = array($type);
    
	}
}


/**
* Implementation of hook_settings.  
*/
function ymap_settings() { 
  $form['ymap_apikey'] = array(
    '#type' => 'textfield',
    '#title' => t('Yahoo! Maps API key'),
    '#default_value' => variable_get('ymap_apikey', 'drupalmaps'),
    '#size' => 20,
    '#maxlength' => 255,
    '#description' => t('Enter in your Yahoo! maps API key from ') . 
		l('here', 'http://api.search.yahoo.com/webservices/register_application') . t('.'),
  );

  return $form;
}

/**
 * Validates the individual content type YMap settings form, in particular,
 * the size specifications for the teaser and detail view.
 * @param $form_id
 * @param $form_values
 * @param $form
 */
function ymap_form_validate($form_id, $form_values, $form) {

  // we need to get the content type name as this makes
  // up the keys for the form values we are about to test.  
  $type = $form['#validate']['ymap_form_validate'][0];
  if (!$type) {
    return;
  }
  
  // validate size specifications
  $size_form_fields = array("ymap_" . $type . "_teaser_size", "ymap_" . $type . "_detail_size");
  foreach ($size_form_fields as $field) {
	  if ($form_values[$field] && !preg_match("/^(\d+)\s*x\s*(\d+)$/i", $form_values[$field], $matches)) {
	    form_set_error($field, t('Invalid size format, size must be width x height (eg. 300x200)'));
	  }
  }
}

/**
 * Returns an array listing the view plugins available from this module.
 */
function ymap_views_style_plugins() {
  return array(
    'ymap' => array(
      'name' => t('Ymap View'),
      'theme' => 'views_view_ymap',
      'needs_fields' => true,
      'validate' => 'views_ui_plugin_validate_list',
     ),
  );
}

/**
 * Returns HTML to render all the nodes in the YMap view on a 
 * single Yahoo map.  Those nodes which have location data with
 * longitude and latitude will display the visible fields 
 * configured in the view in an expandable section when the user
 * moves their mouse over the map marker.  
 * 
 * Those locations which only have an address and no long/lat
 * data can have a marker, but can not have an expandable section 
 * attached displaying the visible fields configured in the view.  
 * This is due to a limitation of the Yahoo map API in the way
 * it performs geocoding with an asynchronous network call.
 * 
 * @param $view
 * @param $nodes
 */
function theme_views_view_ymap($view, $nodes) {

  $fields = _views_get_fields();
  $fullnodes = array();
  foreach ($nodes as $node) {
    	$ndata = node_load(array('nid'=>$node->nid));
    	
     	// only create markers for nodes which are mappable
    	if (_ymap_location_is_mappable($ndata->location)) {
    	  
	      // create markers with possible custom styling for
	      // each field in the view.
	    	$marker_label = "";
				foreach ($view->field as $field) {
				  
				  // output any labels if the fields have labels (from view settings)
				  if ($field['label']) {
		        $marker_label .= "<div class=\"view-label view-label-$field[queryname]\">" . $field['label'] . "</div>";
		      }
		      
		      // now output the field data itself for those exposed fields set in
		      // the view.
		      $marker_label .= "<div class=\"view-field view-data-$field[queryname]\">" . views_theme_field('views_handle_field', $field['queryname'], $fields, $field, $node, $view) . "</div>";
				}
				
				// We need a container to wrap the field data
	      $ndata->ymap_marker = '<div style="width:160px;height:50px;">' . strtr($marker_label,"'\n\r",'" ') . "</div>";		
	      
	      $fullnodes[] = $ndata;
    	}
	}
  
	return theme_ymap_nodes($fullnodes, _ymap_get_default_detail_map_settings());
}

/**
 * Returns a default set of map settings containing display
 * properties to render the Yahoo map.  For a complete list of
 * map setting properites, refer to theme_ymap_nodes().
 */
function _ymap_get_default_teaser_map_settings() {
  return _ymap_get_map_settings_for_node(null, 1);
}

/**
 * Returns a default set of map settings containing display
 * properties to render the Yahoo map.  For a complete list of
 * map setting properites, refer to theme_ymap_nodes().
 */
function _ymap_get_default_detail_map_settings() {
  return _ymap_get_map_settings_for_node(null);
}

/**
 * Returns a map settings array with the dispaly properites needed to 
 * create the Yahoo map to render a specific node. Refer to 
 * theme_ymap_nodes() for a list of all the properties required for the map.  
 * 
 * This function currently returns the map settings based on the
 * node type which is configured in the admin/settings/content-type menu.
 * 
 * Future enhancements will allow a node to override the default node
 * type settings so an individual node can configure it's own map
 * settings.
 * 
 * @param $node
 * 		The node to return map settings for.  If null, a default set of 
 *    map settings is returned using default map width/height for
 *    the 'detail' map type. 
 * @param $teaser
 *    a flag either 1/0 which affects the size of the displayed map.  A 
 *    teaser view ($teaser = 1) can have a different size than the 
 *    detailed view ($teaser = 0).
 */
function _ymap_get_map_settings_for_node($node, $teaser = 0) { 
  
  // used for caching map settings per node type, saves
  // a bit of work.
  static $settings_map;
  
  // for now, we get settings based on node type, but
  // in the future, a node could override with specific node settings
  $type = $node->type ? $node->type : "nonode";
  $settings = $settings_map[$type];
  if ($settings) {
    return $settings;
  }
  
  // there are two sizes, one for teaser, and one for detail.
  $size = $teaser ? variable_get('ymap_'. $type .'_teaser_size', '300 x 200') 
                  : variable_get('ymap_'. $type .'_detail_size', '500 x 300'); 
  preg_match("/^(\d+)\s*x\s*(\d+)$/i", $size, $matches);
	$settings['width']                  = $matches[1] ? $matches[1] : 500;
	$settings['height']                 = $matches[2] ? $matches[2] : 300;
	$settings['map_type']               = variable_get('ymap_'. $type .'_map_type', 0);
	$settings['show_zoom_control']      = variable_get('ymap_'. $type .'_show_zoom_control', 1);
	$settings['show_map_type_control']  = variable_get('ymap_'. $type .'_show_map_type_control', 1);
	$settings['show_zoom_scale']        = variable_get('ymap_'. $type .'_show_zoom_scale', 1);
	$settings['show_pan_control']       = variable_get('ymap_'. $type .'_show_pan_control', 0);
	$settings['enable_map_dragging']    = variable_get('ymap_'. $type .'_enable_map_dragging', 1);
	$settings['enable_key_controls']    = variable_get('ymap_'. $type .'_enable_key_controls', 0);
	
	// save a bit of work for multi node display by 
	// caching fetched/computed settings by type
	$settings_map[$type] = $settings;
  
	return $settings;
}

/**
 * Delegates to theme_ymap_nodes(array($node)).  
 * 
 * @param $node
 *   the node to display the location of
 * @param $teaser
 *   a flag either 1/0 which affects the size of the displayed map.  A 
 *   teaser view ($teaser = 1) can have a different size than the 
 *   detailed view ($teaser = 0).
 */
function theme_ymap_node($node, $teaser = 0) {
	return theme_ymap_nodes(array($node), _ymap_get_map_settings_for_node($node, $teaser));
}

/**
 * Outputs a javascript snippet for displaying the given set of 
 * nodes which have mappable locations onto a Yahoo map.  The map
 * can display exact locations based on location longitude and latitude,
 * as well as locations with only addresses.  Address locations are 
 * handled by Yahoo maps built in support for geocoding address locations.
 * 
 * The map is configured based on the given map settings array.  The settings
 * array uses the following properties to configure the map:
 * 
 * width = map width in pixels
 * height = map height in pixels
 * map_type = YAHOO_MAP_REG, YAHOO_MAP_SAT, YAHOO_MAP_HYB
 * show_zoom_control = 0-off, 1-short zoom contro, 2-long zoom control
 * show_map_type_control = 0-off, 1-on
 * show_zoom_scale = 0-off, 1-on
 * show_pan_control = 0-off, 1-on
 * enable_map_dragging = 0-off, 1-on
 * enable_key_controls = 0-off, 1-on
 * 
 * @param $nodes
 * 	 an array of nodes to display the locations of
 * @param $map_settings
 *   display settings for the map, an array, properties listed above
 */
function theme_ymap_nodes($nodes, $map_settings = null){
  
  if (!$map_settings) {
    $map_settings = _ymap_get_default_detail_map_settings();
  }
   
  // if no nodes, nothing to do.
  if (!$nodes || !count($nodes)) {
    return "";
  }
  
	static $one_time_stuff_done = false;
	static $AJAX_MAP_TYPES;
	static $multi_map_counter = 0;
	if (!$one_time_stuff_done){
		//add yahoo js files and css
		_ymap_add_ajax_head();
		
		$AJAX_MAP_TYPES = array("YAHOO_MAP_REG", "YAHOO_MAP_SAT", "YAHOO_MAP_HYB");
	  
	  $one_time_stuff_done = true;
	}
	
	// if we have an array of nodes, then we are displaying them all on one map,
	// else we just have one to display and we can use the node id to create a unique
	// name for the map container.
	$map_id = count($nodes) == 1 ? $nodes[0]->nid : $multi_map_counter++;
	
	// if more than 1 node, then we let ymap estimate the best zoom, else
	// we estimate.
	$zoom_level = count($nodes) > 1 ? "zoomAndCenter.zoomLevel" : _ymap_get_best_zoom_for_location($nodes[0]->location);
	
	drupal_set_html_head('<style type="text/css"> 
	#mapContainer_'.$map_id.' { 	 
	  height: '.$map_settings['height'].'px; 	 
	  width: ' .$map_settings['width'].'px;
	}
	</style>');
	
	$output = '<div id="mapContainer_'.$map_id.'"></div>
		<script type="text/javascript">
		// Create a map object
		var map = new YMap(document.getElementById(\'mapContainer_'.$map_id.'\'), ' . $AJAX_MAP_TYPES[$map_settings['map_type']] . '); 

		// Display the map centered on given address 
		map.resizeTo(new YSize('.$map_settings['width'].', '.$map_settings['height'].'));
				
		var _geoPoints = [];

		// for those locations where we do not have lat/long, then
		// we define a callback function to be used with the
		// map.geoCodeAddress() calls.  The callback will get the
		// geocoded location and add a marker.  For those locations where
		// we have a lat/long, we create the marker directly.
		var myCallback = function(resultObj) {
			// check if OK
			if (resultObj.success) {
				
				// TODO customize marker image
				var marker = new YMarker(resultObj.GeoPoint);
				//marker.addAutoExpand(resultObj.Address);
				map.addOverlay(marker);

				_geoPoints.push(resultObj.GeoPoint);

				// TODO calls to these two functions allow the map to zoom and center itself
				// automatically after each marker is added.  This is probably creating a lot of 
				// work for the API to calulate this on each marker placement and could get
				// very slow with hundreds of markers... how best to handle this ?
				var zoomAndCenter = map.getBestZoomAndCenter(_geoPoints);
				map.drawZoomAndCenter(zoomAndCenter.YGeoPoint, ' . $zoom_level . ');
			}
		}

		// Register geocoder callback for those nodes which require
		// geocoding
		YEvent.Capture(map,EventsList.onEndGeoCode,myCallback);
		
		// controls
';
	
	// do controls
	if ($map_settings['show_zoom_control']) {
	  $output .= $map_settings['show_zoom_control'] == 1 ? "		map.addZoomShort();\n" : "		map.addZoomLong();\n";
  }
  $output .= $map_settings['show_map_type_control'] ? "		map.addTypeControl();\n" : "";
	$output .= $map_settings['show_zoom_scale']       ? "		map.addZoomScale();\n"   : "		map.removeZoomScale();\n";
  $output .= $map_settings['show_pan_control']      ? "		map.addPanControl();\n"  : "";
  $output .= $map_settings['enable_map_dragging']   ? "		map.enableDragMap();\n"  : "		map.disableDragMap();\n";
  $output .= !$map_settings['enable_key_controls']  ? "		map.disableKeyControls();\n" : "";
  
  // do markers
  $output .= "\n" . '		// markers'. "\n";
  $isMappable = false;
	foreach ($nodes as $node) {
		if (_ymap_location_is_mappable($node->location)) {
			$output .= _ymap_get_location_javascript($node) . "\n";
			
			// if we have at least one node with a mappable location,
			// then will return the output
			$isMappable = true;
		}
	}
	
	$output .='		var zoomAndCenter = map.getBestZoomAndCenter(_geoPoints);';
	$output .= "\n" . '		map.drawZoomAndCenter(zoomAndCenter.YGeoPoint, ' . $zoom_level . ');';

  
	$output .= "\n" . '		</script>';
		
	return $isMappable ? $output : "";
}


/**
* Add the JS to the html head of our returned page
*/
function _ymap_add_ajax_head(){
	drupal_set_html_head('
			<script type="text/javascript" 
			src="http://api.maps.yahoo.com/ajaxymap?v=3.4&appid='.variable_get('ymap_apikey', 'drupalmaps').'">
			</script>
	');
}

/**
* Format node location for yahoo mapping.  If the node has a 
* longitude and latitude, then we use that by creating a new 
* YGeoPoint in the javascript, else we rely on the Yahoo 
* geocoder by massaging the location address into a form 
* suitable for the geocoder.
* 
* Note: As of Dec/06, geocoding is supposed to be restricted to US
* locations, so country wasn't listed as a valid attribute, but
* it does seem to work for some Euorpean countries which indicates
* wider support in the future, so we use country and hope for the best.
*
* Available formats are:
* city, state
* city, state, country
* city, state, zip
* city, state, country, zip
* zip
* street, city, state
* street, city, state, country
* street, city, state, zip
* street, city, state, country, zip
* street, zip
* 
* @param $node
*/
function _ymap_get_location_javascript($node){
  
  // if we have long/lat, then create a marker, else we just 
  // geocode the address
  if ($node->location['longitude'] && $node->location['latitude']) {
    $js_string  = '		var point_' . $node->nid . ' = new YGeoPoint('. $node->location['latitude'] . ', ' . $node->location['longitude'] . ');';
    $js_string .= "\n" . '		var marker_' . $node->nid . ' = new YMarker(point_' . $node->nid .');';
    if ($node->ymap_marker) {
      $js_string .= "\n" . '		marker_' . $node->nid . '.addAutoExpand(\''. $node->ymap_marker . '\');';
    }
    $js_string .= "\n" . '		map.addOverlay(marker_' . $node->nid . ');';
    $js_string .= "\n" . '		_geoPoints.push(point_' . $node->nid . ');';
    return $js_string;
  }
	
  // geocode the address
	$address = null; 	
	$keys = array('street', 'city', 'province', 'country', 'postal_code');
	foreach ($keys as $key)
		if ($node->location[$key]) $address .= $node->location[$key] . ', ';

	//strip last ', ' off of string...
	$address = substr($address, 0, strlen($address) - 2);
	
	return '		map.geoCodeAddress("'. $address .'")';
}

/**
 * Returns the best estimated zoom level based on the given location
 * data.
 * @param $location
 */
function _ymap_get_best_zoom_for_location($location) {

  static $zoom_types = array(
    "longlat"  => 1, 
    "street"   => 3, 
    "city"     => 6, 
    "province" => 14, 
    "country"  => 16, 
    "world"    => 18);
  
  if (!$location) return 3;
  
  if ($location['longitude'] && $location['latitude']) 
    return $zoom_types["longlat"]; 
  
  if ($location['zip'] || $location['street'])
    return $zoom_types["street"];
  
  if ($location["city"])
    return $zoom_types["city"];
  
  if ($location["province"])
    return $zoom_types["province"];
  
  if ($location["country"])
    return $zoom_types["country"];
  
  return 3;
}

