This site will look much better in a browser that supports web standards, but is accessible to any browser or Internet device.

Signup Documentation

NAME

signup.pl - a script for automating on-line signup for volunteer events.

DESCRIPTION

This script was written to simplify the use of an on-line signup form for volunteer participation in events. This script does not support scheduling or conflict resolution through any database. It's only purpose was to automate the email-based system my wife was already using for this job.

The only action this script takes is to call the sendmail program to mail the results of this signup request to the listed recipients. It also returns an HTML page with the same information to the user.

PREREQUISITES

This script require the CGI and CGI::Carp modules. It also explicitly depends on access to sendmail.

COREQUISITES

None

OSNAMES

any, provided access to a sendmail program

SCRIPT CATEGORIES

unknown

INSTALLATION

Installation of the signup.pl script is a simple 4 step process.

  1. Copy the signup.pl file to an appropriate CGI directory on your web server.

  2. Create a directory named conf in the directory where signup.pl will run.

  3. Copy the default.conf file to the conf directory.

  4. Change the configuration parameters to match your application.

USAGE

The signup.pl script is designed to be called from an HTML form. The ACTION attribute of the FORM should point to the signup.pl script you installed. For example, if you installed signup.pl in the directory referenced by /cgi-bin/ on the server www.volunteer.org, you would set the ACTION attribute to the following:

        http://www.volunteer.org/cgi-bin/signup.pl

When the results of a signup form are directed to the signup.pl script, it sends a customized email to a list of addresses where the submission is processed. The script also returns a customized confirmation page to the volunteer that lists the submitted information.

The signup.pl script can be used for multiple independent events by building a configuration file for each event. All of the information common to all events would still reside in default.conf. All of the event-specific information would be placed in separate configuration files.

To access an alternate configuration file, provide a cfg parameter providing the name of the appropriate file (without the .conf extension). The signup.pl script will read this file after reading default.conf, modifying the configuration accordingly.

CONFIGURATION

The signup.pl script has several configurable options. These allow you to specify the look of the confirmation page sent to the volunteer and the format and recipients of the submission email.

The configuration files are loaded from the conf subdirectory under the directory the script runs in. Configuration files located in other locations will not be found.

There are two ways to determine the configuration files that are loaded.

First, the file default.conf in the conf subdirectory is always loaded if it exists. This allows for default configuration parameters even if you use signup.pl for several different projects.

In addition, a second file is named by the cfg parameter to the signup.pl script. The value of this parameter is the name of the file without the .conf extension. If the value of cfg is conference, the file read will be conf/conference.conf. This file is read after default.conf and allows overriding of the configuration parameters as necessary for a particular application.

The configuration files must be valid Perl code. If you receive compile errors from Perl when running the script, you likely have syntax errors in your configuration file.

All of the configuration files must return TRUE in order for Perl to use them properly. The easiest way to accomplish this is to end the script with the line

        1;

CONFIGURATION VARIABLES

$SendMail
This is the complete path to the sendmail program.

$sep
Define the separator string used in determining the fields of the schedule shift fields.

$listsep
Define the output separator string used for writing the output of the various fields.

$To
This string lists the To addresses for the sendmail program. It may contain replaceable parameters of the form {{name}}. See REPLACEABLE PARAMETERS for details.

$CC
This string lists the CC addresses for the sendmail program. It may contain replaceable parameters of the form {{name}}. See REPLACEABLE PARAMETERS for details.

$ReplyTo
This string lists the ReplyTo addresses for the sendmail program. It may contain replaceable parameters of the form {{name}}. See REPLACEABLE PARAMETERS for details.

$Subject
This string lists the subject field for the mail to be sent by sendmail. It may contain replaceable parameters of the form {{name}}. See REPLACEABLE PARAMETERS for details.

$From
This string contains the From address for the sent email. It must not contain replaceable parameters.

%text_format
This hash contains instructions for converting the schedule descriptions into a text format. See FORMATTING for details.

%html_format
This hash contains instructions for converting the schedule descriptions into an HTML format. See FORMATTING for details.

@RequiredParameters
This array contains the names of the CGI parameters that are required for submission. If one or more of these parameters is missing, an error page is returned to the user and no email is sent.

$MailTemplate
This string contains a the general format of the email messages. The text will be sent as the body of the email message after replacing any parameters of the form {{name}} with the appropriate text. See REPLACEABLE PARAMETERS for details. The value of this parameter may also be a call of the form load_file( "conf/htmlmail.tmpl" );. This call sets the variable to the contents of the file conf/htmlmail.tmpl.

