Authoring KML documents for use with kmltree

The goal of this library is to create an widget that can be used with any arbitrary kml file, and for the most part it accomplishes that. As with anything though, there are some limitations. Mostly these have to do with performance limitations and small styling quirks due to limitation in the Google Earth API.

Authoring for performance

limit the number of nodes in the tree

In some cases kmltree can render even faster than the Google Earth desktop client, but you'll still want to author files so that your users aren't waiting for kmltree to render thousands of features they will never want to interact with. Say you have a folder of 10k points related to offshore oil rigs. That might render quite quickly on the map, but kmltree has to make at least 10k DOM elements to represent those features. But if you put those into a single folder and set it's ListStyle to have a listItemType of 'checkHideChildren', kmltree won't traverse and render all these nodes. Users will still be able to toggle these features from the folder level, but not expand the folder's contents.

Going a step further, you could break up the kml document so that this folder is instead a NetworkLink that points to another document containing those features. This reduces the size of the linking document so that the initial download is fast and only the NetworkLinks toggled by the user would be loaded. You would still want to set the listItemType of this NetworkLink to 'checkHideChildren' to improve kmltree performance.

specify an explicit LookAt

When users double-click on a feature in kmltree it will attempt to pan and zoom the map to that feature. Also, if you set the optional `setExtent` constructor property to true the map will be set to the extent of the newly loaded kml file. This works much better if the kml file has LookAt tags defined for the document and the features within it. Without that tag, kmltree will attempt to calculate an appropriate view automatically. This is computationally expensive and will cause the browser to freeze momentarily with complicated kml files.

Styling issues

• Placemarks will be displayed in the tree with the same icon that represents them on the map, assuming the user is not using Internet Explorer. This will not be possible in IE until it supports the CSS3 background-size property.
• Until this enhancement is made to the Google Earth API, use of the ItemIcon will be very limited. If an ItemIcon is set with a style tag nested within a feature, it will be used if the supportItemIcon property is set to true. This has negative performance implications though, so this feature should not be used for anything but very simple kml files. See this example.
• To support full html/js/css within description popups, enable them via the selectable option (Pay close attention to security notes).

Accessing Protected Content

When creating any non-trivial application, a common problem to run into is difficulty accessing protected content. For example, in MarineMap we needed to access shapes tied to a user's account that should be kept private to that user. Like most web frameworks, Django has built-in session management tied to the use of cookies. Unfortunately the Google Earth Plugin create's it's own channel for requesting information and does not make use of the same cookies that the host web browser manages. There also appears to be no way to set cookies for the plugin to use or set them from a webserver when it requests content.

This leaves only two options:

1. Use the plugin's support for http basic or digest authentication, or
2. Encode session information within web requests

Our testing indicates that http authentication options are fully functional, but the user interface is totally unsuitable for most applications. The login prompt seems to make use of odd operating system services and is usually revealed behind windows or minimized, and on OS X can become completely inaccessible after the window loses focus. There is also no way to use javascript to automate the login process for the user, necessitating the user log in once for the application and then another time for data layers.

Option 2 can actually work well, and is what we employ for MarineMap. We encode the session cookie in urls for protected data and handle it within our web application to authenticate requests. It is no less secure than transmitting session keys within a cookie because the same information is being transmitted over the wire. For absolute security, https should be used in either case.

The downside of encoding session keys within urls is that it prevents most caching mechanisms, so authentication should only be utilized for kml files that must be protected.