=== Easeful Themes for ACF ===
Contributors: htmgarcia
Tags: acf, advanced custom fields, custom fields, tailwind, layout
Requires at least: 6.3
Tested up to: 7.1
Requires PHP: 7.4
Stable tag: 1.0.0
License: GPLv2 or later
License URI: https://www.gnu.org/licenses/gpl-2.0.html

Give your Advanced Custom Fields groups a front-end design. Pick or create a theme, arrange the layout, and render your fields — no template code.

== Description ==

**Easeful Themes for ACF** adds front-end *design themes* to your Advanced Custom Fields groups (free and PRO). Instead of hand-coding `the_field()` calls and CSS for every layout, you pick a theme and arrange the fields on the field group's own edit screen, then render it anywhere with a shortcode or a single function call.

A theme is a set of design settings — spacing, borders, corner radius, shadow, text size, label style and colors. Start from a built-in theme or create your own under **ACF → Themes**, with a live preview as you adjust it.

= Features =

* **Theme editor** — under **ACF → Themes**: create, edit, duplicate and delete themes, with a live preview on sample content (every field type) or on one of your own field groups.
* **Four built-in themes** — Classic (light cards), Minimal (flat, bordered), Plain (no cards, just the fields and the space between them) and Midnight (dark). Duplicate one to make your own version.
* **Per-group theme picker** — in a new Design tab on the ACF field group edit screen.
* **Per-field width** — full, half, third or quarter of the row, no CSS required.
* **Drag-and-drop field order** — decide which fields show on the front end, in what order, and how wide each one is.
* **Automatic display** — add a group to any post matching its Location rules with no shortcode: before the content, after it, or *between* your fields, with the post content itself dragged into whatever spot in the field order you like (plain, or in a card like the fields around it).
* **Theme-overridable templates** — copy any template into your active theme to fully customize the markup, the same pattern used by WooCommerce.
* Works with **ACF (free)** and **ACF PRO**, including repeater, group and flexible content fields.
* `[easeful_themes_for_acf]` shortcode and `easeful_themes_for_acf_the_group()` / `easeful_themes_for_acf_get_group()` template tags.
* No external requests, no CDN assets — everything ships with the plugin.

= How it works =

1. Install and activate Easeful Themes for ACF alongside Advanced Custom Fields.
2. Edit any ACF field group. A new **Design** tab appears in its Settings box.
3. Choose a theme, and drag fields into the order you want — set each field's width and toggle any field off if you don't want it on the front end.
4. To change how a theme looks, go to **ACF → Themes**. Built-in themes are read-only: duplicate one, adjust it with the live preview, and save.
5. Render the group wherever you like:

`[easeful_themes_for_acf group="group_xxxxxxxxxxxxx"]`

or in a template file:

`<?php easeful_themes_for_acf_the_group( 'group_xxxxxxxxxxxxx' ); ?>`

If no `post` / `post_id` is supplied, the current post in the loop is used. Add `theme="..."` with a theme's key (shown on the Themes screen, e.g. `minimal`) to render with a different theme than the group's own.

= Documentation =

Step-by-step guides with screenshots, from picking a theme to customizing the markup, are in the [Easeful Themes for ACF documentation](https://htmgarcia.com/docs-category/easeful-themes-for-acf/). Most questions are answered there, so please check it before opening a support topic.

== Installation ==

1. Make sure [Advanced Custom Fields](https://wordpress.org/plugins/advanced-custom-fields/) (or ACF PRO) is installed and active.
2. Upload the `easeful-themes-for-acf` folder to `/wp-content/plugins/`, or install it through the **Plugins** screen in WordPress.
3. Activate **Easeful Themes for ACF** through the **Plugins** screen.
4. Edit an ACF field group and pick its theme in the **Design** tab of its Settings box. Create or edit themes under **ACF → Themes**.

== Frequently Asked Questions ==

= Does this work without Advanced Custom Fields? =

No. Easeful Themes for ACF is an add-on for ACF and requires ACF (free) or ACF PRO to be installed and active. It will show an admin notice and stay dormant if ACF is missing.

= Does this work with ACF field groups stored as local JSON or registered in PHP? =

Rendering works for any field group ACF can resolve by its group key. The Design tab (theme and field order) appears on the field group's edit screen, which requires the group to exist in the database (ACF's normal "sync" step for JSON/PHP-registered groups).

= Will this add unused CSS to my site? =

One small stylesheet (a few KB), scoped to the plugin's own `easeful-themes-for-acf` classes so it never touches the rest of your page, plus one line of CSS variables per theme. Both load on every front-end page rather than only where a group is rendered, since a themed group can appear from a template tag as well as a shortcode and there's no reliable way to know in advance which pages will use one.

= Can I customize the markup? =

Yes. Copy any file from `wp-content/plugins/easeful-themes-for-acf/templates/` into `wp-content/themes/your-theme/easeful-themes-for-acf/` (keeping the same sub-folders) and edit it — your copy takes priority automatically, whichever theme a group uses. Style your markup with the plugin's CSS variables (e.g. `var(--etfa-radius)`) so it still follows the theme settings.

Rendered markup is escaped with the same tags and attributes WordPress allows in post content, plus `<iframe>` for embeds. If your copy outputs something beyond that — a `<form>`, inline SVG — allow it with the `easeful_themes_for_acf_allowed_html` filter, which receives and returns a `wp_kses()` allowed-HTML array:

`add_filter( 'easeful_themes_for_acf_allowed_html', function ( $allowed ) { $allowed['form'] = array( 'action' => true, 'method' => true ); $allowed['input'] = array( 'type' => true, 'name' => true, 'value' => true ); return $allowed; } );`

= Does uninstalling the plugin delete my settings? =

No. Easeful Themes for ACF never deletes your themes or field group designs (theme choice, field order) when you uninstall it. Deactivating, deleting, or reinstalling the plugin leaves everything exactly as you configured it.

= Where can I get help? =

Start with the [documentation](https://htmgarcia.com/docs-category/easeful-themes-for-acf/): its step-by-step guides cover setting up a field group, themes, layouts, automatic display and customizing the markup. If your question isn't answered there, open a topic in the plugin's support forum on WordPress.org.

== Screenshots ==

1. Custom fields shown on a post automatically, laid out by a theme. No shortcode, no template editing, no code.
2. The Design tab on a field group: pick a theme, drag fields into order, set how wide each one is, and show them on your site automatically or with a shortcode.
3. The Themes page in the ACF menu, listing the built-in themes and your own.
4. Editing your own theme: adjust spacing, borders, shadows, text and colors, with a live preview beside the settings.
5. The live preview shows any theme on a light or dark page, with sample content or one of your own field groups.

== Credits ==

The theme editor's transparency strip in the color picker is [wp-color-picker-alpha](https://github.com/kallookoo/wp-color-picker-alpha) by Sergio (kallookoo), GPLv2 or later, included unmodified and unminified in `assets/vendor/wp-color-picker-alpha/`.

== Changelog ==

= 1.0.0 =
* Initial release: theme editor with live preview and four built-in themes, field group Design tab, drag-and-drop field order, automatic display, shortcode and template tags.

== Upgrade Notice ==

= 1.0.0 =
Initial release.
