13/04/12

XML.com: Build AJAX-Based Web Maps Using ka-Map

Publishe d on XML.com http://www.x m l.com /pub/a/2005/08/10/k a-m ap.htm l Se e this if you're having trouble printing code e x am ple s

Build AJAX-Based Web Maps Using ka-Map

By Tyle r Mitche ll August 10, 2005

The recent popularization of certain web technologies used by Google Maps has encouraged the development of more interactive web mapping techniques. Google's web mapping tools use a technology known as AJAX (Asynchronous JavaScript and XML). AJAX is a style of web application development that uses a mix of modern web technologies to provide a more interactive user experience. Wikipedia has a good discussion of AJAX technology. By using AJAX, Google's maps draw and zoom quickly, pan smoothly, and can be extended to display a wide variety of information. This article shows how to make similar AJAX-based web mapping sites using an open source web mapping toolkit called ka-Map. ka-Map uses the MapServer web mapping server behind the scenes with AJAX and PHP to serve up the map content. All this comes together to provide a highly interactive means to viewing maps online. Google Maps provides some very powerful tools, but once you want to add your own data layers, or further customize your own components, it may be easier to use your own toolkits. Tools exist for creating your own AJAX-based web mapping sites and are fairly easy to use. ka-Map coupled with MapServer is a powerful combination of open source web-mapping technologies. For a good example of a ka-Map application see DM Solutions Group's Maps for MapServer site.

AJAX Mapping Power

The open source MapServer web-mapping platform is the tool of choice for many web developers wanting to publish maps online. MapServer's robust set of features and widespread use provide a solid base for a stable, interactive web-mapping experience. However, MapServer alone doesn't provide the level of interactivity, prerendering, caching of tile images, smooth panning, etc. that many users are turning to AJAX for. ka-Map is also open source and works directly with MapServer. MapServer prepares the map images, ka-Map serves them to the web browser. ka-Map also caches (saves copies of) maps as they are created by MapServer. When the same area on the map is viewed again, MapServer sits idle while ka-Map grabs the cached map image tiles. This is a departure from the traditional cycle: start map application, click to zoom in, wait for entire map image to be created, wait for the browser to receive the image, click again, repeat. Instead, small pieces of the map are created
www.xml.com/lpt/a/1606 1/12

Related Reading

13/04/12

XML.com: Build AJAX-Based Web Maps Using ka-Map

once when first requested and stored on the server. As they are created, they are sent to the web browser and the web browser pieces them together as they are received.

Preparing MapServer

Web Mapping Illustrated Using Open Source GIS Toolkits By Tyler Mitchell

To use ka-Map, you need to have a working MapServer application configuration file. In traditional (nonAJAX) MapServer applications, you create web pages, prepare data, create a configuration file that points to the data, and set up the look and feel of the map. For a ka-Map application you can ignore the web page set up by using the default one that comes with it. Instead, the focus is on preparing map data and setting up the MapServer application configuration file. MapScript Programming Library You must have the MapServer programming library, MapScript, up and running. ka-Map uses the PHP MapScript API to render maps. The easiest way to do this is to use one of the binary MapServer installers that are available. The Windows installer is called MapServer For Windows (MS4W). You simply unzip some files onto your drive and you are ready to go. You can then install other packages that make certain functionality available, e.g. ka-Map. See here to get started with MS4W: http://maptools.org/ms4w. The Linux installer is called the FOSS GIS Suite (FGS). FGS includes a standardized set of modules, including all library dependencies preconfigured to run together. FGS has an installer shell script, which takes a module and automatically extracts it to your system. It also checks dependencies and grabs other packages as required. Get started with FGS here: http://maptools.org/fgs. The MapServer website has more installation instructions if you want to start from source code. I also walk through this process in Web Mapping Illustrated. Data Preparation Before you move on to creating a simple MapServer configuration file, you need some map data. Global country border data are available here as part of a FreeGIS.org world data package. It provides a basic set of map data in the ESRI Shapefile format. You will need the files starting with c u t i s s m l These are low-resolution onre_ip. files to keep the file size small. If you want a higher resolution dataset, grab the one from here instead. As an image backdrop, you will use a global cloud image from here. It was created from Xplanet data and a weather map hack from the book Mapping Hacks. Using their hack you can download a new image every six hours and have it automatically update your web mapping applications with current global cloud cover. The image is a TIFF file, with an additional TFW file that provides the information to geolocate the image. Extract both the country boundaries and image file into a folder called data.

