README

eZGMapLocation Datatype Extension
Version 1.x by eZ Systems AS

Version 0.5 developed by Blend Interactive
http://blendinteractive.com
------------------------------------------------------------------
The GmapsLocation datatype extension provides a handy way to store
latitude/longitude points (as decimal degrees) on an object by using
Google Maps to identify and mark positions using their address.

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

1.) Obtain a Google Maps Key for all domains you'll be using by registering
your domains with Google at http://www.google.com/apis/maps/

2.) Upload the ezgmaplocation folder to the extensions folder in your
eZ Publish installation.

3.) Activate the extension from the 'Extensions' portion of the
'Setup' tab in the eZ publish admin interface.
And update the autoload array by clicking "Regenerate autoload arrays for extensions"

4.) Add your Google Maps JavaScript API key to ezgmaplocation.ini [GMapSettings] ApiKey
(settings/override/ezgmaplocation.ini.append.php, or per siteaccess). Without a key
the edit form and the view load no Google script and show the coordinates without
a map. (The old site.ini [SiteSettings] GMapsKey is not read.)

5.) Apply the ezgmaplocation table to your database with the included sql file:
<eZP root>/extension/ezgmaplocation/sql/mysql/mysql.sql
Using either phpmyadmin (easiest) or shell/console commands.

Sql files are also provided for postgresql and oracle - refer to the
database documentation on how to execute queries from a command-line clients

6.) Now you can add the ezgmaplocation datatype like any other datatype when editing classes.


Upgrade from 6.0.7 or earlier (required)
---------------
Earlier versions stored the address with HTML entities ("M&uuml;llerstra&szlig;e 5"); this version stores
it as typed and escapes it on output. Before editors work with the new version, decode the stored rows
once per database (siteaccess):

    php extension/ezgmaplocation/bin/php/decodeaddressentities.php -s <siteaccess>          (dry run: lists the rows)
    php extension/ezgmaplocation/bin/php/decodeaddressentities.php -s <siteaccess> --apply

Check the dry-run list first: rows that were never encoded (package import, fromString()) and hold a
literal "&xxx;" are decoded as well. Run it once only; addresses saved after the upgrade are stored as
typed. Search index, sort key and object names follow on the next publish or a reindex.


Use (editing)
---------------
1. Type in the address you want to find beneath the map.
2. Click 'Find address'
3. Click 'Update Values' to grab the coordinates.

Repeat to change.
Unless you change the marker on the map, the address will be saved as you typed it.
This address is searchable! (see below for filtering / sorting on coordinates as well)


Use (fetching)
---------------

For fetching multiple nodes based on location, you can use the included ezgmlLocationFilter.
Example fetches users in a distance of roughly 30-50km from Oslo, Norway, and sorts the
results based on how close the nodes are to the given coordinates.


{def $users_close_by = fetch( 'content', 'tree', hash(
                              'parent_node_id', 12,
                              'limit', 3,
                              'sort_by', array( 'distance', true() ),
                              'class_filter_type', 'include',
                              'class_filter_array', array( 'user' ),
                              'extended_attribute_filter', hash( 'id', 'ezgmlLocationFilter', 'params', hash( 'latitude', 59.917,
                                                                                                              'longitude', 10.729,
                                                                                                              'distance', 0.5 ) )
                              ) )}

 Note that the distance filter is using a 'bounding box' for sql speed, see classes/ezgmllocationfilter.php for more info
 and parameters to be able to get true ('arccosine') or closer to true ('pythagorean') circular distance filter accuracy.
 The sort on the other hand is accurate, so if your main concern is to show the closest node, then the filter is ok by default.

 Also see 'arccosine' parameter in combination with 'as_object', false() to be able to get value to easily calculate distance.
 Example use: user x is 2,5 km away from you. Or Oslo, Norway is 416.8km from Stockholm, Sweden.



Content Security Policy
---------------
See doc/CSP.md (with the settings in doc/SETTINGS.md and the Google setup in
doc/GOOGLE_SETUP.md). Without an ApiKey nothing from Google is loaded.
se7enxweb / ezgmaplocation

Package info

Security

Fund package maintenance!

Statistics

README
