01Overview

Webcasata Filter Gallery lets you build beautiful, responsive image galleries where visitors can filter images using custom dropdown menus — instantly, without any page reload. Images can be tagged across multiple filter groups simultaneously, and filtering uses AND logic across groups with OR logic within a group.

The plugin ships with a WooCommerce-style template override system so theme developers can customise every part of the output by simply placing template files in their active theme folder — no plugin hacking required.

02Features

03Getting Started

Step 1 — Install & Activate

Upload the plugin zip via Plugins → Add New → Upload Plugin, then click Activate.

Step 2 — Create a Gallery

Go to Filter Galleries → Add New in your WordPress admin. Give the gallery a title.

Step 3 — Add Filter Groups

In the Filter Groups meta box, click Add Filter Group. Name it (e.g. “Country”), then add values (e.g. “India”, “USA”, “UK”). Drag to reorder. Add as many groups as you need.

Step 4 — Upload Images

In the Gallery Images meta box, click Upload / Add Images. For each image you can set:

• Title — displayed below the image on the front end
• Caption — shown on hover inside the image
• Link URL — optional external URL (+ new tab option)
• Filter assignments — multi-select box per group (Ctrl+click for multiple)

Step 5 — Publish & Copy Shortcode

Click Publish. The shortcode appears in the sidebar — click Copy and paste it into any page, post, or widget.

[wbfg_gallery id="42"]

04Filter Groups

Filter groups are the core concept of the plugin. Think of each group as a dimension you want visitors to filter by.

How Groups Work

Multi-Value Assignment

In the image card, each filter group shows a scrollable <select multiple> box. Hold Ctrl (Windows/Linux) or Cmd (Mac) to select multiple values. This is ideal for groups with 50+ values like countries.

05Shortcode Reference

The shortcode [wbfg_gallery] accepts the following parameters. All are optional except id.

06Use Cases & Examples

[wbfg_gallery id="42" columns="3" lightbox="no" title="show" per_page="12"]

[wbfg_gallery id="55" layout="masonry" columns="3" animation="fade" lightbox="yes"]

[wbfg_gallery id="68" lightbox="no" columns="4" title="show" per_page="12" loadmore="12"]

[wbfg_gallery id="71" layout="masonry" columns="4" per_page="-1" title="hide" animation="fade"]

[wbfg_gallery id="84" columns="4" lightbox="no" title="show" per_page="-1" filter="show"]

[wbfg_gallery id="90" filter="hide" lightbox="yes" columns="3" per_page="9" loadmore="9"]

[wbfg_gallery id="96" columns="3" lightbox="yes" title="show" animation="slide"]

[wbfg_gallery id="101" filter="hide" lightbox="no" per_page="-1" title="show" columns="5"]

07Template Override System

Like WooCommerce, this plugin allows you to customise the front-end output by placing template files in your active theme. The plugin checks your theme first; if no override is found, it falls back to its own templates.

Template Lookup Order

1. Child theme: child-theme/webcasata-filter-gallery/<template>.php
2. Parent theme: parent-theme/webcasata-filter-gallery/<template>.php
3. Plugin default: plugins/webcasata-filter-gallery/templates/<template>.php

Available Templates

How to Override

Create this folder in your active theme:

Copy the template file(s) you want to customise from the plugin’s templates/ folder into that folder, then edit freely.

Variables Available in image-card.php

All of these PHP variables are available in your overridden image card template:

Filter Labels Example

To output the assigned filter values as ribbon badges in your template override:

<?php // Output all filter values as badges ?>
<?php foreach ( $filters as $group_name => $values ) : ?>
  <?php foreach ( $values as $val ) : ?>
    <span class="fig-filter-label">
      <?php echo esc_html( $val ); ?>
    </span>
  <?php endforeach; ?>
<?php endforeach; ?>

<?php // Output only a specific group ?>
<?php if ( ! empty( $filters['Country'] ) ) : ?>
  <span class="fig-ribbon">
    <?php echo esc_html( $filters['Country'][0] ); ?>
  </span>
<?php endif; ?>

Developer Hooks

The template system fires these WordPress hooks around every template load:

// Before a template is included
do_action( 'fig_before_template', $template_name, $path, $args );

// After a template is included
do_action( 'fig_after_template', $template_name, $path, $args );

// Modify variables passed to any template
add_filter( 'fig_template_args', function( $args, $template_name, $path ) {
    // Add a custom variable to every image-card.php
    if ( 'image-card.php' === $template_name ) {
        $args['my_custom_var'] = 'hello';
    }
    return $args;
}, 10, 3 );

08Plugin Settings

Go to Filter Galleries → Settings to configure global defaults that apply to all galleries. Any setting can be overridden per gallery using shortcode parameters.

09Frequently Asked Questions

Can one image belong to multiple filter values?

Yes. In the image card, each filter group shows a multi-select box. Hold Ctrl (or Cmd on Mac) and click to select multiple values. A cuisine photo can be tagged India and USA — it will appear when either country is selected.

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. The Load More button is automatically hidden.

Can I use the same gallery on multiple pages with different settings?

Yes — shortcode parameters override global settings per instance. The same gallery ID can be used on two different pages with completely different column counts, animations, or visible filters.

Does filtering use AJAX?

No. All images are rendered into the page on load (hidden beyond the initial count). Filtering, search, and Load More all run entirely client-side in JavaScript — making them instantaneous.

My theme overriding image-card.php works but gallery-template.php does not — why?

Make sure you are using version 2.1.0 or later. Earlier versions had a hardcoded include for gallery-template.php that bypassed the template locator. The fix was shipped in 2.1.0.

Can I use the gallery without any filter dropdowns?

Yes — use filter="hide" in the shortcode. This hides all dropdowns and the search box, showing a clean image grid with lightbox, titles, and pagination only.

Is the plugin compatible with page builders?

Yes. Use the shortcode in any page builder text/shortcode widget (Elementor, Divi, WPBakery, etc.). A native Gutenberg block is also included for the block editor.

What is the keyboard shortcut inside the lightbox?

ESC closes the lightbox. ← Arrow goes to the previous image. → Arrow goes to the next image.

Can I change the colour of the filter buttons?

Yes — go to Filter Galleries → Settings → Filter Dropdown Colours. You can set the inactive background, active colour, and text colour using colour pickers.

Does it work with child themes?

Yes. The template locator checks the child theme first, then the parent theme, then falls back to the plugin’s own templates.