=== IngotForge Cards for ACF ===
Contributors: ingotpress
Donate link: https://ingotforge.wordpress.com
Tags: acf, cards, grid, slider, custom fields
Requires at least: 5.3
Tested up to: 7.0
Requires PHP: 7.4
Stable tag: 1.6.5
License: GPLv2 or later
License URI: https://www.gnu.org/licenses/gpl-2.0.html

Display responsive ACF cards in grid, list, or slider layouts with filtering, AJAX pagination, and scoped design controls.

== Description ==

IngotForge Cards for ACF displays posts and ACF data as responsive cards. Version 1.6.5 retains `[ingotforge_cards]`, existing shortcode defaults, and stored data.

Main features:

* Grid, list, and accessible Swiper slider layouts.
* AJAX pagination for grid and list layouts.
* ACF text, textarea, date, taxonomy, post object, relationship, file, and common scalar return types.
* Post type, taxonomy, meta, multiple-filter, and `{today}` date filtering.
* The Events Calendar date, cost, venue, upcoming-event, and past-event support.
* Visibility controls for images, titles, excerpts, ACF fields, taxonomy fields, dates, and document buttons.
* Instance-container, card, image, typography, spacing, border, shadow, hover, and responsive-height controls.
* Image-only cards and optional removal of image/title links.
* Instance-scoped styles and slider controls for pages containing multiple shortcodes.
* Conditional slider assets: Swiper loads only when a slider instance is rendered.
* Keyboard, focus, status, reduced-motion, and error-handling improvements.
* No analytics, tracking, telemetry, or external runtime asset requests.

The complete option reference and examples are available after activation under **Settings > IngotForge Cards Manual** and in `SHORTCODE-REFERENCE.md` inside the plugin package.

== Installation ==

1. Install the ZIP through **Plugins > Add New Plugin > Upload Plugin**, or copy the `ingotforge-cards-for-acf` folder to `/wp-content/plugins/`.
2. Activate **IngotForge Cards for ACF**.
3. Activate Advanced Custom Fields or Advanced Custom Fields PRO.
4. Add `[ingotforge_cards]` to a page, post, block, widget, or page-builder shortcode element.
5. Open **Settings > IngotForge Cards Manual** for the full reference.

Basic example:

`[ingotforge_cards post_type="post" fields="location,event_date" columns="3"]`

== Frequently Asked Questions ==

= Does this update change the shortcode or saved data? =

No. The shortcode remains `[ingotforge_cards]`. Version 1.6.5 does not add a database table, rename the existing option, or require content migration.

= Does the plugin require Advanced Custom Fields? =

Yes. Advanced Custom Fields or Advanced Custom Fields PRO must provide the `get_field()` and `get_field_object()` functions.

= Can it display custom post types? =

Yes. Use the registered post type slug, for example:

`[ingotforge_cards post_type="document" fields="description,pdf_documents_url"]`

= Can I hide individual card elements? =

Yes. Controls include `show_title`, `show_image`, `show_excerpt`, `show_acf_fields`, `show_taxonomies`, `show_date`, and `show_button`.

Image-only example:

`[ingotforge_cards post_type="programme" show_title="false" show_excerpt="false" show_acf_fields="false" show_button="false"]`

= Can I disable image and title links? =

Yes. Set `link_to="none"`. The legacy default remains `link_to="post"`.

= Can I style the background behind the complete card instance? =

Yes. Use `container_bg` for the outer instance and `card_bg` for individual cards. It accepts HEX, RGB/RGBA, `transparent`, and safe gradients, and is empty by default.

Example: `container_bg="linear-gradient(135deg, #ffffff 0%, #e2e8f0 100%)"`

= Can columns control the number of cards in a slider? =

Yes. With `layout="slider"`, explicit `columns` is a compatibility alias when `slides_per_view` is omitted. `slides_per_view` wins when both are supplied.

= Are slider files loaded on every page? =

No. The plugin pre-detects common shortcode placements so required styles can be printed in the page head. The shortcode callback remains as a fallback for builders and templates stored elsewhere. Swiper CSS and JavaScript load only when at least one instance uses `layout="slider"`.

= Is Swiper loaded from a CDN? =

No. Swiper v11.1.14 is bundled locally and makes no remote request by itself.

= Which design value formats are supported? =

Design options accept validated values such as HEX, RGB, RGBA, HSL, HSLA, `currentColor`, CSS variables, dimensions, shadows, and supported CSS functions. Values attempting to add declarations, URLs, markup, at-rules, or `!important` are rejected.

