GeoMaps Add-on Manual

Last update: January 9th, 2014

Copyright © 2010-2014 ClickFWD LLC

Chapter 1 GeoMaps Add-on Overview & Installation

1.1 Overview

GeoMaps delivers an amazing implementation of the Google Maps experience right on your website so you can keep your visitors on your site. We've made it dead simple to add the location of a listing on a map with the click of a 'map it' button and you can drag the marker to fine tune its location. You can also assign different marker icons per category and enable 'get directions' and 'streetview'. Combined with the file upload capability in JReviews, it's easy to add a KML layer to each listing by uploading KML files attachments. If you already have a large database of listings with addresses, GeoMaps can batch geocode them to add the coordinates for you.

The GeoMaps add-on incorporates two distinct and powerful functionalities into JReviews: Proximity search and Mapping.

1.1.1 Proximity search

This functionality enables your site's users to use a partial or full address to find nearby locations stored in the JReviews database and sorted by distance. Users can perform address search, zipcode and postal code searches. The add-on takes advantage of the JReviews Advanced Search module for complex custom searches that can use both the address and custom fields. GeoMaps comes with bulk Geocoding functionality that easily converts listings’ physical addresses to coordinates, processing thousands of listings in a short time. It also enables your site's users to geocode an address when submitting new listings and even fine-tune the location by dragging the marker on the map.

1.1.2 Mapping

Once a listing's address has been geocoded it's possible to show its location on a map. The GeoMaps addon allows you to display a map with markers for your listings in category pages, search results and detail view. A GeoMaps module is also included to display marker locations on a map. The addon has a lot of customization features for the map so you can have different markers for different types of businesses and toggle many of the features available with the Google Maps API including Street Views and walking and driving Directions.

Google has introduced usage limits for the display of maps taking place in early 2012. You get 25,000 free map loads per day. You can create a Google API Console account to start tracking your API usage. More information can be found here: https://developers.google.com/maps/faq#usagelimits.

1.1.3 A note on geocoding

Geocoding is the process of converting a physical address to its coordinate equivalent (latitude/longitude). To perform this task GeoMaps uses the Google Maps API geocoding service, which has a limit of 2,500 free geocoding transactions per day per IP Address. More information here: http://code.google.com/apis/maps/documentation/geocoding/#Limits.

Geocoding calls to the API are made during bulk geocoding, use of the add-on’s Map It feature and also whenever an address search is performed because the address needs to be converted to coordinates first in order to find nearby points.

1.2 Installation

The add-on can be installed via the Install & Update menu in the JReviews administration.

To install or update the addon you must have previously purchased it, your JReviews version needs to match or be greater than the one specified for the addon and you must have a valid "Upgrades & Support" package for your JReviews license.

If you purchased the addon, but it still says "addon not active for this license", go to the JReviews admin license screen, clear the local key text area and re-submit the license number. This will fetch a new local key that includes the addon information.

On the Install & Update page, check the Updates checkbox, and click on the Install button next to the GeoMaps Add-on like on this image:

Reload the page to see the GeoMaps link appear under the Add-ons header on the left sidebar:

Chapter 2 GeoMaps Configuration

2.1 Basic Setup

Google Maps API url - to add a country bias to geocoding requests you can use the Google url for that country. For example: //maps.google.es, //maps.google.it, //maps.google.de.

Google Maps API Key - the key is optional, but it is useful for tracking usage of the API requests. Get a key here.

This is where you tell the GeoMaps add-on which custom fields of your listings contain address information. All custom fields that you enter here must be previously created in the JReviews Fields Manager.

Latitude and Longitude custom fields must be created as decimal fields in the JReviews Fields Manager. They are used to store latitude and longitude data, but it is not necessary to show those fields on the listing form or listing details. You can hide them from your site’s registered users by de-selecting the access groups from the field’s Add/Edit Access Settings in the Fields Manager.

Map it field - a button will be appended to this field in listing forms. Clicking this button will automatically geocode the address and popup a map so the user can adjust the marker location.

Automatic geocoding on new submissions - by default a listing’s address will only be geocoded if the user submitting the listing clicks the Map It button. By enabling this setting you ensure that addresses are auto geocoded if the user doesn’t do it himself using the Map It button.

Proximity search - disabling this defaults to regular text searches on the address field.

