#####################################
#                                   #
# RobPoll Version 1.1               #
# Copyright 1998 by Rob Eisler      #
# eislerr@tdi.uregina.ca            #
# http://tdi.uregina.ca/~eislerr    #
#                                   #
# Last modified on Sept 12, 1998    #
#                                   #
#####################################
#
# Copyright Notice:
# Copyright 1998 Robert S. Eisler.  All Rights Reserved.
#
# This code may be used and modified by anyone so long as this header and
# copyright information remains intact.  By using this code you agree to 
# indemnify Robert S. Eisler from any liability that might arise from its 
# use.  You must obtain written consent before selling or redistributing 
# this code.
#
#####################################
#
# The cookie functions used in this script are based on the HTTP
# Cookie Library 2.1 by Matt Wright. The copyright information for his
# library are at the end of this file. Check out Matt's Script Archive:
# http://www.worldwidemart.com/scripts
#
#####################################

----- If you are a web designer or hosting service, and you want to offer
      this or any other of these scripts as part of your paid service, you
      must obtain my written permission before doing so. This falls under
      the 'obtain written consent before selling or redistributing this
      code' mentioned above. Please check the FAQ, question 1 at
      http://rob.webking.com/cgi/faq.shtml or e-mail me for more
      information. 

Here's the deal.  There are a couple things I'd like for you to do if you're
using my scripts, although I have no way of holding you to them, and I
probably wouldn't try to if I did.

-- Please keep my name and copyright info included in this stuff.

-- Tell me you're using my script.  I like to see where my programs are
   being implemented on the web, and I'll add a link to your page on 
   mine.  You can just e-mail me, or fill out the form at 
   http://rob.webking.com/cgi/form.shtml

-- If it's at all possible, I'd appreciate a link to my page from yours.
   It's no big deal, though.  You can get a link from my page by filling
   out the form as mentioned in the last point.

-- If you make an improvement to the code, please let me know.  I won't
   include the code in my future distributions if you don't want me to,
   but I'll certainly give you full credit if you do allow your code to
   be included.

-- I'm starting up a mailing list to announce updates and new programs.
   You can add/remove yourself by sending me mail or by filling out that
   same form, or through the form at http://rob.webking.com/cgi/

-- Thanks --


Read this section. Please.

If you are having trouble getting this script to work, please do 3 things
before e-mailing me with questions: 
1. read through this file carefully.
2. Check the FAQs on my website.
3. post a message at http://cs.uregina.ca/~eisler/robboard/index.cgi

*Then* e-mail me (well, not right then, give people on the board time to
reply to you :). I don't mean you should spend hours trying to install 
this yourself before asking me for help - I don't mind answering questions, 
I just get a little frustrated when I've given the answer in
the readme or an FAQ :).  Also, I often get more mail than I can handle, so
you're much more likely to get a response on the board than from me directly.
If you're really stuck, send mail to eislerr@tdi.uregina.ca - 
and please include as much detail as you can.  I won't be able to help you if I 
don't know what's going on. Saying something like, "When I try to run the 
script, I get a 500 error. What's wrong?" tells me nothing.

--

This is version 1.1 of RobPoll.  It's compatible with 1.0.  If you are upgrading
from 1.0, just use the new .cgi files - the data files haven't changed. Also, if
you want to view the results in an SSI without voting, you can now use a URL
like poll.html?results. Check poll.html.

There are two options for using this script - one requires server side 
includes; you might want to contact your system administrator if you're not 
sure how your server is set up to handle SSI. More on this below.

The first option is to run the script through a server-side include in one
of your HTML pages.  This will cause one poll question to appear embedded in 
one of your HTML pages.  If you choose this option, you will need to edit and 
install both .cgi files.  The second option is to run the script through a 
button or link, as a stand-alone application, with a list of all the available
questions.  In this case, you don't need to worry about pollssi.cgi.
For running samples of both versions, check
http://tdi.uregina.ca/~eislerr/cgi/index.html
There is an admin function for adding and removing questions, which
is run through the robpoll.cgi, as shown in poll.html.

The admin section of the script is password protected.  The default password
is 'robpoll'.  You can change it through one of the admin functions.

These are the files you should have:

  1.  robpoll.cgi  . . . . . . the main Perl script
  2.  pollssi.cgi  . . . . . . the Perl script for SSI
  3.  poll.html  . . . . . . . sample html file
  4.  data.txt . . . . . . . . main data file
  5.  q1.txt . . . . . . . . . question data
  6.  ip1.txt  . . . . . . . . ip data
  7.  num.txt  . . . . . . . . data
  8.  white.jpg  . . . . . . . image for graphing
  9.  robpoll.jpg  . . . . . . link image
  10. readme.txt . . . . . . . this file


Here's what you need to do with these files:

- Put robpoll.cgi and pollssi.cgi in your cgi-bin and chmod them 755.

- Make a directory somewhere and chmod it 777. You can put it in your
  public_html, but then anybody who knows this directory can view your
  data files. For this script that's not really a problem.
  This is your poll directory for the $polldir below.  Put all the 
  .txt files (except readme.txt),  in this directory.  DO NOT change the 
  names of any of these files.  Do chmod 777 on the files numbered 4-7 above.

