Template Overrides

WB Polls supports template overrides so you can customize the appearance of polls without modifying plugin files. Copy template files to your theme directory and customize them while keeping the plugin updatable.

How Template Overrides Work

Plugin templates are located in:

wp-content/plugins/buddypress-polls/template/

To override a template, copy it to your theme:

wp-content/themes/your-theme/buddypress-polls/

Or in a child theme (recommended):

wp-content/themes/your-child-theme/buddypress-polls/

The plugin checks your theme directory first. If a matching template file exists there, it uses your version instead of the plugin default.

Available Templates

Template File	Purpose
archive-wbpoll.php	Poll archive page listing all polls
single-wbpoll.php	Single poll page displaying one poll
create-poll.php	Frontend poll creation form (template page)
poll-dashboard.php	User poll management dashboard
create-poll-shortcode.php	Poll creation form via shortcode

Override Steps

Step 1: Create the Override Directory

Create a buddypress-polls folder in your theme:

mkdir -p wp-content/themes/your-theme/buddypress-polls/

Step 2: Copy the Template

Copy the template you want to customize:

cp wp-content/plugins/buddypress-polls/template/single-wbpoll.php \
   wp-content/themes/your-theme/buddypress-polls/single-wbpoll.php

Step 3: Customize

Edit the copied template. Your theme version takes priority over the plugin version.

Template Details

single-wbpoll.php

Displays a single standalone poll on its dedicated page.

Template hooks available:

do_action( 'buddypress_polls_before_main_content' );
do_action( 'before_single_buddypress_polls' );
// Poll content renders here
do_action( 'after_single_buddypress_polls' );
do_action( 'buddypress_polls_after_main_content' );

Override example:

<?php
get_header();
do_action( 'buddypress_polls_before_main_content' );
?>

<div class="my-custom-poll-wrapper">
    <?php
    while ( have_posts() ) :
        the_post();
        do_action( 'before_single_buddypress_polls' );
        ?>
        <article id="poll-<?php the_ID(); ?>" class="poll-single">
            <header class="poll-header">
                <h1><?php the_title(); ?></h1>
            </header>
            <div class="poll-content">
                <?php the_content(); ?>
            </div>
        </article>
        <?php
        do_action( 'after_single_buddypress_polls' );
    endwhile;
    ?>
</div>

<?php
do_action( 'buddypress_polls_after_main_content' );
get_footer();
?>

archive-wbpoll.php

Displays the poll archive page listing all published polls.

Template structure:

do_action( 'buddypress_polls_before_main_content' );

if ( have_posts() ) :
    while ( have_posts() ) :
        the_post();
        do_action( 'before_single_buddypress_polls' );
        // Poll card HTML
        do_action( 'after_single_buddypress_polls' );
    endwhile;
    the_posts_pagination();
endif;

do_action( 'buddypress_polls_after_main_content' );

create-poll.php

The frontend poll creation form used by the template-based Create Poll page. This is a complex template with significant JavaScript interactions. Override with caution and keep the form structure intact.

poll-dashboard.php

The user poll management dashboard showing statistics, filter tabs, poll cards with status indicators, and action buttons.

create-poll-shortcode.php

The poll creation form rendered by the [wbpoll_create] shortcode. This template handles the shortcode-based form separately from the template page version.

CSS Customization

Key CSS Classes

Use these classes to style polls without overriding templates:

/* Poll container */
.wbpoll-single-poll { }
.wbpoll-poll-wrapper { }

/* Question and title */
.wbpoll-question { }
.wbpoll-question-title { }

/* Answer options */
.wbpoll-question-choices { }
.wbpoll-question-choices-item { }
.wbpoll-single-choice { }

/* Results display */
.wbpoll-question-results { }
.wbpoll-result-bar { }
.wbpoll-result-percentage { }

/* Voting controls */
.wbpoll-vote-button { }
.wbpoll-submit-vote { }

/* Dashboard */
.wbpoll-dashboard { }
.wbpoll-dashboard-item { }
.wbpoll-dashboard-actions { }

Adding Custom CSS

In your theme stylesheet:

.wbpoll-single-poll {
    background: #f5f5f5;
    border-radius: 8px;
    padding: 20px;
}

Via the Customizer: Navigate to Appearance > Customize > Additional CSS.

With a custom enqueued stylesheet:

function my_poll_styles() {
    if ( is_singular( 'wbpoll' ) || is_post_type_archive( 'wbpoll' ) ) {
        wp_enqueue_style(
            'my-poll-styles',
            get_template_directory_uri() . '/css/polls.css',
            array( 'buddypress-polls' ),
            '1.0.0'
        );
    }
}
add_action( 'wp_enqueue_scripts', 'my_poll_styles', 20 );

JavaScript Events

WB Polls dispatches custom JavaScript events you can listen for:

// Fires after a successful vote
document.addEventListener( 'wbpoll_vote_success', function( e ) {
    console.log( 'Vote recorded for poll:', e.detail.poll_id );
});

// Fires when a vote fails
document.addEventListener( 'wbpoll_vote_error', function( e ) {
    console.log( 'Vote failed:', e.detail.message );
});

// Fires when a poll form is submitted
document.addEventListener( 'wbpoll_form_submit', function( e ) {
    console.log( 'Poll created:', e.detail );
});

Adding Custom JavaScript

function my_poll_scripts() {
    if ( is_singular( 'wbpoll' ) ) {
        wp_enqueue_script(
            'my-poll-scripts',
            get_template_directory_uri() . '/js/polls.js',
            array( 'jquery', 'buddypress-polls' ),
            '1.0.0',
            true
        );
    }
}
add_action( 'wp_enqueue_scripts', 'my_poll_scripts', 20 );

Template Location Filter

Use the wb_poll_locate_template filter to change where the plugin looks for template files:

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

Using Hooks Instead of Full Overrides

For minor changes, use action hooks instead of overriding entire template files. This approach is safer during plugin updates:

// Add content before the poll without overriding single-wbpoll.php
add_action( 'before_single_buddypress_polls', function() {
    echo '<div class="custom-poll-intro">Cast your vote below!</div>';
});

Best Practices

Use Child Themes

Always place template overrides in a child theme. This preserves your changes during parent theme updates.

Keep Core Functionality

When overriding templates, maintain the essential action hooks and form structure. Removing hooks can break plugin functionality.

Test After Plugin Updates

When WB Polls updates, compare your overridden templates with the new plugin versions. Template changes in updates may require updating your overrides.

Prefer Filters Over Full Overrides

For small display changes, use filters like wbpoll_form_html or action hooks like before_single_buddypress_polls instead of copying entire template files.