7.1 How the Plugin Integrates with Ultimate Member

UM Faceted Search integrates with Ultimate Member at three points:

1. Sidebar injection — Hooks into um_members_directory_before_head (priority 1) to output the sidebar HTML and JavaScript configuration object before the member grid renders.
2. Query filtering — Hooks into um_pre_users_query (priority 10) to inject SQL JOIN and WHERE clauses into UM’s raw user query, applying the active filter selections.
3. AJAX count refresh — Registers its own AJAX action (um_fs_get_facet_counts) to return updated filter value counts after each filter change, keeping count badges accurate.

7.2 Available Actions and Filters

UM Faceted Search provides the following WordPress hooks for developer customisation:

Hook / Filter	Type	Purpose
um_fs_before_sidebar	Action	Fires before the sidebar wrapper is rendered. Parameters: $form_id, $hash, $facets, $config.
um_fs_inside_sidebar	Action	Fires inside the sidebar wrapper, after the facets panel. Use this to add custom HTML inside the sidebar.
um_fs_after_sidebar	Action	Fires after the sidebar closing tag. Use this to add elements immediately after the sidebar.
um_fs_facet_base_args	Filter	Modify the base WP_User_Query args used by the facet count engine. Receives $args (array), $directory_id (int).
um_fs_facet_max_users	Filter	Override the maximum number of user IDs loaded per facet count query. Default: 5000. Increase for very large directories.
um_fs_field_type_overrides	Filter	Return an associative array of meta_key => type to override how the plugin resolves a field’s type. Useful for non-standard custom fields.
um_fs_user_card_data	Filter	Modify the data array for each member card when faceted search is active. Receives $data_array, $user_id, $directory_id, $directory_data.

7.3 Field Type System

Internally, every user meta key is resolved to one of the following internal types. The type determines how the facet engine counts values and how the WHERE-clause builder filters the query:

Internal Type	Description
text	Standard string fields. Matched with an exact IN() comparison, or a JSON-encoded LIKE fallback for values stored as JSON arrays.
numeric	Integer or decimal fields (e.g., Number, Rating). Range filters cast values with CAST(… AS DECIMAL(15,4)).
currency	Currency fields stored with a $ prefix. The engine strips the currency symbol for numeric comparisons.
timestamp	Unix timestamp fields. Treated as numeric for range queries.
date_slash	Date fields stored in D/M/YYYY format (UM’s default date field format). Automatically converted to ISO Y-M-D for consistent range comparisons.
date_dash	Date fields stored in ISO Y-M-D format. Passed directly to DATE comparison queries.
serialized_array	Multi-value fields stored as PHP serialised arrays (e.g., UM Checkbox and Multi-select fields). Each array element is counted and matched individually using a serialised string fragment LIKE search.
file / url / password	Blocked from faceting entirely. These types are never returned in filter counts and any attempt to filter by them is silently ignored.

7.4 Caching

Facet value counts are cached using WordPress transients with a 3-minute TTL. This prevents repeated heavy COUNT queries on every AJAX call. The cache is automatically invalidated in the following situations:

• When any user’s meta data is updated (updated_user_meta action).
• When any user’s meta data is deleted (deleted_user_meta action).
• When a directory’s facet configuration is saved in the admin (save_post action).

Cache invalidation uses a “bump” strategy: a global option (um_fs_cache_bump) is incremented with the current timestamp, and all cache keys are prefixed with this bump value. Old transients expire naturally via WordPress transient cleanup, so there is no risk of stale cache data being served after a member update.

7.5 Security

UM Faceted Search applies the following security measures:

• All AJAX requests are nonce-verified using directory-specific nonces (um_fs_nonce_{directory_id}).
• All incoming filter keys are validated against the directory’s stored facet configuration before being used in a query. Arbitrary meta keys sent by a visitor cannot be queried.
• A hardcoded list of sensitive meta keys (user_pass, user_activation_key, 2FA keys, etc.) is permanently blocked from faceting, even if a developer adds them to the facet configuration by mistake.
• All user-supplied values are sanitised with sanitize_key(), sanitize_text_field(), and absint() before being used in database queries.
• SQL queries use $wpdb->prepare() throughout to prevent SQL injection.
• Capability checks (current_user_can(‘manage_options’) and current_user_can(‘edit_post’)) are applied to all admin AJAX actions.

8. Troubleshooting

Issue	Solution
The sidebar does not appear on the frontend.	Check that the “Enable Faceted Search” toggle is ON in the directory’s admin screen and that you have added at least one facet row. Also confirm Ultimate Member is active.
The filter returns no results.	Verify that the Meta Key you entered exactly matches the key used to store data in wp_usermeta. Use the autocomplete suggestions in the admin to pick from existing keys.
Count badges show 0 for all values.	This typically means no members have data for that meta key. Confirm the field is populated on member profiles. You can check via Users → All Users → any user → screen options to see user meta.
The Numeric Range slider does not appear.	Ensure the UI Type is set to “Numeric Range” and that the meta key stores a plain number (not a string like “five years”). If the field uses a currency symbol, the plugin handles this automatically.
Filters break after a UM update.	UM Faceted Search hooks into UM’s query system. Major UM updates may occasionally change hook signatures. Check the plugin’s changelog and update UM Faceted Search if an update is available.
The sidebar appears but members are not filtered.	Check your browser console for JavaScript errors. Also confirm the wp-hooks script is loading — it should be enqueued automatically but some themes dequeue all scripts on certain pages.
Role-restricted facets are visible to all users.	Confirm that your UM roles are properly assigned to members, and that the facet’s “Visible to Roles” option has the correct role keys selected (not role labels).