MapServe allows World Wide Web servers to serve clickable graphics with "hotspots" that can call any other document available on the World Wide Web via URLs.

First of all, you have to have a graphic file that you want to make clickable. This could be a map of something like a campus or a building, or just a picture that you want to highlight parts of. It's also useful for making graphical menus. It's all up to your imagination to come up with good uses for clickable "imagemaps" as they're called by many.

Once you have a graphic file, you need to make an HTML document that uses that graphic as an inline graphic. You can read about this in most all HTML documentation. To give you a quick example, say you have a folder on your server called "Graphics" and a GIF file called "MyMap.gif" inside it. You would link to that graphic using HTML like this: <img src="/graphics/mymap.gif" ISMAP>. The ISMAP part just tells the client's browser program that it needs to send the coordinates of where the user clicked to the server.

Next you must make the graphic clickable, and specify MapServe as the program to link to when the graphic is clicked. Do this by adding <a href="/path/to/mapserve.cgi$mapfilename"> </a> around the <img src tag.

So the complete HTML hyperlink reference to your clickable graphic named mygraphic.gif would be:

1. 
   <a href="www.eos.net/cgis/mapserve/mapserve.cgi$mygraphic.map"><img src="mygraphic.gif" ismap>
   
   

To add the "hotspots" to your graphic file, you need to make a map file that maps the coordinates and shapes of your hotspots to areas in the image file, and specifies the URL you want that hotspot to load up. There are a few good programs that can help you do this. One such program is WebMap, which allows you to draw the hotspots on top of your graphic. You can also use any program that can give you the coordinates of certain locations on your graphic, like Photoshop or GraphicConverter. Then simply put the coordinates and shapes into a text file following the map file format specified in the next section.

If you don't want to use WebMap to make your map files, or you want the added features available in MapServe that WebMap doesn't support at the time of this writing, then you need to know the format of the map file.

The map file is a plain text document that can be made with TeachText (or SimpleText) and many other text editors. For large graphics, you could even use a database program that can export it's data as tab or space separated text, though you're much better off just editing the text file yourself. (Also, very large, complex graphics with lots of objects defined will take longer to decode.) This map file or an alias to it must reside in the the same folder as the mapserve application. I hope to make it easier in the future to keep the map file with the graphic, instead of having to keep it with MapServe. Although, I don't know of too many sites that have more than 2 or 3 imagemapped graphics, so keeping track of those two or three really isn't much of a problem for most people.

The general form of each line is: shape URL coordinates where the shape specifies the shape or kind of hotspot, the URL specifies which document the hotspot should be linked to, and the coordinates are the coordinates in the graphic of the points that make up the shape.

Here is an example of a line that specifies a circle with it's center located at 13,12 and an edgepoint at 45,34:

circle http://your.server/folder/file.gif 13,12 45,34

Each line can be made up of any one of the following shapes or directives:

Comments

# this is a comment

A hash mark at the beginning of a line indicates a comment

Default

default URL

This defines the default URL that should be returned if the user didn't click on an object defined elsewhere in the file. If more than one default is specified, the last one is the one that is used as the default.

Note: If one or more point URL coordinates where coordinates is an X,Y pair

If the click doesn't occur within another object (rect,circle,poly,oval) and one or more points are specified, then MapServe determines the nearest point to where the user clicked, and returns the URL for that point.

The URLs that you specify in the map file can be either full URLs, which include the service type (http://, ftp://, gopher://, mailto:, etc.), and the full path to the file. If the file resides on your server, you can use a local URL, which must start from the root of your server (the folder that your server program resides in). Local URLs must start with a '/' character in the map file for MapServe to treat them as local. If a file is local, MapServe appends "http://your.server.address:port" to the front of what you specify as the local URL in the map file.

Since the fields in the map file are separated by whitespace (tabs or spaces), you cannot have any whitespace in your URL's (It's not a good idea to have any whitespace in any filenames on your web server). If you do happen to need to specify a URL for a file that has whitespace or funny characters in it's name, then you must encode that with the %xx encodings as specified in the MacHTTP/WebSTAR documentation, and several other documents specifying the use of URLs.

An example MapServe map file

#
# Order of entries does not matter, although the map will
# run faster if you put more frequently used objects at the
# top. Also, a little speed will be gained by placing the
# objects in the following order: Default, Rectangle, Circles,
# Ovals, Polygons, Points.
            
# default URL -- MapServe example
default /mapserve/
            
# Blue rectangle
rect /mapserve/mapservetest/blue.html 4,5 71,39
            
# Green circle
circle /mapserve/mapservetest/green.html 181,57 198,57
            
# Orange polygon
poly /mapserve/mapservetest/orange.html 224,23 219,55 268,67
281,24 257,4 250,36 224,23
            
# Red oval
oval /mapserve/mapservetest/red.html 99,2 167,46
            
# Point 1
point /mapserve/mapservetest/point1.html 7,73
            
# Point 2
point /mapserve/mapservetest/point2.html 105,76
            
# Point 3
point /mapserve/mapservetest/point3.html 312,69
            
# Point 4
point /mapserve/mapservetest/point4.html 348,16

There are a few programs that will allow you to make the map file a little bit easier than figuring out where all the points are. One is WebMap, which is available for Macintoshes. Another good map file editor is MapMaker.