MapServer Configuration
www.xml.com/lpt/a/1606 2/12

13/04/12

XML.com: Build AJAX-Based Web Maps Using ka-Map

Next, you need to create a MapServer application configuration file. This is a simple text file that tells MapServer how to access data and draw the map. This file is commonly called a mapfile. It contains several sections called objects. They start with a keyword for the object type and close with the E Dkeyword. N Here is a basic map file using the two data layers mentioned above:
MP A NM goa_a AE lblmp SAU O TTS N SZ 6030 IE 0 0 ETN -8 -0109 XET 10 9 8 0 UISD NT D IAEOO 252525 MGCLR 5 5 5 IAEYEpg MGTP n WB E IAEAH"otfsap/aa-../tostp" MGPT /p/g/pskmp011hdc/m/ IAER "k-a/m/ MGUL /amptp" ED N LGN EED TASAETTU RNPRN RE ED N SAEA CLBR TASAETTU RNPRN RE ED N LYR AE NM cod AE lus TP RSE YE ATR SAU O TTS N DT "aadycod.i" AA dt/a_lustf ED N LYR AE NM cutis AE onre TP LN YE IE SAU O TTS N DT "aacutissmlsp AA dt/onre_ip.h" CAS LS NM "onr Budre" AE Cuty onais SYE TL CLR201010 OO 0 0 0 ED N ED N ED N ED N

Save the above into a simple text file named g o a . a . lblmp Testing the Map File Incorrect settings in your map file will cause problems. Before trying to use a map file with ka-Map, you should
www.xml.com/lpt/a/1606 3/12

13/04/12

XML.com: Build AJAX-Based Web Maps Using ka-Map

test it. Depending on how you have MapServer installed, you may have a program called s p i g This command-line h2m. tool uses the map file to create an image file. You run it like:
>spig- goa.a - ts.n h2m m lblmp o etpg

If all goes well, there should be a t s . n image file containing a map. If the program fails or gives errors, then etpg you have a problem with your map file. Further testing may be required to fully guarantee that the map file is working, but this test is a good first cut. To make sure that the maps created from the map file are going to be readily accessible to a web server, you should also test it in a web environment. This is discussed further in the "Further Adventures" section below.

Preparing ka-Map
If you were building a traditional MapServer web map, the next step would be to create some HTML form pages and process it with the MapServer CGI executable. With ka-Map, you can get started out-of-the-box with minimal configuration. First, you need to have ka-Map's configuration files and PHP scripts. ka-Map comes in three different packages. 1. As a source package from the ka-Map section of MapTools in the form of: A g'zipped tar ball archive A zip format archive An online CVS repository 2. As a module for the FGS Linux Installer, grab it by using the command:
fsisalkmpbs:.. ht:/lmpol.r/lfsmdls g ntl aa-ae011 tp/d.atosogd/g/oue/

3. As a zip package for MapServer For Windows (MS4W). The ka-Map 0.1.1 distribution is comprised of about 38 files: Two JavaScript scripts Two text files Two HTML files Eight PHP scripts 24 GIF/JPEG/PNG images You may have more files than this if you acquired a different version of ka-Map. The files are stored in a very simple folder structure:
www.xml.com/lpt/a/1606 4/12

13/04/12

XML.com: Build AJAX-Based Web Maps Using ka-Map

..kmp011 ./aa-../ ..kmp011hdc/ ./aa-../tos ..kmp011hdc/mgs ./aa-../tosiae/

You then create another folder for storing map-image tiles generated by ka-Map:
..kmp011hdc/m/ ./aa-../tostp

