=== Map Field for Contact Form 7 ===
Contributors: gravitymaster
Tags: contact form 7, google maps, address autocomplete, map field, google places, cf7, location field, address field, geocoding, draggable marker
Requires at least: 5.5
Tested up to: 7.0
Stable tag: 5.0
Requires PHP: 7.4
Requires Plugins: contact-form-7
License: GPLv2 or later
License URI: https://www.gnu.org/licenses/gpl-2.0.html

Add a Google Maps autocomplete address field with a live interactive map to any Contact Form 7 form. Supports draggable marker, address components, and responsive map heights.

== Description ==

**Google Map Field for Contact Form 7** is the most complete solution for adding a Google Places address autocomplete field to your Contact Form 7 forms. Users type a few characters, select from live suggestions, and an interactive Google Map appears instantly — no page reload needed.

The draggable marker lets users fine-tune the exact pin position. When dragged, the address and coordinates update automatically via reverse geocoding — so what gets submitted is always accurate.

### ✨ Key Features

* **Google Places Autocomplete** — real-time address suggestions powered by the Google Places API (new PlaceAutocompleteElement)
* **Always-visible interactive map** — map renders on page load using your configured default centre; no address selection required
* **Draggable marker** — users drag the pin to the exact location; address and lat/lng fields update automatically via reverse geocoding
* **Responsive map heights** — set separate pixel heights for desktop (> 768 px) and mobile (≤ 768 px) from the admin
* **Default map centre** — configure a default latitude and longitude so the map opens on the right region for your audience
* **Address component sub-fields** — optionally show separate inputs for Street Number, City, State, Postcode, and Country; each auto-populated on place selection
* **Country filter** — restrict autocomplete suggestions to one or more countries using ISO 3166-1 alpha-2 codes (e.g. `in`, `us`, `gb`)
* **Place type filter** — limit suggestions to specific place types such as `airport`, `restaurant`, or `art_gallery`
* **Mail-tag support** — use `[fieldname-locality]`, `[fieldname-state]`, `[fieldname-postcode]`, and `[fieldname-country]` mail tags in CF7 email templates
* **Lat/Lng hidden fields** — latitude and longitude are captured as hidden fields for backend processing or CRM integrations
* **Elementor popup compatible** — autocomplete and map re-initialise correctly when used inside Elementor popups
* **Elegant form field design** — modern, accessible frontend styling with focus rings, smooth transitions, and validation error states
* **Translation ready** — all field labels are customisable from the settings page; compatible with WPML and Polylang

### 🗺️ How It Works

1. Install and activate the plugin (Contact Form 7 must be active)
2. Go to **Contact → Google Place API** and enter your Google Places API key
3. In any CF7 form editor, use the new **Field Autocomplete** tag to insert a `[googlemapfield]` tag
4. Configure map height, default centre, and address sub-fields from the settings page
5. The map appears automatically on your form — users pick an address and the marker updates in real time

### 🔑 Google API Key Setup

This plugin requires a Google Cloud API key with the following APIs enabled:

* Maps JavaScript API
* Places API (New)

