What is Polls

Polls Module is an ExpressionEngine 2 Module which simplifies the creation of polls on your website. Polls can be added to your site with a single template tag or you can completely customize the look of your polls with the available template tags.

Installation

Once you've downloaded and extracted Polls Module for ExpressionEngine 2 copy the 'system/expressionengine/third_pary/polls' directory into 'system/expressionengine/third_party/polls' and the 'themes/third_pary/polls' directory into 'themes/third_party/polls'of your ExpressionEngine installation.

Next, login to your ExpressionEngine control panel and install the module from the 'Modules' section.

Getting Started

Once you've installed the Polls Module, you can create your first poll. Click the "Create a Poll" and fill out your poll question, any options you want the user to select from and the status. A status of "Open" means the poll will be shown and "Closed" means the poll will be hidden from view.

You can add as many options to the poll as you desire. However, you must have a minimum of 2 options. During creation, you can add more options, reorder how they will be displayed and remove them. Once you are satisfied with the poll click "Submit" to save it.

User votes are limited by using a cookie (optional). Setting 'Limit Votes' to no, allows users to vote an unlimited number of times.

Once you've created your poll, you will find the ID of that poll on the "Dashboard" page. You will need that ID for the following template tag to display your poll in a template:

{exp:polls:poll poll_id="your_poll_id" output_html="1"}

Easy right? Read on to learn how to customize it even more!

Viewing Stats

Polls provides you with a very simple way to view the stats of your poll and all the votes. Below is an example of the stats page in the module's control panel.

Tag Reference

poll tag

{exp:polls:poll}

The Polls Module tag only takes two parameters: poll_id and output_html.

poll_id=[required]

poll_id="1"
poll_id="random"
poll_id="newest"

Passing the ID of the poll will display that specific poll. You can find this ID on the "dashboard" page of the Polls Module. You can also pass "random" to return a random poll or newest" to return the latest poll.

output_html=[optional]

output_html="1"

If this parameter is set, the default poll style will be output to the browser. If you want to customize the poll, omit this parameter.

submit=[optional]

submit="new submit button text"

Allows you to change the default text of the submit button.

view_results=[optional]

view_results="new view results button text"

Allows you to change the default text of the view results button.

Conditional Variables

poll_is_open

{if poll_is_open}
    display poll
{/if}

This condition allows you to control if thepoll is shown or not by setting the status attribute in the Polls control panel.

poll_show_vote

{if poll_show_vote}
    Show info for voting form
{/if}

This condition determines if the user is on the voting "page" of the poll process.

poll_show_results

{if poll_show_results}
    Show poll results data
{/if}

This condition determines if the user is on the poll results "page" of the poll process.

poll_limit_votes

{if poll_limit_votes}
    <p>limited to one vote.</p>
{/if}

This condition returns true if the poll votes are limited per user.

has_voted

{if has_voted}
    <p>You've already voted.</p>
{/if]

This condition determines if the current visitor has voted on the current poll yet.

Variables

poll_id

{poll_id}

Outputs the poll id

poll_question

{poll_question}

Outputs the poll question

poll_total_votes

{poll_total_votes}

Outputs the total number of votes on the poll

poll_options

{poll_options}
    {option_input}
	{option_label}
	{option_value}
	{option_votes}
	{option_ratio}
{/poll_options}

Loops through the poll options

option_input

{option_input}

Outputs the option radio button for the poll form.

option_label

{option_label}

Outputs the option text

option_votes

{option_votes}

Outputs the total votes for the option

option_ratio

{option_ratio}

Outputs the percentage of votes for the option

poll_form

{poll_form}{/poll_form}

Outputs the form html

poll_form_errors

{poll_form_errors}

Outputs the errors returned from submitting invalid form data

poll_form_submit

{poll_form_submit}

Outputs the form submit button

poll_view_results

{poll_view_results}

Outputs the "View Results" submit button

poll_view_options

{poll_view_options}

Outputs the poll view options button

Default Poll HTML

This is the default style html for polls. Use it as a reference when customizing to fit your needs.

{exp:polls:poll poll_id="your_poll_id"}
    <div id="poll-{poll_id}" class="poll">
        {if poll_is_open}

            <h1>{poll_question}</h1>

            {poll_form_errors}

            {poll_form}
                <ul class="answers">
                    {poll_options}
                        <li class="option">
                            {if poll_show_vote}
                                <div class="radio">{option_input}</div>
                                <label>- {option_label}</label>
                                {if option_is_other}
                                    <div class="textfield">{option_input_other}</div>
                                {/if}
                            {if:elseif poll_show_results}
                                <div class="option-value">{option_value}</div>
                                <div class="option-detail">
                                    <div class="vote-count">{option_votes} votes</div>
                                    <div class="vote-ratio">{option_ratio}%</div>
                                </div>
                                <div class="option-bar"><div class="option-bar-value" style="width:{option_ratio}%;"></div></div>
                            {/if}
                        </li>
                    {/poll_options}
                </ul>

                {if poll_show_vote}
                    <div class="buttons">
                        <div class="cast-vote">{poll_form_submit}</div>
                        <div class="view-results">{poll_view_results}</div>
                    </div>
                {if:else}
                    <div class="poll-detail">
                        {if poll_limit_votes AND has_voted}
                            <p>Thank you for voting!</p>
                        {if:else}
                            <div class="view-options">{poll_view_options}</div>
                        {/if}
                        <div class="total-votes">{poll_total_votes} Total Votes</div>
                    </div>
                {/if}

                <input type="hidden" name="poll_id" value="{poll_id}" />
            {/poll_form}

        {/if}
    </div>
{/exp:polls:poll}