GeoMaps Add-on Manual

Size: px

Start display at page:

Download "GeoMaps Add-on Manual"

Polly Johnson
6 years ago
Views:

1 GeoMaps Add-on Manual

2 Last update: January 9th, 2014 Copyright ClickFWD LLC

3 Table of contents Chapter 1 GeoMaps Add-on Overview & Installation Overview Installation Chapter 2 GeoMaps Con>guration Basic Setup Markers & Infowindow Maps Chapter 3 Address Geocoding Geocoding individual addresses Batch Geocoding Geocoding addresses in new listings Chapter 4 Custom Markers Marker icons by category Marker icons by custom Peld options Using diserent icons for featured listings and mouseover event Chapter 5 Performing Proximity Searches Chapter 6 Displaying Maps Map on listing detail and list pages GeoMaps Module Chapter 7 Theme Customization Listing detail page map List pages map GeoMaps module map Marker infowindow Chapter 8 Tips & Tricks How can I show the Map inside a tab on the listing detail page How to hide the map from certain categories Chapter 9 Troubleshooting Marker assignment via a custom Peld not working List page map overlapping template header

4 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 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. Copyright ClickFWD LLC 4

5 Chapter 1 GeoMaps Add-on Overview & Installation 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 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: faq#usagelimits. Copyright ClickFWD LLC 5

6 Chapter 1 GeoMaps Add-on Overview & Installation 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: 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. Copyright ClickFWD LLC 6

Chapter 1 GeoMaps Add-on Overview & Installation 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

7 Chapter 1 GeoMaps Add-on Overview & Installation 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: Copyright ClickFWD LLC 7

8 Chapter 1 GeoMaps Add-on Overview & Installation Reload the page to see the GeoMaps link appear under the Add-ons header on the left sidebar: Copyright ClickFWD LLC 8

9 Chapter 1 GeoMaps Add-on Overview & Installation Copyright ClickFWD LLC 9

that country. For example: //maps.google.es, //maps.google.it, //maps.google.de.

10 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 ( Copyright ClickFWD LLC 10

11 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. Copyright ClickFWD LLC 11

$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$

12 Chapter 2 GeoMaps ConPguration 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 alpha-2 ( 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 Copyright ClickFWD LLC 12

Chapter 2 GeoMaps ConPguration 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.

13 Chapter 2 GeoMaps ConPguration 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: Copyright ClickFWD LLC 13

) that will be made available for inclusion via tags in the infowindow theme

14 Chapter 2 GeoMaps ConPguration 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. Copyright ClickFWD LLC 14

15 Chapter 2 GeoMaps ConPguration 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. Copyright ClickFWD LLC 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 &

16 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: Copyright ClickFWD LLC 16

17 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: Copyright ClickFWD LLC 17

Addresses button to begin batch geocoding.

18 Chapter 3 Address Geocoding 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. Copyright ClickFWD LLC 18

19 Chapter 3 Address Geocoding 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: Copyright ClickFWD LLC 19

20 Chapter 3 Address Geocoding If you want to change the address then you need to click on "Clear LatLng" to geocode the new address. Copyright ClickFWD LLC 20

in a couple of ways: 1. By category - all listings in a category will have the same marker 2.

21 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: Copyright ClickFWD LLC 21

22 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: Copyright ClickFWD LLC 22

Chapter 4 Custom Markers 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.

23 Chapter 4 Custom Markers 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} Copyright ClickFWD LLC 23

24 Chapter 4 Custom Markers {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. Copyright ClickFWD LLC 24

25 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: Copyright ClickFWD LLC 25

26 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: Copyright ClickFWD LLC 26

27 Chapter 5 Performing Proximity Searches Copyright ClickFWD LLC 27

28 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: Copyright ClickFWD LLC 28

29 Chapter 6 Displaying Maps Example of a map on a list page: Copyright ClickFWD LLC 29

Chapter 6 Displaying Maps 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.

30 Chapter 6 Displaying Maps 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: Copyright ClickFWD LLC 30

31 Chapter 6 Displaying Maps 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. Copyright ClickFWD LLC 31

Chapter 6 Displaying Maps Directory/Category/Listing IDs - Plter the markers shown using these settings. It s not necessary to Pll in all of them, just one.

32 Chapter 6 Displaying Maps 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 ( 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. Copyright ClickFWD LLC 32

33 Chapter 6 Displaying Maps You can turn on and os all of the standard Google Map controls using these parameters. Copyright ClickFWD LLC 33

34 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 ( 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 If you want to customize it, copy it Prst 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 Ple: Copyright ClickFWD LLC 34

$thtml If you want to customize it, copy it Prst to your custom theme in overrides: /templates/jreviews_overrides/views/themes/{your_theme}/modules/geomaps.thtml 7.$

35 Chapter 7 Theme Customization /components/com_jreviews_addons/geomaps/views/themes/geomaps/modules/geomaps.thtml If you want to customize it, copy it Prst 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 Ple /components/com_jreviews_addons/geomaps/views/themes/geomaps/geomaps/map_infowindow.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_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> Copyright ClickFWD LLC 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/?

36 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 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 Copyright ClickFWD LLC 36

37 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. Copyright ClickFWD LLC 37

38 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: Copyright ClickFWD LLC 38

39 Chapter 9 Troubleshooting.jr-map-results-wrapper.fixed { } top: 55px; In these examples, 55 represents the height of the header/menu. Copyright ClickFWD LLC 39

MyLists Add-on Manual

MyLists Add-on Manual Last update: July 27th, 2015 Copyright 2010-2015 ClickFWD LLC Table of contents Chapter 1 MyLists Overview & Installation............... 4 1.1 Features....................................................................