=== Webcasata Filter Gallery ===
Contributors:      webcasata
Tags:              gallery, image gallery, filterable gallery, filter, lightbox
Requires at least: 5.8
Tested up to:      6.9
Stable tag:        2.4.2
Requires PHP:      7.4
License:           GPL-2.0+
License URI:       https://www.gnu.org/licenses/gpl-2.0.html

Create beautiful filterable image galleries with dropdown filtering, lightbox, load more pagination, shortcode and Gutenberg block support.

== Description ==

**Webcasata Filter Gallery** lets you build stunning, responsive image galleries where visitors can instantly filter images using custom dropdown menus — all without any page reload.

= Key Features =

* **Multi-group dropdown filtering** — Create filter groups (e.g. "Country", "Room Type"). Each becomes a styled dropdown on the front end.
* **AND logic across groups, OR within a group** — Country=India AND Room=Kitchen; image can belong to multiple countries.
* **Custom styled dropdowns** — Single-select, closes on pick, with active pill indicators.
* **Real-time title search** — Search box with 220ms debounce filters images as you type.
* **Equal Grid & Masonry layouts** — Choose your preferred display style.
* **Configurable columns** — 1 to 6 columns with automatic responsive breakpoints.
* **Slide / Fade / None animations** — Smooth transitions when switching filters.
* **Load More pagination** — Shows a configurable number of images on load; load more on click. Set to -1 to show all.
* **Built-in Lightbox** — Full-screen image viewer with prev/next, keyboard support, and optional Visit Link button.
* **Image URL link** — Assign an external URL to any image, with optional new tab.
* **Image Title & Caption** — Display below each image. Title hideable via shortcode.
* **Filter labels on image cards** — Show assigned filter values as badge labels or ribbons.
* **Template override system** — WooCommerce-style. Copy templates to your theme to customise layout completely.
* **Shortcode** — `[wbfg_gallery id="X"]` with full inline attribute overrides.
* **Gutenberg Block** — Live preview block with full sidebar controls.
* **Per-gallery custom CSS** — Fine-tune each gallery independently.
* **Global settings** — Control defaults for all galleries from one Settings page.
* **Accessibility** — ARIA roles, keyboard-navigable dropdowns, focus management.
* **Fully responsive** — Mobile-first CSS with sensible breakpoints.

= Template Override System =

Copy templates to your active theme to customise the output:

`your-theme/webcasata-filter-gallery/image-card.php`
`your-theme/webcasata-filter-gallery/gallery-template.php`

All image variables are available in `image-card.php`: `$image`, `$title`, `$caption`, `$link_url`, `$link_new_tab`, `$filters`, `$lightbox`, `$show_title`, `$index`, `$gallery_id`.

= Shortcode Parameters =

`[wbfg_gallery id="X" columns="3" show_all="yes" per_page="6" loadmore="6" layout="grid" lightbox="yes" animation="slide" title="show"]`

| Parameter   | Values                         | Default      |
|-------------|--------------------------------|--------------|
| id          | Gallery post ID                | *(required)* |
| columns     | 1–6                            | 3            |
| show_all    | yes / no                       | yes          |
| per_page    | number or -1                   | 6            |
| loadmore    | number                         | 6            |
| layout      | grid / masonry                 | grid         |
| lightbox    | yes / no                       | yes          |
| animation   | slide / fade / none            | slide        |
| title       | show / hide                    | show         |

The **Image Size** setting (Thumbnail / Medium / Full) is configured globally in Settings → Display Settings and applies to all galleries.

= Credits =