All the files you are going to deal with are in the h d c folder. To keep things really simple, move the map file tos and data folder here as well. Your structure should look like:
..kmp011hdc/lblmp ./aa-../tosgoa.a ..kmp011hdc/aacutissml* ./aa-../tosdt/onre_ip. ..kmp011hdc/aadycod. ./aa-../tosdt/a_lus*

Security Warning In a production or public environment it is not a good practice to put your g o a . a file in a publicly lblmp accessible location. This example is meant only for internal testing and to keep folder management to a minimum for getting started. Because g o a . a is in the h d c folder it can be accessed through a web URL. This is lblmp tos a particularly bad idea if you are connecting to databases in your map file where database user names may be explicitly set. This commonly used folder structure keeps the h d c folder separate from the map file and data: tos
..kmp011mpgoa.a ./aa-../a/lblmp ..kmp011dt/onre_ip. ./aa-../aacutissml* ..kmp011dt/a_lus* ./aa-../aadycod.

Web Server Aliases To allow your web server to use ka-Map, you need to set some web server aliases. With FGS and MS4W this may be done for you automatically. Otherwise, you will need to add something like this to your web server configuration, for example in an Apache h t d c n file: tp.of
Ais/amp "otfsap/mp011hdc/ la k-a/ /p/g/pska-../tos" <ietr "otfsap/mp011hdc/> Drcoy /p/g/pska-../tos" OtosIdxs pin nee AlwvrieNn loOerd oe Odralwdn re lo,ey Alwfo al lo rm l <Drcoy /ietr>

This allows you to enter a simple URL (/ a m p ) and have it point to the file path where ka-Map content is k-a/ stored. ka-Map Configuration Files ka-Map comes with one main configuration file:
www.xml.com/lpt/a/1606 5/12

13/04/12

XML.com: Build AJAX-Based Web Maps Using ka-Map

..kmp011hdc/ofgpp ./aa-../toscni.h

Once the handful of settings in this file are set, you will have a fully functioning ka-Map application. For FGS and MS4W packages, many of these settings are already taken care of. There is documentation throughout c n i . h to guide you through each setting. There are only three different types of settings that ofgpp you really need to worry about.
Setting Up Library Pointers

ka-Map requires both PHP MapScript and the GD module for PHP. c n i . h needs to point to these ofgpp library files (around line 23):
$zHMpcitoue='h_asrp_v_e....ea..H_HI_UFX sPPaSrpMdl ppmpcitcsrl460bt2'PPSLBSFI; $zHGMdl ='h_d'PPSLBSFI; sPPDoue ppg..H_HI_UFX

The first one points to the file name prefix for the PHP MapScript library. This looks somewhat verbose, because the above example uses a very recent beta version of PHP MapScript. You change this to match the filename for the p p m p c i tlibrary that is on your system. In many cases this looks as simple as: h_asrp
$zHMpcitoue='h_asrp..H_HI_UFX sPPaSrpMdl ppmpcit'PPSLBSFI;

Or:
$zHMpcitoue='h_asrp_6'PPSLBSFI; sPPaSrpMdl ppmpcit4..H_HI_UFX

The documentation says that the pointer to p p g will likely need to be changed to p p g 2 if running on h_d h_d, Windows. Note that the P P S L B S F I variable will automatically add the filename suffix. For example, . oor H_HI_UFX s . l , depending on your operating system. Don't include the suffix in this filename setting. dl
Adding Your Map File

To have your custom application show up in ka-Map, you need to tell ka-Map where your map file is, as well as some other map-specific settings. Around line 80 you'll find the settings for the $ s M p i e array. It will azaFls already be set to use a mapping application called G a , but you can change it to match this one: Mp
$sMpie =ary azaFls ra( "ete" wahr = ary "lblWahr, > ra( Goa ete" "otfsap/aa-../tosgoa.a" /p/g/pskmp011hdc/lblmp, ary 10000 5000,1000 ) ra( 0000, 0000 5000 , "N" PG) ) ;

This sets up an array of information, all stored within the $ s M p i e variable. The first setting is the name of azaFls the ka-Map instance you are configuring; in this case the application is called " e t e "and uses the wahr g o a . a file you created earlier. This name is used in other places, as you will see later on. lblmp The second setting is the text, " l b l W a h r , which is the name that will appear in the drop-down box on Goa ete" the web page. From this drop-down you can choose which map file you want to use.
www.xml.com/lpt/a/1606 6/12

