What Is jKMLMap?
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.
- 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.
- 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.)
You can see the script in action on my Travellog page.
Getting your first KMLMap up and running is simple:
<body> <div id="jKMLMap" style="width:800px; height:600px;"></div> </body>3. Initialize jKMLMap and tell it to load a KML File:
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.
OptionsTo specify options to jKMLMap, we pass a single JSON object to its constructor, like so:
- 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".
CallbacksIn 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:
Google Maps APIAnother 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:
Map SwitchingOne 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:
Latest Version: 1.1.3 (01/03/2013):
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.
If you have feedback or support requests, please use the comment form below and I'll reply as soon as I can.