=== Faceted Search for Ultimate Member ===
Contributors: userelements
Tags: ultimate-member, member-directory, faceted-search, user-search, filters
Requires at least: 6.0
Tested up to: 7.0
Requires PHP: 7.4
Stable tag: 1.0.2
License: GPLv2 or later
License URI: https://www.gnu.org/licenses/gpl-2.0.html

Add AJAX facet filters to Ultimate Member member directories so visitors can narrow members by profile fields with live counts and no page reloads.

== Description ==

**Faceted Search for Ultimate Member** adds a configurable filter sidebar to any Ultimate Member member directory. Visitors combine filters on profile fields — country, industry, skills, job title, or any custom UM field — and see matching members update instantly over AJAX.

The plugin hooks into Ultimate Member's native member directory (`um_get_members`), so member cards, pagination, sorting, and keyword search keep working as before. Facet counts refresh in real time as filters are applied, showing how many members match each option.

= Key features =

* **Per-directory setup** — enable faceted search on each Member Directory individually.
* **Six filter UI types** — checkbox list, radio list, dropdown, tag cloud, numeric range, and date range.
* **Live facet counts** — option labels show member totals (e.g. United States (24)) that update with each selection.
* **AJAX filtering** — no full page reload; results update through UM's member directory.
* **Multiple layouts** — sidebar left, sidebar right, or horizontal top bar.
* **Active filter chips** — visitors see and remove active filters at a glance.
* **URL state persistence** — shareable filter URLs when enabled.
* **Mobile-friendly** — optional collapsible facet panels on small screens.
* **Role-based facet visibility** — show different filters to different UM roles.
* **Sortable facet values** — by count (high/low) or alphabetically (A–Z / Z–A).
* **Meta key autocomplete** — admin facet builder suggests UM profile field keys.
* **Smart field detection** — maps UM field types (text, select, radio, checkbox, multiselect, date, number, and more) to the correct filter logic.
* **Security by default** — passwords, 2FA tokens, file URLs, and other sensitive meta keys are never offered as facets.

= Who is this for? =

* **Membership communities** — help members find others by location, interests, or expertise.
* **Professional directories** — filter consultants, freelancers, or staff by specialty or availability.
* **Alumni and association sites** — browse graduates or members by class year, region, or industry.
* **Niche marketplaces** — narrow vendor or service listings on UM-powered directories.
* **Any WordPress site using Ultimate Member directories** — turn a long member list into a browsable, filterable experience.

= Front-end experience =

* Combine multiple facet filters at once (AND logic — members must match all active filters).
* Use facet filters together with Ultimate Member's built-in directory search and sort.
* Clear individual filters or reset everything with **Clear all**.
* See a results summary (e.g. "Showing 12 of 48 members") above the member grid.
* Keyboard-accessible facet controls for better usability.

= Admin configuration =

Configure everything under **Ultimate Member → Member Directory → Add/Edit**, in the **Faceted Search** metabox:

* Enable or disable faceted search per directory.
* Add facet fields mapped to UM user meta keys (profile field keys).
* Set a custom label and UI type for each facet.
* Drag to reorder facets.
* Choose layout and toggle **Show Counts**, **Active Filter Chips**, **Collapsible on Mobile**, and **URL State Persistence**.
* Set how many options appear before a facet panel collapses ("Collapse after X items").
* Configure per-facet sort order and role visibility in advanced options.
* Set min, max, and step for numeric range facets; from/to dates for date range facets.

No shortcode is required — the filter sidebar appears automatically on directories where faceted search is enabled.

= How it works =

1. Enable faceted search on a Member Directory and choose which profile fields become filters.
2. When a visitor opens that directory, the filter sidebar renders alongside the member grid.
3. Each filter selection is sent with Ultimate Member's member query.
4. The member list updates via AJAX; facet counts recalculate for the current filter combination.
5. Only members matching all active filters are shown.

= For developers =

Hooks and filters for customization:

* `um_fs_before_sidebar` — before the sidebar wrapper is rendered
* `um_fs_inside_sidebar` — inside the sidebar, after the facets panel
* `um_fs_after_sidebar` — after the sidebar closing tag
* `um_fs_user_card_data` — filter data passed to member cards
* `um_fs_field_type_overrides` — override detected field types by meta key
* `um_fs_facet_max_users` — cap users scanned when building facet counts (default 5000)
* `um_fs_facet_base_args` — adjust base `WP_User_Query` args used for counting

== Installation ==

