• View
• Edit
• History
• Print
• Backlinks

FoxVoteCSV

Questions answered by this recipe

How to make forms for voting and polling and accumulate the voting results, ready for display in various ways (not covered in this recipe, see links).

Description

gather voting results via a Fox form using radio and checkboxes mainly and adding the vote choices to a csv table on a wiki page section, as well as PTVs of the sums of each of the vote choices.

Installation

Download foxvotecsv.phpΔ, copy to cookbook folder and include in config.php.

Configuration

The script is an add-on to Fox, so Fox needs to be installed and enabled for posting vote submission to a target page. The script is called as a foxfilter in a Fox form. That causes it to process input data before Fox processes it for addition to a target page. The form needs to be set up carefully, read below.

You can use variable $FoxVoteConfig in config.php to enable a few settings:

• $FoxVoteConfig['IP_log'] = true; //enables IP address logging to vote records.
• $FoxVoteConfig['IP_block'] = true; //enables blocking of repeated voting by IP.
• $FoxVoteConfig['date_log'] = true; //enables date/time logging to vote records.
• $FoxVoteConfig['date_fmt'] = 'd/m/Y H:i:s'; //change the default date format used by the date logging.

Fox vote form setup

A Fox form needs to be set up with some additional specific requirements:

• foxfilter=foxvotecsv needs to be added as parameter.
• A foxptv markup directive is needed for posting and updating PTVs to hold numeric sums of the vote results. For example:

(:foxptv target=Site.FoxVoteResults#votesums :)

• A hidden input named vote-options with a string of all the voting choice options, comma-seperated, like this example:

(:input hidden vote-options "a1,a2,a3,b1,b2,b3,b4,b5,c1,c2,c3,comment" :)

• A hidden input named vote-inputs with a string of all the IDs of the inputs used for the voting, comma-separated. Example:

(:input hidden vote-inputs "a,b,c" :)

• The form input controls to be used for the voting need to be named with prefix vote- or vote_.
• The naming need to correspond with the values given in vote-inputs and vote-options.
  For this example (see box below) we have controls named vote-a, vote-b, vote-c and vote-comment. vote-a and vote-b are radio controls, vote-c is a checkbox control, and vote-comment a text input control. You can see this corresponds to the string in vote-inputs, but without the comment text input, because that delivers only one output, text. Radio and checkbox controls deliver the values set in them, and in the example these values are just numbers, and correspond to the numbers of the vote-options string provided: Three options for radio vote-a, five for radio vote-b and three for checkbox vote-c, plus the one for vote-comment.

Here is the form as an example:

(:foxmessages:)
(:fox voteform foxfilter=foxvotecsv target=Site.FoxVoteResults#votes :)
(:foxptv target=Site.FoxVoteResults#votesums :)
(:input hidden vote-options "a1,a2,a3,b1,b2,b3,b4,b5,c1,c2,c3,comment" :)
(:input hidden vote-inputs "a,b,c" :)
!!!Question A: ........... - Yes/No/Undecided
(:input radio vote-a 3:) Yes
(:input radio vote-a 2:) No
(:input radio vote-a 1:) Undecided
!!!Question B: ........... - A wider scale of choices
(:input radio vote-b 5:) very good
(:input radio vote-b 4:) good
(:input radio vote-b 3:) okay
(:input radio vote-b 2:) not so good
(:input radio vote-b 1:) bad 
!!!Question C: ......... - Choose any you like
(:input checkbox vote-c[] 1:) A apples
(:input checkbox vote-c[] 2:) B bananas
(:input checkbox vote-c[] 3:) C cherries
!!!Any comment you like to make?
(:input text vote-comment size="60" :) 
(:input submit post "Vote":)
(:foxend voteform:)

If you like, add parameters foxsuccess="<posted successfully message>" and foxfailure="<failed to post message>" to the (:fox voteform .... :) markup. Note that a template string or location is not set (it could be), as the script adds it automatically constructed from the vote-options string set.

Of course the form can be shaped and added in many ways. For instance it may be better to post comments to a different page, or a different location on the results target page. You could add to the form a line like this:
(:foxadd target=Site.FoxVoteComments#comments foxtemplate="{$$vote-comment}\n----" :)
In this case you would remove comment from the vote-options string. But by keeping the text input control named as in the example above, the script will check if no text entry was made, and will prevent posting to that particular target, but still posting the voting choices made with the radio inputs and chechboxes.

Setup for results page

The target page for the voting results, for the data submitted, should have a section. In the example it is called #votes, FoxVoteResults#votes, referring to an anchored section. Fox will add a line to this section each time a vote gets submitted. It needs to be set up with a header row as a csv table. The separator used is a semi-colon ';'. The header names or IDs could be any words, without spaces. I kept it minimally simple by just using the same IDs as set up in the form under vote-options, or it could be more verbose.

The script reads the data csv table when a vote gets submitted. It uses it to determine how many columns there are, and calculates the sums for each column, to calculate values for posting as PTVs. The posting and updating of these SUM PTVs is automatic, but it will help to set these up in an orderly way, and in its own anchored page section. In the example above I used the anchored section #votesums (target Site.FoxVoteResults#votesums). The example data sections may look like, after 10 votes:

[[#votesums]]
(:VOTES: 10:) Total of votes submitted
(:TOTL_a: 10:) Total of votes for control vote-a
(:SUM_a1: 2:) sum of votes for control vote-a value 1 (Undecided vote)
(:SUM_a2: 2:) sum of votes for control vote-a value 2 (No vote)
(:SUM_a3: 6:) sum of votes for control vote-a value 3 (Yes vote)
(:TOTL_b: 10:) ditto for control vote-b
(:SUM_b1: 2:) etc
(:SUM_b2: 1:)
(:SUM_b3: 1:)
(:SUM_b4: 3:)
(:SUM_b5: 3:)
(:TOTL_c: 13:)
(:SUM_c1: 5:)
(:SUM_c2: 3:)
(:SUM_c3: 5:)

(:if false:)
[[#votes]]
a1;a2;a3;b1;b2;b3;b4;b5;c1;c2;c3;
0;0;1;0;0;0;0;1;1;1;1;
0;0;1;0;0;0;0;1;1;0;0;
0;0;1;1;0;0;0;0;0;0;0;
0;0;1;0;0;0;0;1;0;0;0;
0;1;0;0;1;0;0;0;0;0;1;
0;0;1;0;0;0;1;0;1;0;1;
1;0;0;1;0;0;0;0;1;0;1;
0;0;1;0;0;0;1;0;1;0;1;
0;1;0;0;0;1;0;0;0;1;0;
1;0;0;0;0;0;1;0;0;1;0;

I recommend (till I get this automated) to set up the PTVs with 0's as values for a start, just to have them in a nice order. Theses are hidden PTVs, so they can be all in the same row if wanted. As PageTextVariables they can then be accessed and displayed in many ways and on different pages. More on this later.

The vote results csv table consists just of 1's and 0's, a 1 for each choice made. It coud be displayed, if needed, likely just by an admin, with a tool like FoxCSV. But really it is just a record of all the individual vote choices, for statistical analysis, to get the sums of choices, and perhaps spot abuse.

Usage

Mainly aimed at use for community polling, never for serious political voting, or voting in the thousands of submissions.

...to be continued...

Notes

To do / some day / maybe

If you have future plans or wishes for this recipe.

Change log / Release notes

If the recipe has multiple releases, then release notes can be placed here. Note that it's often easier for people to work with "release dates" instead of "version numbers".

See also

Contributors

Comments

See discussion at FoxVoteCSV-Talk