Hooks Filters

WB Polls provides action hooks and filters for developers to extend and customize polling functionality. This reference covers the most commonly used hooks organized by feature area.

Action Hooks

Activity Poll Hooks

bp_polls_after_submit_polls

Fires after a vote is submitted on an activity poll.

do_action( 'bp_polls_after_submit_polls', $user_id, $activity_id );

Parameter	Type	Description
$user_id	int	ID of the user who voted
$activity_id	int	ID of the activity containing the poll

add_action( 'bp_polls_after_submit_polls', function( $user_id, $activity_id ) {
    // Award points for voting
    mycred_add( 'poll_vote', $user_id, 5, 'Voted on a poll', $activity_id );
}, 10, 2 );

bpolls_after_save_poll_activity

Fires after a poll activity is saved.

do_action( 'bpolls_after_save_poll_activity', $activity_id, $poll_data );

Standalone Poll Hooks

wbpoll_on_vote

Fires when a vote is recorded on a standalone poll.

do_action( 'wbpoll_on_vote', $insertArray, $vote_id, $published );

Parameter	Type	Description
$insertArray	array	Vote data array including poll_id, user_id, and answer
$vote_id	int	ID of the vote record
$published	int	Whether the vote is published

add_action( 'wbpoll_on_vote', function( $data, $vote_id, $published ) {
    // Log vote to external analytics
    wp_remote_post( 'https://api.example.com/votes', [
        'body' => [
            'poll_id' => $data['poll_id'],
            'user_id' => $data['user_id'],
            'answer'  => $data['answer']
        ]
    ]);
}, 10, 3 );

wbpoll_form_validation

Fires after vote form validation, before saving the vote.

do_action( 'wbpoll_form_validation', $poll_result, $poll_id );

Template Hooks

These hooks let you inject custom content around poll templates without overriding entire template files.

buddypress_polls_before_main_content

Fires before the main poll content wrapper in templates.

do_action( 'buddypress_polls_before_main_content' );

buddypress_polls_after_main_content

Fires after the main poll content wrapper in templates.

do_action( 'buddypress_polls_after_main_content' );

before_single_buddypress_polls

Fires before an individual poll is displayed.

do_action( 'before_single_buddypress_polls' );

after_single_buddypress_polls

Fires after an individual poll is displayed.

do_action( 'after_single_buddypress_polls' );

Form Hooks

These hooks let you add content around poll answer sections.

wbpoll_answer_html_before

Fires before the poll answer HTML container.

do_action( 'wbpoll_answer_html_before', $poll_id, $reference, $poll_result );

wbpoll_answer_html_before_question

Fires before the question/options section within the answer HTML.

do_action( 'wbpoll_answer_html_before_question', $poll_id, $reference, $poll_result );

wbpoll_answer_html_after_question

Fires after the question/options section within the answer HTML.

do_action( 'wbpoll_answer_html_after_question', $poll_id, $reference, $poll_result );

add_action( 'wbpoll_answer_html_after_question', function( $poll_id, $ref, $result ) {
    echo '<div class="poll-disclaimer">Your vote is anonymous.</div>';
}, 10, 3 );

wbpoll_answer_html_after

Fires after the poll answer HTML container.

do_action( 'wbpoll_answer_html_after', $poll_id, $reference, $poll_result );

Filters

Poll Creation Filters

bpolls_user_can_create_poll

Filter whether a user can create activity polls.

apply_filters( 'bpolls_user_can_create_poll', $can_create, $user_id );

add_filter( 'bpolls_user_can_create_poll', function( $can_create, $user_id ) {
    // Restrict to users with 100+ posts
    return count_user_posts( $user_id ) >= 100;
}, 10, 2 );

wbpoll_user_can_create_poll

Filter whether a user can create standalone polls.

apply_filters( 'wbpoll_user_can_create_poll', $can_create, $allowed_roles );

wbpoll_enabled_poll_types

Filter which poll types are available.

apply_filters( 'wbpoll_enabled_poll_types', $enabled_types, $settings );

add_filter( 'wbpoll_enabled_poll_types', function( $types, $settings ) {
    // Disable audio polls programmatically
    unset( $types['audio'] );
    return $types;
}, 10, 2 );

wbpoll_guest_can_create

Filter whether guests can create polls.

apply_filters( 'wbpoll_guest_can_create', $can_create );

Vote Filters

wbpoll_vote_status

Filter the vote status before saving.

apply_filters( 'wbpoll_vote_status', $status, $poll_id );

add_filter( 'wbpoll_vote_status', function( $status, $poll_id ) {
    // Moderate votes from users registered less than 7 days ago
    $user = get_userdata( get_current_user_id() );
    if ( strtotime( $user->user_registered ) > strtotime( '-7 days' ) ) {
        return 0; // Set to pending
    }
    return $status;
}, 10, 2 );

wbpoll_form_extra_process

Filter vote data before database insertion.

apply_filters( 'wbpoll_form_extra_process', $insertArray, $poll_id );

wbpoll_is_user_voted

Filter the check for whether a user has already voted.

apply_filters( 'wbpoll_is_user_voted', $count );

