Customizingp.

mapper(notatutorialbut
insight)
I am responding to a request by one user following an earlier post that I did on p.mapper.
Basically, (s)he needs a p.mapper tutorial for customizing p.mapper based on my experience. It
was quite a while ago that I did my p.mapper customization, and in any case, making a tutorial
at the moment is fairly a tall order for me. I cannot afford to make a tutorial, but I can share
my experience. One thing I should not hesitate to say is that pmapper customization is very
simple, but without prior experience, it will require some serious reading.
I hope the summary that I will give below will help the user and any others who might want to
start customizing p.mapper. This summary is based on my personal experience and may not be
absolutely perfect, but considering the kind of application that I have customized, and which is
being used as a platform for sharing maps, I have no doubt that the things that I did were the
right things to do. In addition, everybody (and anybody) is welcome to supplement my humble
submission as it may be very basic and not comprehensive at all.
A basic assumption I am making is that one already has p.mapper 3.2.0 (or other version??)
installed and the demo version is running. If not, installation can be a subject for another time
- but dont forget that there are existing tutorials on p.mapper installation. And installation is
a piece of cake, anyway.
For starters, the following three files are the key ones that will require some editing in the
p.mapper customization process:
File1: config/default/pmapper_demo.map (you may want to rename this file to your own)
File2: config/config_default.ini
File3: config/default/php_config.php
Another important file is search.xml for search/identify functionality (note that for search
functionality to work, you must have TEMPLATE in the layer definition in the map file - you can
just have TEMPLATE void for this sake).
Yet another important file is php.ini in the cgi-bin folder of Apache. There are several settings
that can be done from this file. One of the settings of interest to me is for releasing session
variables (setting no cookies i.e. session.use_cookies = 0) which helped me a lot in ensuring
that each session starts from its own defined map parameters - map extent, projection,
window size, etc. Without this setting, subsequent sessions would not load as expected.
Other files that I edited for enhancements are: pm_cjs, dialog, layout, print, and epsg_list. You
should also have your shapefiles saved somewhere within the main folder.
I will handle only the first three files in this post. In my illustration, I will show how to make
two layers, one polygon called Parishes and a point layer called Clinics. At the end, you
should be able to see your clinics within the parishes.
Throughout this guide, note that a single quote is very different from a double quote . So be
careful to put exactly the type of quote that you see. Also note that you will simply be editing
settings in all cases since they already exist in the files by default.
1. File1: config/default/pmapper_demo.map
This is the map file which contains your map configurations - projections, map extent,
formatting, scale bars, map layers, etc. You would obviously want to re-name the file to your

favorite - but also remember that there are references made to this file from other files. If you
do a simple search of files containing the word pmapper_demo, you should be able to track
files that reference pmapper_demo.map so that you can change the names accordingly.
Note that in this file, a "#" means comment.
1.1 Start by setting the following parameters (use your own values for the settings - the values
you see are for my specific case):
EXTENT 445491.484879 23700.879953 463188.684821 44757.138863
UNITS meters
SIZE 600 500
SHAPEPATH "../../../pmapper-3.2.0/data" #path of shapefiles
RESOLUTION 96
IMAGETYPE png
INTERLACE OFF
PROJECTION
"init=epsg:21096"
END
1.2 Some other optional settings are:
SYMBOLSET "../common/symbols/symbols-pmapper.sym" #path of symbol files
FONTSET "../common/fonts/msfontset.txt" #specify path of fonts file
1.3 In this file, you will also specify all layers that will appear in your p.mapper application. An
example of a layer definition is below:
#Parishes Layer
#
LAYER
NAME "Parishes" #Layer name
TYPE POLYGON
DATA "Parishes"# this is the name of the shapefile
TRANSPARENCY 90
METADATA
WMS_TITLE "ParishesMap"
WMS_ABSTRACT "Parishes shapefile."
WMS_SRS "epsg:21096"
END
# Use field DIVID for symbology
CLASSITEM 'DIVID'
CLASS
EXPRESSION '61'
NAME 'KAWEMPE Division'
OUTLINECOLOR 0 0 0 #really black
COLOR 251 202 181 #255 102 153
END
CLASS
EXPRESSION '62'
NAME 'NAKAWA Division'
OUTLINECOLOR 0 0 0 #really black
COLOR 210 214 95 #255 255 0

