DemoChoice: Ranked Choice Web Polls
Copyright (C) 2001 Dave Robinson
License information:
This program(*) is free software: you can redistribute it and/or modify
it under the terms of the GNU General Public License as published by
the Free Software Foundation, either version 3 of the License, or
(at your option) any later version.
This program is distributed in the hope that it will be useful,
but WITHOUT ANY WARRANTY; without even the implied warranty of
MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
GNU General Public License for more details.
You should have received a copy of the GNU General Public License
along with this program. If not, see .
(*) "This program" refers to software distributed with this document. The
original version was made available at:
http://www.demochoice.org
To clarify, the following are NOT covered by this license:
(1) The graphical logo appearing on the DemoChoice site, and any links or
scripts related to advertising (Google ads, for example). If any of these
were included with the program, this was unintentional. Links to logos or
other files not distributed with the program may appear in the program.
These should be considered bugs and should be deleted before they are used
to produce web content.
(2) Data files used by the program, and any web content generated by both
those data files and the program, with the exception of configuration, ballot,
and tally data files distributed with the program.
(3) Content on the DemoChoice website (http://www.demochoice.org) that
cannot be generated by the program alone.
(4) Files whose header comments indicate that they are not covered by the
license or intended for release.
(5) Any section of code between /* NOGPL */ and /* GPL */ comments, which were
intended to be deleted or modified before release.
(6) The directory buttons, if included, were not created by me and I
believe they are in the public domain.
Please do not attempt to make a mirror site (one that could be confused
with the main DemoChoice site, or with a poll hosted by someone else)
without appropriate permission. Please try to make your implementation
unique in some way.
If you will have an introductory page for your poll (similar to the
DemoChoice main page) and/or a help file (similar to info.php), please
include a copyright statement in both places, as is done on the DemoChoice
website. If you have neither, please display the copyright statement in a
place that is comparable or similarly accessible to the user. Including a
link to the DemoChoice website (assuming it still exists) along with the
copyright statement would be appreciated.
---
DemoChoice is written mostly in PHP, an open-source, cross-platform scripting
language (http://www.php.net), and uses no special software components (except
for the pie charts, which use the GD graphics library that is usually, but not
always, installed with PHP). You can run DemoChoice on any web server with PHP
- you can even install a web server like Apache on a laptop and run DemoChoice
during presentations or conventions.
For improved performance, the main counting engine is in C++. It's easy to
compile this (one file, one line) on most machines and a precompiled Windows
version is available.
Performance boundaries:
It is optimized so that it performs well for large-scale polls (more than
100,000 votes). Note that, for multi-winner elections, it allows for a
small amount of inaccuracy in surplus transfers in order to achieve this
scalability. Just do a full recount by calling the dccast script with no
form data if you want to see the exact results.
The scalability does not apply when voter registration is used, which is best
done with a few thousand voters or less.
The number of candidates is limited to 255, but this could be expanded without a
massive effort by changing from char to int in the appropriate parts of the C++
source file. Also, the javascript ballots become slow when the number of
candidates is huge. Beyond this, to protect itself against corrupt data files,
DemoChoice contains an arbitrary file line length limit that limits the number
of candidates to about 200 in a multi-winner election and 700 in a single-winner
election. Changing this limit or the numerical precision can increase this.
DemoChoice is an open-source software package released under the GNU
General Public License. I hope that this license arrangement will
encourage development of new features or of other ranked-choice voting
packages and generally results in widespread use of this election method
on the web.
Dave Robinson
Installation issues:
PLEASE TAKE THESE STEPS RIGHT AWAY:
The setup, edit, invite, feedback, keydist, and keynote scripts include an email
address at the beginning of the file that should be changed to an address
that you receive. The feedback script may also contain a link to graphic
image of an email address that should be modified or deleted.
The keydist and keynote scripts have a dummy password that should be changed.
The standard DemoChoice distribution is configured to run on a Windows computer with XAMPP and Cygwin installed (and in the system path).
The "dcdir" script needs the "ls" function provided by Cygwin.
For non-Windows computers, edit the "dcinctally" script so that $cfile has a prepended "./" as described in the comments there.
The server must have write permission on the "data" directory, although permissions should be set so this directory is not publicly visible on the internet.
You can check configuration settings by running a script.
DemoChoice has been tested on:
Windows 95 through 10 using XAMPP
Linux / Apache
FreeBSD / Apache
Mac OS X (built-in Apache)
using PHP 5.6 through 7.2.
On many Unix-based systems, including Mac OS X, permissions must be set
with the chmod command using the operating system's terminal program.
If your Apache server doesn't recognize index.php as a default page, use a
non-script default page, or modify the server configuration file in
/etc/httpd/httpd.conf. On OS X, only the root user can do this, so it is
necesary to enable the root user. See the OS X documentation for details.
The same is true for the PHP configuration file in
/usr/bin/php/lib/php.ini. The OS X "finder" program doesn't normally find
these files.
If you have successfully installed and tested DemoChoice on a different
system, please let me know.
If you customize the ballot and place a form before the ballot form, the
references to document.forms[0] in ballot scripts must be changed to
document.forms[n] where n is the number of forms preceding the ballot.
Options:
dcballot.php?terse=on&norot=on
The first parameter shows only the ballot and not the surrounding
instructions that normally appear. The second disables the periodic
shuffling of ballot order, so candidates appear in the order given in the
ballot file.
dccast.php?terse=on
The option disables the long-winded explanation of one's vote that
normally appears.
If you call dccast.php with no form data, it will do a full recount (see
the note about the tally file below if this is the first count).
For invitation-only polls, if you enter the password in the email field on
the ballot, you can submit a bulk number of votes. For other polls, the time
delay between votes can be set to zero in the config file or the password can be
sent in the URL using &who=[password].
dcresults.php?barmax=500&barht=10&charmax=50&cellpad=3&digits=2
These parameters allow the sizes of the bars in bar charts to be adjusted
(charmax adjusts the bar size in text-only browsers). Cellpad refers to the
spacing in the table form of the results. Digits is the number of digits after
the decimal point for numbers reported.
Making a customized poll:
For convenience, you can use the dcsetup.php form, but there are some
extra features available if you create or edit your poll manually.
Choose a poll name such as "DC" and create the following files:
DC_config.txt (described below)
DC_tally.txt (blank)
DC_ballots.txt (blank)
The tally file should contain "Ballots |1" if you are tallying a new
ballot file (containing at least one vote) by calling dccast.php with no
form data.
The config file contains a series of tags:
Who should win the poll?
The title appears at the top of the ballot.
<SEATS> 2
The number of seats to be elected. Default is 1.
<HARE>
use the Hare quota (votes/seats) instead of Droop (votes/[seats+1])
I think I removed support for this in the summer of 2005.
<NOEX>
Disables the exclusion of exhausted ballots from threshold calculation (for seats > 1)
<DELAY> n
For public polls, impose a delay of n seconds between votes from the same IP
address.
<UNRECYCLE>
DemoChoice usually recycles ballots to their highest-ranked winner
if they end up in the exhausted pile in multi-seat elections, but doesn't for
single-seat elections. This tag reverses that behavior.
<NODIVS>
Disable the list-sorting feature in touchscreen-style ballots
<INVITE> n
n = number of voters
Voters must enter an email address that is in the DC_registrants.txt file (one
address per line). Create a blank DC_voters.txt file too. Registrants can be
added during the course of a poll, but n should be updated too.
<USEKEYS>
This tag tells the invite script to look for a registration key rather
than an email address to use to authenticate voters.
<EXPIRE> n
n = number of seconds between midnight 31 December 1969 and the expiration date.
This only works for <INVITE> polls. Votes cast after the deadline do not count.
Voters can cast a hypothetical vote after the deadline to see who it would count
for.
<WITHHOLD>
This only works for <INVITE> polls. Results are withheld until the poll
expires.
<CANDIDATE> Fred
List the candidates using these tags, using a separate tag for each candidate.
Candidate names can contain HTML tags, so you can add pictures or links to
candidate platforms or websites. A tag in the form
<a target=_blank href=http://LincolnIn64.com>Abe Lincoln</a>
will create a pop-up that will not reset any existing rankings.
Candidates can be added during the course of the poll, but bad things will
happen if you delete candidates or change their order. To remove a candidate,
use:
<EXCLUDE> x,y,z
where x, y, and z are the numbers of the candidates to be excluded, starting
with zero, in the order that they appear in the config file.
Several config file tags allow for customization, allowing for adaptation
to your site or for multiple language support:
<HOMEFILE> myindex.php
sets the 'main page' links that appear in various places.
<INFOFILE> myhelp.php
sets the link to the help file. Some information is passed in the
querystring, such as the number of winners and type of ballot used. This
can be ignored if you want.
<CASTFILE> mycast.php
sets the form landing page after the ballot is submitted.
<CASTLINK> http://dcballot.php?poll=nextpoll&terse=on
Offers voters a link to another poll after casting a vote.
<RESULTFILE> myresults.php
sets the result page.
<BALLOTFILE> myballot.php
sets the ballot page (I don't think this is used anywhere though)
<BALLOTSTO> MyPoll
Given the label of another poll, all ballots will be written to that poll.
This allows the results of polls for different languages, precincts, etc.
to be combined: you would create polls called MyPoll, MyPollSpanish,
MyPollChinese, etc; the latter two would include the above tag as well as
BALLOTFILE, CASTFILE, INFOFILE and RESULTFILE tags pointing to files in
those languages. It is hoped that files using different languages will
eventually appear in this distribution.
<INVISIBLE>
This tag is used on the DemoChoice site to prevent polls from being shown
in the directory.
<EDITPW>
This tag contains a password and email address that can be used to access
the poll editor script.