Maps and Locations (Paid Addon)

This module allows to easily build locations/regions database, so users search by selecting locations they are interested in, instead of typing them, this will ensure there are no: typos or incorrectly spelled names when searching by location.

Google API Key

If you are going to display Google Maps on Ad details pages or use the Google Autocomplete feature to fill locations database it is best to signup for a free Google API Key.

The process is a bit complicated but once you know what to do it will not take longer than a few minutes. To make it easier for you we created a separate article with Google API Key setup instructions for MAL, the article also includes a video with the exact steps you need to take.

About entering a location in Ads

Before we go into configuration details, there is one important decision (by important I mean hard to change later when your Ads database will grow) you need to make. The decision is how do you want to enter Ads location? The “Maps and Locations” add-on (short MAL) allows two methods: using Google Places Autocomplete or using a normal dropdown field filled with location taxonomy. I will describe the pros and cons of each below so you can make an informed decision:

Google Places Autocomplete

• users will fill locations database when adding new Ads, so less work for you.
• allows users to quickly fill location with one click.
• locations are applied to Ads, so the Google Map can show the specific point on map, for example, a street number.
• more complicated setup and usage than in the second method
• locations database can be filled only with locations available in Google Places API

 

Taxonomy Dropdown

• you need to fill the locations database manually from wp-admin panel
• locations are applied to Terms, so usually on maps, the marker will point to zip-code or city only.
• easy for users, they just need to pick a location from the select box

Configuration

Once you have the add-on installed, go to wp-admin / Classifieds / Options / Maps and Locations panel in order to configure it. You should see form similar to the one below:

There are following fields in the form:

• Google API Key, you can get the API key as explained at the beginning of this article, once you enter it make sure to click “Check” button to make sure your API key is valid.
• [adverts_add] Location Field, as explained in previous chapter select how you would like to enter locations in the [adverts_add] shortcode and in wp-admin panel (basically every time you post or edit an Ad). Note that if you select Google Autocomplete option, few more fields to fill will show.

• Location Format – select how you would like to have the location displayed once user will fill the form (notice bold “New York, NY” on the right side of the first image). This will apply only to the form, on Ad details page location will display as a taxonomy path.
• Options – currently only one option, checking it allows to fill location with a single click, the location is picked from user browser. In other words, the single click allows filling the location form with current user location (notice blue crosshair on the first image).
• Language – allows to select Google Autocomplete language, this will not only set the UI language but will also return results localized.
• Limit Results To – enter two-letter ISO-3166-1 country code here, this will force Google Autocomplete to return results for your selected country only.

 

Ok, let us get back to the basic configuration:

• [adverts_list] Configuration, here you can replace the default search by location input text with either: auto-complete field or a drop-down.

• Radius (since 1.1.0), checking this check box will enable search by radius and it will automatically insert Radius drop down into [adverts_list] search form.
• Distance Unit (since 1.1.0), this field allows to select how do you want to measure distance, allowed options are either kilometers or miles.

 

• Ad Details Page – Use Map, allows to enable / disable displaying Google Map on Ad details page.

• Ad Details Page – Map Visibility: allows selecting if the map should be visible on page load or on click on the “show on map” button. If you select visibility on page load then the “show on map” link will not be visible, so it will not be possible to hide the map.

Maps with Adverts Shortcode

Since version 1.2.0 there is [adverts_mal_map] shortcode available, it allows to display Ads on a Google Map, the shortcode has following attributes

• autolocation: boolean (default false)
• width: string (default “100%”) – sets map width either in percentages or pixels
• height: string (default “500px”) – sets map height either in percentages or pixels, although for height pixels are recommended
• disable_filter: int (default 0) – if set to 1 the filter on map will not show
• redirect_to: string (default “”) – either ID or an URL to page where user will be redirected when searching
• form_scheme: string (default null) – this should be a name of a form scheme to use. The form scheme will be applied to the search bar on map. This parameter should be used only if you have Custom Fields add-on installed and some custom forms configured.
• js_engine: string (default “google”) – one of “google” and “osm” allows selecting if you want to use Google or Open Street Maps.
• js_search_form: (for developers only) – a CSS class pointing to <form> which will be used a search form for the map.
• js_search_submit: (for developers only) – a CSS class pointing to a button or input which submits the js_search_form.
• js_results_list: (for developers only) – a CSS class pointing to a <div> which will show results.
• js_results_pagination: (for developers only) – a CSS class pointing to a <div> which will show pagination.