The contents of this string may be either straight text for a simple plain text email or valid HTML. If the string is HTML, an HTML email message is sent instead of plain text. This allows for more formatting options. The signup.pl script determines the whether or not the text is HTML by looking for both the <html> and </html> tags.

$PageTemplate
This string contains a the general format of the confirmation page as HTML. The page will be returned to the user's browser after replacing any parameters of the form {{name}} with the appropriate text. See REPLACEABLE PARAMETERS for details. The value of this parameter may also be a call of the form load_file( "conf/confirm.tmpl" );. This call sets the variable to the contents of the file conf/confirm.tmpl.

$ErrorTemplate
This string contains a the general format of the error messages as HTML. Upon detecting an error, signup.pl returns this page to the user's browser after replacing any parameters of the form {{name}} with the appropriate text. See REPLACEABLE PARAMETERS for details. The token {$errormsg$} is replaced with the actual text of the error message. The value of this parameter may also be a call of the form load_file( "conf/error.tmpl" );. This call sets the variable to the contents of the file conf/error.tmpl.

$GroupDescr
This string contains the group descriptor. This is a list of the groups participating in the event, the full group names, and the group's contact people. This information may be used to help customize the email used to report the volunteer and the confirmation page. The value of this parameter may also be a call of the form load_file( "conf/groups.desc" );. This call sets the variable to the contents of the file conf/groups.desc. See GROUPS for details.

FORMATTING

The signup script has a capability for nice formatting of structured parameters. If a parameter value has the defined separator character embedded (; by default) in it, signup.pl splits the value into fields on that character and formats it in an outline form. The formatting is controlled through the use of one of two hashes, %text_format and %html_format. These hashes define a list of strings for use in different portions of the formatting process. These strings are

-listsep
output separator for simple list items

-pretree
write before tree output

-posttree
write after tree output

-preitem
before each item in the tree

-postitem
after each item in the tree

-addpre
prepended to the -preitem for a new level

-pretopitem
written before -preitem on the upper-most items

-posttopitem
written after -postitem on the upper-most items

-prechildren
written before output of child elements

-postchildren
written after output of child elements

The default version of %text_format generates a tab-indented outline format. The default version of %html_format generates a nested unordered list format.

GROUPS

In some volunteer events, a person may wish to represent a particular group when signing up. The Group Description variable gives signup.pl the capability of dealing with this kind of information. The contents of the $GroupDescr variable must be a multiline string that looks like the following:

  BFC:Bob's Fone Company
     bob@bfc.com
     edna@bfc.com:Edna C. Potts
  SPCA:SPCA
     coordinator@spca.org:Myra Katz
  DEFAULT
     info@example.org

Each group is defined by a line containing an abbreviation that is used in any parameters sent by the script. Following that may be a colon followed by the group's full name. After that line is zero or more indented lines ginving contact information, one contact per line. Each line is an email address followed by an optional colon and person's name.

There may also be a special entry with a value of DEFAULT. The contacts under the default entry are used in any case where no group or an unrecognized group is supplied.

REPLACEABLE PARAMETERS

The confirmation page, confirmation email, and error page have the capability of supporting replaceable parameters. These parameters customize the page (or mail headers) based on choices made by the volunteer. There are three different forms of these parameters:

{{param}}
This kind of parameter will be replaced by the value of the named parameter. For instance, if the form used with signup.pl has a parameter called name and the string {{name}} is used in the email, the value of the name parameter will replace the string {{name}} in the email.

If the value of a parameter contains the special $sep value the output will be formatted as a list.

{{set[param]}}
This kind of parameter uses the value of the supplied parameter to look up a value in one a few sets of information related to groups. The legal values for the set are email, group, or groupcontacts. These correspond to the group contact email list, the full group name, and the group contacts. The string in square brackets is used as a form parameter name. The value of this parameter is used to look up the information supplied in the group description.

For example, given a parameter of grp with a value of BFC, the following results would be returned using the group descriptor from the previous section.

{{email[grp]}}
bob@bfc.com, edna@bfc.com

{{group[grp]}}
Bob's Fone Company

{{groupcontacts[grp]}}
bob@bfc.com, Edna C. Potts

In the last case, the email address is used for the first contact because no name was given. By the same token, the abbreviated name would be used for the group if no full name were given.

{$errormsg$}
This parameter only is used in the error page. It is replaced with the actual text of the error message.