# sfGMapsPlugin

## Overview

This plugin tries to help you use [Google maps api](http://www.google.com/apis/maps/) 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 ([sfDoctrine](sfDoctrine)(/plugins/sfDoctrine sfDoctrine)) (if you want to use module sfGMapsGeoCode)
  * [Prototype 1.5.1](http://prototypejs.org/) (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 [module sfGMapsGeoCode](#sfGMapsGeoCode)

### Modules

#### sfGMapsGeoCode

Enable the module in settings.yml : 
    
        all:
          enabled_modules:        [sfGMapsGeoCode](default,)
    

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

  * 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[$map['lng'], $map['id'], $map['zoom']('lat'],)  // like in the config, but only for that map
            $map['options'] // this can contain an array of options for google map 
                            // like array('doubleClickZoomEnabled');
    
    [see methods configuration for google maps options](http://www.google.com/apis/maps/documentation/reference.html#GMap2)    
    
 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.