CS Dev Guide: Polls : CSharp Feeds

CS Dev Guide: Polls

by Keyvan Nayyeri via Keyvan Nayyeri on 11/17/2006 5:57:52 AM

Poll is a very nice feature in Community Server and I love it. Having a powerful voting system in forums (which is available through APIs to other applications) is very helpful.

Working with polls via APIs can be a real world scenario because some people ask for poll functionality in blogs on Community Server forums. Actually I haven't implemented a voting system for blog with Community Server APIs to be aware of any possible error or issue for working with them but provided methods and properties should work for all applications. Although appropriate user interface isn't provided for all applications to let you create your polls and this is left to you. I hope I can find time to work on creating a custom control to add polls to blogs as a useful feature and good practice on these APIs but if you're interested to write someone for Community Server this is a good point.

Before start talking in details it's better to give a short introduction about some words that I frequently use in this post:

In Community Server each post may have no or one poll. Each poll may have one or more answers. Each user can send a vote. A vote assigns a user to an answer. Later you can use these information to present a summary of polls to end users.

As you probably know, Post class has three properties to let you define the title, description and expiration date for a poll (PollTitle, PollDescription, PollExpirationDate) as well as a Boolean HasPoll property to specify if a post has a poll. Using these properties you can define a poll but what about poll items and answers?

Four classes in CommunityServer.Components namespace help you to work with poll items and their summary:

PollItem: Represents an answer to a poll.
PollVote: Represents a vote which is actually a relationship between a user and an answer.
PollSummary: Represents a summary of your poll, its answers, its votes and ... by providing appropriate properties and methods.
PollVoteSet: Keeps a list of user votes (a list of PollVote) objects.

Let me talk about each of above classes in some details:

PollItem

Each PollItem is an answer to a poll. It has some properties as follows:

AnswerID: It's an identifier for PollItem object.
Answer: A string property to specify answer's text.
OrderNumber: Integer property that lets you to set the order of answer in other answers.
Total: Integer property which helps you to get or set the total number of votes to answer.

You can create an instance of PollItem by passing required properties to its constructor as well.

PollVote

It's a user's vote to a poll. It assigns an answer to a user. It has some ReadOnly properties to let you access to some common information easier. You can create an instance of PollVote object by passing a PollSummary object as well as UserID and AnswerID to its constructor. PollSummary will be described in next section.

PollSummary

This class is very helpful because lets you to have all information about your poll in one place. You pass a Post object to its constructor and get a summary of available poll for that post and its answers and votes. Like PollVote, all of its properties are ReadOnly.

There are two important properties for this object: Answers is an ArrayList of PollItem objects which contains all answers to poll and Voters is a HashTable of voters (users and their votes).

In addition to these properties, PollSummary provides some methods which are actually some handy shortcuts to help you retrieve some common information about poll:

GetPollItemByAnswerID: You can pass the string value of answer ID to this method to get an instance of PollItem for that answer.
GetUserVote: Gets a UserID and returns a PollItem object for that user's vote.
GetUserVotes: Gets two integer values as page size and page index and returns a PollVoteSet object which contains a list of votes to poll. PollVoteSet will be described in next section.
HasVoted: Gets a UserID and returns a Boolean value to check if user has voted or not.

PollVoteSet

This object is very simple. It keeps a list of PollVote objects for a poll. Its PollVotes property returns an ArrayList of PollVote objects, its HasResults Boolean property checks for any available PollVote in list and its TotalRecords integer property returns the number of PollVote objects in the list.

Dealing with Votes

So far we've talked about objects in theory but how we can add a vote to a poll? Answer is simple and doesn't need much information about above theories!

CommunityServer.Polls namespace has two static methods which let you to get a PollSummary for a post and add a vote to a poll in a post:

GetPoll: Gets an instance of Post object and returns a PollSummary object for its poll.
Vote: Gets a PostID, UserID and AnswerID and creates a vote for that answer and user.

Below is an example. AddVote() method gets a string value of an answer which user has chosen and creates a vote for that user and its chosen answer.

void AddVote(String answerID)
{
    CSContext context = CSContext.Current;
 
    Polls.Vote(context.Post.PostID, context.User.UserID, answerID);
}

In following code, CheckForVote() Boolean function checks to make sure if current user (who is viewing the site) has voted to the poll of current post that is being viewed or not.

bool CheckForVote()
{
    CSContext context = CSContext.Current;
 
    PollSummary summary = Polls.GetPoll(context.Post);
 
    return summary.HasVoted(context.User.UserID);
}

Below ReturnUserAnswer() is a string function which checks to make sure if current user has voted then returns its answer text.

String ReturnUserAnswer()
{
    CSContext context = CSContext.Current;
 
    PollSummary summary = Polls.GetPoll(context.Post);
 
    if (summary.HasVoted(context.User.UserID))
    {
        PollItem item = summary.GetUserVote(context.User.UserID);
        return item.Answer;
    }
    return null;
}

And as the last example: GetFirstVoterName in following code returns the DisplayName of first user who has voted to poll of current post.

String GetFirstVoterName()
{
    CSContext context = CSContext.Current;
 
    PollSummary summary = Polls.GetPoll(context.Post);
 
    PollVoteSet votes = summary.GetUserVotes(0, 5);
    if (votes.HasResults)
    {
        PollVote vote = votes.PollVotes[0] as PollVote;
        return vote.UserDisplayName;
    }
    return null;
}