=== FFL Filters ===
Contributors: coriolisagency
Tags: woocommerce, product filter, filters, firearms, faceted search
Requires at least: 6.5
Tested up to: 7.1
Requires PHP: 7.4
WC requires at least: 9.2
WC tested up to: 11.2
Stable tag: 1.3.5
License: GPLv2 or later
License URI: https://www.gnu.org/licenses/gpl-2.0.html

Faceted product filters for WooCommerce store catalogs.

== Description ==

FFL Filters is a free WooCommerce product filter plugin built for gun stores. Your shoppers can narrow the catalog by caliber, brand, price, barrel length, capacity and what's in stock, from a filter panel that sits in your shop sidebar on a computer and opens as a drawer on a phone.

It's made by Coriolis Agency for FFL dealers who sell on WooCommerce, and it's set up to be run by the person who runs the shop, not a developer.

= Built around how gun stores sell =

* Caliber merging: 9mm, 9mm Luger and 9x19 can show up as one Caliber choice, so a shopper checks one box and sees every gun in that chambering. You review the synonym groups on the Presets tab.
* Ranges for barrel length, capacity, bullet weight and optics magnification, read from the attribute values you already have, such as 16 in or 10+1.
* A Firearm type filter that shows the type values already in your catalog.
* An In store toggle for products you've tagged as on the shelf, for the buyer who wants to drive over and pick it up today.

= Set up from the Welcome tab =

* The Welcome tab walks you through setup in three steps. The first step ticks itself as soon as FFL Filters finds the panel on your shop page.
* Turn each filter on or off with one switch, right on the Welcome tab.
* Click Add to my shop sidebar and FFL Filters places the panel in your shop sidebar for you. If you change your mind, Undo takes it back out.
* The sidebar steps cover classic themes and block themes, and the [ffl_filters] shortcode has a Copy button.
* If another filter plugin is active on your site, a notice names it so you know which one to deactivate.

= Fits your shop =

* The panel shows up on your shop and category pages on its own. If you'd rather place it yourself with the FFL Filters block or the [ffl_filters] shortcode, a switch in the settings turns automatic placement off.
* It uses your theme's font and colours instead of loading its own, and on Kadence it picks up your theme palette.
* On a phone you choose how it behaves: a drawer, a collapsible panel, or the regular sidebar. With the drawer, shoppers on tablets and phones tap a Filter products button to open the panel.
* You can change the heading at the top of the panel, or keep the default, Filter products.
* Long lists such as Brand show the top choices first, with Show all and a search box for the rest.
* The filters are a plain form underneath, so they still work for a shopper who has JavaScript turned off.
* Groups are labelled for screen readers, keyboard focus is easy to see, and the result count is announced when it changes.
* The panel fills the width of its column, filters with a single row like In stock and Price stay open, and the Show products button stays at the bottom of the panel in the sidebar and in the mobile drawer.
* Active filters show as chips in your theme's accent colour, each with an x to remove it.

= Keeps the shop quick and the SEO clean =

* Filter counts are cached and refreshed when your products change, and the storefront doesn't send filter requests through admin-ajax.
* Filtered pages are set to noindex, follow, and a robots.txt block covers the filter URLs, so search engines spend their time on your real shop and category pages. Those pages aren't changed.
* Filtered pages tell your page cache not to store them.

= Settings you can run yourself =

* A Welcome tab that opens the first time you go to WooCommerce > FFL Filters, plus a Settings link on the Plugins screen.
* A Filters tab where you rename, reorder and hide filters and choose which terms show.
* A Health tab that shows the WooCommerce lookup table status and the filter cache, keeps a log of slow filter queries, and tells you why a product isn't showing up.
* An Import tab with a Download a backup button that saves your FFL Filters settings to a file. To restore them, upload that file, or paste in the settings text if you'd rather.

== Installation ==

