Overview
What Is jKMLMap?
jKMLMap is a flexible, easy-to-use Javascript library for generating a Google Map from a KML file and embedding it in a webpage.
The main concept behind this script is that once you have it up and running, presenting user-friendly maps requires nothing more than making a KML file in Google Earth and dropping it on your server; the rest is handled automatically: paths, markers, pop-up marker descriptions, and default views are all taken directly from the KML.
The library can also generate a hierarchical sidebar menu based on the folder structure found in the KML, which visitors can use to show/hide individual markers or groups of markers in realtime. And because all the loading is done via AJAX, swapping maps does not require reloading the page - it can be done dynamically.
Features:
- Automatically downloads a KML file and uses it to create an embedded Google Map.
- Maps include clickable paths and markers (with pop-up descriptions).
- Map views will automtically default to those set in the KML (and can be overridden).
- Downloading is performed asynchronously; realtime progress can be displayed as a new map loads.
- Collapsable sidebar menu allows users to dynamically add/remove/locate their markers.
- Marker icons are customizable based on the text found in marker descriptions.
- Doesn't depend on any third-party frameworks - just javascript.
- No limit on the size of the KML file (beyond your browser's capabilities and desired download time).
- Tested on IE6-9, Firefox 3-6, Opera 10, Safari 4, and Chrome 4-13.
(Note that larger KMLs are likely to be slow on IE6, due to its outdated js engine.)
Live Demo
You can see the script in action on my Travellog page.
Basic Installation
Getting your first KMLMap up and running is simple:
1. Include the Google Maps and jKMLMap javascript in your page's <head> section, like this:
<head> <title>My KML Map</title> <script type="text/javascript" src="http://maps.googleapis.com/maps/api/js?sensor=false" ></script> <script type="text/javascript" src="/jKMLMap.js" ></script> </head>2. Setup the div where you'd like your map to be output, including its height and width. By default, maps will be outputted to "jKMLMap" (this can be customized later):
<body> <div id="jKMLMap" style="width:800px; height:600px;"></div> </body>3. Initialize jKMLMap and tell it to load a KML File:
<script type="text/javascript"> //<!-- myKMLMap = new jKMLMap(); //Create a new jKMLMap Object myKMLMap.LoadMap( '/maps/testMap.kml' ); //Load a map // --></script>4. That's it! The script will download the KML file, parse it, and generate an embedded Google Map in the "jKMLMap" div. Now let's move on to some of the real features...
Configuration
Once you've got a simple KMLMap up and running, you're ready to play with a bit of customization. There are three ways to customize your jKMLMap: by passing options to its constructor, by registering event callbacks, and by modifying the GMap object directly.
Options
To specify options to jKMLMap, we pass a single JSON object to its constructor, like so:
<script type="text/javascript"> //<!--
myKMLMap = new jKMLMap({
mapDiv: 'kmlMapOut',
menuDiv: 'kmlMenuOut',
mkrBasic: null,
mkrLinks: CreateGIcon('/icons/book.png', 25, 20, true),
mkrSpecial: CreateGIcon('/icons/me.png', 39, 45, false),
mkrSpecialRegex: /Current Location/
});
myKMLMap.LoadMap( '/maps/testMap.kml' ); //Once initialized, load as usual
// --></script>
Here's what each of the options mean:
- mapDiv - Specifies the ID of the div where the map will be output; defaults to "jKMLMap"
- menuDiv - Specifies the ID of the div where the menu will be output; omit to skip menu generation.
- mkrBasic - An icon to be used for the map's markers. If unspecified or null a default icon will be used.
I've provided a global function CreateGIcon() to make it easier to create custom icons (described below). - mkrLinks - An icon that can differentiate markers whose pop-up descriptions contain a hyperlink.
- mkrSpecial - An icon that can differentiate markers with user-defined text in their descriptions.
- mkrSpecialRegex - A regular expression used to trigger a mkrSpecial. Default is "Current Location".
Callbacks
In addition to specifying options to the constructor, you can register callbacks to be notified when a certain event occurs. This is useful if you want to hide the menu while it's loading, show the user a progressbar, etc. Events are registered by calling RegisterCallback(name, func), like this:
<script type="text/javascript"> //<!--
myKMLMap = new jKMLMap();
//Register a callback to hide the menu and show a status div when loading begins
myKMLMap.RegisterCallback('onStart', function()
{
jQuery("#kmlStatusOut").toggle(true);
jQuery("#kmlMenuOut").toggle(false);
});
//Register a callback to show progress updates while loading
myKMLMap.RegisterCallback('onProgress', function(msg,percent)
{
document.getElementById('kmlStatusOut').innerHTML = msg + " ("+percent+"%)";
});
//Register a callback to hide the status div and reveal the menu when complete
myKMLMap.RegisterCallback('onComplete', function()
{
jQuery("#kmlStatusOut").toggle(false);
jQuery("#kmlMenuOut").toggle(true);
});
myKMLMap.LoadMap( '/maps/testMap.kml' ); //Load the map as usual
// --></script>
Google Maps API
Another way you can customize your map is by modifying it directly with the Google Maps API. For example, if you want to manually override the view parsed from the KML:
<script type="text/javascript"> //<!--
myKMLMap = new jKMLMap();
myKMLMap.RegisterCallback('onComplete', function()
{
myKMLMap.map.setCenter(new google.maps.LatLng(-164, 9.5), 2);
});
myKMLMap.LoadMap( '/maps/testMap.kml' );
// --></script>
There are loads of advanced customizations you can achieve directly with the Google Maps API.Map Switching
One handy feature is that it's easy to dynamically swap between maps without requiring the user to reload the page. You can see my Live Demo for an example of this:<h3>Map Selection:</h3> <form name="mapSelection" action="javascript:void(0);"> <select onchange="myMap.LoadMap(this.options[this.selectedIndex].value)" name="k"> <option value="/kml/map1.kml">Current Location</option> <option value="/kml/map2.kml">My Trip to Europe</option> <option value="/kml/map3.kml">RoadTrip 2010</option> </select> </form>
Download
Latest Version: 1.1.0 (8/26/2011):
- Production Version - YUI Compressed Javascript. Most users should download this version.
- Development Version - Uncompressed Javascript. For coders wanting to modify the script themselves.
License & Usage
This script is released under the creative commons Attribution-ShareAlike 2.5 license for personal use, meaning you're free to use, modify, and redestribute it as you see fit - provided that you do not represent it as your own work, and that you attribute it to me as the author. By default the script will output a very small "Created by jKMLMap" link below the map itself; as long as you don't remove it, you're fine. If it is necessary to remove it for aesthetic reasons, you must replace it with something similarly visible that refers back to this page. Other than that, it's all yours.
If you're interested in using it commercially, please contact me directly.
Feedback/Support
If you have feedback or support requests, please use the comment form below and I'll reply as soon as I can.
Beautiful plugin. I’d love to see it working with an event’s calendar !
Thanks!
Haha with the nearly 500 comments on one of my other plugins I’d wondered if anyone even noticed this one – but I guess in general people like plug-and-play better than something that requires writing actual code 
I’d be interested to see your use for it, if you do get one up-and-running!
Great Job Justin. Thanks
Looks great. Been looking for a wordpress plugin to visualize my travels for ages. Now before I start, do you know of a good and free KML editor? preferably a visual one? The only one I can find doesn’t seem to work with the latest Google Earth version…
It definitely works with Google Earth – that’s exactly what I wrote it for (and what I used to make everything on the travellog)!
*putting on my confused look* I thought one has to manually generate a KML file? I googled and all I found was Google’s explanations how to hand-code a kml file… which is kind of hard and takes forever!
Are you saying I can use Google Earth to create a kml file? Any hints how to do that?
I was asking for a graphical tool to create a kml file. Found one but not compatible with the latest Google Earth..
Right click on any folder of placemarks/paths and save it as a kml file…
Alternatively, you can export KML’s right from google maps in your web browser…
well and how do I get those placemarks? Anyway, currently playing around with Google Earth, searching for places, then saving them into my places, then exporting my places as KML….
so good so far but is there a way to connect them? I understand that Google Earth KML files support paths as well… reading the manual if you have a shortcut for me or a hint please speak up
not sure about where to do step 4:
`4. Initialize jKMLMap and tell it to load a KML File: `
where do I insert that code? in the palce I want the output or Insert it into the header?
sorry for these newbie questions I am a plugin user but I am getting slowly where I want to be with your script here…
I think I figured things out, I mean where to position them. But now there is no error, nothing, the page just shows the basic Google maps controls and nothing else !?
Here you can find my page template: http://pastebin.com/rctBuT1J here is the livepage: http://pacura.ru/travelmap/ and all I can supply is that there is nothing in the error log only firebug reports this on the page: `document.getElementById(“jKMLStatus”) is null
Line 240`
Besides this info, these scripts are loaded via a dynamic widget in my header: `
`
oh and in this tutorial you always refer to jKMLMap.js but I exchanged that with jKMLMaps-min.js I hope that is right… I am playing around with your demo KML file so far.
I really hope you can give me a hint, please.
As stated in the instructions and sample code above, you need to give the map div your desired dimensions. You haven’t.
sorry I just thought I’d keep styling and content separate and added it in my cs file. its in the template now and your demo map is working just fine, check here: http://pacura.ru/travelmaps/ now onto creating my own.
Thanks a lot for this wonderful script!
Cool, glad you got it
There still seem to be a lot of bugs over there, but it’ll be nice to check it out once it’s finalized & up & running!
yeah, I tried different methods of including the js, via widgets, via the template file, etc…
but I’ll figure it out!
I’ll let you know once I got a proper kml map. still reading up on that trying to figure out how to add a path
hi,
Great work dud. I love it.
Thanks!
Hi, great library . Have you got this working with google api version 3 yet. Thanks
No
are you looking to get this working with V3?
Unless Google plans to depreciate the previous version, I didn’t really see any reason to
Great plugin!!!
I installed it on my site and I love it:
http://saragiovanni.com/rtwt-path/
Question, how do you create the sidebar widget that says: Current Location?
I tried but failed …
Thanks!
Giovanni
That’s a separate bit of code that I haven’t released, loosely based on jKMLMap but using the Static Maps API. It contains a lot of hard-coded stuff and isn’t really suitable for public consumption, but should be pretty easy to reproduce (as it only uses a small subset of jKMLMap itself, which of course is open-source
)
Hey Justin. Do you know what happened to the API? Your demo is not working and neither is the one on my website that was based on your code. =(
http://saragiovanni.com
Thanks.
Giovanni
I noticed it too, but won’t have time to look into it for at least a few weeks
Ukraine? Nice. Let me know when you take a look at it please!
I’ll be in Europe Sept/Oct/Nov, maybe we can meet up?
Love to if I’m still here! Plans are totally up in the air at the moment tho
OK, so I had a few minutes and got to it sooner than expected
You can grab the updated script from here for now, as I haven’t “officially” submitted it yet:
http://www.justin-klein.com/travellog_/jKMLMap.js
Hey Justin!
I changed the file “jKMLMap.js” on my server but that did not work unfortunately.
http://saragiovanni.com/the-route/
Anything else I need to do?
Thanks!
Giovanni
Include the v3 api instead of v2: http://maps.googleapis.com/maps/api/js?sensor=false (not http://maps.google.com/maps?file=api&v=2...)
Hey Justin!
That did it! Thanks!
Do you know how to change the color of a path? On Google Earth I have each path set on different colors but when I create the KML file and put it on my server, all paths are red…
Lastly, I’d like to show my map in MAP mode and not satellite mode for defaul. Thoughts?
Thanks!
Giovanni
All of this is hardcoded atm; you’ll have to edit the source if you want it to look different
Hi Justin.
Thanks for the feedback! I’m finally getting the hang of it. There is still a few questions I can’t figure out:
- How can I make it so that certain paths have one color and others have another? I looked into the docs for KML files and even though I make changes in my KML files, nothing happens.
- Same as above, change the icon for “visited cities” and another icon for “future cities”
- Lastly, I noticed that your script creates a default “center”. Can that be overridden by each KML? Or its the same center for all KML files?
I’m OK with hard coding it, I just don’t know where exactly? The KML files or the JS script?
Any advice would be appreciated!
Take a look at our current location image: http://saragiovanni.com/the-route
One more question, how can I make it so that the Lon and Lat of the center of the map be assigned in the backend?
I assume I can create a wp_options variable and pass these values via php into the JS function when I call
myKMLMap=new jKMLMap …
However, I have no idea what the syntax would be. Any idea or do you have a better method?
Thanks!
Giovanni
For all of these, please refer to the JS first which is pretty thoroughly commented – I’m sorry but I really don’t have the resources to personally provide such user-by-user customization/instruction for each of my free plugins (especially while traveling, as I sometimes get hundreds of requests a day when I already have far more work requests than I can take on
).
Hard coding means the JS. View is automatically set by the KML, or can be changed by manipulating the map object directly, as documented above. Icons can be changed via the JSON object parameter, as documented above.