- Put poll.html somewhere in your public_html and chmod 644.

- Put white.jpg (or any other graphic you want to use for the graph)
  somewhere in your public_html, and chmod 644. The URL of this file 
  goes in your $graph_image as explained below. 


Now, you need to make a few small edits to the following files:

--- robpoll.cgi ---

--- Change the first line of this file to reflect the location of the perl
    interpreter on your system.  If the interpreter is at /bin/perl, then
    this line should be #!/bin/perl.  You can get this information with the
    command "which perl" or "where perl".  Check with the system admin
    if you're not sure.

--- $polldir - This is the absolute location of the directory you created to 
    hold the poll data files.  Don't include a trailing / !  Anyway, for
    example, my poll files are in /usr/people/eislerr/poll, so
    in my script the line is:
    $polldir = '/usr/people/eislerr/poll';

--- $graph_image - This is the URL of the image you want to use for the
    graphs produced by the script.  For example:
    $graph_image = 'http://tdi.uregina.ca/~eislerr/poll/white.jpg';

--- $cgi - This is the URL of the robpoll.cgi file.  This will go in the
    <form action> tag.  For example:
    $cgi = 'http://tdi.uregina.ca/~eislerr/cgi-bin/robpoll.cgi';
    This should be the same as what you have entered in your HTML <form>
    tag in the poll.html. (more below)

--- $check_cookies, $check_ip - These are switches for using cookies and/or
    ip logging to stop people from voting twice. They should both be either
    a 1 for yes, or 0 for no. You can use either, neither, or both.

--- $return_page - This is only for the SSI implementation of the poll.
    This is the page you want the user to be sent to after they vote
    through the SSI poll. If you return the user to the same page they 
    voted from (or any other page with the SSI statement) they'll see 
    the current results.

The rest of the variables are used to change the appearance of the script's
output.  For colours, you can use either a word like 'black' or an RGB like
'#FFFFFF'.  Numbers (like $textsize, $border) should be entered without
quotes around them.  $graph_width is a factor for the width of the graph.
The $include variables should either be a 1 or a 0.
    

--- pollssi.cgi ---

--- $q - This is the number of the question you want to appear in the SSI
    poll.

Do everything else the same as in robpoll.cgi above.


--- poll.html ---

In this file, change the action="" part of the <form> tag (in both <form> 
tags), and the hrefs to the location of robpoll.cgi.  For example:

<form action="http://tdi.uregina.ca/~eislerr/cgi-bin/robpoll.cgi"
       method="post">

<a href="http://tdi.uregina.ca/~eislerr/cgi-bin/robpoll.cgi?admin">

Also, change the SSI to point to the location of pollssi.cgi.
For example:

<!--#exec cgi="cgi-bin/pollssi.cgi"-->

The view results link after the SSI is not particularly important - it's
only for people who don't want to vote, but who want to see the results.
Anyone who votes is taken to the results anyway.

Once you have these working, you can just copy the code into
one of your pages, where you want the poll functions to appear.

NOTE:  Some systems only execute server side includes on pages ending
in .shtml, and some will not execute SSIs at all.  You can check this 
by trying to call the program from a page ending in another extension.  
Then, load up the page off your server and view its source.  If the 
above statement is visible in the page, the SSI has not executed 
properly.  

You can e-mail me if you're having trouble with this command, but you 
may need to ask your system administrator how SSI's are set up on 
your server.

-------

Ok!  That should be everything you need.  Good luck!  E-mail me with 
any trouble.

-------

Version Info

1.1 - Added Cookies
    - Added query strings for stand-alone functions (?admin, ?start)
    - Added query strings for SSI results (?results)
    - Added deletion of old files

1.0 - First Version

-------
Rob Eisler
eislerr@tdi.uregina.ca
http://tdi.uregina.ca/~eislerr

Matt Wright's HTTP Cookie Library v2.1 Copyright & Header Information:

##############################################################################
# HTTP Cookie Library           Version 2.1                                  #
# Copyright 1996 Matt Wright    mattw@worldwidemart.com                      #
# Created 07/13/96              Last Modified 12/23/96                       #
# Scripts Archive at:           http://www.worldwidemart.com/scripts/        #
# Parts of Code Contributed by Jeff Carnahan (http://terminalp.com/scripts/) #
##############################################################################
# COPYRIGHT NOTICE                                                           #
# Copyright 1996 Matthew M. Wright  All Rights Reserved.                     #
#                                                                            #
# HTTP Cookie Library may be used and modified free of charge by anyone so   #
# long as this copyright notice and the comments above remain intact.  By    #
# using this code you agree to indemnify Matthew M. Wright from any          #
# liability that might arise from it's use.                                  #  
#                                                                            #
# Selling the code for this program without prior written consent is         #
# expressly forbidden.  In other words, please ask first before you try and  #
# make money off of my program.                                              #
#                                                                            #
# Obtain permission before redistributing this software over the Internet or #
# in any other medium.  In all cases copyright and header must remain intact #
##############################################################################