[Full setup guide →](https://www.codesmade.com/create-google-map-place-api-key/)

### 📬 Mail Tag Reference

After adding a `[googlemapfield your-location]` tag to your form, use these mail tags in your CF7 email template:

| Mail Tag | Returns |
|---|---|
| `[your-location]` | Full formatted address |
| `[your-location-locality]` | City / Locality |
| `[your-location-state]` | State / Province |
| `[your-location-postcode]` | Postal code |
| `[your-location-country]` | Country |

### 💼 Use Cases

* **Delivery forms** — capture precise delivery addresses with postcode and city auto-filled
* **Event registration** — let attendees specify their nearest location or venue
* **Job applications** — collect applicant location with lat/lng for distance filtering
* **Real estate enquiries** — capture property address with map confirmation
* **Service booking** — validate service area coverage before form submission
* **Travel & hospitality** — autocomplete hotel, airport, or attraction names

== Installation ==

= Automatic Installation =

1. Log in to your WordPress dashboard
2. Go to **Plugins → Add New**
3. Search for **Map Field for Contact Form 7**
4. Click **Install Now**, then **Activate**

= Manual Installation =

1. Download the plugin ZIP file
2. Go to **Plugins → Add New → Upload Plugin**
3. Upload the ZIP file and click **Install Now**
4. Click **Activate Plugin**

= After Activation =

1. Make sure **Contact Form 7** is installed and active
2. Go to **Contact → Google Place API**
3. Enter your Google Places API key ([how to get one](https://www.codesmade.com/create-google-map-place-api-key/))
4. Configure map height and default map centre
5. Open any CF7 form and add the **Field Autocomplete** tag via the tag generator

== Frequently Asked Questions ==

= Does this plugin require Contact Form 7? =

Yes. Contact Form 7 must be installed and active. The plugin will not load without it.

= Which Google APIs do I need to enable? =

Enable **Maps JavaScript API** and **Places API (New)** in your Google Cloud Console. Both must be active on the same API key. [Step-by-step guide →](https://www.codesmade.com/create-google-map-place-api-key/)

= Can I restrict autocomplete to a specific country? =

Yes. In **Contact → Google Place API**, enter comma-separated ISO 3166-1 alpha-2 country codes in the **Country Filter** field. For example: `in,gb,us` to allow India, UK, and USA only.

= Can I show only certain address sub-fields? =

Yes. In the **Address Sub-fields** section of the settings page, tick only the components you want to display: Street Number, Postcode, City, State, and/or Country.

= How do I use the address value in CF7 emails? =

Add the mail tag that matches your field name. If your field is named `your-location`, use `[your-location]` in your email template for the full address. For individual components, use `[your-location-locality]`, `[your-location-state]`, etc.

= Can I capture latitude and longitude? =

Yes. Add hidden inputs named `your-field-name_latitude` and `your-field-name_latitude` to your form. They are populated automatically when an address is selected or when the marker is dragged.

= Does the map work inside Elementor popups? =

Yes. The plugin listens for the `elementor/popup/show` event and re-initialises the autocomplete and map automatically.

= Is the map always visible or only after address selection? =

The map is always visible as soon as the page loads. It centres on your configured **Default Latitude / Longitude** with a wide zoom level. When the user selects an address, it zooms to street level and moves the marker.

= Can the user fine-tune the pin location? =

Yes. The marker is fully draggable. When the user drags it, the plugin reverse-geocodes the new position using the Google Geocoding API and updates the address field and coordinate fields automatically.

= Is the plugin compatible with caching plugins? =

Yes. All dynamic data (API key, heights, default coords) is output server-side on page load. Standard full-page caching is compatible as long as the page containing the CF7 form is not cached when the API key is blank.

= Can I translate the field labels? =

Yes. Every visible label — including the autocomplete placeholder, City, State, Postcode, Country, and Street Number labels — can be customised from **Contact → Google Place API → Field Labels**.

== Screenshots ==

1. Frontend form field with Google Places autocomplete and interactive map
2. Draggable marker — drag to fine-tune location, address updates automatically
3. Admin settings page — API key, map height, default centre, address sub-fields
4. CF7 tag generator panel — insert the googlemapfield tag with one click
5. Email template using address mail tags

== Changelog ==

= 4.0 =
* New: Map is always visible on page load — no longer hidden until address selection
* New: Configurable default map centre (latitude and longitude) from admin settings
* New: Separate responsive map heights for desktop and mobile screens
* New: Draggable `AdvancedMarkerElement` with automatic reverse geocoding on drag end
* New: Elegant card-based admin settings page with dedicated `admin.css` file
* New: Admin CSS loaded only on plugin settings page via `admin_enqueue_scripts`
* New: Elegant frontend field styling — rounded inputs, focus rings, transitions
* Fixed: Replaced deprecated `google.maps.Marker` with `AdvancedMarkerElement` (required for Maps v=beta)
* Fixed: Added `marker` library to Google Maps API script URL
* Fixed: Map instance now reused on subsequent address selections — no more re-creation flicker
* Fixed: Replaced deprecated `WPCF7_Shortcode` class with `WPCF7_FormTag` (CF7 5.6+)
* Fixed: Settings link in plugin action links now points to the correct admin page slug
* Fixed: Include file names now match class names so the autoloader can find them
* Fixed: Tag generator "Setup API Key" link now points to the correct admin page

= 3.0 =
* Added address component sub-fields (Street Number, City, State, Postcode, Country)
* Added mail-tag support for address components
* Added country filter and place type filter options
* Added translation/label customisation settings

= 2.0 =
* Added Google Map display on address selection
* Added Elementor popup compatibility

= 1.0 =
* Initial release — Google Places autocomplete field for Contact Form 7

== Upgrade Notice ==

= 4.0 =
Major update. The map is now always visible and the marker is draggable. The deprecated `google.maps.Marker` has been replaced — if you use Maps v=beta this update is required for the map to work correctly. Please re-save your settings after upgrading.

== Privacy Policy & External Services ==

This plugin connects to Google's servers to load the Maps JavaScript API and retrieve place suggestions and geocoding results. By using this plugin you agree to:

* [Google Maps Platform Terms of Service](https://cloud.google.com/maps-platform/terms)
* [Google Privacy Policy](https://policies.google.com/privacy)

No personal data is collected or stored by this plugin itself. Address data entered by users is sent directly to Google's API from the visitor's browser.