Display Filters

bp_activity_new_poll_action

Filter the activity action text for polls.

apply_filters( 'bp_activity_new_poll_action', $action, $activity );

add_filter( 'bp_activity_new_poll_action', function( $action, $activity ) {
    return sprintf(
        '%s created a poll - vote now!',
        bp_core_get_userlink( $activity->user_id )
    );
}, 10, 2 );

bppolls_activity_user_can_edit

Filter whether a user can edit an activity poll.

apply_filters( 'bppolls_activity_user_can_edit', $can_edit, $activity );

wbpoll_description

Filter the poll description output.

apply_filters( 'wbpoll_description', $poll_content, $post_id );

wbpoll_login_html

Filter the login link HTML shown to guests.

apply_filters( 'wbpoll_login_html', $html, $login_url, $redirect_url );

add_filter( 'wbpoll_login_html', function( $html, $login_url, $redirect ) {
    return sprintf(
        '<a href="%s" class="btn btn-primary">Sign In to Vote</a>',
        esc_url( $login_url . '?redirect_to=' . $redirect )
    );
}, 10, 3 );

wbpoll_default_avatar

Filter the default avatar URL for anonymous voters.

apply_filters( 'wbpoll_default_avatar', $default_url );

Form HTML Filters

wbpoll_form_html

Filter the complete poll form HTML output.

apply_filters( 'wbpoll_form_html', $poll_form_html, $post_id );

wbpoll_form_html_before / wbpoll_form_html_after

Filter HTML before or after the poll form.

apply_filters( 'wbpoll_form_html_before', $html, $post_id );
apply_filters( 'wbpoll_form_html_after', $html, $post_id );

Template Filters

wb_poll_locate_template

Filter the template file location for theme overrides.

apply_filters( 'wb_poll_locate_template', $template_part, $file_name );

add_filter( 'wb_poll_locate_template', function( $template, $file ) {
    $custom = get_template_directory() . '/polls/' . $file;
    if ( file_exists( $custom ) ) {
        return $custom;
    }
    return $template;
}, 10, 2 );

Post Type Filters

wbpoll_post_type_args

Filter the wbpoll custom post type registration arguments.

apply_filters( 'wbpoll_post_type_args', $args );

add_filter( 'wbpoll_post_type_args', function( $args ) {
    $args['rewrite'] = [ 'slug' => 'surveys', 'with_front' => false ];
    return $args;
});

Options and Settings Filters

wbpoll_display_options

Filter available poll display options (text, bar, pie).

apply_filters( 'wbpoll_display_options', $methods );

wbpoll_display_options_backend

Filter display options shown in backend settings.

apply_filters( 'wbpoll_display_options_backend', $methods );

wbpoll_display_options_widget_result

Filter display options available in widget results.

apply_filters( 'wbpoll_display_options_widget_result', $methods );

wbpoll_status_by_value

Filter the poll status options array.

apply_filters( 'wbpoll_status_by_value', $states );

wbpoll_userroles

Filter the available user roles list used in poll settings.

apply_filters( 'wbpoll_userroles', $userRoles, $plain, $include_guest );

wbpoll_fields

Filter the poll meta fields array. Use this to add custom meta fields to polls.

apply_filters( 'wbpoll_fields', $post_meta_fields );

add_filter( 'wbpoll_fields', function( $fields ) {
    $fields['_wbpoll_custom_field'] = [
        'label' => 'Custom Field',
        'type'  => 'text'
    ];
    return $fields;
});

Admin Display Filters

wbpoll_admin_listing_votes

Filter the vote count display in admin poll listings.

apply_filters( 'wbpoll_admin_listing_votes', $total_votes, $post_id );

add_filter( 'wbpoll_admin_listing_votes', function( $votes, $post_id ) {
    return number_format( $votes );
}, 10, 2 );

Form Answer Filters

wbpoll_form_answer_start

Filter HTML at the start of the answer options section.

apply_filters( 'wbpoll_form_answer_start', $html, $post_id );

wbpoll_form_answer_end

Filter HTML at the end of the answer options section.

apply_filters( 'wbpoll_form_answer_end', $html, $post_id );

wbpoll_register_html

Filter the registration link HTML shown to guests who need to register.

apply_filters( 'wbpoll_register_html', $html, $redirect_url );

CSV Export Filters

bpolls_csv_export_filename

Filter the CSV export filename.

apply_filters( 'bpolls_csv_export_filename', $file, $activity_id, $poll_name );

bpolls_csv_export_settings

Filter CSV export settings including delimiter, enclosure, and date format.

apply_filters( 'bpolls_csv_export_settings', $csv_settings, $activity_id );

bpolls_csv_export_header

Filter the CSV header row.

apply_filters( 'bpolls_csv_export_header', $csv_header, $activity_meta, $activity_id );

bpolls_csv_export_row

Filter each CSV data row.

apply_filters( 'bpolls_csv_export_row', $fields, $user, $activity_meta, $activity_id );

Asset Loading Filter

bpolls_enqueue_assets_condition

Filter when poll CSS and JavaScript assets should be loaded.

