The Mallard CGI programs, like all CGI programs, are sent data via the Common Gateway Interface. This data may be information filled out in a form, or a specified file being uploaded to the Mallard server. Either way, this data is sent to the server in various environment variables. The names of these variables and the format for the data which they contain are specified by the Common Gateway Interface. It is the responsibility of the CGI program to read the data out of the specified environment variables and parse that data so that it might be used by the program.
Mallard provides a library module to take care of all this for you. That library module is called Mallard.pm. This module provides much of the same functionality as CGI.pm (a common publically available CGI library module) as well as various utilities specific to Mallard, such as methods which print the uniform header and footer found on each Mallard page, methods to handle user authentication, and code to automatically change the working directory for your program to the correct root directory for the Mallard course from which your program is accessed.
Mallard.pm also provides various user authentication functions. These are called automatically for you before the data sent to the program is parsed and formatted. This authentication first determines who a user is, then determines if that user is registered in the Mallard course, and then finally, if the user is registered, what access permissions that user has. If at any point the user fails to meet the access restrictions given for the program, Mallard.pm will simply print an "access denied" page and not allow the user to run the program. These functions will be described in greater detail below.
The Mallard library files are located in the directory $MALLARD_HOME/lib, where $MALLARD_HOME is an environment variable containing the location of the Mallard "root" on your server. This environment variable is exported to all of the Mallard CGI scripts by the web server.
To ensure that your program can access the Mallard libraries, you need to add this directory to the @INC array (the list of directories which a program will search for any modules the program requires). You may do this with the following code at the beginning of your program:
BEGIN {
use Env qw(MALLARD_HOME);
unshift(@INC, "$MALLARD_HOME/lib");
}
If you omit this code, the Mallard libraries will not be found, and your
program will fail to compile. This will produce a server error.
Each Mallard CGI program you write should be "jumpstarted" by
The constructor method of Mallard.pm calls all of the necessary methods to parse any data sent to the program and restrict access to the program to the appropriate users. It also checks the validity of the Mallard license and reacts accordingly.
Instantiation of a Mallard object consists of the following code:
use Mallard;
my $mallard = new Mallard();
This should be the first thing that your CGI program does. The Mallard object is called $mallard by convention. You should follow this convention to allow other library modules and programs to assume the existence of a variable $::mallard in the main package.
As soon as you create this $mallard object, all of the data sent to your program exists, neatly formatted, in various fields of the $mallard object which will be described below. Various information about the user and her browser are similarly stored.
Note that the above basic instantiation restricts access to the program to all valid Mallard users. This means that all Mallard users, including students and demo users, may use the program. To restrict access to a subset of Mallard users, you should make a call to $mallard->require_access_level() as follows:
$mallard->require_access_level($Authent::ADMIN);
The above call will restrict access to your program to Mallard course directors. This call should come immediately after the $mallard object is created. The available access levels are
With the data parsing and user authentication completed, before any text is printed to the screen (stdout), you will need to print a valid HTTP header with a call to $mallard->print_head() as follows:
$mallard->print_head("My Nifty Mallard Program");
This will do the following:
Content-type: text/html\n\n
If you wish to add anything to the HTTP header (such as extra mime types, or a pragma directive) you must print the extra header information before the call to $mallard->print_head(), as follows:
print "pragma:no-cache\n";
$mallard->print_head("My Nifty Mallard Program");
Note that you must have a valid HTTP header as the first thing printed to stdout, or your program will produce a server error.
Finally, you should end your Mallard CGI program with a call to $mallard->print_tail() as follows:
$mallard->print_tail();
This will print the Mallard copyright and course material copyright at the bottom of the page. Both $mallard->print_head() and $mallard->print_tail() may take various arguments, which will be described below. It will also print the standard HTML </BODY> and </HTML> closing tags.
All of the data sent to your CGI program via either the GET or POST methods is parsed and saved into fields on the Mallard object by the $mallard->read_form() method. This method is called for you automatically from the Mallard constructor.
The data is stored in the following fields:
Example: The form element
<INPUT TYPE=TEXT NAME="fruit">
which someone fills in with banana will be retrievable
from the Mallard object with
my $fruit = $mallard->{'form'}{'fruit'};
Note that this is an HTML form input element, not a Mallard
question type input.
FILE
form input elements used to upload the files, and the values
are the actual names of the files uploaded. An example is
given with the next item.
FILE form input elements used to upload the files, and the
values are the contents of the files uploaded.
Example: The form input element
<INPUT TYPE=FILE NAME="my_file" SIZE=30>
will cause a file specified by the user to be uploaded from the client
machine. The name of the file uploaded (i.e. the name of the local file the
user typed in the blank for uploading) will be retrievable from the
Mallard object with
my $filename = $mallard->{'sent_files'}{'my_file'};
The contents of the file (which may be either binary or text, depending
on the file uploaded) will be retrievable from the Mallard object with
my $file_contents = $mallard->{'sent_data'}{'my_file'};
FILE form input elements used to upload the files, and the
values are the "Content-type" values of the files uploaded.
my $hash_ref = $mallard->form('prefix');
This will read all of the form variables whose names begin with the given
prefix into the local $hashref. Variables may then be retrieved
from this local variable in the same way that they are retrieved from
$mallard->{'form'}.
The Mallard object constructor automatically calls the $mallard->user_authent() method to perform user authentication. This method does several things:
Just before the user authentication, Mallard reads in the contents of the server configuration file and the course configuration file. The server configuration file is created by the Mallard Administrator when the server is originally set up. The course configuration file is created at the time the course is created, and later edited by the Course Director. The contents of these files must be read in before user authentication, because among other things, these files specify what sort of user authentication system is to be used (PWF or Bluestem). Fields in the course configuration file override identically named entries in the server configuration file.
The various entries in the configuration files are stored in a hash, accessible via the hash reference variable $mallard->{'config'}. These variables are accessed in the same manner as form variables are accessed from the $mallard->{'form'} variable.
There is no limit to the number or names of variables which may exist in the course configuration, as course directors are free to specify non-standard variables of their own choice. However, the standard ones are listed below:
<BODY> tags on Mallard pages. This field will
eventually be renamed bodyargs. (Example: BGCOLOR=#FFFFFF TEXT=blue)
Mallard users are also able to specify individual preferences with the user_config utility. The Mallard object constructor reads these in as well, and stores them in a hash, accessible via the hash reference variable $mallard->{'user_config'}. These variables may be accessed directly as shown below, or may be accessed via a method call $mallard->user_config('field') as follows:
my $email = $mallard->user_config('email');
A few of the fields you may wish to access directly are listed below:
my $email = $mallard->other_user_config('email');
The main use for this is retrieving the email and homepage
fields.
Calls to the $mallard->print_head() method provide a valid HTTP header as well as a fully finished <HEAD> section, a complete <BODY> tag, and a printed title followed by a horizontal rule. This means that $mallard->print_head() determines the look of the page, including its color scheme, as these are specified with arguments in the <BODY> tag.
You may change the look of the page in two ways. The first is to make use of the arguments to $mallard->print_head(). These arguments are given in order as follows:
If that is not enough variance for you, you may use the $mallard->print_min_head() method, which provides a valid HTTP header as well as a fully finished <HEAD> section and a complete <BODY> tag, but does not print any visible text to the page. Its arguments are given in order as follows:
Should you not wish to provide even the <TITLE> </TITLE> tags, or do anything in the standard manner, you are of course free to explicitly print a valid HTTP header yourself. However, it is strongly suggested that you use the $mallard->print_head() method so as to give a uniform look to all the Mallard pages. Should the look ever be changed, it will be easy to do so in one location.
Example: To give a title of "Mallard is Great" on a yellow page with green text, in a slightly smaller than usual size, and with quiz icons on either side of it, use the following call:
$mallard->print_head("Mallard is Great","BGCOLOR=yellow TEXT=green",
"quiz.gif","h2");
The $mallard->print_tail() method will print the Mallard copyright
and course material copyright at the bottom of the page.
It is absolutely necessary that these be included on every page for
legal reasons. Therefore, you must ensure that every way that your program
exits makes a call to $mallard->print_tail() (in fact,
$mallard->print_tail() ends with a perl exit; statement
to be sure that the code exits cleanly).
$mallard->print_tail() also prints the standard HTML </BODY> and </HTML> closing tags, which are a good idea to include on every HTML page you write.
Finally, you may use the $mallard->print_tail() method to dynamically change the help file which is provided to the user when she clicks on the question mark icon. The file to be provided with your page is specified with the following arguments:
Example: To have the question icon bring up the help file "questions.help" with the explanation "Help for writing Mallard questions" appearing in the status bar when the user moves the mouse over the icon, use the following call:
$mallard->print_tail("questions","Help for writing Mallard questions");