# Poll¶

The poll directive allows students to vote or rate topics on a scale.

## Synopsis¶

The general format of the poll directive is:

.. poll:: unique_id
:optional: parameter value

+ --- Content area ---
|
| A question or prompt
|
+ --------------------

## Required Arguments¶

unique id
A unique identifier after a space and the :: in the poll directive. Valid identifiers must not contain spaces. You should also avoid the characters   , `,, :, and *.

## Optional Arguments¶

content area
The poll directive should contain at least one line of content to serve as a prompt for the poll.
allowcomment
Boolean. If present, renders a comment box underneath the poll. Default is no comment box.
option_N (through 10)

String. Define up to 10 a manually specified entries. The provided parameter defines the text displayed for this option.

• The value after the underscore must be in the range 1 through 10.
• Plain text only.
• The order defined also specifies the rendering order.
• This option is ignored if :scale: is present.
scale
Integer. Implements the “On a scale of 1 to N” type method of poll. The provided parameter defines the maximum scale value.

Not applicable.

## Sphinx configuration options¶

No directive specific configuration options exist.

tbd.

## Known limitations¶

Polls require a backing database to be useful.

Polls are always oriented vertically. There is no way to change the orientation of the option buttons.

The question text must be plain text. No embedded Sphinx markup or HTML formatting is allowed.

There is no upper bound on the :scale: value. A large value could cause long page loads and take large amounts of space.

There is no check when using both both :scale: and :option_N:. If the scale option is used, then the :option_N: options are ignored.

## Examples¶

A simple example using the :scale: option with comments enabled.

.. poll:: poll-ex1
:scale: 5
:allowcomment:

On a scale from 1 to 5,
how important do **you** think it is to have a polling directive in the <em>Runestone</em>?
On a scale from 1 to 5, how important do **you** think it is to have a polling directive in the Runestone?
• 1
• 2
• 3
• 4
• 5

An example using :option_N: options to manually configure choices.

.. poll:: poll-ex2
:option_1: Red
:option_2: Orange
:option_3: Yellow
:option_4: Green
:option_5: Blue
:option_6: Indigo
:option_7: Violet

What is your favorite color in the rainbow?
What is your favorite color in the rainbow?
• Red
• Orange
• Yellow
• Green
• Blue
• Indigo
• Violet

Note that a ‘null poll’ won’t throw any warnings, but does not render anything useful in your book.

.. poll:: poll-ex3

This might happen if you make a mistake indenting your poll markup.