13/04/12

XML.com: Build AJAX-Based Web Maps Using ka-Map

The third setting points to the location of the g o a . a file. Depending on how your system is configured, this lblmp will vary. In this example, g o a . a was stored in the ka-Map h d c folder, alongside the data folder. lblmp tos
Setting Map Scales and Image Formats

The fourth setting is a list of scales. These are the map scales that the user will be allowed to view the map at. For example, 1,000 would be the map scale as a representative fraction of 1:1,000. This means that one inch on screen represents one thousand inches on the ground. The final setting is the output image format to be used, in this case " N " PG. Note that there are two closing parentheses, one after " N " which ends the settings for the " e t e "array. PG, wahr If you want to add more than one instance to ka-Map, put a comma after this parenthesis and create a whole new instance key. The second closing parenthesis is on a separate line and followed by a semicolon. It ends the settings for the $ s M p i e array. azaFls With those changes made to c n i . h , you are ready to test your map. ofgpp

Testing the Basic Application

If you've made changes to your web server configuration (e.g. set up new aliases) then you need to restart the web server. Restart the Web Server With FGS, it's as easy as initializing the FGS environment and then stopping-and-starting the FGS server:
>./p/g/eevs otfsstn.h *FSrnierayi 'otfs,uefscmad G utm ed n /p/g' s g omn. >fsso g tp /p/g/t/ntdaah so:htdsopd otfsecii./pce tp tp tpe >fssat g tr Poesn cni drcoy /p/g/w/ofd*cn rcsig ofg ietr: otfswwcn./.of Poesn cni fl:/p/g/w/ofdkmpcn rcsig ofg ie otfswwcn./aa.of /p/g/t/ntdaah sat htdsatd otfsecii./pce tr: tp tre

With MS4W you need to stop and restart the Apache process. This often runs as an application in its own command window. You can open that window and press the C R + key combination to stop the Apache web TLC server. Then start it again by launching the a a h . x file found in C \ s w a a h \ If Apache was pceee :m4\pce. installed as a service, then it can be restarted using the Services application in the Windows Control Panel, under Administrative Tools. Load Map
www.xml.com/lpt/a/1606 7/12

13/04/12

XML.com: Build AJAX-Based Web Maps Using ka-Map

Now you should be able to access your map using a modern web browser. Firefox and Internet Explorer work well with this example. Safari web browser on OS X seemed to only partially work as some of the page layout was broken. Open up the URL to the ka-Map instance. For example, with the default FGS install you would open:
ht:/oahs:00k-a/ tp/lclot88/amp

When you install FGS, you are asked what port the web server should run on. The default is 8 8 . With MS4W 00 it defaults to port 8 . The port number in the URL should be replaced by your web server port, or left blank if it 0 is running on the default port 8 . 0 Figure 1 is a screenshot of Firefox displaying the initial map. Adding the key/reference map in the lower-right corner will be introduced in another section.

Figure 1. Initial web page view of tutorial application Be patient the first time around, as it may take a minute to get started. Each time you zoom in it will create a new master map, tile it up into tiny chunks, and store it on the server. Then it will send you just the pieces that you need. Navigating the World The interface is simple. Click Zoom In for more detail and Zoom Out for less. The image data used in this
www.xml.com/lpt/a/1606 8/12

13/04/12

XML.com: Build AJAX-Based Web Maps Using ka-Map

example is very low resolution, so zooming in doesn't look that great. But, you have the option of using any data you want for your application. When you want to centre the map on a particular location, you have two choices. You can click-and-drag the map around until the area of interest is in the middle of the map. Then zoom in more if you'd like to see that area in detail. Another way to move the map around is by quickly double-clicking on a location. This will automatically center the map on that location -- it's a neat effect. Keyboard shortcuts include the plus (+) and minus (-) keys for zooming in and out. You can also use Page Up, Page Down, Home, End, and the arrow keys to pan the map. Click on the map once first to enable these controls.

