Programmer's Guide:
Using Polls and Poll Pages

In the eRoom user interface, a poll is an eRoom page for taking a vote. Polls help teams reach closure by moving them away from open-ended discussion and closer to making decisions. In the user interface, as well as with SAAPI, you can create a poll, edit a poll, and vote in poll. Polls can be embedded in another Item, like a discussion topic.

Poll Pages and Polls are similar SAAPI objects. A Poll object is an item that appears in the context of a topic, while a Poll Page is a principal item that appears as its own page in the eRoom user interface. Because these two objects share so much functionality, the features they have in common are consolidated into a single interface, IERUPoll, which is implemented by both objects. A Poll Page object also implements the IERUPollPage interface, which allows you to manipulate some of the page display options associated with a Poll Page, such as whether or not to show a topic or an attachment box.

The Poll object functions as a container of Poll Entry objects. Each Poll Entry corresponds to a single question, its set of predefined answers on which users can vote, and the set of ballots that have been cast.

Poll Questions and Choices

Once you have an IERUItem interface for a Poll Entry or a Poll Page, you can then access the polling information for that item by getting the IERUPoll interface. For example, you can use the Poll interface accessor property defined in IERUItem. If the item is not actually a Poll or Poll Page object, then the Poll interface accessor property returns the error E_NOTIMPL. Through the IERUPollEntry interface, you can create and modify the polling information in any way you choose. However, after the first person has voted in the poll, you can no longer modify the question and the choices.

The Question property returns an IERURichText interface. This interface is used to retrieve or modify the poll entry question. The IERURichText interface allows you to get or set values in either plain text or HTML. The following example shows how to create a Poll Page and set up the polling information for that page.

Dim SMgr as IERUSvrManager
Dim Room as IERURoom
Dim PollPage as IERUPollPage
Dim PollEntry as IERUPollEntry
Dim Choices as Array(1)
Dim Var as Variant
Choices(0) = "Yes"
Choices(1) = "No"

' assume that the SMgr and Room variables have been initialized.

'Create a Poll Page in the Home Page of the Room.
' Here I create a Poll Page named "Weather." The first and only question for the poll
' is "Will it rain?", which is in plain text format. The fourth parameter
' lists all of the poll choices separated by a new line character. There
' must be at least two choices. The last parameter contains the create
' options. I have specified that the vote totals should be displayed.
Set PollPage = Room.HomePage.Container.CreatePollPage("Weather", _
"Will it rain?", erFormatPlainText, Choices, erCreateOptShowVotes)

'Here I modify the vote choices, so that I can add the option, "I don't know."
Set PollEntry = PollPage.poll.PollEntries(1)
Var = PollEntry.Choices
ReDim Preserve Var(UBound(Var) + 1)
Var(UBound(Var) - 1) = "I don't know"
PollEntry.Choices = Var

Setting Options for Polls

There are three options that describe how the poll operates and how it is displayed. Each option has an ERUCreateOption flag defined for it that can be passed to CreatePollPage, CreatePollEntry, or CreatePoll as the last parameter. If you want to specify more than one option, then list all of the desired options in the last parameter, separated by the OR symbol (|). Alternatively, you can modify any of these options by setting the appropriate property on the IERUPoll interface. Like the poll questions and choices, these options can't be changed after the first person has voted in the poll or poll entry.

The previous example used the option erCreateOptShowVotes. This option specifies that as each person votes, that user's name will be listed beneath the poll along with his vote. Prior to version 5.0, this option could be turned on or off by setting the ShowVotes property on IERUPoll to TRUE or FALSE. Starting with version 5.0, ShowVotes is superseded by two new properties: ShowVoteTotalsTo and ShowVotesCastTo. These new properties provide more control than the all-or-nothing scenario you got with ShowVotes. You can use these properties to display votes cast and vote totals to everybody, only those who have voted, or only the poll's creator and the room's coordinators.

The second option is specified by the erCreateOptAllowMultipleVotes flag. If you set this option, users can vote for more than one choice. This option is turned on or off by setting the AllowMultipleVotes property on IERUPollEntry.

The last option is specified by the erCreateOptAllowWriteIn flag. If you set this option, users can ignore the predefined choices and write in their own votes. This option is turned on or off by setting the AllowWriteIn property on IERUPollEntry.

The following example shows how to modify these options through the IERUPoll and IERUPollEntry interfaces. If someone had already voted, then setting the property raises an error. This example builds on the previous example.

'I change the Poll options regarding the display of voting results.
PollPage.poll.ShowVotesCastTo = erShowVotesCastToVoters PollPage.poll.ShowVoteTotalsTo = erShowVoteTotalsToVoters

'I change the Poll Entry options to allow write-in votes.
Set PollEntry = PollPage.poll.PollEntries(1)
PollEntry.AllowWriteIn = TRUE

Adding and Deleting Votes

Votes are created by calling CreateVote through the IERUPollEntry interface, and are deleted by calling Delete through the IERUVote interface. You can change users' votes through the API, just as users can change their votes through the eRoom user interface. The example running through this section does not allow multiple votes, so in order to change a user's vote, you must delete the old vote and then add a new one. When you create a vote, just as when you create any item, the vote is assigned to your current user context for the logged-in user.

The following example shows how to create and then change a vote.

Dim Vote as IERUVote
' I have created a vote by choosing the first choice in the "Will it rain?" poll.
Set PollEntry = PollPage.Poll.PollEntries(1)
Set Vote = PollEntry.CreateVote(1, "")
' I decide that I want to change my vote to a write-in, but first I must delete
' my first vote, since I cannot have multiple votes in this poll.
Vote.Delete
' Now I may add my write-in vote. I pass in 0 as the index of my choice, which
' means that I am not picking any of the choices.
Set Vote = PollEntry.CreateVote(0, "It may snow.")

Working with Ballots and Votes

Ballot objects represent all of the votes a single user has cast in a Poll Entry. Ballot objects are useful when you want to tally the votes in the poll or when you want to change a particular user's votes. A Poll Entry object returns a collection of all of its Ballots through the Ballots property in IERUPollEntry. The IERUBallot interface has a single property, called Votes, which returns a collection of all of the Vote objects for a particular voter. The Ballot object implements the IERUItem interface, so you can determine which voter belongs to the Ballot object by calling the Creator property of the IERUItem interface for the Ballot. In fact, the Ballots property on the Poll object returns a collection of IERUItem interfaces rather than IERUBallot interfaces, so you will have access to the IERUItem properties and methods for the Ballot objects.

The following example shows how to build a report that lists who voted in a Poll Page and how each user voted.

Dim BallotItem as IERUItem
Dim BallotList as IERUCollection
Dim VoteList as IERUCollection
Dim Vote as IERUVote
Dim Name as String
Dim WriteInVote as String
Dim IndexVote as Integer

Set BallotList = PollEntry.Ballots
For each BallotItem in BallotList
Name = BallotItem.Creator
' Write code here that logs the voter's name somewhere.
Set VoteList = BallotItem.Ballot.Votes
For each Vote in VoteList
  If (Vote.IsWriteIn) Then
Set WriteInVote = Vote.WriteIn
' Write code here that logs the write-in that the voter made.
  Else
Set IndexVote = Vote.Choice
' Write code here that logs the choice the voter made.
  End If
Next
Next