The location/map field type
Note: These features are part of the Visforms Subscription and are not included in the free Visforms version.
For a better understanding, we recommend reading the documentation completely and using the
Section Introduction
to start.
Relationships explained in earlier sections of the documentation are not repeated here.
What is a location
Locations are points on the earth’s surface. Their location can be specified with the help of so-called geo-coordinates.
These are two values:
- a latitude describing the location in north/south direction and
- a longitude describing the location in east/west direction.
Valid latitudes are between -90 and 90 degrees.
Valid longitudes between -180 and 180 degrees.
In Visforms all geo-coordinates must be specified as decimal values and not as arc minutes and seconds. Geo coordinates must have at least one decimal place of accuracy.
Note: A period should be used as the decimal separator.
Create a location field
Create a new field for your form in the usual way and select “Location” as the field type.
If you want to display a map with the field, please set appropriate default values for the latitude and the longitude, which should be used as the map center. These values determine which map section is displayed as long as the Geolocation fields in the form are empty. By default, Visforms sets the map center to 0.00, 0.00. This is the point where the 0th degree of longitude intersects the equator.
Without further settings, the location field in the frontend is now displayed as shown in the figure.
Depending on the selected form layout, the display may differ slightly.
Automatic location detection
In addition to manually entering geo-coordinates in the form, you also have the option of offering the user an automatic location determination.
Visforms offers two options for automatic location determination:
- Determination of the user’s current location using the web browser Geo API.
- Location search based on an address using Google Geocoder.
Both options can be switched on separately and also used simultaneously.
Determining the current location of the user using the Browser Geo API
The “My Location” button that appears with the location field on the form allows the user to determine their current location. The location data is automatically transferred to the input fields for latitude and longitude. If a map display is activated, the adopted location is shown with a marker on the map.
This functionality uses the Geolocation API. The Geolocation API is an API provided by the browser. The user can decide for himself whether he wants to allow a location determination or not. If necessary, the browser asks the user before determining the location. The user decides for himself whether he wants to allow location determination.
It is possible that the browser does not provide a geolocation API or that the user refuses to determine the location. In these cases, Visforms issues a corresponding message when the user clicks on the “My location” button.
Set the “Show my location button” option to “yes”.
Address search
When searching for an address, the user is shown an additional input field in which he can enter an address. The geo-coordinates can be determined for this address. The determined location data is then automatically transferred to the input fields for latitude and longitude. If a map display is activated, the adopted location is shown with a marker on the map.
This functionality uses Google’s Geocoder API. You can only use this functionality if you have a valid Google Maps API key and have saved it in the Visforms configuration. If the geocoder does not find a suitable location for a search query, a corresponding error message is issued.
You must note the following:
- Make sure you have a valid Google Maps API key and have it stored in the Visforms configuration.
More in: First Steps. - Set the “Show address search field” option to “yes”.
Show map
In the field configuration you can specify whether a map should also be displayed in the form in addition to the input fields for the geo-coordinates. Additional settings can be made for this card.
Map configuration options in the form
You must note the following:
- Make sure you have a valid Google Maps API key and have it stored in the Visforms configuration.
More in: First Steps. - Check the “Show map” checkbox in the field options.
- You can specify default values for latitude and longitude.
- You can adjust the map height.
The map height must always be specified as a number and is the height in pixels. - You can adjust the zoom factor at which the map is displayed.
The larger the zoom factor, the more detail you can see on the map.
Map display in the form
Check out this sample form: Form with card.
Note: The display may look slightly different depending on the form layout.
Marker and map center
Visforms differentiate between the case that valid geo coordinates are available and no valid geo coordinates are available.
If valid geo-coordinates are available, these are used as the center of the map. Furthermore, Visforms automatically adds a marker to the map. The marker shows the location specified by the geo coordinates.
If no valid geo-coordinates are available, the values stored in the field configuration for the map center are used and no marker is displayed on the map.
Miscellaneous
You can use the saved geo coordinates in emails and use Geolocation fields as placeholders in email and result texts. All field settings are supported in the frontend data editing view. Editing of the geo-coordinates in the data view in the administration is only possible to a limited extent.