PHP Hooks

Table of Content

Hooks Overview

All hooks provided by the plugin. Hooks marked with {$query_id} are scoped by the widget’s Query ID. Use the Post widget’s Query ID for post hooks, and the Filter widget’s Filter Query ID for filter hooks.

HookTypePurpose
bpfwe/post_wrapper_attr/{$query_id}, bpfwe/post_wrapper_inner_attr/{$query_id}, bpfwe/post_attr/{$query_id}FilterChange the HTML attributes of the Post widget’s wrapper, inner wrapper and posts. Also available as global /loop versions. Details
bpfwe/get_terms_args/{$query_id}FilterChange the arguments used to fetch taxonomy terms for a filter. Details
bpfwe/get_meta_terms/{$query_id}FilterChange the options of a Custom Field filter. Details
bpfwe/get_relational_terms/{$query_id}FilterChange the options of a Relational Field filter. Details
bpfwe/get_numeric_meta_terms/{$query_id}FilterChange the values of a numeric Custom Field filter. Details
bpfwe/target_widget_classesFilterChoose which widgets can be targeted. Details
bpfwe_custom_html_imageFilterChange the image markup used by #IMAGE#. Details
bpfwe_enable_background_image_resolutionFilterTurn on dynamic background image resolution. Details
bpfwe/filter_request_languageActionSwitch language for filter requests with translation plugins other than WPML. Details
bpfwe/query/{$query_id}, bpfwe/filter_query_args/{$query_id}, bpfwe_ajax_query_argsAction / FilterChange the post query and the filter query. See the Custom Query Guide.

Custom Attributes for Post Widget

The plugin provides filters to customize HTML attributes on the wrapper and individual posts in the Posts widget. You can add classes, IDs, data attributes, and ARIA attributes programmatically, scoped by the widget’s Query ID.

Hook Details

Hook TypeFilter Hook
Hook Namesbpfwe/post_wrapper_attr/{$query_id}
bpfwe/post_wrapper_inner_attr/{$query_id}
bpfwe/post_attr/{$query_id}
Global Hook Namesbpfwe/post_wrapper_attr/loop
bpfwe/post_wrapper_inner_attr/loop
bpfwe/post_attr/loop
AffectsHTML attributes for wrapper, inner wrapper, and post containers

Hook Arguments

ArgumentTypeDescription
attributesarrayAssociative array of attributes (class, id, data-*). class is an array of class names.
widget\Elementor\Widget_BaseThe widget instance rendering the posts.
contextstringThe element being filtered: wrapper, wrapper_inner or post.

Using the Custom Filter

add_filter( 'bpfwe/post_wrapper_attr/{$query_id}', function( $attributes, $widget ) {
    // Modify attributes here
    return $attributes;
}, 10, 2 );

Examples

Example 1: Add Custom Classes and ID to Wrapper

add_filter( 'bpfwe/post_wrapper_attr/my_custom_query', function( $attributes, $widget ) {
    $attributes['class'][] = 'custom-wrapper';
    $attributes['class'][] = 'extra-style';
    $attributes['id'] = 'wrapper-id';
    return $attributes;
}, 10, 2 );

Example 2: Add Data Attributes to Inner Wrapper

add_filter( 'bpfwe/post_wrapper_inner_attr/my_custom_query', function( $attributes, $widget ) {
    $attributes['data-filter'] = 'category-2';
    $attributes['aria-label'] = 'Custom Widget';
    return $attributes;
}, 10, 2 );

Example 3: Highlight Specific Posts

add_filter( 'bpfwe/post_attr/my_custom_query', function( $attributes, $widget ) {
    $post_id = get_the_ID();
    $attributes['class'][] = 'single-post';
    $attributes['class'][] = 'highlight-' . $post_id;
    $attributes['data-post-type'] = 'featured';
    return $attributes;
}, 10, 2 );

Example 4: Add a Class to Every Post Widget

add_filter( 'bpfwe/post_wrapper_attr/loop', function( $attributes, $widget ) {
    $attributes['class'][] = 'my-site-loop';
    return $attributes;
}, 10, 2 );

Notes

  • Replace my_custom_query with your actual Query ID.
  • The /loop hooks run for every Post widget, before the Query ID hook. The Query ID hook then receives the result, so it adds to the global changes instead of replacing them.
  • get_the_ID() can be used in bpfwe/post_attr/ to retrieve the current post ID.
  • Attributes with an empty value are skipped. All attributes are automatically escaped before output.

Custom Filter for Term Queries

When retrieving taxonomy terms for the filter, the plugin lets you modify the get_terms() arguments programmatically. Useful for excluding terms, adjusting order, or adding custom conditions beyond the available widget options.

Hook Details

Hook TypeFilter Hook
Hook Namebpfwe/get_terms_args/{$query_id}
AffectsTaxonomy Term Queries

Hook Arguments

ArgumentTypeDescription
argsarrayThe arguments array passed to get_terms(). You can modify or extend these. It also includes bpfwe_query_id.
widget\Elementor\Widget_BaseThe widget instance triggering the query.

Setting Up a Custom Filter

