Documentation

Defining API keys

Some websites require API keys in order to properly display a google map or geocode addresses. To define these keys, simply add the following to your config/site.php:

define('GOOGLE_MAPS_API_KEY', 'Your-maps-api-key-goes-here');
define('GOOGLE_GEOCODE_API_KEY', 'Your-geocode-api-key-goes-here');

As long as you are using version 2.0.2+, dealer locator will begin to use your keys when requesting google's APIs. You can get both of these keys from https://developers.google.com/maps


 

The Dealer Locator is a block, but it also installs a few other components to help you add, manage and geocode your data (convert it into a point on a map). The first thing you might notice are two new Dashboard pages: Manage Dealers and Import Dealers.

dealerlocator-dashpanes.png

Adding and Managing Dealers

Manage Dealers

This page lists all dealers that you've added. Use the edit and delete links in the rightmost column to alter or remove a single dealer entry. To delete more than one entry at a time, check the checkboxes at left and click the red "Delete Checked" button.

Export Dealers
The Export link will prompt you to download a file named dealer_locator_records.csv, which includes all your currently stored dealers in a comma separated value format.

The Manage Dealers page also allows to to add a single dealer and fill in all the necessary informational fields.

Add Single Dealer

From the Manage Dealers page, click "Add New". You'll be presented with a list of all available fields, where you can store your information. This is also what you'll see when you edit an existing dealer entry.

Record Status

The status column displays whether or not the record has been successfully geocoded. The process of "geocoding" takes the address data you've submitted and sends it to Google, whose powerful computers take a guess at where your dealer is supposed to be located on the map. Then Google returns a set of latitude & longitude coodinates. Geocoding happens automatically for manually-added single dealers. If it's sucessful, your dealer's Status column will contain a link titled "Success". Clicking it will go to the point on the map that Google calculated-- for example:

http://maps.google.com/?q=45.522505,-122.662894

If Google can't find your address, the Status column will read "Failed". If the status column for your record reads "Pending", then the geocode job hasn't run. In this case, you should try running the job manually (see below) to have Google process the record's data.

Importing Dealers

The Dealer Locator also allows you to import dealer information en masse. The Import Dealers dashboard page will allow you to select a CSV (comma separated value) format file from your computer, and attempt to import it into your list of dealers.

Two options allow to to control what the Dealer Locator does with the imported data:

  • Replace - This option wipes out the current dealer records and replaces them with the entries contained in your CSV file. This option works well for users who prefer to manage their dealer list outside of concrete5, in a program like Excel. The whole set of records would simply be replaced each time you imported.
  • Append - This adds the new data to your existing dealer entries. This option is good if you want to keep the existing data, but add a batch of new records.

Export Sample CSV

This feature prompts you to download a comma-separated file with sample data. If you're having trouble getting your records to import as CSV, take a look at the sample file and make sure it uses the correct structure.

Run the Geocoding Job

After importing a CSV file, you must run the Geocoding job. This sends the new dealers' address data to Google and returns map coordinates for each.

The job can be run by visiting Dashboard > System & Settings > Optimization > Automated Jobs. Look for the job titled "Geocode Dealer Locator Addresses":

dealerlocator-geocode-before.png

Click the triangle icon at left to run the job. Google will try to determine where to place the address info on the map. If all is well, you'll get a success message, like so:

dealerlocator-geocode-after.png

Google is pretty good at guessing where an address is, even with partial information. However, if your Geocoding job is returning a tally of "Failed" status records, it means it couldn't figure anything out given the information provided. We suggest you double-check your information and making sure it's correct. Then, try running the job again.

Remember that the Geocoding process happens automatically when you add a single record (fill out all the fields by hand) from the Manage Dealers page-- but if you've added records via CSV import, you'll need to run the job before they'll show up on the map.

Got a lot of records? Run the Geocoding job multiple times

The geocoding job processes 250 records at a time. This allows the job to complete, on most servers, without running into the time limit for PHP processes. If your site has hundreds or thousands of dealer records, you'll need to run the job repeatedly until it has processed all records.

Block Setup

Search Options

Control which types of data you want to include in the search. Options include:

  • Units - Specify miles or kilometers.
  • Form Label - Change the search label text.
  • Form Width - Specify a width for the search form.
  • Distance Options - This defines the options users can select to limit the range of their search. Place each option on a new line.
  • Allow Filter by Type - Allow users to filter by type of dealers available.

Results Options

These options control the results displayed to users.

  • Show the map, the results list, or both.
  • Show or hide each of the fields that hold data about your dealers.