1. Make sure WooCommerce is installed and active. FFL Filters needs WooCommerce 9.2 or newer.
2. In WordPress, go to Plugins > Add New Plugin, search for FFL Filters, click Install Now, then click Activate. If you have the zip file, use Plugins > Add New Plugin > Upload Plugin instead.
3. Go to WooCommerce > FFL Filters, or click Settings under FFL Filters on the Plugins screen. The Welcome tab walks you through three steps, starting with which filters to show.
4. Open your shop page. The filter panel shows up on your shop and category pages on its own.
5. If your theme has a shop sidebar, click Add to my shop sidebar in step 3 of the Welcome tab and FFL Filters places the panel there for you. To place it yourself instead, on a theme with widgets, go to Appearance > Widgets and add the FFL Filters block to your shop sidebar. On a block theme, go to Appearance > Editor > Templates, open the Product Catalog template and add the FFL Filters block beside your products. Either way, a Shortcode block with [ffl_filters] in it works too.

== Frequently Asked Questions ==

= Is FFL Filters free? =

Yes. FFL Filters is free and licensed under the GPL.

= Do I need WooCommerce? =

Yes. FFL Filters filters WooCommerce products, so WooCommerce has to be installed and active. If it isn't, FFL Filters shows a notice in your admin and stays out of the way.

= Where does the filter panel show up? =

On your shop page and your product category pages. If your theme has a shop sidebar, it goes there. On a block theme it sits above the product grid until you place the FFL Filters block where you want it. If you turn automatic placement off, the panel shows only where you've placed the block or the [ffl_filters] shortcode.

= Can I keep my old filter plugin? =

We'd pick one. Running FFL Filters next to another filter plugin, such as HUSKY or one of the YITH filter plugins, can give shoppers two sets of filters on the same page. WooCommerce's own filter widgets and blocks can also apply a second, conflicting filter, which shows up as empty or doubled results. If another filter plugin is active, FFL Filters names it in a notice. Set up FFL Filters, check your shop page, and then deactivate or remove the old filters.

= Will filtered pages hurt my search rankings? =

They're kept out of the way. Every filtered page is set to noindex, follow, with no canonical link, and FFL Filters adds a robots.txt block for filter URLs. The Clear all and page links on filtered pages are marked nofollow. Your regular shop and category pages stay the same, and you can change these settings on the SEO tab.

= I use a page cache plugin. Do I need to do anything? =

Filtered pages tell page caches not to store them. If your cache plugin ignores that and shoppers see stale results, exclude filtered pages in the cache plugin's settings and then flush the filter cache on the FFL Filters Health tab.

= A product isn't showing up in the filters. What do I check? =

Open the Health tab and use the Why isn't this product showing lookup. Search by product ID, SKU or name and it tells you what's keeping that product out. If the Health tab says the WooCommerce lookup tables are missing or incomplete, regenerate them under WooCommerce > Status > Tools.

= Does the Firearm type filter decide what type my guns are? =

No. It shows the type values that are already in your product attribute, under the label Firearm type. FFL Filters doesn't classify anything, and you can change the label on the Presets tab.

= Does it work with my theme? =

It's built to sit quietly in most themes. The panel uses your theme's font and colours, and on Kadence it picks up the theme palette. If your theme doesn't show the panel where you want it, place the FFL Filters block or the [ffl_filters] shortcode yourself.

= Does FFL Filters send anything to Coriolis? =

Not unless you choose to use the optional contact form, and then only after you tick its consent box and click Send to Coriolis. The Privacy section below lists exactly what that form sends.

= What happens if I delete the plugin? =

Deleting FFL Filters from the Plugins screen removes its settings, its filter cache and its slow-query log. Your products, attributes, categories and tags aren't touched. To keep your settings for later, click Download a backup on the Import tab before you delete the plugin.

== Screenshots ==

1. The filter panel on a WooCommerce shop page, with caliber, barrel length, capacity and firearm type groups and an in-store toggle next to the product grid.
2. On a phone the filters open in a drawer over the product grid, and closing it puts the shopper back on the Filters button.
3. One Caliber filter covers 9mm, 9mm Luger and 9x19, so the shopper checks a single box and sees every gun in that chambering.
4. A long filter group such as brand, opened with Show all and narrowed by typing a few letters into its search box.
5. The Welcome tab, which walks you through setup in three steps the first time you open FFL Filters under the WooCommerce menu.
6. The Filters tab in settings, where you rename, reorder and hide filters and choose which terms show.
7. The Presets tab, where you review caliber merging, the ranges for barrel length, capacity, bullet weight and optics magnification, the firearm type filter and the in-store toggle.
8. The Health tab, which shows the WooCommerce lookup table status, the filter cache details with a flush button, the slow-query log and a lookup that tells you why a product isn't showing.

