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 Type |
Filter Hook |
| Hook Names |
bpfwe/post_wrapper_attr/{$query_id}
bpfwe/post_wrapper_inner_attr/{$query_id}
bpfwe/post_attr/{$query_id} |
| Affects |
HTML attributes for wrapper, inner wrapper, and post containers |
Hook Arguments
| Argument |
Type |
Description |
| attributes |
array |
Associative array of attributes (class, id, data-*) |
| widget |
\Elementor\Widget_Base |
The widget instance rendering the posts |
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';
$attributes['aria-hidden'] = 'true';
return $attributes;
}, 10, 2 );
Notes
- Replace
my_custom_query with your actual Query ID.
get_the_ID() can be used in bpfwe/post_attr/ to retrieve the current post ID.- All attributes are automatically escaped before output.
- Multiple classes should be added by pushing into the
class array (each class as a separate array item).
- These hooks allow integration with CSS, JS, or accessibility enhancements.
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 Type |
Filter Hook |
| Hook Name |
bpfwe/get_terms_args/{$query_id} |
| Affects |
Taxonomy Term Queries |
Hook Arguments
| Argument |
Type |
Description |
| args |
array |
The arguments array passed to get_terms(). You can modify or extend these. |
| widget |
\Elementor\Widget_Base |
The widget instance triggering the query. |
Setting Up a Custom Filter
Assign a unique Query ID under Content > Query > Filter Query ID. 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: Show Empty Terms Only for Logged-in Users
add_filter( 'bpfwe/get_terms_args/my_filter', function( $args, $widget ) {
if ( is_user_logged_in() ) {
$args['hide_empty'] = false;
}
return $args;
}, 10, 2 );
Example 3: Filter Terms Based on Current Page
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 ];
}
} elseif ( is_singular( 'post' ) ) {
global $post;
$args['include'] = wp_get_post_terms( $post->ID, 'category', [ 'fields' => 'ids' ] );
}
return $args;
}, 10, 2 );
Notes
- Replace
my_filter with your actual Query ID.
- Refer to get_terms for available arguments.
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 Type |
Filter Hook |
| Hook Name |
bpfwe/get_meta_terms/{$query_id} |
| Affects |
Meta term values generated from post meta keys |
| Argument |
Type |
Description |
| terms |
array |
Associative array of meta values and their counts. Each item is formatted as [ 'label' => 'Meta Value', 'count' => 12 ]. |
| widget |
\Elementor\Widget_Base |
The Elementor widget instance rendering the filter. |
| item |
array |
The internal configuration array for this specific filter field. |
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 );
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 );
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 );
- Replace
my_meta_filter with your actual Filter Query ID.
- This hook only runs for filters using the Custom Field option.
- The array always includes
label and count keys.
- Ideal for renaming, sorting, or excluding specific meta values.
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 Type |
Filter Hook |
| Hook Name |
bpfwe/get_relational_terms/{$query_id} |
| Affects |
Related items generated from post, user, or other relational meta fields |
Hook Arguments
| Argument |
Type |
Description |
| terms |
array |
Associative array of related IDs with label and count data. Each item is formatted as [ 'label' => 'Item Title', 'count' => 3 ]. |
| widget |
\Elementor\Widget_Base |
The Elementor widget instance rendering the filter. |
| item |
array |
The 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
Example 1: Hide Certain Related Posts
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 Type
add_filter( 'bpfwe/get_relational_terms/my_relation_filter', function( $terms, $widget, $item ) {
$type = isset( $item['relational_field_type'] ) ? $item['relational_field_type'] : 'post';
foreach ( $terms as &$data ) {
$data['label'] = ucfirst( $type ) . 'My Awesome Prefix ' . $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 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.