Adding a Key/Reference Map You don't need to have a reference in your application, but to add one you need a R F R N Esection in the EEEC g o a . a file. You can add it right after the S A E A . . N section: lblmp CLBR.ED
RFRNE EEEC ETN -8 -0109 XET 10 9 8 0 SZ 2111 IE 4 2 IAEdt/emppg MG aakya.n CLR- - OO 1 1 1 OTIEOO 2500 ULNCLR 5 ED N

This example requires a reference map image named k y a . n to be saved with the cloud image and emppg shapefiles in the data folder. You can download Figure 2 and use it for your reference map image.

Figure 2. Reference map image (k y a . n ): emppg ka-Map will automatically show the current extent of the map using a red box on top of the reference map, as shown in Figure 1.

Troubleshooting
Can't get ka-Map working? Here are some tips for improving your experience or finding problems with your setup.
www.xml.com/lpt/a/1606 9/12

13/04/12

XML.com: Build AJAX-Based Web Maps Using ka-Map

Use a more recent web browser version. AJAX is highly dependent on recent web browser technology. Check your web server aliases to make sure that the /ka-map/ directory points to the proper . . k m p 0 1 1 h d c folder. ./aa-../tos Test your map file by running s p i g If you don't have this utility already, you should get it. If it doesn't h2m. work with your map file, then ka-Map won't either. s p i galso comes as part of the precompiled h2m FWTools collection. Check your temporary/cache folders. For simplicity, your map file I A E A Hand I A E R should MGPT MGUL correspond to the $ z a e a h D rsetting in c n i . h . If no files are being made in that folder, sBsCcei ofgpp then your settings are to blame. Ensure that the web server is allowed to write in that folder. Turn on the debug option in config.php. Setting $ D b g = t u will draw the rectangles of the tiles on beu re top of your map data. If nothing appears, then you have a problem with the ka-Map installation. Consider using a more recent version of ka-Map (e.g. using CVS). There are bug fixes, performance improvements, and new features in newer versions, but I have found 0.1.1 to be the most stable at present. More recent versions of ka-Map come with a s r p s folder, which the user that the web server runs as cit must be able to write into that folder. If you are familiar with JavaScript, you could also install a debugger that can help you debug configuration problems. Consider using Mozilla's Venkman debugger. If you are still having problems, you can try loading the i i . h file in your URL to see more runtime ntpp settings and errors (e.g. h t : / o a h s : 0 0 k - a / n t p p t p / l c l o t 8 8 / a m p i i . h ).

