.\" -*- mode: troff; coding: utf-8 -*-
.\" Automatically generated by Pod::Man 5.01 (Pod::Simple 3.43)
.\"
.\" Standard preamble:
.\" ========================================================================
.de Sp \" Vertical space (when we can't use .PP)
.if t .sp .5v
.if n .sp
..
.de Vb \" Begin verbatim text
.ft CW
.nf
.ne \\$1
..
.de Ve \" End verbatim text
.ft R
.fi
..
.\" \*(C` and \*(C' are quotes in nroff, nothing in troff, for use with C<>.
.ie n \{\
. ds C` ""
. ds C' ""
'br\}
.el\{\
. ds C`
. ds C'
'br\}
.\"
.\" Escape single quotes in literal strings from groff's Unicode transform.
.ie \n(.g .ds Aq \(aq
.el .ds Aq '
.\"
.\" If the F register is >0, we'll generate index entries on stderr for
.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index
.\" entries marked with X<> in POD. Of course, you'll have to process the
.\" output yourself in some meaningful fashion.
.\"
.\" Avoid warning from groff about undefined register 'F'.
.de IX
..
.nr rF 0
.if \n(.g .if rF .nr rF 1
.if (\n(rF:(\n(.g==0)) \{\
. if \nF \{\
. de IX
. tm Index:\\$1\t\\n%\t"\\$2"
..
. if !\nF==2 \{\
. nr % 0
. nr F 2
. \}
. \}
.\}
.rr rF
.\" ========================================================================
.\"
.IX Title "CGI::HTML::Functions 3pm"
.TH CGI::HTML::Functions 3pm 2024-03-24 "perl v5.38.2" "User Contributed Perl Documentation"
.\" For nroff, turn off justification. Always turn off hyphenation; it makes
.\" way too many mistakes in technical documents.
.if n .ad l
.nh
.SH NAME
CGI::HTML::Functions \- Documentation for CGI.pm Legacy HTML Functionality
.SH SYNOPSIS
.IX Header "SYNOPSIS"
Nothing here \- please do not use this functionality, it is considered to
be legacy and essentially deprecated. This documentation exists solely to
aid in maintenance and migration of legacy code using this functionality
and you are strongly encouraged to migrate away from it. If you are working
on new code you should be using a template engine. For more information see
CGI::Alternatives.
.PP
If you really want to continue using the HTML generation functionality of CGI.pm
then you should take a look at HTML::Tiny instead, which may give you a migration
path away from CGI.pm's html generation functions; i strongly encourage you to
move towards template driven page generation for anything involving markup as
it will make porting your app to other frameworks much easier in the long run.
.SH DESCRIPTION
.IX Header "DESCRIPTION"
The documentation here should be considered an addendum to the sections in the
CGI documentation \- the sections here are named the same as those within the
CGI perldoc.
.SH "Calling CGI.pm routines"
.IX Header "Calling CGI.pm routines"
HTML tag functions have both attributes (the attribute="value" pairs within the
tag itself) and contents (the part between the opening and closing pairs). To
distinguish between attributes and contents, CGI.pm uses the convention of
passing HTML attributes as a hash reference as the first argument, and the
contents, if any, as any subsequent arguments. It works out like
this:
.PP
.Vb 6
\& Code Generated HTML
\& \-\-\-\- \-\-\-\-\-\-\-\-\-\-\-\-\-\-
\& h1()
\& h1(\*(Aqsome\*(Aq,\*(Aqcontents\*(Aq);
some contents
\& h1({\-align=>left});
\& h1({\-align=>left},\*(Aqcontents\*(Aq);
contents
.Ve
.PP
Many newcomers to CGI.pm are puzzled by the difference between the calling
conventions for the HTML shortcuts, which require curly braces around the HTML
tag attributes, and the calling conventions for other routines, which manage
to generate attributes without the curly brackets. Don't be confused. As a
convenience the curly braces are optional in all but the HTML shortcuts. If you
like, you can use curly braces when calling any routine that takes named
arguments. For example:
.PP
.Vb 1
\& print $q\->header( { \-type => \*(Aqimage/gif\*(Aq, \-expires => \*(Aq+3d\*(Aq } );
.Ve
.PP
If you use warnings, you will be warned that some CGI.pm argument names
conflict with built-in perl functions. The most frequent of these is the
\&\-values argument, used to create multi-valued menus, radio button clusters
and the like. To get around this warning, you have several choices:
.IP 1. 4
Use another name for the argument, if one is available.
For example, \-value is an alias for \-values.
.IP 2. 4
Change the capitalization, e.g. \-Values
.IP 3. 4
Put quotes around the argument name, e.g. '\-values'
.SS "Function-oriented interface HTML exports"
.IX Subsection "Function-oriented interface HTML exports"
Here is a list of the HTML related function sets you can import:
.IP \fB:form\fR 4
.IX Item ":form"
Import all fill-out form generating methods, such as \fBtextfield()\fR.
.IP \fB:html2\fR 4
.IX Item ":html2"
Import all methods that generate HTML 2.0 standard elements.
.IP \fB:html3\fR 4
.IX Item ":html3"
Import all methods that generate HTML 3.0 elements (such as
, and ).
.IP \fB:html4\fR 4
.IX Item ":html4"
Import all methods that generate HTML 4 elements (such as
, and ).
.IP \fB:netscape\fR 4
.IX Item ":netscape"
Import the