GeoMaps Add-on Manual - JReviews Documentation

Transcription

GeoMaps
Add-on Manual
GeoMaps Add-on Manual
Last update: January 9th, 2014
Copyright © 2010-2014 ClickFWD LLC
Table of contents
Chapter 1 GeoMaps Add-on Overview & Installation. . . . . . . 4
1.1 Overview. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4
1.2 Installation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6
Chapter 2 GeoMaps Con>guration . . . . . . . . . . . . . . . . . . . . . 10
2.1 Basic Setup. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 10
2.2 Markers & Infowindow . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 12
2.3 Maps . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 15
Chapter 3 Address Geocoding . . . . . . . . . . . . . . . . . . . . . . . . . . 16
3.1 Geocoding individual addresses . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 17
3.2 Batch Geocoding . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 18
3.3 Geocoding addresses in new listings . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 19
Chapter 4 Custom Markers . . . . . . . . . . . . . . . . . . . . . . . . . . . . 21
4.1 Marker icons by category. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 22
4.2 Marker icons by custom Peld options . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 22
4.3 Using diSerent icons for featured listings and mouseover event . . . . . . . . . . . . . . . . . . . 23
Chapter 5 Performing Proximity Searches. . . . . . . . . . . . . . . 25
Chapter 6 Displaying Maps . . . . . . . . . . . . . . . . . . . . . . . . . . . . 28
6.1 Map on listing detail and list pages . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 28
6.2 GeoMaps Module . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 30
Chapter 7 Theme Customization . . . . . . . . . . . . . . . . . . . . . . . 34
7.1 Listing detail page map . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 34
7.2 List pages map. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 34
7.3 GeoMaps module map. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 34
7.4 Marker infowindow. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 35
Chapter 8 Tips & Tricks. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 36
8.1 How can I show the Map inside a tab on the listing detail page . . . . . . . . . . . . . . . . . . . . 36
8.2 How to hide the map from certain categories . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 36
Chapter 9 Troubleshooting . . . . . . . . . . . . . . . . . . . . . . . . . . . . 38
9.1 Marker assignment via a custom Peld not working . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 38
9.2 List page map overlapping template header . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 38
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
Pne tune its location. You can also assign diSerent marker icons per category and enable 'get
directions' and 'streetview'. Combined with the Ple upload capability in JReviews, it's easy to
add a KML layer to each listing by uploading KML Ples 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 >nd 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 Pelds. 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 Pne-tune
the location by dragging the marker on the map.
4
Chapter 1 GeoMaps Add-on Overview & Installation
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 diSerent
markers for diSerent 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.
5
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 Prst in order to Pnd nearby points.
1.2 Installation
The add-on can be installed via the Install & Update menu in the JReviews administration.
6
To install or update the addon you must have previously purchased it, your JReviews version
needs to match or be greater than the one speciPed 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:
7
Reload the page to see the GeoMaps link appear under the Add-ons header on the left sidebar:
8
9
Chapter 2
GeoMaps Con2guration
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 (http://code.google.com/apis/maps/documentation/javascript/tutorial.html#api_key) .
10
Chapter 2 GeoMaps ConPguration
This is where you tell the GeoMaps add-on which custom Pelds of your listings contain address
information. All custom Pelds that you enter here must be previously created in the JReviews
Fields Manager.
Latitude and Longitude custom Pelds must be created as decimal Pelds in the JReviews Fields
Manager. They are used to store latitude and longitude data, but it is not necessary to show
those Pelds 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 Peld’s Add/Edit Access Settings in the Fields
Manager.
Map it >eld - a button will be appended to this Peld 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 Peld.
11
Advanced search address >eld - tell the addon which Peld it should use for address searches
in the JReviews Advanced Search Module. For instance, if you have a jr_address Peld, then you
can add this Peld to the advanced search module as {jr_address} and when the user types an
address in that Peld the addon will geocode the address to Pnd 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 speciPed country only. Fill
out the two letter code based on the ISO 3166-1 alpha-2 (http://en.wikipedia.org/wiki/
ISO_3166-1_alpha-2#Current_codes) dePnition.
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
Pelds in the listing details. If you want to customize the distance output, set this setting to No,
and use this code in the theme Ple 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 su?x - here you can enter a speciPc theme suRx for the
search results list page.
2.2 Markers & Infowindow
12
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 Ples
and css.
Example of a Google default infowindow:
Example of a Callout infowindow:
13
Example of a Custom infowindow:
Infowindow >elds - custom Pelds comma list, without spaces (jr_Peldone,jr_Peldtwo,etc.) that
will be made available for inclusion via tags in the infowindow theme Ple. Only add Pelds that
exist in JReviews.
14
2.3 Maps
You can turn on and oS 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.
15
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 Plters to select the listing types that require geocoding:
16
Chapter 3 Address 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 satisPed with the marker location so
your changes are saved to the database:
17
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.
18
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 Qy and adjust
the marker’s location if necessary. The add-on adds a couple of buttons after the Peld that you
designate as the "Map It" Peld in the conPguration settings.
If you enabled auto-geocoding option in the GeoMaps conPguration, it is not necessary to click
the Map it button after entering the address, but you can use it to Pne-tune the location:
19
If you want to change the address then you need to click on "Clear LatLng" to geocode the new
address.
20
Chapter 4
Custom Markers
By default, all maps will use standard red markers. If you want, you can choose diSerent marker icons for diSerent types of listings, for example:
The GeoMaps add-on lets you assign custom markers to listings in a couple of ways:
1. By category - all listings in a category will have the same marker
2. By custom >eld options - the images assigned to the select list Peld options will be used
as markers so you can have diSerent markers even within the same category.
To assign custom markers, go to the Assign Custom Markers page in GeoMaps add-on administration:
21
Chapter 4 Custom Markers
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 diSerent
folder which can be speciPed in GeoMaps conPguration.
4.2 Marker icons by custom 2eld options
If you use the custom Peld 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 Peld that contains Peld options with images.
To assign images to speciPc Peld options, go to the Field Options Manager of a custom Peld
and add images to Peld options like this:
22
If you want to use the Peld option images for map markers, but show the Peld option text in
the regular display of Pelds, theres's a setting in the Peld's Advanced Options:
4.3 Using di3erent icons for featured listings and
mouseover event
GeoMaps will use the following suRxed images for featured listings and the mouseover event
when hovering over a marker:
• {icon_name}_hover.{icon_extension}
23
• {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 Peld are setup for a category, then the select Peld takes
priority and if an option is not selected then the category icon is used.
24
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 SuRx:
This will load an alternative theme Ple for this module that includes the code for address
searching:
/components/com_jreviews/jreviews/views/themes/default/modules/advanced_search_map.thtml
The theme Ple use "jr_address" as custom Peld to perform address searches. If you named
your address Peld diSerently in the Fields Manager, edit this theme Ple and adjust the Peld
name. You can also adjust the available radius search options:
25
Chapter 5 Performing Proximity Searches
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:
26
Chapter 5 Performing Proximity Searches
27
Chapter 6
Displaying Maps
6.1 Map on listing detail and list pages
If you conPgured 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:
28
Chapter 6 Displaying Maps
Example of a map on a list page:
29
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 diSerent 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:
30
• Normal (Use ltering settings) - the map will display listings based on the Basic/Advanced
Plters 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 Su?x - if you need multiple copies of the GeoMaps module and you want
each one to use a diSerent theme Ple, you can specify a theme suRx here.
Featured Only - if enabled, the map will display only featured listings.
Click2Search Autodetect - automatically Plters results when in Click2Search pages using the
value from the click2search Peld.
Category Autodetect - Plters 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.
31
Directory/Category/Listing IDs - Plter the markers shown using these settings. It’s not necessary to Pll in all of them, just one.
Custom WHERE - Plter the markers shown based on custom database query. For more
info
read
Using
Custom
WHERE
and
Custom
ORDER
BY
parameters
(http://docs.reviewsforjoomla.com/?title=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 Pnd 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.
32
You can turn on and oS all of the standard Google Map controls using these parameters.
33
Chapter 7
Theme Customization
The GeoMaps theme Ples are located here:
/components/com_jreviews_addons/geomaps/views/themes/geomaps/
Even though you can customize the theme Ples there, that is not recommended. Instead
use
the
JReviews
Code
Overrides
(http://docs.reviewsforjoomla.com/?title=JReviews_Code_Overrides) functionality to copy specific geomaps theme Ples that you want to customize into your custom theme in jreviews_overrides folder.
7.1 Listing detail page map
The theme Ple of the JReviews listing detail page (/listings/detail.thtml) calls this Ple to load the
map:
/components/com_jreviews_addons/geomaps/views/themes/geomaps/geomaps/map_detail.thtml
If you want to customize it, copy it Prst 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 Ples call this Ple to load the
map:
/components/com_jreviews_addons/geomaps/views/themes/geomaps/geomaps/map_results.thtml
/templates/jreviews_overrides/views/themes/{your_theme}/geomaps/map_results.thtml
7.3 GeoMaps module map
The GeoMaps module uses this theme Ple:
34
Chapter 7 Theme Customization
/components/com_jreviews_addons/geomaps/views/themes/geomaps/modules/geomaps.thtml
/templates/jreviews_overrides/views/themes/{your_theme}/modules/geomaps.thtml
7.4 Marker infowindow
Marker infowindow popups use this theme Ple
/components/com_jreviews_addons/geomaps/views/themes/geomaps/geomaps/map_infowindow.thtml
/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 Pelds. First you need to specify which custom Pelds you want
to make available for the infowindow in the GeoMaps conPguration:
After that, add the Pels to the infowindow theme Ple like this:
<span class="jr-map-jr_address"></span>
<span class="jr-map-jr_phone"></span>
35
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
(http://docs.reviewsforjoomla.com/?title=Adding_jQuery_UI_tabs_to_listing_detail_page) . The
included _tabs suRxed detail theme Ple 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 speciPc categories regardless of the listing type, you can customize the theme Ples to remove the map code:
\com_jreviews\jreviews\views\themes\default\listings\detail.thtml
\com_jreviews\jreviews\views\themes\default\listings\listings_blogview.thtml
36
Chapter 8 Tips & Tricks
First create copies of those Ples and rename them to this:
\detail_nomap.thtml
\listings_blogview_nomap.thtml
Then delete the code for maps in those Ples and clear the File Registry in JReviews conPguration.
To hide the map from speciPc categories, use the Theme Manager and add a "_nomap" theme
sufPx to those categories.
37
Chapter 9
Troubleshooting
9.1 Marker assignment via a custom 2eld not working
The add-on allows you to use the images assigned to custom Peld options as markers. This is
particularly useful if you've used a custom Peld for categorization. If the marker is not appearing on your maps you need to check a couple of things:
1. The Peld needs to be a single select or radio Peld because it's no possible to show more
than one marker per listing.
2. 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 addon can Pnd it.
9.2 List page map overlapping template header
If your Joomla template uses a Pxed header/menu, it is possible that the map on JReviews list
pages will overlap the header when scrolling the page.
To Px the conQict, it is necessary to push down the map by the height of the header. To do that,
modify this Ple:
/components/com_jreviews_addons/geomaps/views/js/geomaps.js
Find this line in the Ple:
var y = jQuery(window).scrollTop();
and add the height of your Pxed header like this:
var y = jQuery(window).scrollTop()+55;
If you enabled Load All Mini>ed in JReviews ConPguration, you will need to create a miniPed
geomaps-ck.js Ple as well.
Besides the change in the geomaps.js Ple, it is necessary to set the height like this in the custom_styles.css Ple of your JReviews theme:
38
Chapter 9 Troubleshooting
.jr-map-results-wrapper.fixed {
top: 55px;
}
In these examples, 55 represents the height of the header/menu.
39

GeoMaps Add-on Manual - JReviews Documentation

Transcription

Similar documents

GeoMaps Add-‐on For JReviews

for your Commercial Real Estate Listings

Guide for Bidders of e-auction - MSTC E

For sale is a 2008 camo Gheenoe 15`4" Highsider W/ a 5HP Honda

CribMaster 9 Software

Custom Fitting Custom Fitting

av fairgrounds lancaster, ca

Citi Habitats - CIR/SEIU Healthcare

Firehouse hosts Great Big Home Show

Auckland Council GeoMaps Solutions

online reporting - Averitt Express