Creating and managing polls

[Discourse]

This guide explains how to create polls in Discourse to gather votes from users on any topic.

Required user level: All users

By default, polls are enabled in Discourse and users of trust level 1 or above are allowed to create them. Site admins can adjust who can create polls via the poll create allowed groups site setting and disable polls using the poll enabled site setting.

Creating a poll from the toolbar

The easiest way to create a poll is to use the poll builder. The poll builder can be accessed from the menu in the composer, and allows you to make a poll without needing to know the exact syntax.

To show advanced options press the icon. This will show you different poll options such as if the poll auto closes, set groups allowed to vote, choose bar or pie, etc.

Poll options

Poll type:

• Single Choice: Default poll type. Users can select a single choice from the poll
• Multiple Choice: Users can select multiple choices from the poll.
  • The poll creator must also define the minimum and maximum number of choices a user can make. By default the minimum will be 1, and the maximum will be the number of poll choices.
• Number Rating: Users can select a single number.
  • The poll creator must also define the min, max and step for the number rating. For example, if the min is 2, the max is 10, and the step is 2, the options will be 2, 4, 6, 8, and 10.

Results:

• Always visible: Default poll results. Users can always see the results of the poll, regardless of if they’ve voted.
• Only after voting: Users must vote before they can see the results of the poll.
• When the poll is closed: Poll results will only be revealed once the poll is closed.
• Staff only: Only site staff will be able to see the poll results.

Allowed groups:

Allows the poll creator to limit which groups can participate in the poll. Users not in the listed groups will be able to view the poll, but not vote. Default is all users can participate, no group limitation.

Chart type:

For Single or Multiple Choice polls, choose whether to display the result in a bar graph or pie chart.

Show who voted:

Enabled by default, this allows those who can view poll results to also view the specific choices of each poll user. (Bar Chart type only)

Automatically close poll:

Allows the poll creator to set a date/time for the poll to close automatically. Unlike manually closed polls, auto-closed polls cannot be re-opened.

Including images

Polls can even include images! After using the poll builder to insert the poll, images can be uploaded to the post and manually added to the poll. Uploaded images should be small, or adjusted to display at a lower percentage:

