No, this guide is not for fools but by a fool, who had kept wondering how CGI.pm is supposed to work and finally got a clue. So here’s how (I think) it works in simplest cases. I hope this might make some other people’s learning curve a little better.

a little idea of how Web pages are created, especially
a vague idea of HTML forms;
actually it might suffice to have used a simple query
form, and you can hardly have avoided them when surfing.
But just in case you have, here’s a sample form:

elementary knowledge aboutPerl; something like the following
shouldn’t scare you too much:

foo = 'hello world'; $foo =~ s/ / cruel /; print $foo;

a vague idea ofwhat CGI is; you should faintly understand that some URLs,
when accessed, may activate a program (script) on a server;
the following does:

OK, first do this: Check that you have the above-mentioned
local information. Double-check that you have understood it.
You should now know where to put your Perl programs in order to run
them as CGI scripts and what you might need to do with them
(setting file protections, perhaps). Fine, then test this with
the following script:

That is, write that into a file,
perhaps adding something into it as needed according to local
instructions
(such as a “magic”

1

#!

line that tells the path name of
the Perl interpreter on the server)
store the file where you need
to put your CGI scripts, and try accessing it via a link or
by directly typing the URL to a browser. It should work
basically the same way as the following link:

You will probably need some help to make
the script work. There are several practical things that need to
be set properly, and they vary from one server to another.
There’s a useful (though Unix-oriented) general resource: the
checklistThe Idiot’s Guide to Solving Perl CGI Problems.

You haven’t used CGI.pm yet. The trivial program above just
writes some fixed text. When executed as a CGI script, the first
lines of the output (up to the first empty line) will be taken asHTTP headers and sent to the browser,
and the rest is sent to the browser as actual data (HTML document,
in this case, and quite often).

is a prelude needed for using CGI.pm (in a particular mode).
And the line after it,

1

$data = param('sample') || '&lt;i>(No input)&lt;/i>';

is in this case the only part of the program that uses CGI.pm,
and it uses it only by calling the

1

param

function.
That function gives the value of the form field whose name is
passed as parameter. Note that the value might be undefined,
even if a field with that name is present in the form markup;
if the user does not fill out the text input field, there will
be no such field in the form data. (In Perl we can handle undefined
values conveniently; if the value is undefined,
the code above uses a fixed string instead.)

This works irrespectively of the

1

<a href="../forms/methods.html">method</a>

(

1

"get"

or

1

"post"

) of the form. More
generally, we need not worry about the mechanisms of
form data transmission, such as “URL encoding”.

You might have tried submitting text like <b>foo</b>
and noticed that the HTML markup “works”. This is simply because the
script writes the data as such into a document that will be sent to the
browser and treated as an HTML document. To prevent characters from
being treated as part of HTML markup, you could add

If we’d like to store the data, we
could do it using Perl’s
normal file operations. So this isn’t interesting from the CGI.pm
point of view, though of course it can be very relevant for
practical purposes. The same applies to other processing
of data, like sending it by E-mail.

But for illustration, here’s
how to set up a simple form that collects data and saves it
onto a file:

One of the great advantages of using CGI.pm is that it provides
very simple tools for
checking data acceptability and requesting the user to fix the data.
For example, we might wish to require that some name be given
(i.e. the name field is not empty or blank),
that an E-mail address satisfying some formal requirements is given,
and that some food preference is selected.
In real-life cases, you would probably want to do some real checking,
like verifying a user name and password combination.
But the basic techniques are perhaps best illustrated with an almost
trivial example. And let’s say that the E-mail is checked only against
a missing “@” sign; this at least filters out some
(accidental) erroneous submissions.

The fundamental idea is to generate a form dynamically
by a CGI script and do this so that the same script also processes
the submitted data. Confused? Well, let’s take an example
(you could alsosee the example in action):

Instead of writing a form which is statically part of an HTML
document, we have a script which generates an HTML document (which
contains a form). We can refer to the script using a normal link;
the URL is in this case

If a plain link to it is followed or there are otherwiseno parameters passed, the script just sends back an HTML document
(containing the form).

If parameters are passed but they fail the checks that the
script has been programmed to perform, an HTML document explaining the
errors and containing the form again, with previous data prefilled.

If parameters are passed and they areaccepted in the checks,
the action proper (whatever it is) is executed and then a “thank you”
page is returned. In this case, the “thank you” page echoes back the
form data. (This is very useful, since it gives the user feedback
that something happened, and the user can then print that confirmation
page for himself, save it locally, or whatever.)

Some key ingredients in the script:

1

use CGI qw(:standard);

is a “standard” prelude for
using CGI.pm

1

header

is an example of a CGI.pm routine; it returns
a string that constitutes a suitable HTTP header for an HTML
document so that you need not worry about such things

1

param()

tests whether any parameters were
passed in the script invocation; note than when the script isfirst invoked, that test probably yields false and we fall
down to code that generates the basic form

1

param()

with some string as argument can be used
to get the value of a parameter with a specific name (if defined,
i.e. if present in the form data; note that the code checks for
parameters being defined, using constructs like

1

if(!$name)

)

1

start_form

etc. are CGI.pm routines for generating
form elements; technically they return strings that you need to print
out (using

1

print

) to make things happen

there are nice structured tools for constructing sets of fields,
like a set of radio buttons; in our example, the hash

1

%labels

defines both the names of the fields (in the form
data) and the visible labels associated with them.

The details will not be explained here. This was basically
to give an idea of how things work with CGI.pm.
Note that if you wish to have a form embedded into a static HTML
page, you need something little more complicated. In effect, you would
need to duplicate things by writing a static

1

form

element
and the Perl code that generates a corresponding element dynamically
in the form handler when an error in data has been detected and
the form needs to be presented to the user. The reason is that dynamic
generation is the only way to use previous user input as default
values for fields so that the user does not need to type everything anew.
(Well, technically, you could save the data onto the server, but that
would be more complicated.)

are optional and used
to change the default (from allowing a single choice only
and from being initially unchecked, respectively).

For resetting fields, the

1

reset()

function is seldom useful. The

1

defaults()

function can
be used to set all fields to their very initial values as specified in
the script itself; the script will in fact be called as if it were called
the first time. In contrast, the button created with

1

reset()

will clear all changes that the user has made since the last invocation
of the script. Thus, if your code contains

1

textfield(-name=>'foo',-value='42')

, then

1

defaults()

will always set

1

foo

to

1

42

; but
if the user had changed the input box content to

1

100

and submitted
the form and got, in addition to other data, the same form in response, then
that form will (normally) contain the latest value

1

100

as response,
and

1

reset()

would set it back to

1

100

, not the
original

1

42

.

An array reference
could consist just of an “anonymous array”, like

1

['none','apples,'oranges,'kiwis']

, or a reference to a named array, such
as

1

\@foo

. In order to make the texts seen by users as different
from the strings used internally, which is often a good idea, you would
use a hash reference instead, e.g.

But beware that in this case the order of the fields in the generated
HTML markup may not correspond to the order of the hash constructor
(since hashes are essentially unordered. Thus, to control the order,
use a