Importing CGI Methods
Importing CGI Methods
A large number of scripts allocate only a single query
object, use it to read parameters or to create a fill-out form, and then discard
it. For this type of script, it may be handy to import CGI module methods into
your name space. The most common syntax for this is:
use
CGI qw(:standard);
This imports the standard methods into your namespace.
Now instead of getting parameters like this:
use
CGI;
$dinner
= $query->param('entree');
You can do it like this:
use
CGI qw(:standard);
$dinner
= param('entree');
Similarly, instead of creating a form like this:
print
$query->start_form,
"Check here if you're happy: ",
$query->checkbox(-name=>'happy',-value=>'Y',-checked=>1),
"<P>",
$query->submit,
$query->end_form;
You can create it like this:
print
start_form,
"Check here if you're happy: ",
checkbox(-name=>'happy',-value=>'Y',-checked=>1),
p,
submit,
end_form;
Even though there's no CGI object in view in the second
example, state is maintained using an implicit CGI object that's created
automatically. The form elements created this way are sticky, just as before. If
you need to get at the implicit CGI object directly, you can refer to it as:
$CGI::Q;
The use CGI statement is used to import method
names into the current name space. There is a slight overhead for each name you
import, but ordinarily is nothing to worry about. You can import selected method
names like this:
use CGI qw(header start_html end_html);
Ordinarily, however, you'll want to import groups of
methods using export tags. Export tags refer to sets of logically related
methods which are imported as a group with use. Tags are distinguished
from ordinary methods by beginning with a ":" character. This example imports
the methods dealing with the CGI protocol (param() and the like) as well as
shortcuts that generate HTML2-compliant tags:
use
CGI qw(:cgi :html2);
Currently there are 8 method families defined in CGI.pm.
They are:
:cgi
These
are all the tags that support one feature or another of the CGI protocol,
including param(), path_info(), cookie(), request_method(), header() and the
like.
:form
These
are all the form element-generating methods, including start_form(),
textfield(), etc.
:html2
These
are HTML2-defined shortcuts such as br(), p() and head(). It also includes such
things as start_html() and end_html() that aren't exactly HTML2, but are close
enough.
:html3
These
contain various HTML3 tags for tables, frames, super- and subscripts, applets
and other objects.
:netscape
These
are Netscape extensions not included in the HTML3 category including blink() and
center().
:html
These
are all the HTML generating shortcuts, comprising the union of html2,
html3, and netscape.
:multipart
These
are various functions that simplify creating documents of the various multipart
MIME types, and are useful for implementing server push.
:standard
This
is the union of html2, form, and :cgi (everything except the HTML3
and Netscape extensions).
:all
This
imports all the public methods into your namespace!
Pragmas
In addition to importing individual methods and method
families, use CGI recognizes several pragmas, all proceeded by dashes.
-any
When
you use CGI -any, then any method that the query object doesn't recognize
will be interpreted as a new HTML tag. This allows you to support the next ad
hoc Netscape or Microsoft HTML extension. For example, to support Netscape's
latest tag, <GRADIENT> (which causes the user's desktop to be flooded with
a rotating gradient fill until his machine reboots), you can use something like
this:
use CGI qw(-any);
$q=new CGI;
print
$q->gradient({speed=>'fast',start=>'red',end=>'blue'});
Since
using any causes any mistyped method name to be interpreted as an HTML
tag, use it with care or not at all.
-compile
This
causes the indicated autoloaded methods to be compiled up front, rather than
deferred to later. This is useful for scripts that run for an extended period of
time under FastCGI or mod_perl, and for those destined to be crunched by Malcom
Beattie's Perl compiler. Use it in conjunction with the methods or method
familes you plan to use.
use CGI qw(-compile :standard :html3);
or
even
use CGI qw(-compile :all);
Note
that using the -compile pragma in this way will always have the effect of
importing the compiled functions into the current namespace. If you want to
compile without importing use the
compile()
method instead.
-autoload
Overrides
the autoloader so that any function in your program that is not recognized is
referred to CGI.pm for possible evaluation. This allows you to use all the
CGI.pm functions without adding them to your symbol table, which is of concern
for mod_perl users who are worried about memory consumption. Warning:
when -autoload is in effect, you cannot use "poetry mode" (functions
without the parenthesis). Use hr() rather than hr, or add
something like use subs qw/hr p header/ to the top of your script.
-nosticky
Turns
off "sticky" behavior in fill-out forms. Every form element will act as if you
passed -override.
-no_xhtml
By
default, CGI.pm versions 2.69 and higher emit XHTML
(http://www.w3.org/TR/xhtml1/).
The -no_xhtml pragma disables this feature. Thanks to Michalis Kabrianis
<kabrianis@hellug.gr> for this feature.
-nph
This
makes CGI.pm produce a header appropriate for an NPH (no parsed header) script.
You may need to do other things as well to tell the server that the script is
NPH. See the
discussion of NPH scripts
below.
-oldstyle_urls
Separate
the name=value pairs in CGI parameter query strings emitted by self_url() and
query_string() with ampersands. Otherwise, CGI.pm emits HTML-compliant
semicolons. If you use this form, be sure to escape ampersands into HTML
entities with escapeHTML. Example:
$href = $q->self_url();
$href = escapeHTML($href);
-newstyle_urls
Separate
the name=value pairs in CGI parameter query strings with semicolons rather than
ampersands. For example:
name=fred;age=24;favorite_color=3
As
of version 2.64, this is the default style.
-no_debug
This
turns off the command-line processing features. If you want to run a CGI.pm
script from the command line to produce HTML, and you don't want it interpreting
arguments on the command line as CGI name=value arguments, then use this pragma:
use CGI qw(-no_debug :standard);
-debug
This
turns on full debugging. In addition to reading CGI arguments from the
command-line processing, CGI.pm will pause and try to read arguments from STDIN,
producing the message "(offline mode: enter name=value pairs on standard input)"
features.
-private_tempfiles
CGI.pm
can process uploaded file. Ordinarily it spools the uploaded file to a temporary
directory, then deletes the file when done. However, this opens the risk of
eavesdropping as described in the
file upload section.
Another CGI script author could peek at this data during the upload, even if it
is confidential information. On Unix systems, the -private_tempfiles
pragma will cause the temporary file to be unlinked as soon as it is opened and
before any data is written into it, eliminating the risk of eavesdropping.
Special Forms for Importing HTML-Tag
Functions
Many of the methods generate HTML tags. As described
below, tag functions automatically generate both the opening and closing tags.
For example:
print h1('Level 1 Header');
produces
<H1>Level 1 Header</H1>
There will be some times when you want to produce the
start and end tags yourself. In this case, you can use the form
start_Itag_name and end_Itag_name, as in:
print start_h1,'Level 1
Header',end_h1;
With a few exceptions (described below),
start_tag_name and end_Itag_name functions are not generated
automatically when you use CGI. However, you can specify the tags you
want to generate start/end functions for by putting an asterisk in front
of their name, or, alternatively, requesting either "start_tag_name" or
"end_tag_name" in the import list.
Example:
use CGI qw/:standard *table
start_ul/;
In this example, the following functions are generated
in addition to the standard ones:
- start_table() (generates a <TABLE> tag)
- end_table() (generates a </TABLE> tag)
- start_ul() (generates a <UL> tag)
- end_ul() (generates a </UL> tag)
|