= How do I troubleshoot an empty result? =

Confirm that the post type and ACF field names are correct and that matching posts are published. Administrators can temporarily add `debug="true"`; debug output is not shown to visitors without the `manage_options` capability.

== Examples ==

= Responsive programme grid =

`[ingotforge_cards post_type="programme" fields="division,start_date" columns="3" per_page="9"]`

= Filtered document list =

`[ingotforge_cards post_type="document" layout="list" fields="description,pdf_documents_url,document_type" meta_filters="division:39175|document_type:32:LIKE" tax_filters="category:finance" per_page="6"]`

= Upcoming event cards =

`[ingotforge_cards post_type="tribe_events" fields="event_start_date,event_venue" event_display="upcoming" per_page="6"]`

= Responsive modern cards =

`[ingotforge_cards post_type="programme" fields="division" card_border_width="0" card_border_radius="18px" card_shadow="0 8px 28px rgba(15,23,42,.12)" card_hover_shadow="0 18px 44px rgba(15,23,42,.18)" card_height_desktop="440px" card_height_tablet="400px" card_height_mobile="auto"]`

= Accessible autoplay slider =

`[ingotforge_cards post_type="testimonial" layout="slider" fields="client_name,quote" slides_per_view="3" slider_autoplay="true" slider_delay="5000" slider_pause_on_hover="true" slider_pause_on_focus="true"]`

== Developer Integration ==

Optional extension points:

* `ingotforge_acf_cards_shortcode_args` filters normalized shortcode arguments.
* `ingotforge_acf_cards_query_args` filters final `WP_Query` arguments.
* `ingotforge_acf_cards_card_html` filters each rendered card before the plugin's final allowed-HTML pass.
* `ingotforge_acf_cards_asset_requirements` filters styles detected before shortcode rendering.
* `ingotforge:cards:updated` fires after successful AJAX pagination.
* `ingotforge:cards:slider-ready` fires when a slider is initialized.
* Trigger `ingotforge:cards:refresh` after dynamically inserting slider markup.
* `window.IngotForgeCards.loadPage(container, page)` and `window.IngotForgeCards.initSliders(context)` are available for controlled integrations.

All approved `ingotforge` PHP identifiers, options, AJAX actions, handles, CSS prefixes, and shortcode names are retained.

== Privacy ==

The plugin does not collect analytics, track users, create remote accounts, or send site content or personal data to an external service. Its front-end JavaScript communicates only with the site's own WordPress AJAX endpoint when AJAX pagination is used.

== Third-Party Library ==

Swiper v11.1.14 is bundled in `assets/js/swiper-bundle.min.js` and `assets/css/swiper-bundle.min.css`.

* Project: [Swiper](https://swiperjs.com/)
* Source for the bundled version: [Swiper 11.1.14 source](https://github.com/nolimits4web/swiper/tree/v11.1.14/src)
* License: MIT

The files are served locally. The plugin does not contact the Swiper project or a CDN at runtime.

== Changelog ==

= 1.6.5 =

* Added the opt-in `container_bg` shortcode attribute for the background behind the complete shortcode instance.
* Preserved existing output and theme/Elementor backgrounds when `container_bg` is omitted; `card_bg` continues to style individual cards only.

= 1.6.4 =

* Fixed symbolic comparisons in `meta_compare` and `meta_filters`; compound `{today}` ranges are no longer truncated.
* Added entity decoding and aliases; APIs are unchanged.

= 1.6.3 =

* Clarified the admin manual and warns when legacy `[acf_cards]` is registered elsewhere; front-end behavior is unchanged.

= 1.6.2 =

* Restored approved slider sizing and supported explicit `columns` when `slides_per_view` is omitted.
* Preserved explicit `slides_per_view`, grid columns, and the 1.6.1 corrections.

= 1.6.1 =

* Corrected field alignment, image/card heights, query normalization, AJAX consistency, and early conditional style detection.

= 1.6.0 =

* Added compatible design, visibility, image, slider, accessibility, AJAX, security, and developer-integration improvements while retaining the approved public interface.

= 1.5.1 =

* Added `not_found_text` for custom empty-state messages.

Earlier release history is included in `changelog.txt`.

== Upgrade Notice ==

= 1.6.5 =

Adds an optional instance background control. Existing shortcodes are unchanged when `container_bg` is omitted. No migration required.