apply_filters( 'bpolls_enqueue_assets_condition', $should_enqueue );

add_filter( 'bpolls_enqueue_assets_condition', function( $should_enqueue ) {
    // Always load poll assets on a custom page
    if ( is_page( 'my-polls-page' ) ) {
        return true;
    }
    return $should_enqueue;
});

Best Practices

Check Plugin Activation

Always verify WB Polls is active before adding hooks:

if ( class_exists( 'Buddypress_Polls' ) ) {
    add_filter( 'bpolls_user_can_create_poll', 'my_custom_check', 10, 2 );
}

Hook Priority

Use priority values to control execution order:

add_action( 'wbpoll_on_vote', 'early_function', 5, 3 );   // Runs first
add_action( 'wbpoll_on_vote', 'normal_function', 10, 3 );  // Default
add_action( 'wbpoll_on_vote', 'late_function', 20, 3 );    // Runs last

Removing Default Hooks

Remove existing hook callbacks when you need to replace default behavior:

remove_filter( 'wbpoll_login_html', 'default_login_html_function', 10 );

AJAX Actions Reference

WB Polls registers these AJAX actions for frontend interactions. All actions use the wp_ajax_ prefix and some also register wp_ajax_nopriv_ variants for guest access.

Activity Poll AJAX Actions

Action	Nonce	Purpose	Guest Access
bpolls_save_poll_vote	bpolls_ajax_security	Submit a vote on an activity poll	No
bpolls_save_image	bpolls_ajax_security	Upload an image to a poll option	No
bpolls_save_video	bpolls_ajax_security	Upload a video to a poll option	No
bpolls_save_audio	bpolls_ajax_security	Upload audio to a poll option	No
bpolls_activity_all_voters	bpolls_ajax_security	Get full voter list for a poll option	Yes
bpolls_activity_add_user_option	bpolls_ajax_security	Add a user-suggested option	No
bpolls_activity_delete_user_option	bpolls_ajax_security	Delete a user-suggested option	No
bpolls_set_poll_type_true	bpolls_ajax_security	Set the poll type flag	No

Standalone Poll AJAX Actions

Action	Nonce	Purpose	Guest Access
wbpoll_user_vote	wbpolluservote	Submit a vote on a standalone poll	Yes
wbpoll_additional_field	None	Add a user-suggested text option	Yes
wbpoll_additional_field_image	None	Add a user-suggested image option	Yes
wbpoll_additional_field_video	None	Add a user-suggested video option	Yes
wbpoll_additional_field_audio	None	Add a user-suggested audio option	Yes
wbpoll_additional_field_html	None	Add a user-suggested HTML option	Yes

Widget AJAX Actions

Action	Nonce	Purpose	Guest Access
bpolls_widget_get_activity_results	bpolls_widget_security	Load activity poll results in widget	Yes
wbpoll_widget_get_results	wbpoll_widget_nonce	Load standalone poll results in widget	Yes

Admin AJAX Actions

Action	Nonce	Purpose
wbpoll_get_answer_template	wbpoll	Get answer template for admin poll editor
wbpoll_log_delete	wbpoll	Delete a poll log entry

Database Schema

WB Polls creates two custom database tables on activation.

Votes Table ({prefix}_wppoll_votes)

Stores all votes cast on standalone polls.

Column	Type	Description
id	mediumint(8)	Auto-increment primary key
poll_id	int(13)	Poll post ID
poll_title	text	Poll title at time of vote
user_name	varchar(255)	Voter display name
is_logged_in	tinyint(1)	Whether voter was logged in
user_cookie	varchar(1000)	Cookie identifier for duplicate prevention
user_ip	varchar(45)	Voter IP address
user_id	bigint(20)	WordPress user ID (NULL for guests)
user_answer	text	Selected answer option IDs
answer_title	text	Selected answer option text
published	tinyint(3)	Vote published status (default 1)
comment	longtext	Vote comment
guest_hash	varchar(32)	Hash identifier for guest voters
guest_name	varchar(100)	Guest voter name
guest_email	varchar(100)	Guest voter email
created	int(20)	Unix timestamp of vote

Indexes: poll_id, user_id, composite poll_user (poll_id, user_id)

Log Table ({prefix}_wppoll_log)

Stores poll activity logs for admin review.

Column	Type	Description
id	mediumint(8)	Auto-increment primary key
poll_id	int(13)	Poll post ID
user_name	varchar(255)	User display name
is_logged_in	tinyint(1)	Whether user was logged in
user_ip	varchar(45)	User IP address
useragent	text	Browser user agent string
user_id	bigint(20)	WordPress user ID
user_action	text	Action performed
poll_status	text	Poll status at time of action
details	text	Action details
created	int(20)	Unix timestamp

Indexes: poll_id, user_id

Duplicate Vote Prevention

The votes table supports multiple methods of duplicate vote detection:

1. Logged-in users: Checked by user_id
2. Guest voters: Checked by combination of user_ip, user_cookie, and guest_hash
3. Cookie tracking: Uses a wbpoll-cookie cookie with a 14-day expiration