Region-based network links in Google Earth API

Question

I have many large KML data-sets, which are served using a hierarchy of region-based network-links; as described in the KML reference:

Using Regions in conjunction with NetworkLinks, you can create a hierarchy of pointers, each of which points to a specific sub-Region. The <viewRefreshMode>, as shown in the following KML file, has an onRegion option, which specifies to load the Region data only when the Region is active. If you provide nested Regions with multiple levels of detail, larger amounts of data are loaded only when the user's viewpoint triggers the next load.

This works nicely when loaded in Google Earth.

I now wish to load these in an application using the Google Earth plug-in. And I need to access the loaded content via the Google Earth API; (i.e. attach click events, alter styles) to integrate the content into the application.

The issue is, I haven't found any reference to an 'on-load' event for network links. In my mind, the way this would work is:

• Load top-level network link via the API, attaching a call-back function which will be invoked when the network-link is loaded.
• In the call-back function, parse the KML returned by network link. For intermediate levels in the regionation hierarchy, this KML will contain only network links to the next regionation level. Load these into the plug-in via the API, again specifying the same call-back function, which will be invoked when these are loaded (i.e. when their region becomes visible).
• Eventually, the KML returned will contain the actual 'content'. At this stage we load the actual content (i.e. placemarks) into the plug-in, after performing any desired modifications (e.g. attaching event-listeners, setting styles, etc).

I'm thinking the javascript would look something like the following.
Please note: this is just a rough sketch to perhaps aid in understanding my question. I am NOT asking why this code doesn't work.

//create network link
var networkLink = ge.createNetworkLink("");
networkLink.setName("Regionated hierarchy root");

// create a Link object
//the network-links contained in the kml that will be returned in this file
//are region-based; they will only be loaded when the user zooms into the relevant
//region. 
var link = ge.createLink("");
link.setHref("http://foo.com/regionatedRoot.kml");

// attach the Link to the NetworkLink
networkLink.setLink(link);

//specify the callback function to be invoked when the network link is loaded
//this is is the part that doesn't actually exist; pure fiction...
networkLink.onLoad = networkLinkLoaded;

// add the NetworkLink feature to Earth
ge.getFeatures().appendChild(networkLink);

// function which will be invoked when a network-link is loaded
// i.e. when its region becomes active
function networkLinkLoaded(kml) {

   //parse the kml returned for child network links,
   //this will create the network link KmlObject, with a 
   //region specified on it.
   for (childNetworkLink in parseNetworkLinks(kml)) {
      //and append them, again hooking up the call-back
      childNetworkLink.onLoad = networkLinkLoaded;
      ge.getFeatures().appendChild(childNetworkLink);
   }

   //if the user has zoomed in far enough, then the kml returned will
   //contain the actual content (i.e. placemarks).
   //parse the kml returned for content (in this case placemarks)
   for (placemark in parsePlacemarks(kml)) {
      //here we would attach event-listeners to the placemark
      ge.getFeatures().appendChild(placemark);
   }
}

Is this possible?
Have I taken a wrong turn in my thinking? I believe I have followed recommended practices for managing large KML datasets, but I am unsure how to use these via the API.

Addendum:

As an example of the type of problem I am trying to solve: Imagine you are building a web application using the Google Earth Plugin, and you want to display a placemark for every set of traffic-lights in the world. The placemarks should only display at an appropriate level-of-detail (e.g. when the camera is at 5km altitude). When a user clicks on a placemark, we want the web app to load statistics for that set of traffic-lights, and display them in a sidebar.

How would you engineer this?

Valvule

Answer 1

You wouldn't need access to the object data directly to provide the functionality you require. You would handle the data load exactly like you have done, using a hierarchy of region-based network-links. Then if your usage scenario is like the one you set out in your addendum then you would simply use the target data from the click event to load your statistical data based on the placemarks as required.

For example, you could simply set up a generic mousedown event handler on the window object and then test to see if the target is a placemark. You can add this generic listener before you load any data and it will still be fired when you click on your dynamically loaded placemarks. There is no need to attach individual event-listeners to the placemarks at all.

e.g.

window.google.earth.addEventListener(ge.getWindow(), 'mousedown', onWindowMouseDown);

var onWindowMouseDown = function(event) {
  if (event.getTarget().getType() == 'KmlPlacemark') {
    // get the placemark that was clicked
    var placemark = event.getTarget();

    // do something with it, or one of its relative objects...
    var document = placemark.getOwnerDocument();
    var parent = placemark.getParentNode();

    // etc...
  }
}

Goods

You are right. By setting-up 'global' level event-handlers, I can then filter on the target ID to determine how to handle the event. Thanks! – Valvule

No worries, glad to have helped. – Goods

Answer 2

Not sure if this is quite what you want but there is a kmltree api that will:

1. build out the kml tree for you based on the kml given
2. allow you to have a 'kmlloaded' event handler

http://code.google.com/p/kmltree/

function initCB(instance){
    ge = instance;
    ge.getWindow().setVisibility(true);

    var gex = gex = new GEarthExtensions(ge);

    var tree = kmltree({
        url: 'http://foo.com/regionatedRoot.kml',
        gex: gex, 
        mapElement: $('#map3d'), 
        element: $('#tree'),
    });

    $(tree).bind('kmlLoaded', function(event, kmlObject){ //do something here });

    tree.load();
}

it does require you to bring in another js api but it works pretty good and gives you some good built in functionality.

So far I haven't found anything just from the plug-in that will fire an event when the kml is loaded...

you might be able to try using fetchKml() especially if you are hardcoding that url for the link in there?

google.earth.fetchKml(ge, 'http://foo.com/regionatedRoot.kml', function(kmlObject){
     //do logic here
});

Libelant

Thanks for the answer Matt. I have looked at the KmlTree project; but I don't believe it addresses the issue. It seems to be about parsing KML into a tree-menu. I don't believe it handles region-based network links? I have added an addendum to my question, with an example of the type of problem I am trying to solve. – Valvule