= sfGMapsPlugin =

== Overview ==

This plugin tries to help you use [http://www.google.com/apis/maps/ Google maps api] easily. With some helpers and there is too a module to geocode informations directly.

This is not a beta, neither an alpha... But it can be used for simple usage. 

My goal was to add geocoding possibilities to existants models in a symfony project using doctrine. But it's not yet implemented.

Actually you can use a module sfGMapsGeoCode :
 
 * to encode address 
 * save these in database
 * list geolocalised addresses

=== Requirement ===
 * ORM Doctrine ([wiki:sfDoctrine sfDoctrine]) (if you want to use module sfGMapsGeoCode)
 * [http://prototypejs.org/ Prototype 1.5.1] (actually included in this plugin, will move soon :D)
 
== Installation ==

To install sfGMapsPlugin:

{{{
#!sh
symfony plugin-install http://plugins.symfony-project.com/sfGMapsPlugin
}}}

If you want to use the database, you need to build it !

{{{
#!sh
symfony doctrine-build-model
}}}

=== Configurations ===

To use GMapsPlugin, you need to set 1 parameter in app.yml :

{{{
sfGMaps:
  key:       # your developper key
  version:   # optional, default version 2
}}}

==== When you use the sf_gmaps_tag helper, it takes some default parameters (that you can override easily) ====
You can add these informations to customise map display

{{{
sfGMaps_helper_default:
  id:           #default : map
  lat:          #define on wich point the map is centered on startup, default : 47
  lng:          #define on wich point the map is centered on startup, default : 8
  zoom:         #default : 7
  div_height:   #default : 400
  div_width:    #default : 500
}}}

== Direct usage ==

You can use this plugin directly to geocode points and save these to database. See [#sfGMapsGeoCode module sfGMapsGeoCode]

=== Modules ===

==== sfGMapsGeoCode ====

Enable the module in settings.yml : 
{{{
    all:
      enabled_modules:        [default, sfGMapsGeoCode]
}}}

If it doen't work (like on my computer) try to set it for your environnment (dev in this example)
{{{
    dev:
      enabled_modules:        [default, sfGMapsGeoCode]
}}}

 * How to geocode an address ? Very simple ! Go on your application : http://yourapp.com/geocoded_address
 * How to view all my geocoded addresses ? Go on your application : http://yourapp.com/addresses_list

== Complet usage ==

=== Helpers ===

==== Config ====
There is few constants used to set type of map display

==== sf_gmaps_tag() ====
This helper add a google map to the page. If you want to use it directly, please refere to source code, else you can use one of these helper :

 * sf_gmaps_clean_tag()  display only a map with no interactions
 * sf_gmaps_simple_tag() diplay a map with little controllers
 * sf_gmaps_full_tag()   display a map with full controllers and !mapTypeSelection

You can pass those (optionals) parameters to any of the following helpers :
 
 1. '''{{{ array() $points }}}''' An array of points like :
    {{{
#!php
<?php 
    $points = array(
                    array('lat' => latnb, 
                          'lng' => lngnb, 
                          'obj' => a GeoData obj
                          ),
                    array('lat' => latnb, 
                          'lng' => lngnb, 
                          'obj' => a GeoData obj
                          )      
                    );
?>
}}}
    Note : obj parameter is optional, you can set it if you want to display an [#infoBulle].
    
 2. '''{{{ array() $map }}}''' some options for the div and what controls and type of map to display
{{{
   #!php
   <?php
        $map['controls'] // dont change, use predefined helpers (listed above)
        $map['type']     // you can set what kind of map to display (SF_GMAPS_TYPE_HYBRID, SF_GMAPS_TYPE_SATELLITE, SF_GMAPS_TYPE_PLAN)
            
        $map['lat'], $map['lng'], $map['id'], $map['zoom']  // like in the config, but only for that map
        $map['options'] // this can contain an array of options for google map 
                        // like array('doubleClickZoomEnabled');
}}}
    [http://www.google.com/apis/maps/documentation/reference.html#GMap2 see methods configuration for google maps options]    
    
 3. '''{{{ array() $options }}}''' you can set height and width of the gmap to display
{{{
   #!php
   <?php
        $options = array('width' => width_in_px, 'height' => height_in_px);
   ?>
}}}

===  I want an infobulle, so what to put in obj ? === #infobulle
By default, it assume that you pass a !GeoData object for data and the partial {{{_infoBulle}}} from {{{sfGMapsPlugin}}} for template.
But if you want to pass something else than !GeoData object this is possible.

In the option {{{ $point }}} you can pass an array with the obj, so pass whatever object you want and add a second parameter to this array : {{{ $point['obj']['moduleName'] }}}, then it will look for an {{{_infoBulle partial}}} in your {{{moduleName}}} !

== Todo ==
 * implement the sfGMapsGeoCode module as a component to add it to an existant model
 * solve bug with model in plugin linked with model in project
 * simplify javascript files --> created a class ??? Add all in helper ???
 * set a zoom that displays all the points on map
 * add a module to import points from a kml
 * add a module to export to kml, gml
 * change the model definition to enable using existing addresses
 
== Bugs ==
 * find what it gets when the address is not complete in geocode_address (why these is no locality.Thoroughfare.ThoroughfareName)

== Coming soon ==

This plugin was first created to easily add possibility of geocode on existant model... but there is nothing working yet, so why ?
Because I'm attempting a few problems.

When doctrine create tables from the yaml schema, it takes schema.yml in the project first... and table creating file, because they referer to geo_data model in sfGMapsPlugin, and I don't know howto solve this problem yet.

=== HowTo add geocode possibilities to an existant model ? ===

 * Create an file named sfGMapsPlugin.yml in your project config dir. (there is a sample file in sfGMapsPlugin/config dir)
 * Add the model name you want they have geo_data support
 * Build symfony model (like when you've installed this plugin)
 * That all !
 
Now you can get geo_data from your model, with this command : 
{{{
#!php
<?php
  $your_model->get('geo_data')->get('column_name_listed_below');
?>
}}}

==== The GeoData model : ====
{{{
    GeoData: 
      tableName: geo_datas
      columns: 
        lat:      double
        lng:      double
        address:  string(50)
        zip:      string(10)
        city:     string(50)
        country:  string(2)
}}}

== License ==

For the full copyright and license information, please view the LICENSE
file that was distributed with this source code.