Assign a unique ID under Content > Query > Filter Query ID in the Filter widget. For example, if you use my_filter, the hook is bpfwe/get_terms_args/my_filter.

Using the Custom Filter

add_filter( 'bpfwe/get_terms_args/{$query_id}', function( $args, $widget ) {
    // Modify the get_terms args here
    return $args;
}, 10, 2 );

Examples

Example 1: Exclude Terms

add_filter( 'bpfwe/get_terms_args/my_filter', function( $args, $widget ) {
    $args['exclude'] = [ 14294, 14292 ];
    return $args;
}, 10, 2 );

Example 2: Change the Term Order

add_filter( 'bpfwe/get_terms_args/my_filter', function( $args, $widget ) {
    $args['orderby'] = 'count';
    $args['order']   = 'DESC';
    return $args;
}, 10, 2 );

Example 3: Limit Terms on Category Archives

add_filter( 'bpfwe/get_terms_args/my_filter', function( $args, $widget ) {
    if ( is_category() || is_tag() ) {
        $current_term = get_queried_object();
        if ( $current_term && ! is_wp_error( $current_term ) ) {
            $args['include'] = [ $current_term->term_id ];
        }
    }
    return $args;
}, 10, 2 );

Notes

  • Replace my_filter with your actual Filter Query ID.
  • Refer to get_terms for available arguments.
  • Caching: the filter’s term lists are cached (see Cache Filter Terms in the Filter widget). The hook runs when the cache is rebuilt, not on every page view. Logic that depends on the user or the current page, other than the archive being viewed, can return stale results. For that kind of logic, set Cache Filter Terms to 0.
  • Editors always see fresh results, since the cache is skipped when editing.

Custom Filter for Meta Field Terms

When using Custom Field filters, you can modify the retrieved meta term values before they are rendered in the filter widget. This allows you to adjust labels, counts, or exclude specific meta values programmatically.

Hook Details

Hook TypeFilter Hook
Hook Namebpfwe/get_meta_terms/{$query_id}
AffectsMeta term values generated from post meta keys

Hook Arguments

ArgumentTypeDescription
termsarrayAssociative array keyed by meta value. Each item is formatted as [ 'label' => 'Meta Value', 'count' => 12 ].
widget\Elementor\Widget_BaseThe Elementor widget instance rendering the filter.
itemarrayThe internal configuration array for this specific filter field.

Using the Custom Filter

add_filter( 'bpfwe/get_meta_terms/my_meta_filter', function( $terms, $widget, $item ) {
    // Modify or filter the meta term list here
    return $terms;
}, 10, 3 );

Examples

Example 1: Exclude Empty Labels

add_filter( 'bpfwe/get_meta_terms/my_meta_filter', function( $terms, $widget, $item ) {
    foreach ( $terms as $key => $data ) {
        if ( empty( trim( $data['label'] ) ) ) {
            unset( $terms[ $key ] );
        }
    }
    return $terms;
}, 10, 3 );

Example 2: Rename Meta Values

add_filter( 'bpfwe/get_meta_terms/my_meta_filter', function( $terms, $widget, $item ) {
    foreach ( $terms as $key => &$data ) {
        if ( $data['label'] === 'Old Value' ) {
            $data['label'] = 'New Display Name';
        }
    }
    return $terms;
}, 10, 3 );

Notes

  • Replace my_meta_filter with your actual Filter Query ID.
  • This hook runs for filters using the Custom Field option.
  • The array always includes label and count keys.
  • The key is the raw value used for filtering, so changing a label renames what visitors see without changing how it filters.
  • Caching: the result is cached according to Cache Filter Terms, so the hook runs when the cache is rebuilt. It always runs in the editor and on faceted filters.

Custom Filter for Relational Field Terms

When using Relational filters (Post, User, etc.), you can customize or enrich the related items retrieved from meta fields that store IDs or serialized arrays. This allows you to override labels, exclude specific related items, or inject custom data.

Hook Details

Hook TypeFilter Hook
Hook Namebpfwe/get_relational_terms/{$query_id}
AffectsRelated items generated from post, user, or other relational meta fields

Hook Arguments

ArgumentTypeDescription
termsarrayAssociative array keyed by related item ID. Each item is formatted as [ 'label' => 'Item Title', 'count' => 3 ].
widget\Elementor\Widget_BaseThe Elementor widget instance rendering the filter.
itemarrayThe internal configuration array for this filter. Includes relational_field_type and meta_key.

Using the Custom Filter

add_filter( 'bpfwe/get_relational_terms/my_relation_filter', function( $terms, $widget, $item ) {
    // Modify the relational terms array here
    return $terms;
}, 10, 3 );

Examples

add_filter( 'bpfwe/get_relational_terms/my_relation_filter', function( $terms, $widget, $item ) {
    foreach ( $terms as $id => $data ) {
        if ( in_array( $id, array( 12, 45, 87 ), true ) ) {
            unset( $terms[ $id ] );
        }
    }
    return $terms;
}, 10, 3 );

Example 2: Prefix Labels with Text

add_filter( 'bpfwe/get_relational_terms/my_relation_filter', function( $terms, $widget, $item ) {
    foreach ( $terms as &$data ) {
        $data['label'] = 'By ' . $data['label'];
    }
    return $terms;
}, 10, 3 );

