[[TOC]]

= FAQ: Customizations =

== Customizations of CSS and !JavaScript ==
Since version 3.1 p.mapper has a function to load all CSS (*.css) and !JavaScript (*.js) files that are loacted under the respective ''config directory'' (the default is {{{/config/default/}}}) ''after'' all files of the {{{/javascript/}}} and {{{/templates/}}} directories. This way all settings of the files in these directories are overwritten with the settings under the config directory. 

It is therefore recommended to make modifications and add '''new styles''' in a separate file (called e.g {{{custom.css}}}) under the config directory. It is also possible to overwrite existing '''!JavaScript functions''' by cloning them and putting them also under the config directory (e.g. in a file called {{{custom.js}}}) and make all modifications there. In addition, any *js file under the {{{/javascript/}}} directory is loaded, so it's also possible to add new !JavaScript functions there in a new *js file

A very good tool for working with CSS is the [http://getfirebug.com Firebug] extension for Firefox. It allows modifying styles on the fly and lets you identify the CSS files determining the style of an element.



== Plugins ==
Since version 3.1 p.mapper has also the possibility to add new functionality using a plugin API. All plugins should be placed under the {{{/plugins/}}} directory and loaded via the {{{config.ini}}} under the {{{plugins}}} key: add all plugins to be loaded as a comma-separated list.

=== Plugin development ===

==== Configuration ====

The name of the plugin and the folder name must be identical. The configuration file for the plugin shall have the name {{{config.inc}}} and must be directly below the plugin directory. {{{config.inc}}} is a PHP file and has the following structure:
{{{
  // PHP files loaded into map.phtml
  $phpFiles = array("exportquery.php", "export.xls.php");

  // JavaScript files referenced in map.phtml 
  $jsFiles  = array("export.js");

  // CSS files referenced in map.phtml
  $cssFiles = array("export.css");
  
  // JavaScript init function to be executed at loading time of the application
  $jsInitFunction = "myPlugin_init()";
}}}

All PHP, !JavaScript and CSS files listed in the respective arrays are loaded into the main file {{{map.phtml}}} and are available there.

If it is necessary to execute a !JavaScript function every time the map is refreshed then add to the init function referenced in {{{config.inc}}} something like
{{{
   $("#pmMapRefreshImg").bind("load", function(e){
      pm_scaleBar.update(PMap.scale);
   });
}}}

This requires a new entry in map.phtml, e.g. after 
{{{
  <div id="pmQueryContainer" class="jqmDialog hide"></div>
}}}

like
{{{
  <div id="pmMapRefresh" style="visibility:hidden">
     <img id="pmMapRefreshImg" src="images/pixel.gif" alt="maprefresh">
  </div>
}}}

and the latest version of {{{/javascript/xmlhttp.js}}}. Binding the event directly to the {{{mapImg}}} object causes less smooth swapping of the map image.


==== Adding a plugin to the GUI ====
A functionality can be attached to the GUI e.g. via a button or a menu entry. In this case the plugin needs to be referenced in the {{{$buttons}}} or the {{{$menu}}} array in the {{{php_config.php}}} file. The steps are shown by an example of the coordinates plugin that shows the coordinates of the mouse click (this could be used as base for digitization of points).

in {{{php_config.php}}} and an entry in the {{{buttons}}} array like
{{{
  "coords"      => array(_p("Show Coordinates"), "0"),
}}}

The "0" means that it is a mouse tool and changes the active button, but does not directly launch anything (like e.g. the "home" button does). There are 2 functions related to this tool and they are included in the file {{{coordinates.js}}} (that is referenced in {{{config.inc}}}):
{{{
  function coords_click() {...}
  function coords_start(imgxy) {...}
}}}

Note that the functions have the {{{coords}}} in common, this prefix must be the one used in {{{php_config.php/$buttons}}}. 

The {{{"_click()"}}} function must specify the behaviour of the tool, e.g. if the mouse shall be able to draw a box or just allow clicks (see examples in {{{mapserver.js/domouseclick()}}} for the various default tools). The {{{"_click()"}}} function is executed by every click in the map and launches the {{{"_start()"}}} function. In this function the developer has to define what to do further on with the information that it has received from the mouse click, i.e. the pixel coordinates from the clicked area on the map. 

==== Limitations of the plugin API ====
p.mapper was developed as an application framework that shall allow multiple functionalities that are fairly easy to set up and use. It has not been designed as a development framework like Chameleon. So the plugins API has been added recently and might lack some functionalities. Therefore an integration of a plugin could in rare cases require some modifications of the main source, e.g. for interaction with mouse events. In this case you can contact me and I will see if and how this can be achieved.

==== Available plugins ====
A short description of plugins is available [AvailablePlugins here].

== Query results rendered into PDF ==
''I'd like to work on the possibility to attach the info related to selected area (for some layers) to the pdf print under the legend. What's the right way?''

The plugins directory has a folder "export" (development version [http://svn.pmapper.net/trac/browser/pmapper/trunk/plugins/export see here]) that allows export of query results to PDF, Excel and CSV.