=== Extra Fields for ACF ===
Contributors: ikamal
Donate link: https://acfaddons.com
Tags: acf, acf fields, acf addons, acf extension, custom fields
Requires at least: 5.6
Tested up to: 6.9
Requires PHP: 7.4
Stable tag: 1.1.1
License: GPLv2 or later
License URI: https://www.gnu.org/licenses/gpl-2.0.html

Supercharge Advanced Custom Fields with 30 new field types — 17 free and 13 Pro — including Gallery, Map, Tags, oEmbed, Stripe Payment, and more.

== Description ==

**Extra Fields for ACF** is the most complete Advanced Custom Fields extension plugin for WordPress. It adds **30 carefully crafted ACF field types** — 17 available free and 13 exclusive to the Pro licence — covering the most common gaps in standard ACF installations.

Compatible with both the free version of Advanced Custom Fields and ACF PRO. Works with WordPress 5.6 through 6.8.

Full documentation is available at [acfaddons.com/docs](https://acfaddons.com/docs).

---

= 17 Free Field Types =

**Icon Picker**
Select an icon from the Font Awesome Free library using a visual searchable picker. Returns a class string (e.g. `fas fa-home`). Ideal for navigation menus, feature sections, service listings, and Gutenberg blocks that require icon selection.

**Unit Control**
A combined numeric input and unit selector in a single field — supporting px, %, em, rem, vw, vh, and more. Saves `{ value, unit }` as a JSON object. Essential for theme option panels, block spacing controls, and font size settings.

**Gradient Picker**
A visual CSS gradient builder for linear gradients with drag-and-drop colour stops and a direction control. Saves a ready-to-use CSS gradient string. Used for hero section backgrounds, block editor settings, and theme colour scheme controls.

**Responsive Range**
A single field with three independent range sliders — Desktop, Tablet, and Mobile. Saves `{ desktop, tablet, mobile }`. Eliminates creating three separate range fields for responsive values.

**Date Range Picker**
Calendar-based date range selection saving `{ start, end }`. Replaces the workaround of pairing two ACF Date Picker fields together. Built for events, bookings, and availability calendars.

**Table Field**
A fully editable grid with dynamic rows and columns, saved as structured JSON. Includes `get_table()` and `the_table()` PHP helper functions. Best for pricing tables, product spec sheets, and sports statistics.

**Country Selector**
A complete ISO 3166-1 country dropdown — all 249 countries pre-populated as a bundled PHP array, no API key needed. Returns the ISO alpha-2 code (e.g. `BD`). Useful for user profiles, member directories, and event registration.

**Phone Number**
International phone input powered by intl-tel-input with country dial code selector and flag icons. Returns the full E.164 formatted number. Ideal for contact forms, business directories, and booking systems.

**Markdown Field**
A Markdown editor with toolbar and live preview, powered by EasyMDE. Saves raw Markdown. Great for documentation, blog posts, and developer-focused content workflows.

**Star Rating**
Click-to-rate star widget — up to 5 stars (free) or 1–10 stars with half-star support in Pro. Returns an integer. Used for testimonials, product reviews, and scored content.

**Nav Menu Selector**
Pick from any registered WordPress navigation menu. Returns the menu ID, slug, or name. Useful for dynamically assigning menus to templates or post types.

**JSON Field**
Syntax-highlighted JSON editor with real-time validation, powered by CodeMirror. Saves a JSON string. For API configs, settings objects, and developer-facing structured data.

**Address Field**
A single structured field capturing street, city, state, postal code, and country — stored as a PHP array. Replaces the workaround of five separate Text fields. Suitable for business listings, event venues, and client portals.

**Currency Field**
A searchable dropdown of all ISO 4217 currencies, bundled as a PHP array. Returns the currency code (e.g. `USD`). Useful for WooCommerce pricing fields, invoice builders, and financial tools.

**Color Swatch**
Radio choices rendered as clickable colour swatches. Colour options are defined in field settings. Ideal for product variation selectors, theme palette pickers, and Gutenberg block style options.

**Button Group**
Radio choices styled as a horizontal segmented button group — a cleaner visual alternative to dropdowns. Supports single or multi-select. Used for layout toggles, content type selectors, and style pickers.

**Advanced Link**
An enhanced link picker with internal post search, external URL input, link title, target, and type detection. Saves `{ url, title, target, type, post_id }`. Inspired by ACF Extended Advanced Link field.

---

= 13 Pro Field Types =

Upgrade to **Extra Fields for ACF Pro** to unlock 13 additional field types.

**Photo Gallery**
Drag-and-drop image gallery manager using the WordPress Media Library. Supports per-image caption, alt text, and custom link. Includes min/max image count validation. The best replacement for the abandoned `navz-photo-gallery` plugin (60k+ installs, abandoned 2024).

**OpenStreetMap**
A Leaflet.js map field with Nominatim address autocomplete. Place single or multiple markers, set default location and zoom, and choose from multiple tile themes. Fully GDPR-friendly — no Google API key required. Returns `{ lat, lng, zoom, address, markers[] }`.

**Image Hotspot**
Click to place pins on any image. Each hotspot stores percentage-based coordinates (fully responsive), a label, description, custom link, and icon. Four pin styles: Dot, Map Pin, Numbered, and Custom Icon. Full Gutenberg block support.

**Tags Input**
Type-and-press-Enter tag chips powered by Tagify. Supports a predefined whitelist, optional WordPress taxonomy sync, drag-to-reorder, min/max tag count, and character limits. Returns a PHP array, CSV string, or JSON.

**oEmbed**
Paste a URL from YouTube, Vimeo, Spotify, SoundCloud, TikTok, Twitter/X, or any WP-registered oEmbed provider. Shows a live embed preview in the admin. Saves `{ url, provider, title, thumbnail, html, width, height }`.

**Stripe Payment**
Embed a Stripe Payment Element directly inside an ACF form. Supports cards, Apple Pay, and Google Pay. Creates a PaymentIntent via AJAX. Saves `{ payment_intent_id, status, amount, currency, paid_at }` on success.

**Time Zone Selector**
A searchable dropdown of all ~590 IANA time zones, grouped by continent/region with UTC offset display. Pairs naturally with the DateTime Picker. Returns the IANA string, UTC offset, or a full object.

**Image Selector**
Pick from predefined choices using visual image thumbnails. Supports single or multi-select with configurable grid columns. Choices are defined as `value | label | image_url` in the field settings. Inspired by ACF Extended Pro Image Selector.

**Code Editor**
Full syntax-highlighted multi-language code editor powered by CodeMirror. Supports HTML, CSS, JavaScript, PHP, Python, Shell, SQL, YAML, and plain text. Configurable theme (Default, Monokai, Material), line numbers, tab size, and word wrap.

**DateTime Picker**
Combined date and time picker in a single field, powered by Flatpickr. Supports 12h/24h time format, configurable minute step, include/exclude seconds, and min/max datetime boundaries. Returns a formatted string, Unix timestamp, or DateTime object.

**Hidden Input**
A read-only hidden field that stores a value not visible in the admin. Supports a static default or a dynamic token: `{{user_id}}`, `{{post_id}}`, `{{date}}`, `{{time}}`. Optional auto-update on every save. Inspired by ACF Extended Hidden Input field.

**Post Types Selector**
A dropdown or multi-select of all registered WordPress post types. Supports built-in type inclusion, an exclusion list, and three return formats: slug, label, or `WP_Post_Type` object. Inspired by ACF Extended Post Types field.

**Slug Field**
An auto-sanitized URL slug input with real-time client-side formatting. Supports hyphen or underscore separator, optional uppercase, max length, sync-from-another-field, and server-side uniqueness validation. Inspired by ACF Extended Slug field.

---

= Settings Page =

Extra Fields for ACF includes a central Settings Page at **Settings > Extra Fields for ACF** in the WordPress admin. Enable or disable any field type individually. Disabled fields are not registered with ACF and load no assets — keeping the field type selector clean. Pro fields display a lock icon with an upgrade link when no licence is active.

= Pro Licence =

Unlock all 13 Pro fields at [acfaddons.com](https://acfaddons.com). The free version remains fully functional with all 17 free field types.

= Documentation =

Full developer documentation, field return value references, and template usage guides are available at [acfaddons.com/docs](https://acfaddons.com/docs).

= Compatibility =

Works with Advanced Custom Fields (free) and ACF PRO. Compatible with Gutenberg block editor, Elementor, Beaver Builder, Bricks Builder, Oxygen Builder, GeneratePress, Kadence Blocks, and any page builder or theme framework that integrates with Advanced Custom Fields. All fields are compatible with ACF field groups assigned to posts, pages, custom post types, taxonomies, users, comments, and ACF options pages. Compatible with WooCommerce, The Events Calendar, and WPForms ACF integrations.

== Installation ==

1. Log in to your WordPress admin dashboard.
2. Go to **Plugins > Add New Plugin**.
3. Search for **Extra Fields for ACF**.
4. Click **Install Now**, then click **Activate**.
5. Ensure **Advanced Custom Fields** (free or PRO) is installed and active.
6. Go to **Settings > Extra Fields for ACF** and enable the field types you need.
7. Open or create an ACF field group and add any of the new field types from the field type selector.

**Manual installation:**

1. Download the plugin ZIP from [acfaddons.com](https://acfaddons.com) or WordPress.org.
2. Go to **Plugins > Add New Plugin > Upload Plugin**.
3. Upload the ZIP file and click **Install Now**, then **Activate**.
4. Follow steps 5–7 above.

== Frequently Asked Questions ==

= Does this plugin work with ACF PRO? =

Yes. Extra Fields for ACF is fully compatible with both the free version of Advanced Custom Fields and ACF PRO. All 30 custom field types work with both editions.

= What is the difference between the free version and Pro? =

The free version includes 17 field types. The Pro licence unlocks 13 additional fields: Photo Gallery, OpenStreetMap, Image Hotspot, Tags Input, oEmbed, Stripe Payment, Time Zone Selector, Image Selector, Code Editor, DateTime Picker, Hidden Input, Post Types Selector, and Slug Field. See [acfaddons.com](https://acfaddons.com) for pricing.

= Does it work with the latest version of WordPress? =

Yes. The plugin is tested up to WordPress 6.8 and is updated regularly to maintain compatibility with new WordPress and ACF releases.

= Does it work with the Gutenberg block editor? =

Yes. All field types work inside ACF field groups assigned to Gutenberg blocks, just as standard ACF fields do.

= Can I use these fields with Elementor, Beaver Builder, or Bricks Builder? =

Yes. Any ACF field value returned by Extra Fields for ACF can be used in Elementor dynamic data, Beaver Builder custom modules, Bricks Builder dynamic data, and other page builders that support ACF integration.

= Can I disable field types I do not need? =

Yes. The Settings Page at **Settings > Extra Fields for ACF** lets you enable or disable each field type individually. Disabled field types do not appear in the field type selector inside ACF field groups and do not load any assets.

= How are field values stored and retrieved? =

All field values are stored in the standard WordPress post meta table and retrieved using the standard ACF `get_field()` and `the_field()` functions. No custom database tables are created.

= Does the Icon Picker work with Font Awesome PRO? =

The free version supports Font Awesome Free. Font Awesome PRO icon sets are available in the Pro licence.

= Does the OpenStreetMap field require a Google Maps API key? =

No. The OpenStreetMap field uses the open-source Leaflet.js library with Nominatim geocoding — no API key of any kind is required and it is fully GDPR-compliant.

= Does the Stripe Payment field work in test mode? =

Yes. The field includes a Test / Live mode toggle in the field settings. Use your Stripe test keys for development and switch to live keys for production.

= Is the plugin translation-ready? =

Yes. The plugin uses the `extra-fields-for-acf` text domain and is compatible with Loco Translate, WPML, Polylang, TranslatePress, and any WordPress translation workflow.

= Does the Table Field work inside an ACF Repeater or Flexible Content field? =

Yes. All Extra Fields for ACF field types can be placed inside ACF Repeater Fields, Flexible Content Fields, and Clone Fields.

= Is the plugin compatible with WordPress Multisite? =

Yes. Extra Fields for ACF is compatible with WordPress Multisite installations.

= Where can I find documentation? =

Full documentation is at [acfaddons.com/docs](https://acfaddons.com/docs).

= Where can I report a bug or request a feature? =

Use the [WordPress.org support forum](https://wordpress.org/support/plugin/extra-fields-for-acf/) for bug reports and feature requests.

== Screenshots ==

1. Settings Page — enable or disable any of the 30 field types; Pro fields show a lock icon with an upgrade link
2. Free field types available in the ACF field group editor
3. Pro field types — Gallery, Map, Tags Input, oEmbed, Code Editor, and more

== Changelog ==

= 1.2.0 =
* New: Markdown Field — EasyMDE editor with toolbar and live preview
* New: Star Rating — click-to-rate stars (1–5 free, 1–10 in Pro)
* New: Nav Menu Selector — pick from any registered WP navigation menu
* New: JSON Field — CodeMirror syntax-highlighted JSON editor with validation
* New: Button Group — segmented button toggle, single or multi-select
* New: Advanced Link — enhanced link picker with post search, title, and target
* New (Pro): Photo Gallery — drag-and-drop WP Media gallery with per-image meta
* New (Pro): OpenStreetMap — Leaflet.js map with Nominatim geocoding, no API key
* New (Pro): Image Hotspot — click-to-place pins on an image with labels and links
* New (Pro): Tags Input — Tagify chip input with whitelist and taxonomy sync
* New (Pro): oEmbed — URL-to-embed with live admin preview via WP oEmbed API
* New (Pro): Stripe Payment — Stripe Payment Element inside ACF forms
* New (Pro): Time Zone Selector — all IANA time zones grouped by region
* New (Pro): Image Selector — visual image-thumbnail radio/checkbox grid
* New (Pro): Code Editor — CodeMirror multi-language editor (HTML, CSS, JS, PHP, Python, Shell, SQL, YAML)
* New (Pro): DateTime Picker — Flatpickr combined date + time field
* New (Pro): Hidden Input — read-only field with dynamic tokens (user_id, post_id, date, time)
* New (Pro): Post Types Selector — dropdown of registered WP post types
* New (Pro): Slug Field — real-time slug sanitization with sync-from-field support
* New: Pro licence tier — 13 Pro fields shown as locked in Settings Page with upgrade link
* Improved: Settings Page — Pro fields display lock icon and upgrade button for free users

= 1.1.0 =
* New: Icon Picker field — visual Font Awesome Free icon selector
* New: Table Field — editable rows and columns grid saved as JSON
* New: Country Selector field — ISO 3166-1 country dropdown
* New: Phone Number field — international dial code and number input via intl-tel-input
* New: Address Field — structured street, city, state, postal code, and country inputs
* New: Currency Field — ISO 4217 currency code selector
* New: Color Swatch field — radio choices rendered as clickable colour swatches
* New: Settings Page at Settings > Extra Fields for ACF — enable or disable any field type individually
* Improved: Unit Control field — toggle support added
* Improved: Gradient Picker field — toggle support added
* Improved: Responsive Range field — toggle support added
* Improved: Date Range Picker field — toggle support added
* Tested up to WordPress 6.8

= 1.0.0 =
* Initial release
* Unit Control field
* Gradient Picker field
* Responsive Range field
* Date Range Picker field

== Upgrade Notice ==

= 1.2.0 =
Adds 6 new free field types and introduces the Pro licence tier with 13 additional fields. Safe to upgrade from v1.1.0. No database changes required.

= 1.1.0 =
Adds 7 new ACF field types and a central Settings Page. Safe to upgrade from v1.0.0. No database changes required.

= 1.0.0 =
Initial release.