== Changelog ==

= 1.3.5 =
* Fix: On phones, the Filter products button opens the filter drawer even when the filter script fails to load, on themes whose own scripts used to block it, such as Kadence. Shoppers can still use the In Stock and In store switches and tap Show products.

= 1.3.4 =
* Fix: The filter pills and the In Stock switch stay see-through on themes that style form sections or their headings with more specific rules, in the sidebar and above the products.
* Fix: Shoppers whose device is set to reduce motion no longer see the Show products button flash on while the page loads.
* Fix: If a shopper opens the filter drawer before the page finishes loading, the Show products button is there right away.

= 1.3.3 =
* Fix: On themes that give form headings their own background, such as Storefront, the filter pills no longer sit on a light box, so the panel stays see-through on your site's background.

= 1.3.2 =
* Fix: The Show products button that's meant for visitors without JavaScript no longer appears for a moment while the page loads. If the filter script never loads, the button comes back after about three seconds so shoppers can still apply their filters.
* Fix: The ring on the Filter products button on tablets and phones stays in place while the page loads.
* Fix: The small script that sets the panel's colours no longer uses code that can break when a caching or optimization plugin combines your site's scripts into one file.
* Change: Developer-only files are no longer included in the plugin download.

= 1.3.1 =
* Fix: In Stock now hides out-of-stock products from the results, so the products shown always match the count.
* Change: The filter panel is see-through again, so it sits on your site's own background. Open dropdowns, popovers and the phone drawer get a solid fill that matches the page behind them, so their text stays readable.

= 1.3.0 =
* New: Above products placement. The filters can sit full width above the product grid on the shop and category pages, and they stay there when a search finds no products.
* New: Layout setting with Auto, Bar and Stacked. Auto uses the Bar when the filters have 720px or more to work with, and Stacked when they have less, like in a sidebar. Stacked opens each group in place.
* New: Check my shop page button under Layout. It loads your shop page out of sight and tells you how wide the filter area is, and which layout and panel style Auto will use. Nothing is sent anywhere.
* In the Bar, each filter group is a dropdown button. Groups that allow more than one pick stay open while you tick. Groups with one pick close after you choose. Price and Cost Per Round apply and close when you press Enter.
* Above the products, one row holds the product count, your picks as chips, Clear all and the sort box. On screens 768px and wider it takes the place of the theme's "Showing" line and sort box. Phones keep the Filter products button, the drawer and the theme's own count and sort box.
* New: Panel style setting with Auto, Light and Dark. Auto checks the background behind the filters and uses the dark panel on a dark theme, so filter text stays readable.
* New: Accent color setting with Theme color or Custom, and a preview. The filters darken or lighten the color as needed so text on it stays readable on both panels. Your theme's own colors don't change.
* The Display tab is now called Appearance.
* Fix: product counts now match WooCommerce on Elementor pages and on parent categories.

= 1.2.1 =
* The filter panel fills the full width of the sidebar or widget area. The outer border and padding are removed.
* The stock switch reads "In Stock". The label and count stay on one line.
* Every filter group starts closed, Price and ranges included. A group opens on load when one of its values is picked. With JavaScript off, every group shows.
* Phones show one Filter products button. When the button above the products is shown, the panel's own button hides.
* On themes that hide the sidebar on phones, the filter drawer still opens.
* Open filter headings keep their text and colors on hover, click and keyboard focus. The keyboard focus ring uses the text color.
* Filter values wrap between words, not mid-word. Counts stay on one line on the right.
* Panel styles are scoped to the panel and reset theme button, input and focus styles inside it. Sizes are set in pixels, so a theme's root font size doesn't shrink the panel.

