Gravity Forms Geolocation

This documentation page will teach you how to setup and use the Gravity Forms Geolocation add-on. Gravity Forms Geolocation add-on requires Gravity Forms plugin which is not included when purchasing the add-on. Click here if you would like to purchase your own copy of Gravity Forms plugin.

License key Activation

Once you have Gravity Forms Geolocation add-on installed and activated, it is recommended that you activate the license key provided to you when you purchased the plugin. If you do not remember or lost the license key you can retrieve it from your Purchase History page. The license key will provide you with support and automatic updates for Gravity Forms Geolocation add-on.

To enter the license key navigate to the plugins page of the admin's dashboard.

License Key Box

License Key Box

Gravity Forms Geolocation Setup

Adding the geolocation elements to any of your Gravity forms is as simple as adding any other Gravity Forms' form fields:

First, navigate to the form editor of one of your existing forms ( or create a new form ). In the form editor page you will see the new "Geolocation Fields" fields group created by Gravity Forms Geolocation add-on.  In the Geolocation Fields group you will see the new geolocation fields button;  Geocoder, Locator button, Address, Coordinates, and Google map. You can add as many geolocation fields to the form as you wish, just like any other form fields.

Geolocation fields group

Geolocation fields group

Before I go into details and explain about each of the geolocation fields it is important that you understand how to make the fields work properly.

You can add any of the geolocation fields to the form and they will display and work just fine. However, the important thing is to sync ( or group ) between the different geolocation fields and make them work together, so the location entered by the front-end user will be properly geocoded.

What Does Fields Syncing ( or grouping ) Means?

Say, for example, that you have a form with an address field, locator button, Coordinates and Google map. And you want that each time when the front-end user drags the marker on the map, the address field and coordinates will dynamically populated with the location information returned from the map. And same goes vice versa; if the user manually enters a set of coordinates, an address or uses the address autocomplete to select an address, the map marker would dynamically set in the position of the address that the user entered. Same applied to the locator button; if the user clicks the locator button and the browser successfully detects his current position, then the map, the address field and the coordinates would dynamically populated with the current location returned from the browser.

The field that responsible for the syncing described above is the Geocoder field; The Geocoder field will not only sync between the different geolocation fields but will also perform a complete geocoding for the address entered manually or found via the map or locator button.

You can create unlimited geolocation groups; Groups of an address field, coordinates, Google map and locator button. And it doesn't have to be all fields. It can be a map only, map and address field, map and coordinates, locator button and map and so on.

This way, for example, you can create a form that allows the user to enter the addresses of two locations: home address and work place address. You can present the user with two sets of address field textbox and a Google map, so he can enter or find each of the two locations. On form submission, you will see in the entry page a complete geocoded information for each of the locations entered by the user. You can as well receive the location information via email notification.

Basically, you can sync ( or group ) the different geolocation fields together using the geocoder field ID. You can add as many geolocation fields to the form and sync them using different geocoder fields.

Each geolocation field can only be synced to one geocoder. Means that you can group one address field, one locator button, one coordinates field and one map to a specific geocoder field. But you can create as many such groups as you wish.

The list of the location fields returned by the geocoder are listed below:

  • Street number
  • Street name
  • Street ( street number + street name )
  • Permise
  • Neighborhood
  • City
  • County
  • Region code ( state code )
  • Region name  ( State name )
  • Postcode ( zip-code / postal code )
  • Country code
  • Country name
  • Address ( the original address entered by the user )
  • Formatted address - formatted address returned after geocoding
  • Latitude
  • Longitude
Geocoder field - entry page

Geocoder field - entry page


Geolocation Fields Usage

Gravity Forms Geolocation fields are just like any other Gravity Forms fields. You can add as many fields as you wish and you can place them anywhere in your form.

Geocoder Field

When creating a geolocation fields group, it is always recommended to first add the Geocoder field. The Geocoder field is a hidden field and will not be seen by the front-end user. It comes with different field options and Its main purpose is to sync between the other geolocation fields and to hold the geocoded information. After adding the geocoder field to the form  you need to pay attention to its field ID. The geocoder field ID will serve as the geocoder ID when settings up the other geolocation fields.

