glLocator - Geographic Locator Plugin

The Locator plugin provides a “store locator”-type function where users can find locations within a specified distance from an entered address, or from a selected predefined address.

Locations may be entered by the site administrator, or by end users and may use the glFusion submission queue. Selected locations may be set as “origins” by the administrator, causing them to appear in every user's origin selection. Users may also select locations to appear as origins in their own selection list along with the adminstrator-defined ones.

If the user has specified a location in their account preferences, that will also appear as an origin. If it is used, and if the plugin is using the Google Map API, then the coordinates for that location will be determined by using Google Maps. Whether or not the coordinates can be determined, an entry will be added to a cache table to avoid future lookups. The administrator can edit user-defined locations if necessary.

Requirements

glFusion v1.2.0 or newer
PHP version 5
Google Javascript and Geocoding API keys

Installation

The Locator Plugin uses the glFusion automated plugin installer. Simply upload the distribtuion using the glFusion plugin installer located in the Plugin Administration page.

If necessary, the manual plugin installation method is also supported.

Upgrading

The upgrade process is identical to the installation process, simply upload the distribution from the Plugin Administration page.

Features

Provides a list of locations that fall within a given distance from an origin point.
Uses Google Maps to automatically geo-code addresses.
Offers the user's location (from glFusion's Account Settings) as an origin, if available.
Any location can be defined as a system-wide origin by the administrator.
Any location can be added to a personal “origin list” by any logged-in user.
Any address or other location information can be used. Google Maps is consulted to geo-code the user-entered address.

Usage

Submissions

Administrators can add locations directly to the database. If either coordinate is left blank (or zero), and the plugin has been configured to do so, Google Maps will be used to fill in the coordinates.

Note that the distance calculations require geographic coordinates to be entered for each location. If they're missing, the plugin simply won't do its job.

Regular users, and even anonymous users, can also submit locations depending upon the permission given in the Configuration section. The glFusion submission queue can also be used to moderate submissions by non-admin users. Users with the “locator.submit” privilege can always submit, and always bypass the submission queue.

If you'd like for administrators, defined as those who are members of the “locators Admin” group, to be notified of user submissions, then add “locator” to the “Notification” settings in the “Miscellaneous” area of the glFusion Site Configuration section. This will cause a notification to the administrators group whether or not the submission queue is used.

Searching

The plugin's homepage presents a form where users can search for locations within a specified distance of an “origin”. The “origin” list contains two types of location:

Locations from the main marker table which have been marked as an origin.
The user's home location, from the glFusion account settings, if available.
- The first time that the user's home location is used in a search, it is geocoded by Google Maps and cached in a database table. Thereafter, each time an exactly-matching home location is searched it doesn't have to be re-geocoded.

The search fields are:

Field	Description
Origin	The origin location. This will be the center of a circle with the specified radius, and locations which fall within that circle will be listed.
Address	This is an optional user-entered address. If anything is specified here, it will be used in lieu of the location dropdown. The address must be a valid location for Google Maps; a street address, city/state, or simply a postal code may be entered.
Radius	Enter the number of units (specified in the next field) within which you'd like to find locations.
Units	Select either “miles” or “kilometres”. The distance calculation will change depending upon which is selected.
Keywords	Enter any optional search keywords here, separated by spaces. Only locations which contain all keywords will be returned.

When the search is performed, matching locations will be displayed in a table. Click on the locations Name to view more information about it, including a Google map of the area.

Autotags

The Locator plugin supports one autotag: . This will embed a map of the location specified by location_id at the current position anywhere autotags are supported- stories, staticpages, etc.

Submission Queue

Like all other options, the use of the submission queue is controlled through the Geo Locator settings in the Site Configuration section. If you'd like to use the queue to moderate user submissions, set “Use submission queue” to “yes” in the Locator's General Settings.

Location submissions can be edited and moderated like any other submission type.

Configuration Options

Configuration Options are set by the Geo Locator section in the site Configuration area. There is no config.php required unless you wish to override any other settings.

Option	Description
Default Search Radius	This is the text (should be a number, naturally) that will appear as the search distance when the Locator is accessed.
Distance Units	This is the value for “Units” which will be the default for the plugin.
Show Google Map	If this is set to “Yes”, then a small Google map will be shown on the location detail pages. Set this to “No” to inhibit the map display.
Use Submission Queue	Set to “Yes” to moderate user submissions. Otherwise, user submissions go immediately to the production marker table. Submissions from users with the “locator.submit” privilege always bypass the queue.
Allow anonymous submissions	Indicate whether anonymous users will be able to submit locations. Beware if you enable this but disable the submission queue!
Allow logged-in user submissions	Indicate whether site members can submit locations. Note that it is possible to allow submissions from anonymous users but not site members- something that you probably don't want to do.
Display glFusion Blocks	Select which blocks should be displayed with the Locator page- Left, Right, Both, or None
Days to cache user-entered search locations	When a site visitor enters a location to be used as an origin, such as an address, the coordinates for that location are cached to reduce the lookups against Google. This value indicates how long the address will be left in the cache before being cleaned up.
Show maps in user profiles	This option controls whether a map of the user's location will be shown in the user profile page. If “Yes”, this map will show wherever the user's profile is shown, which may cause some privacy concerns. Keep in mind, however, that only the user-entered location information is used, and that same information could easily be entered into Google or another mapping service to get the same map outside of glFusion.
Show on user menu	This controls whether there will be a link to the plugin on the built-in “Plugins” menu.
Offer to get directions	If “Yes”, then a simple form will be displayed on the location information page below the map where the user can enter an address to get driving directions to the location. The default is “No” to be compatible with versions before 1.0.2 which did not offer this feature.
Automatically fill undefined coordinates	If both coordinates are entered when a location is submitted, then they will be used and no lookup will occur. Locations which are missing either coordinate, or have either one set to zero, will be submitted to Google for lookup if: this field is set to “Yes”, and a Google API key is entred below, and a valid URL to Google's geocoding service is entered.
Google Maps API Key	To use Google Maps, you'll need an API key for your site. It's free and simple. Just visit http://console.developers.google.com to get one. Create a “Server” key and enable both the Google Maps Javascript and Geocoding APIs.
URL to Google Geocoding Service	You shouldn't need to modify this, but it's included here in case Google changes something. There are two variables which will be replaced by data from the plugin: - %address% will be replaced by the url-encoded address to look up. - %google_key% will be replaced by the Google API key that you've entered above.

Note that the permissions are not currently used and may be left at their defaults.

Known Issues

Version 1.0.2

Floating-point values for coordinates are not saved properly in the database for some site locales.
Fixed in version 1.0.3.

Version 1.0.0

A template file used by the autotag function is missing from the package. Unzip this file in your private/plugins/locator/templates directory to fix this problem.

License

This program is free software; you can redistribute it and/or modify it under the terms of the GNU General Public License as published by the Free Software Foundation; either version 2 of the License, or (at your option) any later version.

Table of Contents