= 1.2.0 =
* The filter panel uses less space: tighter border, padding and row spacing.
* Filter values sit in rows 32px tall on desktop and 44px on touch screens.
* Clicking a filter heading opens its values directly.
* The Dropdown display type is removed. Filters set to Dropdown now show as checkboxes.
* Long lists, like Brand and Caliber, scroll inside a box of 8 rows with a search box on top.
* Brands are sorted by product count.
* Filters apply as soon as you click them. If you click several quickly, the last click wins.
* Price and range boxes apply 0.6 seconds after you stop typing.
* Price has min and max boxes only.
* While results load, a thin bar shows at the top of the products and the products fade. The filters stay usable.
* The Show products button only shows when JavaScript is off.
* On phones, filters apply right away and a Show N products button closes the drawer.
* If your store colours are too low in contrast, the panel uses a neutral border and a darker chip colour.
* Cached filter panels are rebuilt after a plugin update.

= 1.1.0 =
* New Welcome tab that walks you through setup in three steps; the first step ticks itself once the filter panel shows up on your shop.
* Turn filters on or off from the Welcome tab with one switch each.
* Sidebar steps for classic themes and block themes, plus the [ffl_filters] shortcode with a Copy button.
* New Add to my shop sidebar button places the panel for you, and you can undo it.
* If another filter plugin is active, a notice names it so you know which one to deactivate.
* The Show products button now stays at the bottom of the panel, in the sidebar and in the mobile drawer.
* Active-filter chips now use your theme's accent colour.
* Filters with a single row, like In stock and Price, now show open.
* The panel now fills the full width of its column.
* Fixed: Honor the page order now works.
* Added a Settings link on the Plugins screen.
* New switch to turn automatic panel placement on or off.
* New Filter products button opens the filter panel on tablets and phones.
* New option to change the heading at the top of the panel.
* New Download a backup button on the Import tab. Restore by uploading the file, or paste the settings text as before.

= 1.0.0 =
* First stable release: faceted WooCommerce filters, setup wizard, presets, and a Health tab.

= 0.0.1 =
* Initial scaffold.

== Upgrade Notice ==

= 1.3.5 =
Phone shoppers can open the filter drawer even if the filter script fails to load, including on Kadence.

= 1.3.4 =
Keeps the filter panel see-through on more themes and tidies how the Show products button behaves while the page loads.

= 1.3.3 =
Removes a light box that some themes, including Storefront, drew behind the filter pills.

= 1.3.2 =
Fixes a brief flash of the no-JavaScript Show products button and a shifting button ring during page load, and improves compatibility with plugins that combine scripts.

= 1.3.1 =
In Stock now hides out-of-stock products, and the filter panel uses your site's own background again.

= 1.1.0 =
Adds a Welcome tab with three-step setup, a one-click sidebar button, a notice for other filter plugins and a Download a backup button, and makes the filter panel easier to use on phones.

= 1.0.0 =
First stable release of FFL Filters.

= 0.0.1 =
Development scaffold. Do not install on a live shop.

== Privacy ==

FFL Filters doesn't send anything to Coriolis, or anywhere else, unless you choose to. It loads no remote scripts, fonts, pixels or images, and no feature of the plugin depends on contacting us.

The one exception is an optional contact form in the FFL Filters settings, for shop owners who'd like Coriolis Agency to get in touch about FFL Filters. Its consent box starts unchecked, and nothing leaves your site until you tick that box and click Send to Coriolis.

When you do, your browser opens https://coriolisagency.com/ffl-filters/connect in a new tab and sends the form there as a form post, not in the web address. That page shows you the details again, and Coriolis stores them only after you confirm. The request goes to Coriolis Agency only.

The form sends your name, your email, an optional message of up to 1,000 characters, your consent, and the version of the consent wording you saw. Nothing else is sent, so no customer data, orders, other users, plugin list, server paths or keys leave your site through it.

On your own site, FFL Filters keeps only the date you sent the form and the consent version, in the fflf_lead option, and never a copy of your message. The Forget button in the plugin clears that date. To ask Coriolis to delete the copy it received, use https://coriolisagency.com/ffl-filters/connect#delete. FFL Filters also adds a short note about this form to the WordPress privacy policy guide.
