Customizing p.

mapper (not a tutorial but 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!