[poll type=regular]
* ![image|690x458,25%](upload://2u570X7kQiPJQaJD1Bd8MLDHDNB.jpeg)
* ![image|690x334,25%](upload://35fmeFw8RMywSxIc4lbCb8UHPaT.jpg)
* ![image|690x499,25%](upload://xSDkRwmuj1pNc2QXKzthfXRlwsX.jpg)
[/poll]

• 
• 
• 

[poll type=regular]
* Cat: a small domesticated carnivorous mammal with soft fur, a short snout, and retractile claws.
![image|690x458,25%](upload://2u570X7kQiPJQaJD1Bd8MLDHDNB.jpeg)
* Dog: a domesticated carnivorous mammal that typically has a long snout, an acute sense of smell, and a barking, howling, or whining voice.
![image|690x334,25%](upload://35fmeFw8RMywSxIc4lbCb8UHPaT.jpg)
* Fish: a limbless cold-blooded vertebrate animal with gills and fins and living wholly in water.
![image|690x499,25%](upload://xSDkRwmuj1pNc2QXKzthfXRlwsX.jpg)
[/poll]

• Cat: a small domesticated carnivorous mammal with soft fur, a short snout, and retractile claws.
  
  
• Dog: a domesticated carnivorous mammal that typically has a long snout, an acute sense of smell, and a barking, howling, or whining voice.
  
  
• Fish: a limbless cold-blooded vertebrate animal with gills and fins and living wholly in water.
  
  

Including relative dates

Polls can also include relative dates! In a similar way to adding images, after using the poll builder to insert the poll you can insert dates into the poll options via the “Insert date / time” composer button:

[poll type=regular]
* [date=2019-10-13 timezone="Europe/Paris"]
* [date=2019-10-12 timezone="Europe/Paris"]
* [date=2019-10-11 timezone="Europe/Paris"]
[/poll]

• 2019-10-12T22:00:00Z
• 2019-10-11T22:00:00Z
• 2019-10-10T22:00:00Z

Multiple polls in a post

If multiple polls are used in a single post (like this one!) each poll will need a unique name or they will not work. When using the poll builder each extra poll will be numbered sequentially, but you can also do this manually by adding name="poll_name" as a parameter:

[poll name="poll_1"]
1. option one
2. option two
3. option three
[/poll]

[poll name="poll_3" type=multiple min=2 max=3]
- option one
- option two
- option three
- option four
[/poll]

[poll name="dave" type=number min=2 max=10 step=2]
[/poll]

Manually creating a poll

While the poll builder is the easiest option, it is also possible to manually create and edit polls within the composer itself.

To create a simple poll, surround a markdown list with [poll] and [/poll]:

[poll]
* option one
* option two
* option three
[/poll]

Any markdown list will work, including using hyphens - or numbers instead of asterisks *.

This will create the following result:

1. option one
2. option two
3. option three

To manually create more complex polls, additional parameters can be added to the poll tag. For instance:

[poll type=multiple results=on_vote min=1 max=2 public=true chartType=pie groups=trust_level_1 close=3024-12-31T00:00:00.000Z]
# Do you like polls?
* Yes
* No
* Maybe
[/poll]

Do you like polls?

• Yes
• No
• Maybe

(Though not all options will make sense for all polls )

Using the poll builder is a great way to find out the format of these additional parameters for later use.

FAQs

Can anyone vote in a poll?

Even with no group voting restrictions on the poll itself, users must be able to reply to the topic where the poll is created in order to participate. Users with see only permissions will not be able to vote.

Can polls be edited?

All votes are cleared when a poll is edited, to ensure the poll creator can’t change the choices a user voted for. As such, by default polls can only be edited for a grace period of 5 minutes after being created.

Votes cannot be recovered once a poll is edited and the votes are cleared

Can I export poll data for further analysis?

Staff can use the Discourse Data Explorer to export poll data as a csv, which can be imported into the data analysis program of their choice.

Last edited by @hugh 2024-07-29T10:05:00Z

Last checked by @hugh 2024-07-02T09:50:57Z

Check document

Perform check on document:

[Torchbearer]

This might seem a novice question, but I do have a query.

Suppose, once I created a poll, in which I set the results to be visible as soon as the votes are cast. I then realize my mistake that I had to set visibility of the results, after the voting is closed. So, is there a way to edit the current poll, so that the visibility of that poll is changed from, “Always visible” to " When the poll is closed" from the options, which are accessed from the gear icon available in the build poll settings.

Or, Do I have to delete this poll and then start a new one and choose the setting, for votes’ visibility “when the poll is closed” ?

I am attaching the screenshot too.

Kindly advice.

if this post is not meant for this topic, I request the moderators/administrators , to kindly move it to the appropriate section.

[Moin]

You can change that without deleting the poll. When you edit the post, your poll starts with something like [poll type=regular results=on_vote public=true chartType=bar]; you can edit the “results” parameter to results=on_close.
Though if I remember correctly, when you edit the poll, all votes are deleted, but at least you don’t have to recreate it.

[nathank (Nathan Kershaw)]

@Moin

Though if I remember correctly, when you edit the poll, all votes are deleted, but at least you don’t have to recreate it.

This is indeed the case.

It would make more sense to me if there was an option to reset the poll, rather than it being ‘forced’ - especially for a minor tweaks like this.

I’ve hacked the database for these type of changes in the past (to avoid an edit triggering a reset), but that is a bit fragile.

[Torchbearer]

That helps a lot.

What do both of you would infer if I tell you that when the admin who created the poll, edited the topic, that is used for the poll, the topic edits go down, instead of going up?

My inference is this, that the poll was deleted and then a fresh poll was started. That will explain the topic edits going down, to a user who his casting their vote.

Example :
The user first came to the poll, which had the votes setting set to, always visible. The topic edits to that poll were 4.

On being pointed out to the admin that the votes setting were set to always visible, the user then sees the poll with the votes setting set to, visible after voting. However, the topic edits went to 3. So, the topic edits, instead of going up, go down.

My thinking is this, that the admin deleted the previous poll and then started a new one.

[meave]

Would it be possible to have this documentation updated to include
ranked choice polls ? Specifically, how and when the rounds are incremented…
TIA folks !

[merefield (Robert)]

Fair point @meave

Author of Ranked Choice polls here, that is a dropped ball.

I do not have edit rights to the OP. Very happy for someone to copy this and format as they see fit, or if converted to a Wiki, happy to contribute:

Currently works exactly as described here, it’s classic Instant Run-off Voting:

https://courses.lumenlearning.com/waymakermath4libarts/chapter/instant-runoff-voting/

(my fork of the poll plugin actually contains that example as a unit test!)

Process is as follows:

Every voter submits an ordered list of candidates. In each round we only consider the 1st placed candidate (and focus on potential winners and the worst losers).

1. Count the first place votes for each candidate
2. Find the candidate(s) with the most votes
3. Check for a clear, single, majority and return if found as winner (no more rounds, stop)

If not:

4. Find the candidate(s) with the least votes
5. Remove the candidate(s) with the least votes from all votes

If votes are now all empty

6. Report the tie of those candidates that were just removed (no more rounds, stop)

Else

7. Shift up all votes so that where 1st place was taken up by a loser (for a specific voter), the 2nd place candidate becomes their 1st choice.

And the rounds continue until a majority or a tie is found.

[meave]

Thanks @merefield !
That’s just what i needed !