Surveys (Polls)
A poll allows you to ask a question to a channel. Channel participants can choose from the answers you specify, and the results can be viewed by everyone in the channel, or optionally only yourself. You can allow voters to select only one answer, or allow them to select multiple answers.
Here is a sample of what a complete poll implementation can look like:
Create Poll
The following example creates a "myPoll" poll to ask about everyone's favorite color.
var myChannel = ...;
// create a poll
var myPoll = new Max.Poll({
name: 'Favorite Color',
question: 'What is your favorite color?',
options: [
new Max.PollOption('Red'),
new Max.PollOption('Blue'),
new Max.PollOption('Green')
],
allowMultiChoice: true,
hideResultsFromOthers: false
});
// publish the poll to a channel
myPoll.publish(myChannel).success(function(mmxMessage) {
// do something with poll object (myPoll)
}).error(function(err) {
// handle error on failure
});
Listen for Incoming Poll Identifiers
Participants of the channel can listen for incoming poll identifiers, which contain a pollId we can use to get the poll object from the server.
var listener = new Max.EventListener('myListener', function(myMessage) {
if (myMessage.contentType && myMessage.contentType.indexOf(Max.MessageType.POLL_IDENTIFIER) != -1) {
// the incoming message contains a poll identifier
var pollIdentifier = myMessage.payload;
var pollId = pollIdentifier.pollId;
}
});
Max.registerListener(listener);
Get poll object from server using a pollId (poll identifier).
var pollId = ...;
Max.Poll.get(pollId).success(function(myPoll) {
// do something with poll object
}).error(function(err) {
// handle error on failure
});
A poll object contains all the information needed to display a poll in your user interface.
var name = myPoll.name; // A user-friendly name of the poll.
var question = myPoll.question; // The question this poll should answer.
var options = myPoll.options; // A list of the available poll selection options.
var allowMultiChoice = myPoll.allowMultiChoice; // If enabled, users can select more than one option.
var hideResultsFromOthers = myPoll.hideResultsFromOthers; // If enabled, participants cannot obtain results from the poll, and will not receive {Max.PollAnswer} when a participant chooses a poll option. The poll creator can still obtain results using {Max.Poll.get} or poll.refreshResults.
var extras = myPoll.extras; // A user-defined object used to store arbitrary data will can accessed from a {Max.Poll} instance.
var startDate = myPoll.startDate; // The date this poll was created.
var endDate = myPoll.endDate; // The date this poll ends. After a poll ends, users can no longer select options.
Poll Options
Participants can choose from one or more options.
// create an array of the PollOptions chosen by the current user.
var option1 = myPoll.options[0];
var option2 = myPoll.options[2];
var selectedOptions = [option1, option2];
myPoll.choose(selectedOptions).success(function(mmxMessage) {
// options have been chosen
}).error(function(err) {
// handle error on failure
});
Listen for Incoming Poll Answers
Channel participants listening for the incoming PollAnswers can view them in the user interface.
var listener = new Max.EventListener('myListener', function(myMessage) {
if (myMessage.contentType && myMessage.contentType.indexOf(Max.MessageType.POLL_ANSWER) != -1) {
// the incoming message contains a PollAnswer
var pollAnswer = myMessage.payload;
var pollId = pollAnswer.pollId;
var pollName = pollAnswer.name; // poll name
var pollQuestion = pollAnswer.question; // poll question
var pollSelections = pollAnswer.currentSelection; // the currentSelection property is a list of PollOption chosen by the sender
var senderUserId = myMessage.sender.userId;
console.log(myMessage.sender.displayName + ' updated poll "' + pollName + '"" with ' + pollSelections[0].text);
}
});
Max.registerListener(listener);
If the current user has voted in the poll, the selected PollOption(s) can be obtained from the poll object.
var myPoll = ...;
var myChoices = myPoll.myVotes; // a list of PollOption selected by the current user
Obtain Poll Results
There are several ways to obtain poll results.
Get the latest poll object from the server using a pollId:
var pollId = ...;
Max.Poll.get(pollId).success(function(myPoll) {
// get the number of votes casts towards each option
var option1VoteCount = myPoll.options[0].count; // returns the number of votes for option 1
var option1VoteText = myPoll.options[0].text; // returns the value of option 1
var option2VoteCount = myPoll.options[1].count; // returns the number of votes for option 2
var option2VoteText = myPoll.options[1].text; // returns the value of option 2
...
}).error(function(err) {
// handle error on failure
});
Refresh existing poll object results:
var myPoll = ...;
myPoll.refreshResults().success(function(myUpdatedPoll) {
// the results for poll object 'myPoll' have been updated
var option1VoteCount = myPoll.options[0].count; // returns the number of votes for option 1
var option1VoteText = myPoll.options[0].text; // returns the value of option 1
...
}).error(function(err) {
// handle error on failure
});
Use a listener to update existing poll object results. This method saves a round-trip to the server, updating the poll results dynamically when a PollAnswer is received.
var myPoll = ...;
var listener = new Max.EventListener('myListener', function(myMessage) {
if (myMessage.contentType && myMessage.contentType.indexOf(Max.MessageType.POLL_ANSWER) != -1) {
// the incoming message contains a PollAnswer
var pollAnswer = myMessage.payload;
// update the poll with answers sent by the other participants
myPoll.updateResults(pollAnswer);
// get the options
var option1VoteCount = myPoll.options[0].count; // returns the number of votes for option 1
...
}
});
If hideResultsFromOthers was selected during poll creation, no poll answers will be sent out. Only the poll creator can obtain the results of the poll. In this case, the poll creator should check for results periodically using poll.refreshResults().
var myPoll = ...;
myPoll.refreshResults().success(function(myUpdatedPoll) {
// the results for poll object 'myPoll' have been updated
var option1Votes = myPoll.options[0].count; //
}).error(function(err) {
// handle error on failure
});
