WP-Polls

Description

WP-Polls adds a poll to your site: a question, its answers, and a result bar that replaces the voting form once a visitor has voted, without a page reload. A poll can go in a post with a shortcode or a block, in a sidebar with the widget, or anywhere in your theme with a template tag.

A poll can accept one answer or several, close on a date you set, and be shown as a form or as its result. The markup of every part of it is a template you can edit, and the bars are styled with CSS custom properties your theme can override.

Donations

I spent most of my free time creating, updating, maintaining and supporting these plugins, if you really love my plugins and could spare me a couple of bucks, I will really appreciate it. If not feel free to use it without any obligations.

Usage

Showing A Poll From A Theme

<?php if ( function_exists( 'vote_poll' ) && ! in_pollarchive() ): ?>
    <li>
        <h2>Polls</h2>
        <ul>
            <li><?php get_poll();?></li>
        </ul>
        <?php display_polls_archive_link(); ?>
    </li>
<?php endif; ?>

• To show specific poll, use <?php get_poll(2); ?> where 2 is your poll id.
• To show random poll, use <?php get_poll(-2); ?>
• To embed a specific poll in your post, use [poll id="2"] where 2 is your poll id.
• To embed a random poll in your post, use [poll id="-2"]
• To embed a specific poll’s result in your post, use [poll id="2" type="result"] where 2 is your poll id.

Showing A Poll In A Block

Two blocks are available in the editor, under Widgets:

• Poll — one poll, as its voting form or as its result. Set Poll ID in the sidebar, or leave it at zero for the current poll, which is what an empty [poll] does. Show chooses between the voting form and the result.
• Polls Archive — every poll with its results, the same listing [page_polls] produces.

Both render on the server, so the block preview in the editor is the real poll rather than an approximation, and changing a poll updates every post showing it without re-saving anything.

The shortcodes still work and are not going anywhere. [poll], [poll=2] and [page_polls] behave exactly as they always have, and a post already containing one needs no change. The blocks call the same code the shortcodes call, so the two render identically — use whichever suits the post.

Showing A Poll In A Widget

1. Go to WP-Admin -> Appearance -> Widgets.
2. Add the Polls widget to a widget area. On block themes the widget is under the Legacy Widget block, or in Appearance -> Editor if your theme has no widget areas at all.
3. Set its title and which poll it shows, then save.
4. Scroll down for instructions on how to create a Polls Archive.

How To Add A Polls Archive?

1. Go to WP-Admin -> Pages -> Add New.
2. Type any title you like in the post’s title area.
3. If you ARE using nice permalinks, after typing the title, WordPress will generate the permalink to the page. You will see an ‘Edit’ link just beside the permalink.
4. Click ‘Edit’ and type in pollsarchive in the text field and click ‘Save’.
5. Type [page_polls] in the post’s content area.
6. Click ‘Publish’.

• If you ARE NOT using nice permalinks, go to WP-Admin -> Polls -> Settings and fill in Poll Archive URL, under the Archive heading, with the URL of the Polls Archive page you created above.

To Display Total Polls

<?php if ( function_exists( 'get_pollquestions' ) ): ?>
    <?php get_pollquestions(); ?>
<?php endif; ?> 

To Display Total Poll Answers

<?php if ( function_exists( 'get_pollanswers' ) ): ?>
    <?php get_pollanswers(); ?>
<?php endif; ?> 

To Display Total Poll Votes

<?php if ( function_exists( 'get_pollvotes' ) ): ?>
    <?php get_pollvotes(); ?>
<?php endif; ?> 

To Display Poll Votes by ID

<?php if ( function_exists( 'get_pollvotes_by_id' ) ): ?>
    <?php get_pollvotes_by_id($poll_id); ?>
<?php endif; ?>

To Display Total Poll Voters

<?php if ( function_exists( 'get_pollvoters' ) ): ?>
    <?php get_pollvoters(); ?>
<?php endif; ?> 

To Display Poll Time by ID and date format

<?php if ( function_exists( 'get_polltime' ) ): ?>
    <?php get_polltime( $poll_id, $date_format ); ?>
<?php endif; ?>

WP-CLI

wp polls list
wp polls list --status=open
wp polls get 3
wp polls open 3
wp polls close 3
wp polls delete 3 --yes

wp polls list --status=open --format=ids | xargs -n1 wp polls close closes every open poll one at a time.

REST API

GET  /wp-json/polls/v1/poll/<id>
GET  /wp-json/polls/v1/poll/<id>/result
POST /wp-json/polls/v1/poll/<id>/vote

Reading is public, because a poll is public. Voting takes the same poll_<id>-nonce the rendered voting form already carries, passed as a nonce parameter, and is subject to the same eligibility and repeat-vote settings as voting through the page.

Each response carries the rendered markup as well as the numbers, because your templates decide what a poll looks like and a client that rebuilt the markup itself would ignore them.

A refusal answers 403, not 400 — a closed poll, a vote already cast, a bad nonce, nothing selected. 400 is kept for a parameter this plugin never had a chance to look at, and a poll that does not exist is 404. So a 403 means the request was understood and the answer is no, and sending it again differently will not help.

These routes are an addition. The admin-ajax.php polls action is unchanged and still supported.

Translating the template

The plugin templates can be translated via template variables.
There are these filters for the custom template variables

wp_polls_template_voteheader_variables
wp_polls_template_votebody_variables
wp_polls_template_votefooter_variables
wp_polls_template_resultheader_variables
wp_polls_template_resultbody_variables
wp_polls_template_resultfooter_variables

The Result Body (Voted) and Result Footer (Voted) templates are filtered by
wp_polls_template_resultbody_variables and wp_polls_template_resultfooter_variables
too – the variables are shared, only the markup filters are separate.

Add filter to your theme and register custom variable where you will add your translation.
Good practice is to name them for example with prefix STR_ in the example STR_TOTAL_VOTERS.

    /**
     * Localize wp_polls_template_resultfooter_variables.
     *
     * @param array $variables An array of template variables.
     * @return array $variables Modified template variables.
     */
    function wp_polls_template_resultfooter_variables( $variables ) {

        // Add strings.
        $variables['%STR_TOTAL_VOTERS%'] = __( 'Total voters', 'theme-textdomain' );

        return $variables;
    }

// Trigger the filter
add_filter( 'wp_polls_template_resultfooter_variables', 'wp_polls_template_resultfooter_variables' , 10, 1 );

In the admin side just call the custom variable like so and the variable has been translated in the front-end.
%STR_TOTAL_VOTERS%’

Technical details