Developed by **Vishal Singh** at [Webcasata](https://webcasata.com).

== Installation ==

1. Upload the `webcasata-filter-gallery` folder to `/wp-content/plugins/`.
2. Activate the plugin through **Plugins › Installed Plugins**.
3. Go to **Filter Galleries › Add New** to create your first gallery.
4. Add filter groups and values, upload images, assign filter values, and publish.
5. Copy the shortcode from the sidebar and paste it into any page or post.

== Frequently Asked Questions ==

= Can one image belong to multiple filter values? =

Yes. Each image has a multi-select box per filter group. Hold Ctrl/Cmd to select multiple values — e.g. a cuisine image can be tagged as both India and USA.

= How does the filtering logic work? =

AND logic across groups, OR within a group. If you select Country=India and Room=Kitchen, only images assigned to India (or both India and USA) AND Kitchen are shown.

= Can I customise the image card layout? =

Yes — copy `image-card.php` from the plugin's `templates/` folder to `your-theme/webcasata-filter-gallery/image-card.php` and edit freely. All image data is available as PHP variables.

= How do I show all images without a Load More button? =

Set `per_page="-1"` in the shortcode, or set "Images on Page Load" to -1 in the Settings page.

= Does this plugin slow down my site? =

CSS and JavaScript are only enqueued on pages that contain a gallery shortcode or block. Images use native `loading="lazy"`.

== Screenshots ==

1. Gallery front end with dropdown filters, equal grid layout, and Load More button.
2. Masonry layout with lightbox open showing Visit Link button.
3. Gallery edit screen — Filter Groups builder with drag-and-drop reordering.
4. Gallery edit screen — Image cards with multi-select filter assignment.
5. General Settings page.
6. Shortcode sidebar meta box with copy button.
7. Gutenberg block with live preview in the editor.
8. Template override notice in the gallery list screen.

== Changelog ==

= 2.4.2 =
* Fix: Filter value multi-select now requires Ctrl+click; plain click toggles only the clicked value (deselects all others).
* Fix: All filter groups are now collapsed by default when opening the gallery edit screen.
* Fix: Version number correctly incremented so WordPress update screen shows the new version.

= 2.4.0 =
* New: Image Size setting — choose Thumbnail, Medium, or Full for gallery rendering (Settings page → Display Settings).
* Improved: Admin image cards now preview at the selected image size and images fill the card with no white space.
* Improved: Fresh, polished admin panel design — cleaner meta boxes, card-based settings page, refined colour scheme and typography.
* Fix: Data Management card now uses CSS class instead of inline styles.

= 2.3.0 =
* New: WooCommerce-style template override system (image-card.php, gallery-template.php).
* New: Filter value labels displayed on each image card (badge and ribbon styles).
* New: `FIG_Template` class with `locate()`, `load()`, `is_overridden()` methods.
* New: Admin notice showing theme override path and active overrides.
* Improved: `render_item()` now delegates to template system; fallback inline renderer kept.
* Fix: Per-gallery custom CSS now uses `wp_add_inline_style()` instead of inline `<style>` tag.
* Fix: Settings page styles moved to `wp_add_inline_style()`.

= 2.0.0 =
* New: Multi-group dropdown filtering with AND logic across groups, OR within a group.
* New: Custom styled single-select dropdowns replace flat filter tabs.
* New: Images support multiple filter values per group via multi-select admin UI.
* New: Image title displayed below each image (hideable via shortcode title="hide").
* New: Image URL link field with open-in-new-tab option.
* New: Visit Link button inside lightbox when image has a URL.
* New: Real-time title search box with debounce and clear button.
* New: Filter group collapse/expand in admin edit screen.
* New: Active filter pill tags shown above gallery with individual remove buttons.
* New: Initial count supports -1 to show all images (no Load More button).
* Improved: Filter assignment uses scrollable multi-select box (handles 50+ values).
* Improved: All filtering is client-side — instant, no AJAX round-trips.
* Improved: Backward compatible with v1 flat-tag galleries.

= 1.0.0 =
* Initial release.

== Upgrade Notice ==

= 2.3.0 =
Adds template override system. Existing galleries work without any changes.

= 2.0.0 =
Major upgrade: flat tags replaced by multi-group dropdown filters. Existing v1 galleries continue working automatically.

= 1.0.0 =
Initial release.
