Document how to use KML module on project page and in readme

You'll need to create a view with a Feed display and using the KML style plugin.

Closing...

Could this be added to the project page and README. Just a few sentence description would be sufficient.

Can we reopen this? I don't understand how to use it either. I have both the KML and Location modules enabled, then I went to create a location view but didn't know what to do with the options given. Any help would be greatly appreciated...

...having the same issue. I've added lat. and long., description and name to a KML feed. Also added a file name....

I've added a path and attached the KML feed to a page display...not sure what else to do.

Thanks in advance for any help.

This support request contains a screen dump of a working views setup (albeit in French).

Oooh...views looks so much more elegant in French :) Maybe sometime in the next month-ish, we'll have deployed KML on our site, and I can take some time to document.

Evan, the KML module is looking good to me. Do you know if it works with OpenLayers CCK, before I dive in? It looks like it works with the location module, but CCK has its own lat/lon field..

This module isn't compatible with OpenLayers CCK fields. The latter stores data as WKT, whereas KML has its own data format.

Following the French screen dump, I see how to create the feed, and that works.

The project page says "Add a KML link to the bottom of all spatially enabled nodes" which I assume means nodes with location module fields, rendering as a a page with a KML link like this one.

Is that a "customized theme function" as in the README? Or is there a setting I'm missing?

UPDATE My use case (see link above) is a link that when clicked opens Google earth to the right lat/lon for a the node being displayed to the user. The URL you need for the link can be created from the KML feed view with the nid as a parameter, like "kml/15" where "kml" is the view path value and "15" is the node nid parameter.

Be sure, in the style options for the KML feed, to fill in a value for Filename, like "node." If you do, the module will add the extension, and the file will be named "node.kml" and Google Earth should open it. If you don't, you'll end up with a filename like KML(0), and Google Earth will open, but won't go to the lat/lon coordinates in the file. I did this with HTML in the body, but I guess hook_link could be used to generate the link at the bottom of the node, using the nid of the object parameter.

Now to see how I can get the lat/lon from the OpenLayers CCK field and not location...

UPDATE And hook_link:

function kml_link($type, $object, $teaser = FALSE) {

  if ($object->type == 'your_content_type_here') {
    $link['google_earth_link'] = array(
      'title' => t('Open in Google Earth'),
      'href' => 'kml/' . $object->nid,
      'attributes' => array('class' => 'kml_node_link'),
    );
  }
  return $link;
}

The href, again, is to the kml feed view with the node nid as a parameter.

Well, just for fun:

After adding an Openlayers CCK field to a content type:

1. Edit the Fields section of the KML feed view to include this single field*: Content: Latitude/Longitude (field_latitude_longitude), instead of using the Location module's two fields for Latitude and Longtitude.

2. Configure the Content: Latitude/Longitude field to use the format WKT value.

3. Edit the Basic Settings section of the KML feed view using the dropdowns, so that the Style Options for Longitude and Latitude both read Latitude/Longitude (the name of the field selected in step 1).

Save and clear caches. Then open up views_plugin_style_kml.inc and look for the map_rows function (around line 123 in version v 1.1.2.3 2010/10/02). Look for the loop where $point['name'], $point['description'], and $point['lat'] and $point['lon'] are set, around line 138. Change this:

  elseif ($key == $this->options['fields']['longitude']) {
    $point['lon'] = $row[$key];
  }
  elseif ($key == $this->options['fields']['latitude']) {
    $point['lat'] = $row[$key];
  }

to this:

   elseif (($key == $this->options['fields']['longitude']) || ($key == $this->options['fields']['latitude'])) {
     if ($lat_lon === NULL) { // set NULL above
      $lat_lon = kml_grab_wkt_lat_lon($row[$key]);
      $point['lat'] = $lat_lon['lat'];
      $point['lon'] = $lat_lon['lon'];
    }
  }

$this->options['fields']['longitude'] and $this->options['fields']['latitude'] have the same value (step #3), which is a WKT string (step #2). (The string is the same string you see when you click the "Show WKT field" link in a node with an Openlayers CCK field.) So we need to parse the lat and lon values out of that string and then store them in the point array. That is what kml_grab_wkt_lat_lon does:

/* WKT string: GEOMETRYCOLLECTION(POINT(-68.673723933327 44.8814061886)) */
function kml_grab_wkt_lat_lon($wkt) {
  $matches = array();
  preg_match('/.+POINT.(?P<lon>-\d+\.\d+) (?P<lat>\d+\.\d+)./', $wkt, $matches);
  return $matches;
}

That function makes a lot of assumptions, especially that there's only going to be one point, but for my use case, that's true. And a production version would be able to take account of the format for the source of the lat/lon, whether Location or Openlayers.

UPDATE * I named my field field_latitude_longitude. Your name may be different.

UPDATE This function works better; I guessed wrong on WKT syntax:

/* GEOMETRYCOLLECTION(POINT(-68.673723933327 44.8814061886)) */
/* GEOMETRYCOLLECTION(LINESTRING(-68.652158972849 44.932473546952,-68.651590344537 44.930825328333,-68.650667664637 44.931000026556,-68.651236292947 44.932633049469,-68.650324341883 44.932807742194,-68.649777171244 44.931159533166,-68.648983237375 44.931296252764)) */
function kml_grab_wkt_lat_lon($wkt) {
  $matches = array();
  // grab the first point
  preg_match('/.*GEOMETRYCOLLECTION\(.+\((?P<lon>-\d+\.\d+) (?P<lat>\d+\.\d+)./', $wkt, $matches);
  return $matches;
}

I guess I really ought to use the WFS WKT parser, and not a regex...

@shunting: Cool. Maybe you could post your code as a patch (in a separate issue), and then the module could have support for both built in.

I can, but with reservations: (1) I forgot to document that the name of the CCK field is particular to my installation, and that's a gotcha, and (2) I'm thinking that the choice of which latlon representation to use should be made in an admin interface, and that needs to be thought through (bigger patch).

Ah OK. That would require at least two settings fields then (one to select the form field, and one to select the lat/lon representation type). No rush from my end, though; I was more curious than anything else - I don't need this functionality personally, though others might.

Bringing this back to the original issue: better docs. Feel free to open another issue for Openlayers CCK stuff.

The attached patch is a quick start to get the ball rolling, adding some usage recommendations to the README.

## Usage

1. Add a Feed display to a View that handles nodes (or other data) that include
locative infomation.
2. Add fields for the Name, Description, Latitude and Longitude for each point.
3. Set the display's Style to KML Feed.
4. Configure the KML Feed's Style Options, choosing the appropriate fields and
optionally choosing a Filename for the downloadble file.
5. Optionally attach the feed display to another display.

Glad for help on crafting this further.

Committed to 6.x-2.x-dev and 7.x-1.x-dev, and added [these usage instructions] to the project page.