Advanced search address field - tell the addon which field it should use for address searches in the JReviews Advanced Search Module. For instance, if you have a jr_address field, then you can add this field to the advanced search module as {jr_address} and when the user types an address in that field the addon will geocode the address to find nearby listings.

Address autocomplete - powered by the Google Places API and returns address suggestions that are NOT related to the addresses in your database.

Autocomplete Country Restriction - limits suggestions to the specified country only. Fill out the two letter code based on the ISO 3166-1 alpha-2 definition.

Maximum radius - puts a cap on the allowed radius search.

Publish distance on search results - if enabled, a Distance will be shown next to the custom fields in the listing details. If you want to customize the distance output, set this setting to No, and use this code in the theme file to output the distance:

<?php echo $CustomFields->field('jr_gm_distance',$listing);?>

Enable map on proximity searches - if disabled, the map will not be shown on the proximity search results page.

Proximity search results theme suffix - here you can enter a specific theme suffix for the search results list page.

2.2 Markers & Infowindow

Marker icon path - enter the path where you want GeoMaps to look for marker images. GeoMaps comes with several images and you can upload additional ones to this folder. Default: components/com_jreviews_addons/geomaps/icons.

Marker infowindow - choose the marker infowindow you want to use. The infowindow is the popup with listing information that appears when you click on a marker. Available options:

Google default - this infowindow can only appear within the map boundaries which makes it impractical for maps of small size.

Callout

Custom - this infowindow can be further customized through the infowindow theme files and css.

Example of a Google default infowindow:

Example of a Callout infowindow:

Example of a Custom infowindow:

Infowindow fields - custom fields comma list, without spaces (jr_fieldone,jr_fieldtwo,etc.) that will be made available for inclusion via tags in the infowindow theme file. Only add fields that exist in JReviews.

2.3 Maps

You can turn on and off all of the standard Google Map controls using these settings. All settings are global, but the ones for the GeoMaps module can also be overriden in the module parameters.

Chapter 3 Address Geocoding

If you installed GeoMaps on a site with existing listings or if you didn't enable auto geocoding, it is required to geocode addresses (convert real addresses to latitude & longitude coordinates) before being able to display the maps on the site.

To do that, click the Geocode Addresses link in GeoMaps administration:

On this page you can geocode individual addresses or perform batch geocoding of existing addresses. Use the filters to select the listing types that require geocoding:

If you see listings without latitude and longitude values, those are the ones that need to be geocoded.

3.1 Geocoding individual addresses

Clicking on the pin button located to the right of the address column opens a dialog allowing you to geocode individual addresses and adjust the location of the marker by dragging it. You need to click on the Apply Changes button once you are satisfied with the marker location so your changes are saved to the database:

3.2 Batch Geocoding

If many of your listings are missing latitude and longitude values, use the Geocode Addresses button to begin batch geocoding. A dialog box will appear where you can see the progress and stop the process. The Google API only allows 15,000 geocode transactions per day. After that the addon defaults to the tinygeocoder.com service.

3.3 Geocoding addresses in new listings

If you allow users to submit listings to your site or you submit them manually, the GeoMaps add-on has a Map It feature that allows users to geocode the address on the fly and adjust the marker’s location if necessary. The add-on adds a couple of buttons after the field that you designate as the "Map It" field in the configuration settings.

If you enabled auto-geocoding option in the GeoMaps configuration, it is not necessary to click the Map it button after entering the address, but you can use it to fine-tune the location:

If you want to change the address then you need to click on "Clear LatLng" to geocode the new address.

Chapter 4 Custom Markers

By default, all maps will use standard red markers. If you want, you can choose different marker icons for different types of listings, for example:

The GeoMaps add-on lets you assign custom markers to listings in a couple of ways:

By category - all listings in a category will have the same marker

By custom field options - the images assigned to the select list field options will be used as markers so you can have different markers even within the same category.

To assign custom markers, go to the Assign Custom Markers page in GeoMaps add-on administration:

Select one or multiple categories and click the Assign Marker button in the top right corner. You will get a popup dialog where you'll be able to choose the marker for selected categories:

4.1 Marker icons by category

The Assign Markers dialog will display all marker icons that you can assign to categories. Default icons are located in /components/com_jreviews_addons/geomaps/icons. If you need more icons, you can upload them there or tell GeoMaps to look for marker icons in a different folder which can be specified in GeoMaps configuration.