Advanced Fields Configuration

Below the basic configuration, you can find Advanced Fields Configuration, it applies mainly to Google Autocomplete, but is also used in Location taxonomy to determine based on level, what kind of region (country, state, city or postal code, address) does the taxonomy represent.

As you can see each region has 3 fields:

• Taxonomy Level – in the setting as visible on the screen, countries will be at level 0, states at level 1 and cities at level 2. Postal Code and Address will not be saved in taxonomies as this can contain private data which most of the time users do not want to share.
• Field Type – allows selecting how the field will be displayed when entering a location (in advanced form after clicking “change” button). It’s recommended not to allow users to edit fields which you will be saving in taxonomies.
• Name Type – Google Autocomplete sometimes returns region name in two forms: short and long. You can decide here which one you want to use.

Location Taxonomy

Location Taxonomy allows administrator group places / locations in hierarchical order. For example, country USA has a child (state) “NY” which has its own child (city) “New York”.

In order to configure location taxonomies (create terms) go to wp-admin / Classifieds / Locations panel. If you are new to WordPress and unsure how to add / edit / delete location there please refer to WordPress: Manage Categories documentation.

It works pretty much the same for WPAdverts Locations, except when editing a location you can set the location place on the map. To set the term location, first add a new Location, next click on it to edit. When a page will load at the bottom you should see a map similar to the one below:

There are few ways to set term location on the map:

• Enter the location in the input box and click “Search …” next to it or hit enter, this should take you to the exact location.
• Drag the pin to the desired place on the map.
• Change zoom value to zoom in or out the map.
• Click Edit button and provide exact Latitude and Longitude.

Search by Radius

Since version 1.1.0 MAL add-on allows to search by radius. This is quite a complex feature and before using, please read the instructions below in order to get most of the radius search and have most accurate results.

In order to do a radius search, some geolocation data (latitude and longitude) are required, usually you will need center (text you enter in “Location” field in the search form) and geolocation data for each Ad, those Ads which do not have geolocation data will never be returned when searching by radius.

Geolocation data is hard to get, MAL is harvesting it from Google Geocoding service, therefore if you would like to allow your users to search by radius it is recommended to use following settings for [adverts_add] and [adverts_list].

• [adverts_add] Location Field set to Google Autocomplete and [adverts_list] Location Field set to Replace ‘location’ input with Google auto-complete. This will allow setting exact position for each Ad (as accurate as the street address) and similarly when searching you can make the search center as accurate as the street address.
• [adverts_add] Location Field set to Dropdown filed with Location taxonomy and [adverts_list] Location Field set to Replace ‘location’ input with drop-down or Replace ‘location’ input with Google auto-complete. Using this method Ads locations will be inherited from predefined Locations terms (wp-admin / Classifieds / Locations panel). To make this work properly you should make sure that each Location has “Location on map” set. Searching allows one of two options: dropdown (when using it the search center will be derived from selected term), Google autocomplete (similarly as above, geolocation data will be returned from Google geo coding service).

If you setup MAL differently then it will NOT be possible to search Ads by radius as there is no way to gather latitude and longitude required to make the search possible.

Coordinates Sync

For easier and faster searching by radius, geolocation data is stored in separate table, if you are upgrading to MAL 1.1.0, and have some ads already created you can add them to this table using MAL Sync plugin.

Using this plugin is very simple, download zip file, then go to wp-admin / Plugins / Add New / Upload panel and install and activate it from there. Next go to wp-admin / Tools / MAL Sync, you should see either:

• “Sync Now!” button – click it and Sync plugin will update geolocation data for all your Ads
• “Create Now!” button – it shows, if MAL is for some reason unable to create the custom table, the button allows to create the table again.