Further Adventures
Testing the Map in a Web Context The settings used in the global.map file are very simple, but in a production environment you may need to change them. You may end up wanting to change the I A E A Hand I A E R settings to put your temporary map MGPT MGUL images somewhere else on your filesystem. These settings also specify where the web browser will be able to find the map images. If you have IMAGEURL set wrong, then the web server won't be able to make the map available to the user. The best way to test for this is to write a simple PHP script and test running it. Take the following PHP script, save it to your kamap-0.1.1/htdocs folder and then load it up using a URL like h t : / o a h s : 0 0 k tp/lclot88/a mpmpetpp a/ats.h.
<pp ?h d(ppmpcit'PPSLBSFI ) l'h_asrp..H_HI_UFX ; $Mp=m_eMpb('lblmp ) oa snwaOj goa.a' ; $Ig=$Mp>rw) om oa-da(; $zR =$Ig>aeeIae) sUL om-svWbmg(; eh "igsc$zR>; co <m r=sUL" ? >

If you map image is drawn, then things will work in ka-Map. If not, then you have some problems with your map file.

www.xml.com/lpt/a/1606

10/12

13/04/12

XML.com: Build AJAX-Based Web Maps Using ka-Map

Customize Look and Feel ka-Map doesn't automatically pick an appropriate scale for your web browser's window size or screen resolution. It always uses the first one you have specified in c n i . h . Therefore, it is difficult to know ofgpp exactly what your map will look like on another screen. This is more of a problem when the geographic extents of your application cover all your data. When there is more data outside your map area it helps fill the screen better. Customising the i d x h m code allows you to change the way the interface looks. For example, you can ne.tl change the colours, add logos, etc. Cleaning Up the Cache Sometimes you really need to clean out the cached tile data and start over, especially if you are modifying your map file or map scales. It would be good to have a more automated way of clearing the cache, e.g. a button on the web page. Until then, you need to delete all the files in your cache folder. For example, clear out all files and folders from / p / g / p s k m p 0 1 1 h d c / m / otfsap/aa-../tostp. Note that if you turn on the debug option, you will need to clear the cache when you turn it back off. Prebuilding Map Tiles Version 0.1.1 comes with a script called p e a h . h . This is a powerful tool that can really improve the rccepp initial performance of your application. You need to edit several pieces of the script before you can use it. Supply the map name (changing it from the default g a ) and set the scales that your map will be using. There is also a mp setting that calls the t l . h script. Make sure this points to t l . h on your server. iepp iepp If you comfortable with PHP, you could modify the precache tool to pick up the settings from c n i . h . ofgpp Then it could process all your maps for all the scales that your application is set up for. Legend Handling There have been some bugs in the way that legends are generated. If you do not include a L G N object in the EED g o a . a file, then the legend doesn't draw properly. Even if the L G N object is empty, it will allow kalblmp EED Map to render it properly. Having such a simple L G N object isn't a very good practice for normal MapServer EED applications, but works fine with ka-Map. By setting the T A S A E Toption, it makes the legend look good RNPRN on top of the web page background.

Advanced Functionality
More recent versions of ka-Map (i.e. CVS or version 0.2) have many more options and features. For example, an advanced, tree-like legend manager tool. This allows layers to be controlled as a group. This requires some more planning and appears to be somewhat unstable at present, but is certainly promising. There are options for setting transparency for layers. You can then make one layer semitransparent and see it overlaid on top of another. Combine this with layer-visibility control and you can make some really interesting
www.xml.com/lpt/a/1606 11/12

13/04/12

XML.com: Build AJAX-Based Web Maps Using ka-Map

tools. Some really powerful maps can be created using WMS data sources in your map file. This could, for instance, allow you to have one layer of changing data that is regularly updated, but never requires you to regenerate map tiles for all layers. This takes some thinking and caution, as you could easily flood a WMS provider, giving poor results, or mistreating a benevolent provider. Adding real-time WMS layers to your application is customisation that ka-Map does not come with out-of-the-box. If you want your WMS layers to be updated, then you will have to clear the cache and let it rebuild the cached tiles.

Conclusion
It took some time to get my first set up of ka-Map to work properly. I had switched between packaged source files and CVS, but found that the best way to get started was by using MS4W or FGS. The set up is relatively simple, but leaves little room for mistakes. Having an AJAX-based web-mapping platform is in high demand and ka-Map does a worthy job filling that need. Because it is an open source product, there is room for others to help develop it further. Whether you are a user or a developer, you can play a part in making the product better and more stable. I hope you enjoy using it as much as I have.

Links and Resources

In a previous article and some weblogs, I introduced some web-mapping tools. This is also the focus of my book, Web Mapping Illustrated. I have focused on the open source tools that are freely available, very powerful, in active use, and under continual development. Here are links to some of the products and web sites mentioned in this article. MapTools - http://maptools.org/ MapServer - http://ms.gis.umn.edu/ ka-Map - http://ka-map.maptools.org/ FreeGIS - http://www.freegis.org/ FWTools - http://fwtools.maptools.org/ Web Mapping Illustrated - http://oreilly.com/catalog/webmapping Mapping Hacks - http://oreilly.com/catalog/mappinghks My other articles and weblogs - http://www.oreillynet.com/pub/au/1898 In June 2005, O'Reilly Media, Inc., released Web Mapping Illustrated. Chapter 3: Converting and Viewing Maps (PDF), is available free online. You can also look at the Table of Contents, the Index, and the full description of the book. For more information, or to order the book, click here.
XML.com C opyright 1998-2006 O 'R e illy Me dia, Inc.

www.xml.com/lpt/a/1606

12/12