Customizing the ka-map interface

From Ka-Map Wiki

A brief (well, it was supposed to be brief) tutorial / tour of the ka-Map interface

Contents 1 Introduction 2 Background 3 index.html 4 Bare Bones 4.1 the html 4.2 the javascript 4.3 the stylesheet 5 Disecting a Sample Interface 5.1 the html 5.2 the javascript 5.3 the stylesheet 6 The End

[edit] Introduction

So you've gotten your ka-map up an running on your web server and you're sample interface provided isn't just how you want it. Where on earth do you start editing? What are all these files for? Hopefully after reading this little tutorial you'll feel a bit more comfortable creating your own layout that uses all the awesome tools provided in the ka-map toolbox.

You're gonna be editing some HTML and then tweaking the CSS and then using some javascript to get everything set up just as you want it. Ready?

[edit] Background

Let's first take a look at the big picture...

ka-Map is built on top of the wonderful open source Mapserver. "But wait, ka-Map is so much cooler than Mapserver... it's so much more responsive than all the other Mapserver apps I've seen out there. Why is that?", you may ask... Well, Mapserver when stripped of its outer shell or HTML and php is basically a CGI executable that when sent certain parameters (a mapfile, view extents, etc) will spit out a jpg or png image that you can show wherever you want in your web page.

Now what ka-map does is it takes the image that Mapserver generated and places it in a 'viewport'. ka-Map also includes all the tools necessary to zoom, pan, query, and control the layers of the map. These tools were developed using AJAX technology (Asynchronous Javascript And Xml) and communicate with the web server asynchronously, which means that, for example, if you query the map you don't have to wait for a response before you can do something else, like zoom in, or whatever. The good folks of the open source community did the hard work of developing these tools and gave us these tools to use however we wish in our own custom web mapping application.

[edit] index.html

What a better place to start than at the beginning? If you take a look at your ka-map directory you'll see that there are a few different index.htmls (if you downloaded the latest release of ka-Map). Try going to ka-map in your web browser and add on "index_query.html" to the address. (For example, instead of http://localhost:8080/ka-map/ add on the different index filename so it looks like http://localhost:8080/ka-map/index_query.html) Whaoh! That looks a lot different, huh? Try checking out the other index_*.htmls that you find in your ka-map directory. Cool, eh?

[edit] Bare Bones

