Merge branch '1.2' into 1.3

README.md

@@ -7,17 +7,102 @@ Displays a map using the Google Maps API. The user may then choose where to plac
 
 You can also search for locations using the search box, which uses the Google Maps Geocoding API.
 
-### Usage
+Supports SilverStripe 3.1
 
-##### `__construct` options
+## Usage
 
-|Option|Default|Description|
-|------|-------|-----------|
-|`field_names`|See `GoogleMapField.yml`'s `default_options.field_names`|A map of field names to save the map data into your object.|
+### Minimal configuration
 
-##### `Field` options
+Given your DataObject uses the field names `Lat` and `Lng` for storing the latitude and longitude respectively then the
+following is a minimal setup to have the map show in the CMS:
 
-|Option|Default|Description|
-|------|-------|-----------|
-|`coords`|Your object's latitude and longitude|The intial coordinates of the map - note: this is not the default value if no object exists|
-|`map`|Zoom of 14, map type of ROADMAP|A [google.maps.MapOptions](https://developers.google.com/maps/documentation/javascript/reference?csw=1#MapOptions) object|
+```php
+class Store extends DataObject
+{
+    public static $db = array(
+        'Title' => 'Varchar(255)',
+        'Latitude' => 'Varchar',
+        'Longitude' => 'Varchar',
+    );
+
+    public function getCMSFields() {
+        $fields = parent::getCMSFiels();
+
+        // add the map field
+        $fields->addFieldToTab('Root.Main', new GoogleMapField(
+            $this,
+            'Location'
+        ));
+
+        // remove the lat / lng fields from the CMS
+        $fields->removeFieldFromTab('Root.Main', 'Lat');
+        $fields->removeFieldFromTab('Root.Main', 'Lng');
+
+        return $fields;
+    }
+}
+```
+
+Remember to set your API key in your site's `config.yml`
+
+```yml
+GoogleMapField:
+  default_options:
+    api_key: '[google-api-key]'
+```
+
+## Optional configuration
+
+### Configuration options
+
+You can either set the default options in your yaml file (see [_config/googlemapfield.yml](_config/googlemapfield.yml)
+for a complete list) or at run time on each instance of the `GoogleMapField` object.
+
+#### Setting at run time
+
+To set options at run time pass through an array of options (3rd construct parameter):
+
+```php
+$field = new GoogleMapField(
+    $dataObject,
+    'FieldName',
+    array(
+        'api_key' => 'my-api-key',
+        'show_search_box' => false,
+        'map' => array(
+            'zoom' => 10,
+        ),
+        ...
+    )
+);
+```
+
+#### Customising the map appearance
+
+You can customise the map's appearance by passing through settings into the `map` key of the `$options` (shown above).
+The `map` settings take a literal representation of the [google.maps.MapOptions](https://developers.google.com/maps/documentation/javascript/reference?csw=1#MapOptions)
+
+For example if we wanted to change the map type from a road map to satellite imagery we could do the following:
+
+```php
+$field = new GoogleMapField(
+    $object,
+    'Location',
+    array(
+        'map' => array(
+            'mapTypeId' => 'SATELLITE',
+        ),
+    )
+);
+```
+
+# Getting an API key
+
+## Google Maps API key
+
+To get a Google Maps JS API key please see [the official docs](https://developers.google.com/maps/documentation/javascript/get-api-key)
+
+## Geocoding access - enabling the search box
+
+To use the search box to find locations on the map, you'll need to have enabled the Geocoding API as well. Please see
+[the official docs](https://developers.google.com/maps/documentation/javascript/geocoding#GetStarted)

composer.json

@@ -14,7 +14,8 @@
     ],
     "require": {
         "php": ">=5.3.0",
-        "composer/installers": "~1.0"
+        "composer/installers": "~1.0",
+        "silverstripe/framework": "^3.1"
     },
     "extra" : {
         "installer-name": "googlemapfield"