Poll (v1.0)

Lets you create polls that users vote on (privately), and publicly displays the results (vote counts) afterwards.

It is worth noting that this plugin will not keep polls over reloads. Unloading the plugin notifies poll creators that their polls will disappear.

This plugin is most likely easiest understood by following an example.

	Example usage

Say we want to run a poll in the channel #deaded to find out if the Poll plugin is useful.

To do this, we start by picking an ID for the poll.
This ID is a sequence of any characters, not including space. It should be short, as it will be used to identify the poll both when managing it and for voting in it. Examples of valid IDs are 4, foo, 5bar, foo8bar.
Just to pick something, say we choose the ID "useful".

Then we create the poll, with the chosen ID and the question we want to ask. (To do this we must be authorized with the bot, to trusted level (unless configured otherwise).) Creating a new poll is done by sending a message privately to the bot:

!NewPoll useful Is the Poll plugin at all useful?

Next, we add a few answers to choose from; still sending privately:

!AddAnswer useful Yes
!AddAnswer useful Maybe?
!AddAnswer useful No.

Up until this point, if we change our minds and don't want to run the poll anyway, we can have the bot forget about the whole thing by using the !ForgetPoll command. We don't want to do this however, on the contrary we are now ready to start the poll. This is done with another private message:

!StartPoll useful #deaded

Notice how we here say which channel we want the poll to run in. A poll can only be started in a channel that both the bot and the user starting the poll is actually in at the time it is started.

When a poll is started like this, the bot tells the channel about it by posting the question and answers, and a message about how to vote. If we later want this information repeated, we can use the !ReDispPoll command.

Votes are cast by the voters sending their choices privately to the bot:

!Vote useful 2

Where 2 is the number of the answer the user wants to vote for. If someone changes their mind, they can simply vote again, and their vote will be changed to the last answer number they gave.

As long as a poll is running, its creator can ask for how many votes have been cast in the poll so far. This is done with the !PollVotes command.

When we are ready for the poll to end, say we have gotten as many votes as we want, or it has run as long as we want, we end it. This is, as usual, done with another private message:

!EndPoll useful

When a poll is ended like this, the results of the poll will be sent to the channel (assuming the bot is there at the time), and privately to the creator of the poll. The poll is also automatically removed and can no longer be voted on.

The configuration file for this plugin is system/Poll/PollConfig.xml

	commandNewPoll

The command for creating a new poll.
You can set the authLevel to control who is allowed to access the command.
The authLevel set here also controls access to several of the other commands.

• authLevel - ANY, ADMIN, MASTER, TRUSTED, NONE

        <commandNewPoll authLevel="trusted">!NewPoll</commandNewPoll>

      

	commandAddPollAnswer

The command for adding a possible answer to a poll (before it is started).

        <commandAddPollAnswer>!AddAnswer</commandAddPollAnswer>

      

	commandForgetPoll

The command for forgetting about a poll before it is started.

        <commandForgetPoll>!ForgetPoll</commandForgetPoll>

      

	commandStartPoll

The command for starting a poll that is ready to be run.

        <commandStartPoll>!StartPoll</commandStartPoll>

      

	commandDoVote

The command for giving a vote on this poll.
You can set the authLevel to control who is allowed to access the command.

• authLevel - ANY, ADMIN, MASTER, TRUSTED, NONE

        <commandDoVote authLevel="none">!Vote</commandDoVote>

      

	commandPollVotes

The command for showing how many votes has been cast in a poll so far.

        <commandPollVotes>!PollVotes</commandPollVotes>

      

	commandEndPoll

The command for ending a poll that is running.
You can set the authLevel to control who is allowed to access the command even for those polls that that user did not start.

• authLevel - ANY, ADMIN, MASTER, TRUSTED, NONE

        <commandEndPoll authLevel="master">!EndPoll</commandEndPoll>

      

	commandReDispPoll

The command for displaying a running poll again.

        <commandReDispPoll>!ReDispPoll</commandReDispPoll>

      

	commandListPolls

The command for showing a list of existing polls.
You can set the authLevel to control who is allowed to access the command.

• authLevel - ANY, ADMIN, MASTER, TRUSTED, NONE

        <commandListPolls authLevel="master">!ListPolls</commandListPolls>

      

	!NewPoll

Command: !NewPoll
Description: This will create a new poll with a given ID and question.
Auth Level: trusted
Where to give command: pm
Outputs to: pm
Example(s):

• !NewPoll useful Is the Poll plugin at all useful?

	!AddAnswer

Command: !AddAnswer
Description: This will add an answer to a poll that hasn't been started yet. Can only be done by the creator of the poll.
Auth Level: same as !NewPoll
Where to give command: pm
Outputs to: pm
Example(s):

• !AddAnswer useful Yes
• !AddAnswer useful Maybe?
• !AddAnswer useful No.

	!ForgetPoll

Command: !ForgetPoll
Description: This will remove a poll that has been created but not started. Can only be done by the creator of the poll.
Auth Level: same as !NewPoll
Where to give command: pm
Outputs to: pm
Example(s):

• !ForgetPoll useful

	!StartPoll

Command: !StartPoll
Description: This will start the given poll, in the given channel.
Starting a poll means closing it so no more answers can be added, it can no longer just be forgotten about, and the question and alternatives are shown in the channel along with a message about how to vote in the poll.
Can only be done by the creator of the poll, and only with a channel both the bot and the poll creator is in.
Auth Level: same as !NewPoll
Where to give command: pm
Outputs to: pm
Example(s):

• !StartPoll useful #deaded

	!Vote

Command: !Vote
Description: Cast a vote in the given poll for the given answer ID. If you vote several times, the last given vote will count.
Auth Level: none
Where to give command: pm
Outputs to: pm
Example(s):

• !Vote useful 2

	!PollVotes

Command: !PollVotes
Description: Find out how many votes have been cast in a given poll. Can only be done by the creator of the poll.
Auth Level: same as !NewPoll
Where to give command: pm
Outputs to: pm
Example(s):

• !PollVotes useful

	!EndPoll

Command: !EndPoll
Description: This will end the given poll, displaying the results. Can only be done by the creator of the poll, or by a user that has authed to the given level.
Auth Level: master to end any poll, same as !NewPoll for polls you have created
Where to give command: pm
Outputs to: pm
Example(s):

• !EndPoll useful

	!ReDispPoll

Command: !ReDispPoll
Description: This will redisplay the given poll in its channel. Can only be done by the creator of the poll.
Auth Level: same as !NewPoll
Where to give command: pm
Outputs to: pm
Example(s):

• !ReDispPoll useful

	!ListPolls

Command: !ListPolls
Description: This will show a list of known polls.
Auth Level: master
Where to give command: pm
Outputs to: pm
Example(s):

• !ListPolls

v1.0	First Version by EdorFaus