Ok, so we're just starting out, why not keep it simple? Let's look at a bare bones ka-map interface that includes just enough to show your map and to zom in/out and pan? Open up iframe.html in your web browser (html://localhost::8080/ka-map/iframe.html). Simple, eh? Yet awesome at the same time!

Now go ahead and open up the file in a text browser. The description at the beginning should show:

**********************************************************************
*
* $Id: iframe.html,v 1.6 2006/02/07 03:19:55 pspencer Exp $
*
* purpose: use as the source of an iframe to embed a ka-Map application
*          inside another page.  The intention is that you would copy
*          this page and then add more javascript functions and user
*          interface to it.
*
* author: Paul Spencer (pspencer@dmsolutions.ca)
*
**********************************************************************

Are we all in the same place? Sweet!

You'll notice that this file is made up of 3 main pieces:

• some HTML
• some javascript
• a CSS stylesheet

[edit] the html

What we are interested in right now is the HTML body at the very bottom. Wow! That is simple! All we have in the body is a viewport div and a kaLogo div.

But wait! The viewport is empty with the exception of a measly little kaLogo. Where is the map coming from?

Well, the viewport div is just a placeholder where the Mapserver-generated image will be placed dynamically by the ka-map tools. You don't have to worry about how or which image to put there because ka-map will take care of it. All you have to do is make sure there is a place to put your map, or viewport.

[edit] the javascript

So how is that map getting placed inside the viewport? Yep! You guessed it. It has to do with the javascript. (Did the heading of the paragraph give it away?) Take a look at the line that says: myKaMap = new kaMap( 'viewport' );. That command is found inside the myOnLoad function. That means that when the page is loaded it's going to create a kaMap instance and place it in the viewport.

Next myOnLoad creates a kaNav object so that you can navigate the map inside the viewport. kaNav then activated.

Also notice the line that says myKaZoomer = new kaZoomer(myKaMap); It just so happens that kaZoomer places itself inside the kaMap, always at the upper left corner. It doesn't need a div to go inside. This is an odd-ball, though. Usually you need to provide a place to put the ka-map objects (like the viewport or scalebar).

The javascript also controls how the page is drawn. Check it out. The drawPage function makes sure that the viewport takes up the entire window.

[edit] the stylesheet

Now take a look at the stylesheet. If you are familiar with CSS then this should all make sense. If you aren't familiar with CSS then you should check out some online tutorials like the one at http://www.w3schools.com/css/default.asp. You can play around with the stylesheet to control stuff like the position of the kaLogo, or the border around the viewport, etc.

[edit] Disecting a Sample Interface

[edit] the html

Ok, now let's take a look at a more complex interface. Why not the default index.html. Open it up in a text editor. You might want to save a copy of it first if you want to play around with it.

The description of the file should be:

**********************************************************************
*
* $Id: index.html,v 1.83 2006/09/25 10:37:28 lbecchi Exp $
*
* purpose: This is the sample ka-Map interface.  Feel free to use it 
*          as the basis for your own applications or just to find out
*          how ka-Map works.
*
* author: Lorenzo Becchi and Andrea Cappugi (www.ominiverdi.org)
*
* ka-Explorer interface has been developed for Food and Agriculture 
* Organization of the United Nations (FAO-UN)
* 
* original code: Paul Spencer (pspencer@dmsolutions.ca)
*
**********************************************************************

Are we all looking at the same file? Great! Just checking.

This file controls the basic content of our ka-map interface. It's style (colors, positioning, etc) are primarily controlled by the screen.css referenced by the line:

• <link href="tools/kaExplorer/screen.css" rel="stylesheet" type="text/css" media="all">

You'll notice that in the head also includes a bunch of ka*.js javascript files. By including these files we have access to the javascript tools I was bragging about earlier. Let's not worry about the content of those files. In a little bit we'll take a look at startUp.js referenced by:

• tools/kaExplorer/startUp.js

Before we move on to looking at the CSS and startUp.js files let's finish looking through the index.html file... Glance through the body of the page a bit. You'll notice a bunch of familiar text. You'll notice a few divs that are empty, like <div id="scalebar"></div> or <div id="contentText"></div>. These divs are placeholders for the scalebar or contentText that is going to be put there dynamically by the ka-map tools. You should already be familiar with the <div id="viewport">.

[edit] the javascript

Ok, let's go ahead and open up the tools/kaExplorer/startUp.js. This file is responsible for customizing the behavior of our awesome application. If you glance through it you'll notice that it includes a myOnLoad function as well as a drawPage function. These functions are a bit more complex because this application has a lot more functionality. This particular implementation of ka-map switches between services when you click on a tool in the toolbar. When you switch the service the content in the left sidebar will change.

For example purposes let's take a look at the myQuery function as it will give us some insight into how ka-map interacts with the mapserver.

In myOnLoad we registered myKaMap for the event KAMAP_QUERY with the line: myKaMap.registerForEvent( KAMAP_QUERY, null, myQuery );. This set myQuery as the event handler for a query event. Looking at the actual myQuery function we see that it takes the coordinates of the query as an argument and then it sets up the query parameters. The interesting part takes place when we execute the line:

• call('map_query_float.php?'+params,this, myQueryOutput);

call is a function that is part of the xhr.js library which is:

"a simple cross-browser XmlHttpRequest interface that adds support for multiple, concurrent requests"

Cool, eh? That means that the call function is actually makinc an asynchronous call to the server! Wahoo! We're doing AJAX now! In this case we are calling map_query_float.php with the parameters 'params', and when it is done it will execute the function myQueryOutput. myQueryOutput will then take the server's response (which will be loaded into the variable szText) and then spit it into the queryOut div.

If you want to customize the output of the query you can do so by editing map_query_float.php. We won't worry with that for now, though.

Be sure to glance through the rest of the startUp.js which is a great example showing how to use more of ka-Map's tools.

[edit] the stylesheet

I suppose now it is time to open up tools/kaExplorer/screen.css. There's no need to take too much time looking at this file as it should be pretty straightforward to an experienced CSS monkey.

You might want to take note of, for example, #layoutFrame which applies absolute positioning to the layoutFrame div but then it doesn't bother mentioning where to put it. This is because it's position is controlled by startUp.js. We just need to make sure that the stylesheet sets up the layoutFrame div is ready with absolute positioning when the javascript sets it with a top and left parameter.

[edit] The End

Go ahead and play around with this sample interface, or maybe look at the other interfaces provided in the ka-map directory (like index_query.html).

I hope this little tour through the top layer of ka-map helps you design your own super awesome ka-map! I'd love to hear your feedback via email at samhiatt at gmail!

If you need help don't be afraid to join the ka-Map-users mailing list and send us your question.

Contributed by Samhiatt, 1 August 2007