4.2 Marker icons by custom field options

If you use the custom field assignment then you need to upload the icons to your theme's /theme_images folder and clear the File Registry in JReviews administration.

In the Assign Marker dialog enter the name of the field that contains field options with images.

To assign images to specific field options, go to the Field Options Manager of a custom field and add images to field options like this:

If you want to use the field option images for map markers, but show the field option text in the regular display of fields, theres's a setting in the field's Advanced Options:

4.3 Using different icons for featured listings and mouseover event

GeoMaps will use the following suffixed images for featured listings and the mouseover event when hovering over a marker:

{icon_name}_hover.{icon_extension}

{icon_name}_featured.{icon_extension}

{icon_name}_featured_hover.{icon_extension}

A real example where the marker image is "hotel.png" would be:

hotel_hover.png

hotel_featured.png

hotel_featured_hover.png

If both a category icon and a select field are setup for a category, then the select field takes priority and if an option is not selected then the category icon is used.

Chapter 5 Performing Proximity Searches

You need to use the JReviews Advanced Search Module to setup address searches. In the Advanced Search Module parameters, enter "_map" as JReviews Theme Suffix:

This will load an alternative theme file for this module that includes the code for address searching:

/components/com_jreviews/jreviews/views/themes/default/modules/advanced_search_map.thtml

The theme file use "jr_address" as custom field to perform address searches. If you named your address field differently in the Fields Manager, edit this theme file and adjust the field name. You can also adjust the available radius search options:

The Advanced Search Module will then look like this:

After performing the search, visitors will get the search results page with listings ordered by proximity:

Chapter 6 Displaying Maps

6.1 Map on listing detail and list pages

If you configured GeoMaps correctly, the maps will automatically appear in listing detail pages and list pages (category pages, search results, etc.).

If you want to hide the map on detail page or list pages, each listing type in JReviews Listing Types Manager have settings for this:

Example of a map on a listing detail page:

Example of a map on a list page:

6.2 GeoMaps Module

The GeoMaps module is automatically installed with the add-on and allows you to show all the locations of a directory, section or category. It has category autodetect functionality so a single module instance can be used on multiple pages showing different markers.

Important: the module is not capable of showing all markers for an address search. Instead the list map must be used.

Example of a GeoMaps module:

The GeoMaps module has many parameters:

Functionality Mode - available options:

Normal (Use filtering settings) - the map will display listings based on the Basic/Advanced filters that you specify.

Geo Targeting (IP Address to Location) - with this mode, the map will be automatically centered to the site's visitor location calculated based on the visitor's IP address. This option requires that you enter Radius and Zoom values.

Custom center & zoom - enter Custom Latitude and Custom Longitude to which the map will center. Radius and Zoom values are required with this mode as well.

Caching - with lots of markers this setting is very important to cache the json object that the map uses to load the markers.

JReviews Theme Suffix - if you need multiple copies of the GeoMaps module and you want each one to use a different theme file, you can specify a theme suffix here.

Featured Only - if enabled, the map will display only featured listings.

Click2Search Autodetect - automatically filters results when in Click2Search pages using the value from the click2search field.

Category Autodetect - filters results to the current category.

In detail view - allows you to change the behavior of the map when the module is shown in listing detail pages.

Directory/Category/Listing IDs - filter the markers shown using these settings. It’s not necessary to fill in all of them, just one.

Custom WHERE - filter the markers shown based on custom database query. For more info read Using Custom WHERE and Custom ORDER BY parameters.

Map Width - remember to include px or %. For example 100% or 500px.

Map Height - enter the height in px.

Address Search Bar - allows users to quickly find a location on the map. Uses the Google geocoder which has a free 15k per day transation limit. This feature is not fully compatible with Geo Targeting with a radius is set because not all markers are available on the map. If a user types an address outside the radius search no markers will be shown.

Limit Results - set a limit to the number of markers shown on a map. This is important for performance gains if you have too many results and all markers should not be shown on the map.

Enable clustering - groups markers at high zoom levels. Must be used when showing a large number of markers for performance gains.

Clustering Min Markers - when clustering is enabled, any number of markers above this setting will trigger the marker clustering functionality.

You can turn on and off all of the standard Google Map controls using these parameters.

Chapter 7 Theme Customization