Notes

  • Replace my_relation_filter with your actual Filter Query ID.
  • This hook runs after counts and labels are generated and sorted for relational data.
  • The $item array includes context like meta_key and relational_field_type.
  • Useful for customizing how relational filters display linked content such as authors, users, or related posts.
  • Caching: the result is cached according to Cache Filter Terms, so the hook runs when the cache is rebuilt. It always runs in the editor and on faceted filters.

Custom Filter for Numeric Field Values

When using Custom Field (Numeric) filters, you can modify the list of values before it is used to build the filter. This lets you remove outliers, cap a range or add values.

Hook Details

Hook TypeFilter Hook
Hook Namebpfwe/get_numeric_meta_terms/{$query_id}
AffectsThe numeric values found for a Custom Field (Numeric) group

Hook Arguments

ArgumentTypeDescription
termsarrayA sorted list of numbers (float). Sorted according to the group’s Order setting.
widget\Elementor\Widget_BaseThe Elementor widget instance rendering the filter.
itemarrayThe internal configuration array for this filter group, including meta_key.

Using the Custom Filter

add_filter( 'bpfwe/get_numeric_meta_terms/my_filter', function( $terms, $widget, $item ) {
    // Modify the list of numbers here
    return $terms;
}, 10, 3 );

Example: Ignore Prices Above 1000

add_filter( 'bpfwe/get_numeric_meta_terms/my_filter', function( $terms, $widget, $item ) {
    return array_values( array_filter( $terms, function( $value ) {
        return $value <= 1000;
    } ) );
}, 10, 3 );

Notes

  • Replace my_filter with your actual Filter Query ID.
  • Return a list of numbers. If it ends up empty, the filter shows a “No numeric values found” message.
  • Caching: the result is cached according to Cache Filter Terms, so the hook runs when the cache is rebuilt.

Custom Target Widget Classes

The Filter, Search Bar and Sorting widgets list the post widgets on the page in their Post Widget Target dropdown, and use the same list to auto-connect to a single post widget. This filter controls which widgets are eligible, so you can make a third-party or custom widget targetable.

Hook Details

Hook TypeFilter Hook
Hook Namebpfwe/target_widget_classes
AffectsThe target picker and target auto-detection

Hook Arguments

ArgumentTypeDescription
classesarrayThe widget CSS classes, without the leading dot. Default: elementor-widget-post-widget, elementor-widget-loop-grid, elementor-widget-loop-carousel and elementor-widget-posts.

Example: Make a Custom Widget Targetable

add_filter( 'bpfwe/target_widget_classes', function( $classes ) {
    $classes[] = 'elementor-widget-my-custom-grid';
    return $classes;
} );

Notes

  • Return an array of class names. If anything else is returned, the defaults are used.
  • Removing a class from the list also removes those widgets from the picker and from auto-connect.
  • The widget still has to render its items in a way the filter can update.

Custom HTML Image Markup

In the Post widget’s Custom HTML skin, the #IMAGE# tag is replaced with the post’s featured image. This filter lets you change that markup.

Hook Details

Hook TypeFilter Hook
Hook Namebpfwe_custom_html_image
AffectsThe #IMAGE# tag in the Custom HTML skin

Hook Arguments

ArgumentTypeDescription
imagestringThe <img> markup that replaces #IMAGE#.
post_idintThe ID of the post being rendered.

Example: Add a Class to the Image

add_filter( 'bpfwe_custom_html_image', function( $image, $post_id ) {
    return str_replace( '<img ', '<img class="my-card-image" ', $image );
}, 10, 2 );

Notes

  • Return a string. Escape any output you add yourself.
  • The default markup is a responsive image with srcset, width, height and lazy loading. Keep those attributes if you replace the markup.

Background Image Resolution

The plugin can resolve dynamic background images, such as the featured image used as a container background inside a filtered list. This is off by default. Enable it if your design relies on dynamic background images.

Hook Details

Hook TypeFilter Hook
Hook Namebpfwe_enable_background_image_resolution
Defaultfalse

Example: Turn It On

add_filter( 'bpfwe_enable_background_image_resolution', '__return_true' );

Notes

  • You can also turn it on for a single Post widget with the Refresh Background Images control under Additional Options.
  • Leave it off if you don’t use dynamic background images. It avoids extra work on each render.

Filter Request Language

When a page is rendered in a given language, filter requests are sent with that language. The plugin switches WPML to it automatically. For other translation plugins, use this action to switch the language yourself before the query runs.

Hook Details

Hook TypeAction Hook
Hook Namebpfwe/filter_request_language
RunsBefore the query of a filter request, when a language is sent

Hook Arguments

ArgumentTypeDescription
langstringThe language code the widget was rendered with.

Example: Switch Language in Polylang

add_action( 'bpfwe/filter_request_language', function( $lang ) {
    if ( function_exists( 'pll_set_language' ) ) {
        pll_set_language( $lang );
    }
} );

Notes

  • Available since version 1.9.1.
  • The example assumes a helper exists in your translation plugin. Check its documentation for the correct call.