Field Options:

  • Default Latitude & Default Longitude - enter default coordinates if you would like populate the location fields with a default location when the form first loads. Otherwise, leave the default coordinates fields blank to load the form with blank location fields.
  • Enable Page Locator - check this checkbox if you'd like the plugin to automatically try to retrieve the user's current position when the form first loads. Note that if the page locator is enabled the default coordinate above will be ignored.
  • Location Found Message - an alert message that will popup on the screen once the page locator successfully found the user's current position. You can leave the field blank for no message.
  • GEO my WP Post Integration ( requires GEO my WP plugin ) - check this checkbox if you would like to sync the geocoder location with GEO my WP when creating a post. This way, the post created will be searchable via GEO my WP search forms. Note that only one geocoder can be synced with GEO my WP posts.
  • GEO my WP User Integration ( requires GEO my WP plugin and User Registration add-on ) - check this checkbox if you would like to sync the geocoder location with GEO my WP users database.  This way, a registered user ( or when a user updates his location ) will be searchable with GEO my WP search forms (  Members Locator and WP Users search forms ). Note that only one geocoder can be synced with GEO my WP users.
  • Custom Field Name - save the complete geocoded information as an array in a single custom field when creating a post.
  • User Meta Field Name - save the complete geocoded information as an array in a user meta field. The information will be saved in a user meta of the user who submitting the form.
  • Meta Fields Setup - save each of the geocoded fields in a custom field, user meta field or BuddyPress profile field ( Require BuddyPress plugin ) or your choice. Click on the "Show Fields" link to see the list of fields.
Geocoder field options

Geocoder field options


Locator Button

The locator button provides the user with an easy way to retrieve his current position. It is an HTML button that once clicked, it will trigger the browser geolocation which will try to retrieve the user's current position ( using HTML 5 geolocation ). If the current position successfully found, it will be geocoded by the geocoder field. If an address field, coordinates or Google map are synced with this locator button, they will be dynamically populated with the location returned by the browser.

Field options:

  • Field Label - Gravity Forms'  field label that will be displayed above the button. Leave it blank for no field label.
  • Geocoder ID - select the geocoder field ID which you'd like to sync the button with.
  • Button label - the label for the HTML button. For example, "Locate me".
  • Location found message - enter a message that will popup once the current location successfully found. For example, "Location found!". You can leave the field blank if you do not want to display a message.

Address Field

Using the address field, the front-end user can enter an address that will then be geocoded by the geocoder field, if synced with one. If the address field is also synced with coordinates or Google map fields, then the map marker will dynamically set to the right position on the map and the coordinates fields will automatically populated with the values.  For the address field, you can also enable the address autocomplete feature and a locator button that will be placed inside the address field.

The address geocoding is happens dynamically when pressing the Enter key while in the address input field or once leaving ( focusout ) the field.

Field options:

  • Geocoder ID - Select the geocoder field ID which you'd like to sync the address field with.
  • Enable Locator Button - Display a locator icon inside the address field that would serve the same purpose as the locator button describe above.
  • Location found message - enter a message that will popup one the current location successfully found by the locator button. For example, "Location found!". You can leave the field blank if you do not want to display a message.
  • Enable Address Autocomplete - enable Google Places address autocomplete which provides the front-end user with live suggested results while typing an address. This way the user does not have to type the full address. Rather, he can quick choose it from the suggested results.
  • Address Autocomplete Types - Select the type of results that will be displayed in the suggested results. Click here to read more about the autocomplete types.
  •  Restrict Autocomplete Results - you can restrict the suggested results to a single country by choosing the country from the drop-down menu.

Coordinates Field

Using the Coordinates field, the front-end user can enter latitude and longitude that will then be reversed geocoded by the geocoder field, if synced with one. If the coordinates field is also synced with address or Google map fields, then the map marker will dynamically set to the right position on the map and the address field will dynamically populated with the address.

The coordinates geocoding is happens dynamically when pressing the Enter key while in one of the coordinates input fields or once leaving ( focusout ) the fields.
Field options:

  • Geocoder ID - Select the geocoder field ID which you'd like to sync the coordinates field with.
  • Latitude Placeholder - enter the text that will be used as the latitude field placeholder.
  • Longitude Placeholder - enter the text that will be used as the longitude field placeholder.

Google Map Field

Using the Google map field, you can provide the user with another method for finding his desired location; That's instead of or together with the address field , coordinates and locator button. The front-end user can drag the marker anywhere on the map and the location, if synced with a geocoder field, will be geocoded. If the map also synced with an address field and/or coordinates, the fields would then be populated with the location values.

Field options:

  • Geocoder ID - select the geocoder field ID which you'd like to sync the map with.
  • Default Latitude - the latitude of the initial location that will be displayed when the form first loads.
  • Default Longitude - the longitude of the initial location that will be displayed when the form first loads.
  • Map Type - select between ROADMAP, SATELLITE, HYBRID or TERRAIN.
  • Zoom Level - Select  the initial zoom level of the map.
  • Map width - enter the map width in pixels or percentage. For example, 100% or 250px.
  • Map height - enter the map height in pixels or percentage. For example, 100% or 250px.
  • Map marker URL - entere a URL of an image that will be used as the map marker. Otherwise, leave the field blank to use the default red marker.
  • Draggable Map Marker - Enable / disable the marker draggable feature. This way you can either allow the use to set his position by dragging the marker on the map or disable marker dragging to only allow the map to be set by the other geolocation fields.
  • Enable Mouse Scroll-wheel Zoom - enable / disable map zoom via the mouse scroll wheel.

