{poll}

A vote among a few answers, once per visitor, then the results as bars with percentages.

Widgets Single tags

Syntax 

{poll 'name', options='Yes, No'}
{poll 'name', options='PHP, Python, Go', title='Question?', button='Vote', results}

Parameters

name
Letters, digits, _ and -, at most 64: names the file the votes are kept in, DATA/poll/<app>/<name>.json.

Options

options
The answers, separated by commas - two or more; duplicates and empty ones are dropped.
title
The question. The name made readable when not given (favorite-language is Favorite language).
button
The text of the vote button, Vote when not given.
results
Bare option: show the results to everyone, also before a vote.

Description

{poll} asks one question with the answers of options= as radio buttons. A visitor votes once per poll: the answer is kept in the session, and a visitor who has voted sees the results instead of the form - a bar per answer with its share in percent. With results everyone sees the results, also before voting, which makes a results page.

The form is built on a {live} region and posts to the page itself: with scripting on the vote goes in the background and the results are swapped in; with scripting off it is an ordinary form post and the page comes back with them. $padCsrf protects it like any other form. A GET request starts no session for a visitor without one.

The votes are counted per answer in DATA/poll/<app>/<name>.json under an exclusive lock. An answer taken out of options= keeps its count in the file but shows no more. From PHP, padPollVote ( $name, $answer ) adds a vote and padPollCounts ( $name ) reads the counts.

A name that is not a valid file name is always an error; fewer than two answers is one under the strict check. Because what it shows depends on the votes stored and on the visitor's session, the examples below are shown but not run.

Examples

A question

Four answers and a question; after the vote the visitor sees the results as bars.

Templateexamples/poll/1-question.src 
{poll 'favorite-language', options='PHP, Python, Ruby, Go', title='Which language do you reach for first?'}

A results page

The same poll with results - the bars show to everyone, voted or not.

Templateexamples/poll/2-results.src 
<h2>How the vote stands</h2>
{poll 'favorite-language', options='PHP, Python, Ruby, Go', results}

See also

  • {live} A region of the page that re-renders on the server when something in it is clicked, submitted or changed, and swaps itself in.
  • {form} A form that posts back to the page, carrying the session's CSRF token and its own name, its fields refilling when it came back.
  • {rating} Draws a score as stars or hearts in inline SVG - whole ones filled, a part of one clipped - and says it in words.
  • {progress} Writes an accessible progress bar - the native progress element, styled, with its label and percentage - or a row of step dots.