README

sfMapFishPlugin
===============

The `sfMapFishPlugin` packages useful libraries and tools to publish and interact with your vector GIS data in a PostgreSQL/PostGIS database.

It is a PHP implementation for the [MapFish framework](http://www.mapfish.org), targeted at the popular Symfony framework and Doctrine ORM.

Installation
------------

  * Install the plugin

        $ ./symfony plugin:install sfMapFishPlugin

  * Clear the cache

        $ ./symfony cache:clear

  * Build (or rebuild) the model and the forms 

        $ ./symfony doctrine:build-model
        $ ./symfony doctrine:build-forms
        
    At this step, your geometry column should be set as a blob in your schema.
    
        the_geom: { type: blob }

Generate a MapFish controller
-----------------------------

It's quite simple to generate a module which exposes your geographic data through a RESTful API, via the [MapFish Protocol](http://trac.mapfish.org/trac/mapfish/wiki/MapFishProtocol). 

Say you want to be able to CREATE/READ/UPDATE/DELETE geographic features in a table with a geographic column. 
Just follow these three easy steps:

  * In lib/model/doctrine/YourModelClass.php, specify your table's geometric column name and its [EPSG code](http://spatialreference.org), by adding such a line:

        [php]
        public static $geometryColumn = array('the_geom' => 4326);
        
      Here, we have a table with a geometric column whose name is 'the_geom', and its projection code is [EPSG:4326](http://spatialreference.org/ref/epsg/4326/)

  * Make YourModelTable extend sfMapFishTable instead of Doctrine_Table: in lib/model/doctrine/YourModelTableClass.php, you should have:

        [php]
        YourModelTable extends sfMapFishTable
        
  * Unset the geometric column from the configure method of the form in lib/form/doctrine/YourModelForm.class.php, and don't forget to disable the CSRF protection on it:

        [php]
        unset($this['the_geom']);
        $this->disableCSRFProtection();
        
  * You're now ready to generate a MapFish module tied to this Model, by the way of the mapfish:generate-module built-in task:
  
        $ ./symfony mapfish:generate-module --generate-route frontend your_module YourModel

      The --generate-route will update the routing.yml file for the frontend application, by adding the corresponding sfMapFishRoute.
      In this example, the resulting module will be named "your_module". You may want to customize this !
      
Once this is done, clear your cache, and check you've got some GeoJSON data out of /index.php/your_module

This being done, you may want to have a look at MapFish client side software, which plays well with this REST API.
Just check out http://www.mapfish.org/svn/mapfish/framework/client/trunk/mfbase/ into your project's web/js directory, and [read the doc](http://www.mapfish.org/doc/index.html) or [browse the examples](http://demo.mapfish.org/mapfishsample/trunk/) ;-)

For quick CRUD operations on your data, you can take advantage of the existing mapfish.widgets.editing.FeatureEditingPanel widget, which is being showcased [here](http://demo.mapfish.org/mapfishsample/trunk/examples/editing/).

In case of problems, feel free to drop us a line on the dedicated [MapFish mailing list, or IRC](http://trac.mapfish.org/trac/mapfish/wiki/Community)

Install print module
--------------------

sfMapFishPlugin comes with a built-in controller for the [MapFish print protocol](http://trac.mapfish.org/trac/mapfish/wiki/PrintModuleDoc#Protocol), which you can optionally activate if you want your app to produce nice PDF with your maps. (see [MapFish PrintModuleDoc](https://trac.mapfish.org/trac/mapfish/wiki/PrintModuleDoc))

You'll need to have [Sun's JRE](http://www.java.com/download/) installed to make this working.

  * Enable this module in your app

        all:
          .settings:
            enabled_modules:  [default, mfPrint]

  * Copy the mandatory config file from the plugin to your config directory
  
        $ cp plugins/sfMapFishPlugin/data/print/print.yml config/print.yml

  * The print module should be ready & responding to /index.php/mfPrint/info to get print configuration. 
    Don't forget to configure the config.yml (see [configuration](https://trac.mapfish.org/trac/mapfish/wiki/PrintModuleServer). For instance, you should at least allow the print service to access the WMS services you're using.
    The provided print.yml example fiel has 3 mandatory fields in the spec: title, comment & mapTitle. 
    If you're getting errors, check your symfony log file to get debug information (if enabled in your application environment).
    
  * Once this is done, you can integrate the [MapFish print widgets](http://www.mapfish.org/svn/mapfish/framework/client/trunk/mfbase/mapfish/widgets/print/) into your client application, which give you the ability to output nice customizable PDF with your maps. Examples can be found [here](http://demo.mapfish.org/mapfishsample/trunk/examples/print/).

  * Troubleshooting: You may need to manually set the java path to get it working:

        [php]
        sfConfig::set('mf_jre_path', '/usr/bin/');

Documentation
-------------

All classes have full API documentation.

You will also find some information on the [MapFish website](http://www.mapfish.org/):

  * [MapFish Wiki](http://trac.mapfish.org/trac/mapfish)
  * [Definition of the MapFish Protocol](http://trac.mapfish.org/trac/mapfish/wiki/MapFishProtocol)


Tasks
-----

  * sfMapFishGenerateModule: Generates a REST controller, according to the specifications from the [MapFish protocol](http://trac.mapfish.org/trac/mapfish/wiki/MapFishProtocol)


How to contribute.
------------------

If you want to contribute, follow these steps:

  * Check the prerequisites
    * The license must be BSD
    * You must follow symfony coding standards
    * The contribution must not be too specific
    * You must be sure you will be able to maintain your contribution
  * Create a ticket and attach a patch
    * Choose `sfMapFishPlugin` as the component
    * Change the qualification to `Ready for core team`

License
-------

This plugin is realeased under a BSD license.