END
# You can have as many classes as you wish
TEMPLATE void
TOLERANCE 0
TOLERANCEUNITS miles
END
#
#Clinics Layer
#
LAYER
NAME "Clinics" #Layer name
TYPE POINT
DATA "allkccclinics" #this is the name of the shapefile
SYMBOLSCALE 300000 #Scale at which symbol attains MAXSIZE below
CLASS
NAME 'Clinics'
STYLE
SYMBOL 'circle'
color 0 0 255
MINSIZE 14
MAXSIZE 26
END
END
TEMPLATE void
TOLERANCE 6 #3
TOLERANCEUNITS pixels
METADATA
WMS_TITLE "Clinics"
WMS_ABSTRACT "Clinics in Kampala"
WMS_SRS "epsg:21096"
END
END
#
Note: There is a very good tool for automatically generating map files from a formatted map
document done using MapWindow (an opensource GIS application). See my post on this subject.
2. File2: config/config_default.ini
This configuration file requires editing in several sections. Below are some of the sections that
I edited.
Note that in this file, a ";" means comment.
2.1 Start with this:
; LAYERS/GROUPS DEFINED MANUALLY - here specify the layer names that you defined in the

.map file above

; ALL groups displayed in TOC in this order
; - without definition, the order from map file will be taken.
; - separated with commas
; if INI setting "useCategories = 1" (see below),
; then define the categories in php_config.php
; === RECOMMENDED ===
allGroups = Parishes, Clinics
2.2 Then also check the following sections in the file (do a search in file and see self
explanatory comments)
; Default Groups (visible at start)
; Groups/Layers that shall be mutually disabled
; Groups/Layers list where to use auto_identify (tooltip) function
2.3 Take time and go through this config file thoroughly. You will find a lot of enhancements
that you can make to your application.
3. File3: config/default/php_config.php
Here you will find some extra enhancement settings.
Note that in this file, a "/* ... */" means comment.
3.1 Try out this optional setting:
If you wanted, for example, to group your two layers in one category called MyLayers, then
have the following in the php_config. php file
$categories['MyLayers'] = array("Parishes", "Clinics");
$categories_pool['MyLayers'] = array("Parishes", "Clinics");
3.2 You may also want to change the toolbar theme to a fancier one like chameleone as
follows:
/**
* Define which toolbar theme (folder under "/images/buttons") to use for toolbar
*/
$toolbarTheme = "chameleon"; //"default"; //"chameleon"; //"theme2_mono";
Conclusion
In conclusion, if you follow the above configurations, you can have a fairly large application
with several map layers and fancy functionalities. A lot depends on how far you go in
understanding the three basic files. If you know some php, things get even much better when
you try to explore some of the other files.
In case you run into some issues and you have to troubleshoot, the error logs will come in
handy. One of the problems with open source, IMHO, is that those systems do not easily tell you
the source of system errors. Take, for example, in p.mapper, there could be this problem of
"Loading" shapefiles which takes forever - actually pretending to be loading a shapefile, yet in
actual fact there is a problem and it will keep pretending forever anyway. As an example, think
of this possible cause of the problem: in the map file, you could have specified a CLASSITEM

field which does not exist in the shapefile (this is just an example). p.mapper will try to "load"
forever but will never tell you there is a problem; but if you check in the php error log, you
will fine something like this:
[MapServer Error]: msDBFGetItemIndex(): Item 'xDISTRICTID' not found. in
G:\ms4w\sites\pmapper-3.2.0-world\incphp\map.php on line 304
In the above case, I had errorneously typed CLASSITEM xDISTRICT instead of DISTRICT in the
map file. So, correcting it solves the problem. But, in general, the error logs can help you a lot
in troubleshooting. If, therefore, you have any issues that you have not easily resolved, a good
option is to check the error logs - both Apache error log and php error log.
Another issue that I encountered: For some reason, I decided to disable the reference map in
the map file. This results into the print and download functionality not working (failing or
crashing, if you will), so make sure you have the reference file enabled!