1. Install and activate **Ultimate Member** (required).
2. Upload the `faceted-search-for-ultimate-member` folder to `/wp-content/plugins/`, or install from the WordPress Plugins screen.
3. Activate **Faceted Search for Ultimate Member** through the **Plugins** menu.
4. Go to **Ultimate Member → Member Directory** and open an existing directory or create a new one.
5. In the **Faceted Search** metabox, check **Enable Faceted Search**.
6. Click **Add Facet** and configure at least one filter (see below).
7. **Update** the directory, then open its front-end page to preview the filter sidebar.

= Setting up your first facet =

Facets use Ultimate Member **profile field meta keys** — the internal key from your UM registration or profile forms.

1. In **Ultimate Member → Forms**, note the meta key of a field you want to filter by (e.g. `country`, `gender`, `skills`).
2. Edit your Member Directory and open the **Faceted Search** metabox.
3. Click **+ Add Facet**.
4. Enter the **Meta Key** exactly as it appears in the UM form.
5. Enter a **Label** visitors will see (e.g. "Country").
6. Choose a **UI type** (checkbox, radio, dropdown, tag cloud, numeric range, or date range).
7. Drag rows to reorder facets if you add more than one.
8. Save the directory and use **Preview directory** to test on the front end.

**Tip:** Fields with a manageable set of distinct values work best — countries, job titles, categories, or select/radio options. Long free-text fields (biographies, descriptions) are not suitable as facets.

== Frequently Asked Questions ==

= Does this plugin require Ultimate Member? =

Yes. Faceted Search for Ultimate Member requires Ultimate Member and its Member Directory feature. The plugin deactivates itself if Ultimate Member is not active.

= Where do I configure facets? =

Go to **Ultimate Member → Member Directory**, then add or edit a directory. The **Faceted Search** metabox is on the directory edit screen.

= Do I need a shortcode? =

No. Once faceted search is enabled on a directory, the filter sidebar is injected automatically on that directory's front-end page.

= Which profile fields can I use as facets? =

Any Ultimate Member user meta key that stores filterable data — typically text, select, radio, checkbox, multiselect, date, or number fields. The plugin auto-detects field types from your UM forms. Passwords, file uploads, URLs, biographies, and other sensitive or unsuitable meta are blocked.

= How do I find the correct meta key? =

Open the UM form that contains the field, check its meta key in the field settings, or start typing in the admin **Meta Key** field for autocomplete suggestions from UM fields and user meta.

= Does filtering reload the page? =

No. Member results update through Ultimate Member's AJAX member directory. Visitors stay on the same page while filters are applied.

= What do the numbers next to filter options mean? =

Those are **live facet counts** — how many members in the current result set have that value. Counts update whenever filters change.

= Can visitors combine multiple filters? =

Yes. Multiple active facets use AND logic: members must match all selected filters to appear in the results.

= What UI types are available? =

Checkbox list, radio list, dropdown, tag cloud, numeric range, and date range. Each facet can use a different UI type.

= Can I show different facets to different user roles? =

Yes. Use **Visible to Roles** in each facet's advanced options. Leave all roles unchecked to show the facet to everyone.

= Does faceted search work with Ultimate Member's directory search? =

Yes. Facet filters combine with UM's keyword search, native directory filters, sorting, and pagination.

= Will this slow down my directory? =

Unfiltered facet counts are cached for a few minutes and refreshed when relevant user meta changes. For very large member bases, developers can tune performance with the `um_fs_facet_max_users` filter. A notice appears if counts may be incomplete on large directories.

= Can visitors share a filtered view? =

Yes, when **URL State Persistence** is enabled. Active filters are stored in the URL query string so the view can be bookmarked or shared.

== Screenshots ==

1. Faceted search sidebar on a member directory with live filter counts
2. Facet configuration metabox on the Member Directory edit screen

== Changelog ==

= 1.0.2 =
* All UI types are now included: checkbox, radio, dropdown, tag cloud, numeric range, and date range.
* Range filters work on the front end and in member queries.

= 1.0.1 =
* Removed trialware licensing; checkbox filtering and directory settings remain fully functional in the free plugin.
* Moved admin and front-end CSS/JS to proper WordPress enqueue APIs.
* Limited persistent facet count caching to unfiltered queries to prevent transient bloat.
* Updated plugin metadata to match userelements.com ownership.
* Free version scoped to checkbox list UI type only; other UI types are available in the separate Pro plugin.
* Single Pro upgrade notice in the admin metabox (no per-feature upsells).
* Removed non-checkbox UI rendering code from the free plugin.

= 1.0.0 =
* Initial WordPress.org release.
* AJAX faceted filtering integrated with Ultimate Member member directories.
* Per-directory facet configuration with drag-and-drop ordering.
* Live facet counts with transient caching.

== Upgrade Notice ==

= 1.0.2 =
All facet UI types are now included in the free plugin. Update to enable radio, dropdown, tag cloud, and range filters.
