Automated Poll Rotation using the Web Services API

You may want to see the helpful visualization chart in the next page before proceeding.

1. The Poll Designer creates a variation on the EmbeddedPoll template which adds a history parameter, as described below. This parameter includes the name of a Cookie that will track activity in all polls used with this API. The EmbeddedResults template can be used as is.

2. The Editor creates a place for the first dynamically created page. In the Settings page, select the templates created in Step 1 and in "Choose how to schedule polls and surveys", select "Only one at a time". The Editor also creates a test poll and schedules it so that it is open for a brief testing interval. In the Security page, set up options as you would normally, except that the settings for Cookies will be ignored. Suggestion: start with all Security settings turned off. See Additional Security Information below.

3. The Administrator modifies the script or program used to generate the dynamically created page to invoke ViewsFlash, as described below. It will refer, by name, to the place created in step 2 and to the Cookie named in step 1. At this point, bringing up the dynamically created page should display the page with the embedded poll; after voting, the page should refresh with the results display instead.

4. After fine-tuning the Security settings, the Editor can create additional places, copying the settings of the first one. When creating polls, it is important to always use Ending Dates; if one is not provided, ViewsFlash will let visitors vote again after 24 hours, since visitors cannot vote in another poll in the same place until the current poll ends.

Similarly, the Administrator can reuse the script or program in additional dynamically created pages. If you're using unusual security settings, it may be useful to set the Security settings of the Default poll in the Default place to these settings so that they will be used by default.

Additional detail on the above steps follows.

Invoking ViewsFlash script
The content management system must be capable of making an HTTP call to the ViewsFlash web server, and must be capable of retrieving cookies and performing string comparisons. Its performance will be increased immensely if it is capable of caching the results of HTTP calls by a given amount.

First, using pseudo-code with a Java syntax, here's what the script must do. A script that performs these functions must be inserted (only once!) in the containing page where the ViewsFlash place goes.

// define the ViewsFlash web server:
String viewsflash="http://...yourcompany.com/ViewsFlash/servlet/viewsflash";
// define the name of this place; for example, Politics:
String pollingplace = "Politics";

// ask for the current time; cache for 1 minute, return very large number if not available
String timenow = httpget (viewsflash + "?cmd=gettime", 1, "9999999999999");
// get a cookie with record of visited places
String cookie = getcookie ("VFPOLLS");

// scan the cookie for the character | followed by the name
// of this place followed by a colon, and return what
// follows until the next |character.
// If there was no cookie, or if this place is not found, return "0"
String poll_ends = cookie.extract ("|" + pollingplace + ":")

// if previous poll in this polling location expired,
// or if visitor's never been to this place,
// insert the poll voting form HTML (cmd=getpoll),
// else insert the poll results HTML (cmd=getresults)
if ( timenow > poll_ends ) {
  // cache poll and results for 1 minute, return space if not available
  insert ( httpget (viewsflash + "?cmd=getpoll&spotname=" + pollingplace , 1, " ");
} else {
  // cache poll and results for 1 minute, return space if not available;
  // use 0 instead of 1 to return results in real time.
  // optional: if command line contains parameter x=y, force real-time display
  insert ( httpget (viewsflash + "?cmd=getresults&spotname=" + pollingplace , 1, " ");
}

In brief, this script examines a cookie to detect a prior vote, and then calls ViewsFlash using cmd=getpoll or cmd=getresults to display the voting form or the results form, as appropriate.

In detail, this script examines a cookie named VFPOLLS (you can use any name you prefer), and determines if the visitor has voted in the current poll on this page by comparing the date now, as represented by ViewsFlash, with the date in the cookie. The cookie has the form:

each "spotname" is the name of a place, and "000" is replaced with the date that the current poll in that location expires.

Checking the cookie is not mandatory, of course. This is just a way to present results to a visitor instead of the voting form. The script can also interrogate its query string to see if it should display the voting form or the results.

If you are using the apiport security feature, then all the above calls to ViewsFlash must be made on that port; if they are not, ViewsFlash will return an empty page. See Application Security.

History template parameter
When ViewsFlash receives a submitted vote, it updates this cookie with the expiration date of the current poll. To do this, it is necessary that the Poll Style Template which generate the voting forms include the following hidden field:

The meaning of the hidden history field is as follows. The 1 specifies the cookie scanning methodology described here. VFPOLLS is the name of the cookie to examine and toss back. [/spotname] is a ViewsFlash template substitution tag which is replaced, when the poll voting form HTML is created, by the name of the place in which the Poll is hosted.

The final parameter, when present, means to redirect the visitor's browser after counting the vote. A * means to redirect to the URL of the referring page, i.e., the page where the voting form appeared. When the client browser receives this redirect, it will ask the web server for the page again. Because the cookie has been reset, however, this time the script described above will insert the poll results instead of the poll voting form, and the visitor will have the desired experience of seeing the vote results after submitting his vote. Instead of *, it is possible to use a standard URL, which is useful when you want to have voting results displayed in a unique page. If this field is omitted, then the standard action (specified in the html by the results hidden field) will be carried out, such as displaying a particular response page with or without current results.

It is also possible to code this field as "*?x=y", for example. This causes ?x=y to be appended to the referring URL. This mechanism can be used with systems such as ATG Dynamo, JSP and ASP to interrogate the URL and display results instead of a voting form, for example. If the URL already contains other parameters, such as ?x=z&p=3, the substitution is "smart" and translates into ?x=y&p=3; in other words, other parameters are preserved and if there's already a parameter by the indicated name, it is replaced.

Note that the "history" hidden field should only be used when you are using a Web Services API as detailed here.

An alternative form of the history parameter is: 2,COOKIENAME,*
The COOKIENAME is an arbitrary cookie name; the [/spotname] must be removed; and the last parameter has the same functionality as the original form. When used like this, the cookie simply contains the id's of the polls the visitor has voted on, like this:
|pollone|polltwo|...| This cookie can be parsed easily, if desired.

Additional Security Information
The settings in the poll Security page are all available, except for Tossing a cookie, which is superseded by the History parameter. Duplicate IP detection is strongly recommended, as it is easy for visitors to just press Back and return to the Voting Form. User authentication may be used.

In the When a duplicate vote is received section, respond normally is best. If you choose to insert a message, then the results shown will be a whole page, without redirection. If you specify to display a page, it will be shown by redirection, so it must be an absolute URL.

Incomplete entries may or may not work in a reasonable fashion. In these applications, it is typical to ask very few questions and to choose tally whatever is available. Other options may produce confusing behavior.

Error checking
The API commands log errors to the ViewsFlash administrative log. In addition, they may return HTML like this:
<viewsflash [/NG] error message >
This message is invisible in a browser, so that if an unexpected error condition occurs, the visitor's experience is not disturbed. When the same command is issued from a browser, the software appears to return a blank page. A view source will reveal the nature of the problem.

The code that issues getpoll and getresults should scan the answer for a string containing [/NG], and if such a string exists, it should report the error condition in an appropriate manner.

Next: Automated Poll Rotation Control Flow