The GeoMaps theme files are located here:

/components/com_jreviews_addons/geomaps/views/themes/geomaps/

Even though you can customize the theme files there, that is not recommended. Instead use the JReviews Code Overrides functionality to copy specific geomaps theme files that you want to customize into your custom theme in jreviews_overrides folder.

7.1 Listing detail page map

The theme file of the JReviews listing detail page (/listings/detail.thtml) calls this file to load the map:

/components/com_jreviews_addons/geomaps/views/themes/geomaps/geomaps/map_detail.thtml

If you want to customize it, copy it first to your custom theme in overrides:

/templates/jreviews_overrides/views/themes/{your_theme}/geomaps/map_detail.thtml

7.2 List pages map

Only Blogview and Thumbview list page layouts can show the map. The /listings/listings_blogview.thtml and /listings/listings_thumbview.thtml theme files call this file to load the map:

/components/com_jreviews_addons/geomaps/views/themes/geomaps/geomaps/map_results.thtml

If you want to customize it, copy it first to your custom theme in overrides:

/templates/jreviews_overrides/views/themes/{your_theme}/geomaps/map_results.thtml

7.3 GeoMaps module map

The GeoMaps module uses this theme file:

/components/com_jreviews_addons/geomaps/views/themes/geomaps/modules/geomaps.thtml

If you want to customize it, copy it first to your custom theme in overrides:

/templates/jreviews_overrides/views/themes/{your_theme}/modules/geomaps.thtml

7.4 Marker infowindow

Marker infowindow popups use this theme file

/components/com_jreviews_addons/geomaps/views/themes/geomaps/geomaps/map_infowindow.thtml

If you want to customize it, copy it first to your custom theme in overrides:

/templates/jreviews_overrides/views/themes/{your_theme}/geomaps/map_infowindow.thtml

By default the infowindow shows the listing thumbnail, editor and user rating stars and review count. You can also add custom fields. First you need to specify which custom fields you want to make available for the infowindow in the GeoMaps configuration:

After that, add the fiels to the infowindow theme file like this:

<span class="jr-map-jr_address"></span>
<span class="jr-map-jr_phone"></span>

Chapter 8 Tips & Tricks

8.1 How can I show the Map inside a tab on the listing detail page

Read the article about Adding jQuery UI tabs to listing detail page. The included _tabs suffixed detail theme file already displays the map inside a tab.

8.2 How to hide the map from certain categories

Each listing type in JReviews has settings to hide the map from all categories that use that listing type:

If you want to hide the map from specific categories regardless of the listing type, you can customize the theme files to remove the map code:

\com_jreviews\jreviews\views\themes\default\listings\detail.thtml
\com_jreviews\jreviews\views\themes\default\listings\listings_blogview.thtml

First create copies of those files and rename them to this:

\detail_nomap.thtml
\listings_blogview_nomap.thtml

Then delete the code for maps in those files and clear the File Registry in JReviews configuration.

To hide the map from specific categories, use the Theme Manager and add a "_nomap" theme suffix to those categories.

Chapter 9 Troubleshooting

9.1 Marker assignment via a custom field not working

The add-on allows you to use the images assigned to custom field options as markers. This is particularly useful if you've used a custom field for categorization. If the marker is not appearing on your maps you need to check a couple of things:

The field needs to be a single select or radio field because it's no possible to show more than one marker per listing.

The marker image needs to be placed in the add-on's icon folder. This means you will need to copy the image from the theme's theme_images folder to the icon folder where the add-on can find it.

9.2 List page map overlapping template header

If your Joomla template uses a fixed header/menu, it is possible that the map on JReviews list pages will overlap the header when scrolling the page.

To fix the conflict, it is necessary to push down the map by the height of the header. To do that, modify this file:

/components/com_jreviews_addons/geomaps/views/js/geomaps.js

Find this line in the file:

var y = jQuery(window).scrollTop();

and add the height of your fixed header like this:

var y = jQuery(window).scrollTop()+55;

If you enabled Load All Minified in JReviews Configuration, you will need to create a minified geomaps-ck.js file as well.

Besides the change in the geomaps.js file, it is necessary to set the height like this in the custom_styles.css file of your JReviews theme:

.jr-map-results-wrapper.fixed {
    top: 55px;
}

In these examples, 55 represents the height of the header/menu.