Advanced Address Field Geolocation

Gravity Forms plugin comes with an advanced address field built in. Gravity Forms geolocation add-on integrates with this address field as well and allows you to sync it with a geocoder and use it for geocoding an address.

You can also enhance the address field with Google Places address autocomplete and with a locator button. When enabled, you will see an additional field added to the address field. This field will serve as the Google address autocomplete field and if the locator button is enabled, the locator icon will be placed inside this field.

The additional field options that Gravity Forms Geolocation add-on adds to the advanced address field are listed below:

  • Geocoder ID - select the geocoder field ID which you'd like to sync the address field with.
  • Enable Locator Button - Display a locator icon inside the address autocomplete field that would serve the same purpose as the locator button describe above.
  • Location found message - enter a message that will popup one the current location successfully found by the locator button. For example, "Location found!". You can leave the field blank if you do not want to display a message.
  • Enable Address Autocomplete - enable Google Places address autocomplete which provides the front-end user with live suggested results while typing an address. This way the user does not have to type the full address. Rather, he can quick choose it from the suggested results.
  •  Restrict Autocomplete Results - you can restrict the suggested results to a single country by choosing the country from the drop-down menu.
  • Autocomplete Placeholder - entere a text that will be used as the placeholder of the address autocomplete field.
  • Field Description - enter a description that will be displayed below the address autocomplete field. Otherwise, leave blank for no description.
  • Custom Field Name - Gravity Forms Geolocation add-on enables the custom field option for the advanced address field. This way, when creating a post, you can save the address fields value as an array in a custom field of your choice. This option is also important when using the "Gravity Forms : Update Post" add-on; It makes it possible to have the address fields value auto-populated with the saved values when updating a post.

Dynamic Location Field Options

The output location field is another useful feature. This is a field option which attached to the single line text, checkbox, drop-down, radio buttons, custom field and hidden fields. Using this field, you can create dynamic location fields that will dynamically populated with the selected address field each time a geocoding is taking place in the form.

This way you can add hidden fields, for example, to the form that will dynamically populate with the coordinates each time a user enters an address in the address field or find his location on a map. You can then save these fields value in custom fields, email to the user or admin and so on.

Field options

  • Dynamic Location Field - select from the dropdown menu the location fields that you would like to dynamically populate.
  • Geocoder ID - select the geocoder field ID which you'd like to sync this field with.

Gravity Forms Update Post Add-on Integration

Gravity Forms Update Post plugin is a free, and very useful, Gravity Forms add-on. The add-on allows you to edit posts using Gravity Forms from the front-end. Gravity Forms Geolocation add-on integrates with Gravity Forms Update Post add-on and the setup is fairly simple.

When updating a post using Gravity Forms from the front-end, the form fields should already be populated with the existing value ( if there are any ) when the form first load. To make this possible, you need to set a custom field for each of the form fields, including the geolocation fields. You can do so using the "Custom field name" field option. You can either choose an existing custom field from the dropdown select menu or enter a new field.

The Geolocation fields that has this field option are the Address, Coordinates and the Geocoder fields. Once you assign custom fields for the geolocation fields, the fields values will be saved after a post was created. These saved values will also be auto-populated when the post update form first loads.

Note that by default, the Advanced Address field ( created by Gravity Forms plugin ) does not have the custom field option. However, Gravity Forms Geolocation plugin enables this option for the field and makes it possible to use it with Gravity Forms Update Post plugin.

Custom field option

Custom field option

User Registration Add-on Integration

Gravity Forms Geolocation add-on also integrates with Gravity Forms User Registration add-on. You can use the Geolocation fields with "Create User" and "Update User" forms created by Gravity Forms User Registration add-on. When you do so, you want to make sure that you assign each of the Geolocation fields to a user meta field. You need to do so if you want the Update User form to already populate the geolocation fields' ( or any other form fields in general ) existing values when the form first loads.

Assigning user meta fields to the form fields is a fairly simple process and is described below. It is very important that you follow the same steps and use the same user meta fields for both "Create User" and "Update User" forms.

Assuming that you already have the Gravity Forms User Registration add-on installed and activated and already have "Create User" and "Update User" forms, follow the steps below to assign user meta field to the geolocation fields of your forms:

  1. Navigate to the "User Registration"  Settings page of your form.
  2. Click to edit an existing "Create User" or "Update User" feed ( otherwise, create a new feed ).
  3. In the Feed page, scroll down the screen to where you will see the "User meta" section.
  4. Choose the form field you'd like to assign from the dropdown select menu and enter a user meta in the text input box. You can add and assign as many fields as you need.
  5. The geolocation fields that need to be assign to user meta are: address, coordinates, advanced address and geocoder.
  6. When assigning user meta to the advanced address field you will need to save each field of the address field in its own user meta.
  7. Update the settings when done.