| 1 | .\" Automatically generated by Pod::Man v1.34, Pod::Parser v1.13 |
| 2 | .\" |
| 3 | .\" Standard preamble: |
| 4 | .\" ======================================================================== |
| 5 | .de Sh \" Subsection heading |
| 6 | .br |
| 7 | .if t .Sp |
| 8 | .ne 5 |
| 9 | .PP |
| 10 | \fB\\$1\fR |
| 11 | .PP |
| 12 | .. |
| 13 | .de Sp \" Vertical space (when we can't use .PP) |
| 14 | .if t .sp .5v |
| 15 | .if n .sp |
| 16 | .. |
| 17 | .de Vb \" Begin verbatim text |
| 18 | .ft CW |
| 19 | .nf |
| 20 | .ne \\$1 |
| 21 | .. |
| 22 | .de Ve \" End verbatim text |
| 23 | .ft R |
| 24 | .fi |
| 25 | .. |
| 26 | .\" Set up some character translations and predefined strings. \*(-- will |
| 27 | .\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left |
| 28 | .\" double quote, and \*(R" will give a right double quote. | will give a |
| 29 | .\" real vertical bar. \*(C+ will give a nicer C++. Capital omega is used to |
| 30 | .\" do unbreakable dashes and therefore won't be available. \*(C` and \*(C' |
| 31 | .\" expand to `' in nroff, nothing in troff, for use with C<>. |
| 32 | .tr \(*W-|\(bv\*(Tr |
| 33 | .ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p' |
| 34 | .ie n \{\ |
| 35 | . ds -- \(*W- |
| 36 | . ds PI pi |
| 37 | . if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch |
| 38 | . if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\" diablo 12 pitch |
| 39 | . ds L" "" |
| 40 | . ds R" "" |
| 41 | . ds C` "" |
| 42 | . ds C' "" |
| 43 | 'br\} |
| 44 | .el\{\ |
| 45 | . ds -- \|\(em\| |
| 46 | . ds PI \(*p |
| 47 | . ds L" `` |
| 48 | . ds R" '' |
| 49 | 'br\} |
| 50 | .\" |
| 51 | .\" If the F register is turned on, we'll generate index entries on stderr for |
| 52 | .\" titles (.TH), headers (.SH), subsections (.Sh), items (.Ip), and index |
| 53 | .\" entries marked with X<> in POD. Of course, you'll have to process the |
| 54 | .\" output yourself in some meaningful fashion. |
| 55 | .if \nF \{\ |
| 56 | . de IX |
| 57 | . tm Index:\\$1\t\\n%\t"\\$2" |
| 58 | .. |
| 59 | . nr % 0 |
| 60 | . rr F |
| 61 | .\} |
| 62 | .\" |
| 63 | .\" For nroff, turn off justification. Always turn off hyphenation; it makes |
| 64 | .\" way too many mistakes in technical documents. |
| 65 | .hy 0 |
| 66 | .if n .na |
| 67 | .\" |
| 68 | .\" Accent mark definitions (@(#)ms.acc 1.5 88/02/08 SMI; from UCB 4.2). |
| 69 | .\" Fear. Run. Save yourself. No user-serviceable parts. |
| 70 | . \" fudge factors for nroff and troff |
| 71 | .if n \{\ |
| 72 | . ds #H 0 |
| 73 | . ds #V .8m |
| 74 | . ds #F .3m |
| 75 | . ds #[ \f1 |
| 76 | . ds #] \fP |
| 77 | .\} |
| 78 | .if t \{\ |
| 79 | . ds #H ((1u-(\\\\n(.fu%2u))*.13m) |
| 80 | . ds #V .6m |
| 81 | . ds #F 0 |
| 82 | . ds #[ \& |
| 83 | . ds #] \& |
| 84 | .\} |
| 85 | . \" simple accents for nroff and troff |
| 86 | .if n \{\ |
| 87 | . ds ' \& |
| 88 | . ds ` \& |
| 89 | . ds ^ \& |
| 90 | . ds , \& |
| 91 | . ds ~ ~ |
| 92 | . ds / |
| 93 | .\} |
| 94 | .if t \{\ |
| 95 | . ds ' \\k:\h'-(\\n(.wu*8/10-\*(#H)'\'\h"|\\n:u" |
| 96 | . ds ` \\k:\h'-(\\n(.wu*8/10-\*(#H)'\`\h'|\\n:u' |
| 97 | . ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'^\h'|\\n:u' |
| 98 | . ds , \\k:\h'-(\\n(.wu*8/10)',\h'|\\n:u' |
| 99 | . ds ~ \\k:\h'-(\\n(.wu-\*(#H-.1m)'~\h'|\\n:u' |
| 100 | . ds / \\k:\h'-(\\n(.wu*8/10-\*(#H)'\z\(sl\h'|\\n:u' |
| 101 | .\} |
| 102 | . \" troff and (daisy-wheel) nroff accents |
| 103 | .ds : \\k:\h'-(\\n(.wu*8/10-\*(#H+.1m+\*(#F)'\v'-\*(#V'\z.\h'.2m+\*(#F'.\h'|\\n:u'\v'\*(#V' |
| 104 | .ds 8 \h'\*(#H'\(*b\h'-\*(#H' |
| 105 | .ds o \\k:\h'-(\\n(.wu+\w'\(de'u-\*(#H)/2u'\v'-.3n'\*(#[\z\(de\v'.3n'\h'|\\n:u'\*(#] |
| 106 | .ds d- \h'\*(#H'\(pd\h'-\w'~'u'\v'-.25m'\f2\(hy\fP\v'.25m'\h'-\*(#H' |
| 107 | .ds D- D\\k:\h'-\w'D'u'\v'-.11m'\z\(hy\v'.11m'\h'|\\n:u' |
| 108 | .ds th \*(#[\v'.3m'\s+1I\s-1\v'-.3m'\h'-(\w'I'u*2/3)'\s-1o\s+1\*(#] |
| 109 | .ds Th \*(#[\s+2I\s-2\h'-\w'I'u*3/5'\v'-.3m'o\v'.3m'\*(#] |
| 110 | .ds ae a\h'-(\w'a'u*4/10)'e |
| 111 | .ds Ae A\h'-(\w'A'u*4/10)'E |
| 112 | . \" corrections for vroff |
| 113 | .if v .ds ~ \\k:\h'-(\\n(.wu*9/10-\*(#H)'\s-2\u~\d\s+2\h'|\\n:u' |
| 114 | .if v .ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'\v'-.4m'^\v'.4m'\h'|\\n:u' |
| 115 | . \" for low resolution devices (crt and lpr) |
| 116 | .if \n(.H>23 .if \n(.V>19 \ |
| 117 | \{\ |
| 118 | . ds : e |
| 119 | . ds 8 ss |
| 120 | . ds o a |
| 121 | . ds d- d\h'-1'\(ga |
| 122 | . ds D- D\h'-1'\(hy |
| 123 | . ds th \o'bp' |
| 124 | . ds Th \o'LP' |
| 125 | . ds ae ae |
| 126 | . ds Ae AE |
| 127 | .\} |
| 128 | .rm #[ #] #H #V #F C |
| 129 | .\" ======================================================================== |
| 130 | .\" |
| 131 | .IX Title "CGI 3" |
| 132 | .TH CGI 3 "2002-06-01" "perl v5.8.0" "Perl Programmers Reference Guide" |
| 133 | .SH "NAME" |
| 134 | CGI \- Simple Common Gateway Interface Class |
| 135 | .SH "SYNOPSIS" |
| 136 | .IX Header "SYNOPSIS" |
| 137 | .Vb 2 |
| 138 | \& # CGI script that creates a fill-out form |
| 139 | \& # and echoes back its values. |
| 140 | .Ve |
| 141 | .PP |
| 142 | .Vb 16 |
| 143 | \& use CGI qw/:standard/; |
| 144 | \& print header, |
| 145 | \& start_html('A Simple Example'), |
| 146 | \& h1('A Simple Example'), |
| 147 | \& start_form, |
| 148 | \& "What's your name? ",textfield('name'),p, |
| 149 | \& "What's the combination?", p, |
| 150 | \& checkbox_group(-name=>'words', |
| 151 | \& -values=>['eenie','meenie','minie','moe'], |
| 152 | \& -defaults=>['eenie','minie']), p, |
| 153 | \& "What's your favorite color? ", |
| 154 | \& popup_menu(-name=>'color', |
| 155 | \& -values=>['red','green','blue','chartreuse']),p, |
| 156 | \& submit, |
| 157 | \& end_form, |
| 158 | \& hr; |
| 159 | .Ve |
| 160 | .PP |
| 161 | .Vb 6 |
| 162 | \& if (param()) { |
| 163 | \& print "Your name is",em(param('name')),p, |
| 164 | \& "The keywords are: ",em(join(", ",param('words'))),p, |
| 165 | \& "Your favorite color is ",em(param('color')), |
| 166 | \& hr; |
| 167 | \& } |
| 168 | .Ve |
| 169 | .SH "ABSTRACT" |
| 170 | .IX Header "ABSTRACT" |
| 171 | This perl library uses perl5 objects to make it easy to create Web |
| 172 | fill-out forms and parse their contents. This package defines \s-1CGI\s0 |
| 173 | objects, entities that contain the values of the current query string |
| 174 | and other state variables. Using a \s-1CGI\s0 object's methods, you can |
| 175 | examine keywords and parameters passed to your script, and create |
| 176 | forms whose initial values are taken from the current query (thereby |
| 177 | preserving state information). The module provides shortcut functions |
| 178 | that produce boilerplate \s-1HTML\s0, reducing typing and coding errors. It |
| 179 | also provides functionality for some of the more advanced features of |
| 180 | \&\s-1CGI\s0 scripting, including support for file uploads, cookies, cascading |
| 181 | style sheets, server push, and frames. |
| 182 | .PP |
| 183 | \&\s-1CGI\s0.pm also provides a simple function-oriented programming style for |
| 184 | those who don't need its object-oriented features. |
| 185 | .PP |
| 186 | The current version of \s-1CGI\s0.pm is available at |
| 187 | .PP |
| 188 | .Vb 2 |
| 189 | \& http://www.genome.wi.mit.edu/ftp/pub/software/WWW/cgi_docs.html |
| 190 | \& ftp://ftp-genome.wi.mit.edu/pub/software/WWW/ |
| 191 | .Ve |
| 192 | .SH "DESCRIPTION" |
| 193 | .IX Header "DESCRIPTION" |
| 194 | .Sh "\s-1PROGRAMMING\s0 \s-1STYLE\s0" |
| 195 | .IX Subsection "PROGRAMMING STYLE" |
| 196 | There are two styles of programming with \s-1CGI\s0.pm, an object-oriented |
| 197 | style and a function-oriented style. In the object-oriented style you |
| 198 | create one or more \s-1CGI\s0 objects and then use object methods to create |
| 199 | the various elements of the page. Each \s-1CGI\s0 object starts out with the |
| 200 | list of named parameters that were passed to your \s-1CGI\s0 script by the |
| 201 | server. You can modify the objects, save them to a file or database |
| 202 | and recreate them. Because each object corresponds to the \*(L"state\*(R" of |
| 203 | the \s-1CGI\s0 script, and because each object's parameter list is |
| 204 | independent of the others, this allows you to save the state of the |
| 205 | script and restore it later. |
| 206 | .PP |
| 207 | For example, using the object oriented style, here is how you create |
| 208 | a simple \*(L"Hello World\*(R" \s-1HTML\s0 page: |
| 209 | .PP |
| 210 | .Vb 7 |
| 211 | \& #!/usr/local/bin/perl -w |
| 212 | \& use CGI; # load CGI routines |
| 213 | \& $q = new CGI; # create new CGI object |
| 214 | \& print $q->header, # create the HTTP header |
| 215 | \& $q->start_html('hello world'), # start the HTML |
| 216 | \& $q->h1('hello world'), # level 1 header |
| 217 | \& $q->end_html; # end the HTML |
| 218 | .Ve |
| 219 | .PP |
| 220 | In the function-oriented style, there is one default \s-1CGI\s0 object that |
| 221 | you rarely deal with directly. Instead you just call functions to |
| 222 | retrieve \s-1CGI\s0 parameters, create \s-1HTML\s0 tags, manage cookies, and so |
| 223 | on. This provides you with a cleaner programming interface, but |
| 224 | limits you to using one \s-1CGI\s0 object at a time. The following example |
| 225 | prints the same page, but uses the function-oriented interface. |
| 226 | The main differences are that we now need to import a set of functions |
| 227 | into our name space (usually the \*(L"standard\*(R" functions), and we don't |
| 228 | need to create the \s-1CGI\s0 object. |
| 229 | .PP |
| 230 | .Vb 6 |
| 231 | \& #!/usr/local/bin/perl |
| 232 | \& use CGI qw/:standard/; # load standard CGI routines |
| 233 | \& print header, # create the HTTP header |
| 234 | \& start_html('hello world'), # start the HTML |
| 235 | \& h1('hello world'), # level 1 header |
| 236 | \& end_html; # end the HTML |
| 237 | .Ve |
| 238 | .PP |
| 239 | The examples in this document mainly use the object-oriented style. |
| 240 | See \s-1HOW\s0 \s-1TO\s0 \s-1IMPORT\s0 \s-1FUNCTIONS\s0 for important information on |
| 241 | function-oriented programming in \s-1CGI\s0.pm |
| 242 | .Sh "\s-1CALLING\s0 \s-1CGI\s0.PM \s-1ROUTINES\s0" |
| 243 | .IX Subsection "CALLING CGI.PM ROUTINES" |
| 244 | Most \s-1CGI\s0.pm routines accept several arguments, sometimes as many as 20 |
| 245 | optional ones! To simplify this interface, all routines use a named |
| 246 | argument calling style that looks like this: |
| 247 | .PP |
| 248 | .Vb 1 |
| 249 | \& print $q->header(-type=>'image/gif',-expires=>'+3d'); |
| 250 | .Ve |
| 251 | .PP |
| 252 | Each argument name is preceded by a dash. Neither case nor order |
| 253 | matters in the argument list. \-type, \-Type, and \-TYPE are all |
| 254 | acceptable. In fact, only the first argument needs to begin with a |
| 255 | dash. If a dash is present in the first argument, \s-1CGI\s0.pm assumes |
| 256 | dashes for the subsequent ones. |
| 257 | .PP |
| 258 | Several routines are commonly called with just one argument. In the |
| 259 | case of these routines you can provide the single argument without an |
| 260 | argument name. \fIheader()\fR happens to be one of these routines. In this |
| 261 | case, the single argument is the document type. |
| 262 | .PP |
| 263 | .Vb 1 |
| 264 | \& print $q->header('text/html'); |
| 265 | .Ve |
| 266 | .PP |
| 267 | Other such routines are documented below. |
| 268 | .PP |
| 269 | Sometimes named arguments expect a scalar, sometimes a reference to an |
| 270 | array, and sometimes a reference to a hash. Often, you can pass any |
| 271 | type of argument and the routine will do whatever is most appropriate. |
| 272 | For example, the \fIparam()\fR routine is used to set a \s-1CGI\s0 parameter to a |
| 273 | single or a multi-valued value. The two cases are shown below: |
| 274 | .PP |
| 275 | .Vb 2 |
| 276 | \& $q->param(-name=>'veggie',-value=>'tomato'); |
| 277 | \& $q->param(-name=>'veggie',-value=>['tomato','tomahto','potato','potahto']); |
| 278 | .Ve |
| 279 | .PP |
| 280 | A large number of routines in \s-1CGI\s0.pm actually aren't specifically |
| 281 | defined in the module, but are generated automatically as needed. |
| 282 | These are the \*(L"\s-1HTML\s0 shortcuts,\*(R" routines that generate \s-1HTML\s0 tags for |
| 283 | use in dynamically-generated pages. \s-1HTML\s0 tags have both attributes |
| 284 | (the attribute=\*(L"value\*(R" pairs within the tag itself) and contents (the |
| 285 | part between the opening and closing pairs.) To distinguish between |
| 286 | attributes and contents, \s-1CGI\s0.pm uses the convention of passing \s-1HTML\s0 |
| 287 | attributes as a hash reference as the first argument, and the |
| 288 | contents, if any, as any subsequent arguments. It works out like |
| 289 | this: |
| 290 | .PP |
| 291 | .Vb 6 |
| 292 | \& Code Generated HTML |
| 293 | \& ---- -------------- |
| 294 | \& h1() <h1> |
| 295 | \& h1('some','contents'); <h1>some contents</h1> |
| 296 | \& h1({-align=>left}); <h1 ALIGN="LEFT"> |
| 297 | \& h1({-align=>left},'contents'); <h1 ALIGN="LEFT">contents</h1> |
| 298 | .Ve |
| 299 | .PP |
| 300 | \&\s-1HTML\s0 tags are described in more detail later. |
| 301 | .PP |
| 302 | Many newcomers to \s-1CGI\s0.pm are puzzled by the difference between the |
| 303 | calling conventions for the \s-1HTML\s0 shortcuts, which require curly braces |
| 304 | around the \s-1HTML\s0 tag attributes, and the calling conventions for other |
| 305 | routines, which manage to generate attributes without the curly |
| 306 | brackets. Don't be confused. As a convenience the curly braces are |
| 307 | optional in all but the \s-1HTML\s0 shortcuts. If you like, you can use |
| 308 | curly braces when calling any routine that takes named arguments. For |
| 309 | example: |
| 310 | .PP |
| 311 | .Vb 1 |
| 312 | \& print $q->header( {-type=>'image/gif',-expires=>'+3d'} ); |
| 313 | .Ve |
| 314 | .PP |
| 315 | If you use the \fB\-w\fR switch, you will be warned that some \s-1CGI\s0.pm argument |
| 316 | names conflict with built-in Perl functions. The most frequent of |
| 317 | these is the \-values argument, used to create multi-valued menus, |
| 318 | radio button clusters and the like. To get around this warning, you |
| 319 | have several choices: |
| 320 | .IP "1." 4 |
| 321 | Use another name for the argument, if one is available. |
| 322 | For example, \-value is an alias for \-values. |
| 323 | .IP "2." 4 |
| 324 | Change the capitalization, e.g. \-Values |
| 325 | .IP "3." 4 |
| 326 | Put quotes around the argument name, e.g. '\-values' |
| 327 | .PP |
| 328 | Many routines will do something useful with a named argument that it |
| 329 | doesn't recognize. For example, you can produce non-standard \s-1HTTP\s0 |
| 330 | header fields by providing them as named arguments: |
| 331 | .PP |
| 332 | .Vb 4 |
| 333 | \& print $q->header(-type => 'text/html', |
| 334 | \& -cost => 'Three smackers', |
| 335 | \& -annoyance_level => 'high', |
| 336 | \& -complaints_to => 'bit bucket'); |
| 337 | .Ve |
| 338 | .PP |
| 339 | This will produce the following nonstandard \s-1HTTP\s0 header: |
| 340 | .PP |
| 341 | .Vb 5 |
| 342 | \& HTTP/1.0 200 OK |
| 343 | \& Cost: Three smackers |
| 344 | \& Annoyance-level: high |
| 345 | \& Complaints-to: bit bucket |
| 346 | \& Content-type: text/html |
| 347 | .Ve |
| 348 | .PP |
| 349 | Notice the way that underscores are translated automatically into |
| 350 | hyphens. HTML-generating routines perform a different type of |
| 351 | translation. |
| 352 | .PP |
| 353 | This feature allows you to keep up with the rapidly changing \s-1HTTP\s0 and |
| 354 | \&\s-1HTML\s0 \*(L"standards\*(R". |
| 355 | .Sh "\s-1CREATING\s0 A \s-1NEW\s0 \s-1QUERY\s0 \s-1OBJECT\s0 (\s-1OBJECT\-ORIENTED\s0 \s-1STYLE\s0):" |
| 356 | .IX Subsection "CREATING A NEW QUERY OBJECT (OBJECT-ORIENTED STYLE):" |
| 357 | .Vb 1 |
| 358 | \& $query = new CGI; |
| 359 | .Ve |
| 360 | .PP |
| 361 | This will parse the input (from both \s-1POST\s0 and \s-1GET\s0 methods) and store |
| 362 | it into a perl5 object called \f(CW$query\fR. |
| 363 | .Sh "\s-1CREATING\s0 A \s-1NEW\s0 \s-1QUERY\s0 \s-1OBJECT\s0 \s-1FROM\s0 \s-1AN\s0 \s-1INPUT\s0 \s-1FILE\s0" |
| 364 | .IX Subsection "CREATING A NEW QUERY OBJECT FROM AN INPUT FILE" |
| 365 | .Vb 1 |
| 366 | \& $query = new CGI(INPUTFILE); |
| 367 | .Ve |
| 368 | .PP |
| 369 | If you provide a file handle to the \fInew()\fR method, it will read |
| 370 | parameters from the file (or \s-1STDIN\s0, or whatever). The file can be in |
| 371 | any of the forms describing below under debugging (i.e. a series of |
| 372 | newline delimited TAG=VALUE pairs will work). Conveniently, this type |
| 373 | of file is created by the \fIsave()\fR method (see below). Multiple records |
| 374 | can be saved and restored. |
| 375 | .PP |
| 376 | Perl purists will be pleased to know that this syntax accepts |
| 377 | references to file handles, or even references to filehandle globs, |
| 378 | which is the \*(L"official\*(R" way to pass a filehandle: |
| 379 | .PP |
| 380 | .Vb 1 |
| 381 | \& $query = new CGI(\e*STDIN); |
| 382 | .Ve |
| 383 | .PP |
| 384 | You can also initialize the \s-1CGI\s0 object with a FileHandle or IO::File |
| 385 | object. |
| 386 | .PP |
| 387 | If you are using the function-oriented interface and want to |
| 388 | initialize \s-1CGI\s0 state from a file handle, the way to do this is with |
| 389 | \&\fB\f(BIrestore_parameters()\fB\fR. This will (re)initialize the |
| 390 | default \s-1CGI\s0 object from the indicated file handle. |
| 391 | .PP |
| 392 | .Vb 3 |
| 393 | \& open (IN,"test.in") || die; |
| 394 | \& restore_parameters(IN); |
| 395 | \& close IN; |
| 396 | .Ve |
| 397 | .PP |
| 398 | You can also initialize the query object from an associative array |
| 399 | reference: |
| 400 | .PP |
| 401 | .Vb 4 |
| 402 | \& $query = new CGI( {'dinosaur'=>'barney', |
| 403 | \& 'song'=>'I love you', |
| 404 | \& 'friends'=>[qw/Jessica George Nancy/]} |
| 405 | \& ); |
| 406 | .Ve |
| 407 | .PP |
| 408 | or from a properly formatted, URL-escaped query string: |
| 409 | .PP |
| 410 | .Vb 1 |
| 411 | \& $query = new CGI('dinosaur=barney&color=purple'); |
| 412 | .Ve |
| 413 | .PP |
| 414 | or from a previously existing \s-1CGI\s0 object (currently this clones the |
| 415 | parameter list, but none of the other object-specific fields, such as |
| 416 | autoescaping): |
| 417 | .PP |
| 418 | .Vb 2 |
| 419 | \& $old_query = new CGI; |
| 420 | \& $new_query = new CGI($old_query); |
| 421 | .Ve |
| 422 | .PP |
| 423 | To create an empty query, initialize it from an empty string or hash: |
| 424 | .PP |
| 425 | .Vb 1 |
| 426 | \& $empty_query = new CGI(""); |
| 427 | .Ve |
| 428 | .PP |
| 429 | .Vb 1 |
| 430 | \& -or- |
| 431 | .Ve |
| 432 | .PP |
| 433 | .Vb 1 |
| 434 | \& $empty_query = new CGI({}); |
| 435 | .Ve |
| 436 | .Sh "\s-1FETCHING\s0 A \s-1LIST\s0 \s-1OF\s0 \s-1KEYWORDS\s0 \s-1FROM\s0 \s-1THE\s0 \s-1QUERY:\s0" |
| 437 | .IX Subsection "FETCHING A LIST OF KEYWORDS FROM THE QUERY:" |
| 438 | .Vb 1 |
| 439 | \& @keywords = $query->keywords |
| 440 | .Ve |
| 441 | .PP |
| 442 | If the script was invoked as the result of an <\s-1ISINDEX\s0> search, the |
| 443 | parsed keywords can be obtained as an array using the \fIkeywords()\fR method. |
| 444 | .Sh "\s-1FETCHING\s0 \s-1THE\s0 \s-1NAMES\s0 \s-1OF\s0 \s-1ALL\s0 \s-1THE\s0 \s-1PARAMETERS\s0 \s-1PASSED\s0 \s-1TO\s0 \s-1YOUR\s0 \s-1SCRIPT:\s0" |
| 445 | .IX Subsection "FETCHING THE NAMES OF ALL THE PARAMETERS PASSED TO YOUR SCRIPT:" |
| 446 | .Vb 1 |
| 447 | \& @names = $query->param |
| 448 | .Ve |
| 449 | .PP |
| 450 | If the script was invoked with a parameter list |
| 451 | (e.g. \*(L"name1=value1&name2=value2&name3=value3\*(R"), the \fIparam()\fR method |
| 452 | will return the parameter names as a list. If the script was invoked |
| 453 | as an <\s-1ISINDEX\s0> script and contains a string without ampersands |
| 454 | (e.g. \*(L"value1+value2+value3\*(R") , there will be a single parameter named |
| 455 | \&\*(L"keywords\*(R" containing the \*(L"+\*(R"\-delimited keywords. |
| 456 | .PP |
| 457 | \&\s-1NOTE:\s0 As of version 1.5, the array of parameter names returned will |
| 458 | be in the same order as they were submitted by the browser. |
| 459 | Usually this order is the same as the order in which the |
| 460 | parameters are defined in the form (however, this isn't part |
| 461 | of the spec, and so isn't guaranteed). |
| 462 | .Sh "\s-1FETCHING\s0 \s-1THE\s0 \s-1VALUE\s0 \s-1OR\s0 \s-1VALUES\s0 \s-1OF\s0 A \s-1SINGLE\s0 \s-1NAMED\s0 \s-1PARAMETER:\s0" |
| 463 | .IX Subsection "FETCHING THE VALUE OR VALUES OF A SINGLE NAMED PARAMETER:" |
| 464 | .Vb 1 |
| 465 | \& @values = $query->param('foo'); |
| 466 | .Ve |
| 467 | .PP |
| 468 | .Vb 1 |
| 469 | \& -or- |
| 470 | .Ve |
| 471 | .PP |
| 472 | .Vb 1 |
| 473 | \& $value = $query->param('foo'); |
| 474 | .Ve |
| 475 | .PP |
| 476 | Pass the \fIparam()\fR method a single argument to fetch the value of the |
| 477 | named parameter. If the parameter is multivalued (e.g. from multiple |
| 478 | selections in a scrolling list), you can ask to receive an array. Otherwise |
| 479 | the method will return a single value. |
| 480 | .PP |
| 481 | If a value is not given in the query string, as in the queries |
| 482 | \&\*(L"name1=&name2=\*(R" or \*(L"name1&name2\*(R", it will be returned as an empty |
| 483 | string. This feature is new in 2.63. |
| 484 | .Sh "\s-1SETTING\s0 \s-1THE\s0 \s-1VALUE\s0(S) \s-1OF\s0 A \s-1NAMED\s0 \s-1PARAMETER:\s0" |
| 485 | .IX Subsection "SETTING THE VALUE(S) OF A NAMED PARAMETER:" |
| 486 | .Vb 1 |
| 487 | \& $query->param('foo','an','array','of','values'); |
| 488 | .Ve |
| 489 | .PP |
| 490 | This sets the value for the named parameter 'foo' to an array of |
| 491 | values. This is one way to change the value of a field \s-1AFTER\s0 |
| 492 | the script has been invoked once before. (Another way is with |
| 493 | the \-override parameter accepted by all methods that generate |
| 494 | form elements.) |
| 495 | .PP |
| 496 | \&\fIparam()\fR also recognizes a named parameter style of calling described |
| 497 | in more detail later: |
| 498 | .PP |
| 499 | .Vb 1 |
| 500 | \& $query->param(-name=>'foo',-values=>['an','array','of','values']); |
| 501 | .Ve |
| 502 | .PP |
| 503 | .Vb 1 |
| 504 | \& -or- |
| 505 | .Ve |
| 506 | .PP |
| 507 | .Vb 1 |
| 508 | \& $query->param(-name=>'foo',-value=>'the value'); |
| 509 | .Ve |
| 510 | .Sh "\s-1APPENDING\s0 \s-1ADDITIONAL\s0 \s-1VALUES\s0 \s-1TO\s0 A \s-1NAMED\s0 \s-1PARAMETER:\s0" |
| 511 | .IX Subsection "APPENDING ADDITIONAL VALUES TO A NAMED PARAMETER:" |
| 512 | .Vb 1 |
| 513 | \& $query->append(-name=>'foo',-values=>['yet','more','values']); |
| 514 | .Ve |
| 515 | .PP |
| 516 | This adds a value or list of values to the named parameter. The |
| 517 | values are appended to the end of the parameter if it already exists. |
| 518 | Otherwise the parameter is created. Note that this method only |
| 519 | recognizes the named argument calling syntax. |
| 520 | .Sh "\s-1IMPORTING\s0 \s-1ALL\s0 \s-1PARAMETERS\s0 \s-1INTO\s0 A \s-1NAMESPACE:\s0" |
| 521 | .IX Subsection "IMPORTING ALL PARAMETERS INTO A NAMESPACE:" |
| 522 | .Vb 1 |
| 523 | \& $query->import_names('R'); |
| 524 | .Ve |
| 525 | .PP |
| 526 | This creates a series of variables in the 'R' namespace. For example, |
| 527 | \&\f(CW$R::foo\fR, \f(CW@R:foo\fR. For keyword lists, a variable \f(CW@R::keywords\fR will appear. |
| 528 | If no namespace is given, this method will assume 'Q'. |
| 529 | \&\s-1WARNING:\s0 don't import anything into 'main'; this is a major security |
| 530 | risk!!!! |
| 531 | .PP |
| 532 | In older versions, this method was called \fB\f(BIimport()\fB\fR. As of version 2.20, |
| 533 | this name has been removed completely to avoid conflict with the built-in |
| 534 | Perl module \fBimport\fR operator. |
| 535 | .Sh "\s-1DELETING\s0 A \s-1PARAMETER\s0 \s-1COMPLETELY:\s0" |
| 536 | .IX Subsection "DELETING A PARAMETER COMPLETELY:" |
| 537 | .Vb 1 |
| 538 | \& $query->delete('foo'); |
| 539 | .Ve |
| 540 | .PP |
| 541 | This completely clears a parameter. It sometimes useful for |
| 542 | resetting parameters that you don't want passed down between |
| 543 | script invocations. |
| 544 | .PP |
| 545 | If you are using the function call interface, use \*(L"\fIDelete()\fR\*(R" instead |
| 546 | to avoid conflicts with Perl's built-in delete operator. |
| 547 | .Sh "\s-1DELETING\s0 \s-1ALL\s0 \s-1PARAMETERS:\s0" |
| 548 | .IX Subsection "DELETING ALL PARAMETERS:" |
| 549 | .Vb 1 |
| 550 | \& $query->delete_all(); |
| 551 | .Ve |
| 552 | .PP |
| 553 | This clears the \s-1CGI\s0 object completely. It might be useful to ensure |
| 554 | that all the defaults are taken when you create a fill-out form. |
| 555 | .PP |
| 556 | Use \fIDelete_all()\fR instead if you are using the function call interface. |
| 557 | .Sh "\s-1DIRECT\s0 \s-1ACCESS\s0 \s-1TO\s0 \s-1THE\s0 \s-1PARAMETER\s0 \s-1LIST:\s0" |
| 558 | .IX Subsection "DIRECT ACCESS TO THE PARAMETER LIST:" |
| 559 | .Vb 2 |
| 560 | \& $q->param_fetch('address')->[1] = '1313 Mockingbird Lane'; |
| 561 | \& unshift @{$q->param_fetch(-name=>'address')},'George Munster'; |
| 562 | .Ve |
| 563 | .PP |
| 564 | If you need access to the parameter list in a way that isn't covered |
| 565 | by the methods above, you can obtain a direct reference to it by |
| 566 | calling the \fB\f(BIparam_fetch()\fB\fR method with the name of the . This |
| 567 | will return an array reference to the named parameters, which you then |
| 568 | can manipulate in any way you like. |
| 569 | .PP |
| 570 | You can also use a named argument style using the \fB\-name\fR argument. |
| 571 | .Sh "\s-1FETCHING\s0 \s-1THE\s0 \s-1PARAMETER\s0 \s-1LIST\s0 \s-1AS\s0 A \s-1HASH:\s0" |
| 572 | .IX Subsection "FETCHING THE PARAMETER LIST AS A HASH:" |
| 573 | .Vb 4 |
| 574 | \& $params = $q->Vars; |
| 575 | \& print $params->{'address'}; |
| 576 | \& @foo = split("\e0",$params->{'foo'}); |
| 577 | \& %params = $q->Vars; |
| 578 | .Ve |
| 579 | .PP |
| 580 | .Vb 2 |
| 581 | \& use CGI ':cgi-lib'; |
| 582 | \& $params = Vars; |
| 583 | .Ve |
| 584 | .PP |
| 585 | Many people want to fetch the entire parameter list as a hash in which |
| 586 | the keys are the names of the \s-1CGI\s0 parameters, and the values are the |
| 587 | parameters' values. The \fIVars()\fR method does this. Called in a scalar |
| 588 | context, it returns the parameter list as a tied hash reference. |
| 589 | Changing a key changes the value of the parameter in the underlying |
| 590 | \&\s-1CGI\s0 parameter list. Called in a list context, it returns the |
| 591 | parameter list as an ordinary hash. This allows you to read the |
| 592 | contents of the parameter list, but not to change it. |
| 593 | .PP |
| 594 | When using this, the thing you must watch out for are multivalued \s-1CGI\s0 |
| 595 | parameters. Because a hash cannot distinguish between scalar and |
| 596 | list context, multivalued parameters will be returned as a packed |
| 597 | string, separated by the \*(L"\e0\*(R" (null) character. You must split this |
| 598 | packed string in order to get at the individual values. This is the |
| 599 | convention introduced long ago by Steve Brenner in his cgi\-lib.pl |
| 600 | module for Perl version 4. |
| 601 | .PP |
| 602 | If you wish to use \fIVars()\fR as a function, import the \fI:cgi\-lib\fR set of |
| 603 | function calls (also see the section on CGI-LIB compatibility). |
| 604 | .Sh "\s-1SAVING\s0 \s-1THE\s0 \s-1STATE\s0 \s-1OF\s0 \s-1THE\s0 \s-1SCRIPT\s0 \s-1TO\s0 A \s-1FILE:\s0" |
| 605 | .IX Subsection "SAVING THE STATE OF THE SCRIPT TO A FILE:" |
| 606 | .Vb 1 |
| 607 | \& $query->save(FILEHANDLE) |
| 608 | .Ve |
| 609 | .PP |
| 610 | This will write the current state of the form to the provided |
| 611 | filehandle. You can read it back in by providing a filehandle |
| 612 | to the \fInew()\fR method. Note that the filehandle can be a file, a pipe, |
| 613 | or whatever! |
| 614 | .PP |
| 615 | The format of the saved file is: |
| 616 | .PP |
| 617 | .Vb 5 |
| 618 | \& NAME1=VALUE1 |
| 619 | \& NAME1=VALUE1' |
| 620 | \& NAME2=VALUE2 |
| 621 | \& NAME3=VALUE3 |
| 622 | \& = |
| 623 | .Ve |
| 624 | .PP |
| 625 | Both name and value are \s-1URL\s0 escaped. Multi-valued \s-1CGI\s0 parameters are |
| 626 | represented as repeated names. A session record is delimited by a |
| 627 | single = symbol. You can write out multiple records and read them |
| 628 | back in with several calls to \fBnew\fR. You can do this across several |
| 629 | sessions by opening the file in append mode, allowing you to create |
| 630 | primitive guest books, or to keep a history of users' queries. Here's |
| 631 | a short example of creating multiple session records: |
| 632 | .PP |
| 633 | .Vb 1 |
| 634 | \& use CGI; |
| 635 | .Ve |
| 636 | .PP |
| 637 | .Vb 8 |
| 638 | \& open (OUT,">>test.out") || die; |
| 639 | \& $records = 5; |
| 640 | \& foreach (0..$records) { |
| 641 | \& my $q = new CGI; |
| 642 | \& $q->param(-name=>'counter',-value=>$_); |
| 643 | \& $q->save(OUT); |
| 644 | \& } |
| 645 | \& close OUT; |
| 646 | .Ve |
| 647 | .PP |
| 648 | .Vb 6 |
| 649 | \& # reopen for reading |
| 650 | \& open (IN,"test.out") || die; |
| 651 | \& while (!eof(IN)) { |
| 652 | \& my $q = new CGI(IN); |
| 653 | \& print $q->param('counter'),"\en"; |
| 654 | \& } |
| 655 | .Ve |
| 656 | .PP |
| 657 | The file format used for save/restore is identical to that used by the |
| 658 | Whitehead Genome Center's data exchange format \*(L"Boulderio\*(R", and can be |
| 659 | manipulated and even databased using Boulderio utilities. See |
| 660 | .PP |
| 661 | .Vb 1 |
| 662 | \& http://stein.cshl.org/boulder/ |
| 663 | .Ve |
| 664 | .PP |
| 665 | for further details. |
| 666 | .PP |
| 667 | If you wish to use this method from the function-oriented (non\-OO) |
| 668 | interface, the exported name for this method is \fB\f(BIsave_parameters()\fB\fR. |
| 669 | .Sh "\s-1RETRIEVING\s0 \s-1CGI\s0 \s-1ERRORS\s0" |
| 670 | .IX Subsection "RETRIEVING CGI ERRORS" |
| 671 | Errors can occur while processing user input, particularly when |
| 672 | processing uploaded files. When these errors occur, \s-1CGI\s0 will stop |
| 673 | processing and return an empty parameter list. You can test for |
| 674 | the existence and nature of errors using the \fI\fIcgi_error()\fI\fR function. |
| 675 | The error messages are formatted as \s-1HTTP\s0 status codes. You can either |
| 676 | incorporate the error text into an \s-1HTML\s0 page, or use it as the value |
| 677 | of the \s-1HTTP\s0 status: |
| 678 | .PP |
| 679 | .Vb 8 |
| 680 | \& my $error = $q->cgi_error; |
| 681 | \& if ($error) { |
| 682 | \& print $q->header(-status=>$error), |
| 683 | \& $q->start_html('Problems'), |
| 684 | \& $q->h2('Request not processed'), |
| 685 | \& $q->strong($error); |
| 686 | \& exit 0; |
| 687 | \& } |
| 688 | .Ve |
| 689 | .PP |
| 690 | When using the function-oriented interface (see the next section), |
| 691 | errors may only occur the first time you call \fI\fIparam()\fI\fR. Be ready |
| 692 | for this! |
| 693 | .Sh "\s-1USING\s0 \s-1THE\s0 FUNCTION-ORIENTED \s-1INTERFACE\s0" |
| 694 | .IX Subsection "USING THE FUNCTION-ORIENTED INTERFACE" |
| 695 | To use the function-oriented interface, you must specify which \s-1CGI\s0.pm |
| 696 | routines or sets of routines to import into your script's namespace. |
| 697 | There is a small overhead associated with this importation, but it |
| 698 | isn't much. |
| 699 | .PP |
| 700 | .Vb 1 |
| 701 | \& use CGI <list of methods>; |
| 702 | .Ve |
| 703 | .PP |
| 704 | The listed methods will be imported into the current package; you can |
| 705 | call them directly without creating a \s-1CGI\s0 object first. This example |
| 706 | shows how to import the \fB\f(BIparam()\fB\fR and \fB\f(BIheader()\fB\fR |
| 707 | methods, and then use them directly: |
| 708 | .PP |
| 709 | .Vb 3 |
| 710 | \& use CGI 'param','header'; |
| 711 | \& print header('text/plain'); |
| 712 | \& $zipcode = param('zipcode'); |
| 713 | .Ve |
| 714 | .PP |
| 715 | More frequently, you'll import common sets of functions by referring |
| 716 | to the groups by name. All function sets are preceded with a \*(L":\*(R" |
| 717 | character as in \*(L":html3\*(R" (for tags defined in the \s-1HTML\s0 3 standard). |
| 718 | .PP |
| 719 | Here is a list of the function sets you can import: |
| 720 | .IP "\fB:cgi\fR" 4 |
| 721 | .IX Item ":cgi" |
| 722 | Import all CGI-handling methods, such as \fB\f(BIparam()\fB\fR, \fB\f(BIpath_info()\fB\fR |
| 723 | and the like. |
| 724 | .IP "\fB:form\fR" 4 |
| 725 | .IX Item ":form" |
| 726 | Import all fill-out form generating methods, such as \fB\f(BItextfield()\fB\fR. |
| 727 | .IP "\fB:html2\fR" 4 |
| 728 | .IX Item ":html2" |
| 729 | Import all methods that generate \s-1HTML\s0 2.0 standard elements. |
| 730 | .IP "\fB:html3\fR" 4 |
| 731 | .IX Item ":html3" |
| 732 | Import all methods that generate \s-1HTML\s0 3.0 elements (such as |
| 733 | <table>, <super> and <sub>). |
| 734 | .IP "\fB:html4\fR" 4 |
| 735 | .IX Item ":html4" |
| 736 | Import all methods that generate \s-1HTML\s0 4 elements (such as |
| 737 | <abbrev>, <acronym> and <thead>). |
| 738 | .IP "\fB:netscape\fR" 4 |
| 739 | .IX Item ":netscape" |
| 740 | Import all methods that generate Netscape-specific \s-1HTML\s0 extensions. |
| 741 | .IP "\fB:html\fR" 4 |
| 742 | .IX Item ":html" |
| 743 | Import all HTML-generating shortcuts (i.e. 'html2' + 'html3' + |
| 744 | \&'netscape')... |
| 745 | .IP "\fB:standard\fR" 4 |
| 746 | .IX Item ":standard" |
| 747 | Import \*(L"standard\*(R" features, 'html2', 'html3', 'html4', 'form' and 'cgi'. |
| 748 | .IP "\fB:all\fR" 4 |
| 749 | .IX Item ":all" |
| 750 | Import all the available methods. For the full list, see the \s-1CGI\s0.pm |
| 751 | code, where the variable \f(CW%EXPORT_TAGS\fR is defined. |
| 752 | .PP |
| 753 | If you import a function name that is not part of \s-1CGI\s0.pm, the module |
| 754 | will treat it as a new \s-1HTML\s0 tag and generate the appropriate |
| 755 | subroutine. You can then use it like any other \s-1HTML\s0 tag. This is to |
| 756 | provide for the rapidly-evolving \s-1HTML\s0 \*(L"standard.\*(R" For example, say |
| 757 | Microsoft comes out with a new tag called <gradient> (which causes the |
| 758 | user's desktop to be flooded with a rotating gradient fill until his |
| 759 | machine reboots). You don't need to wait for a new version of \s-1CGI\s0.pm |
| 760 | to start using it immediately: |
| 761 | .PP |
| 762 | .Vb 2 |
| 763 | \& use CGI qw/:standard :html3 gradient/; |
| 764 | \& print gradient({-start=>'red',-end=>'blue'}); |
| 765 | .Ve |
| 766 | .PP |
| 767 | Note that in the interests of execution speed \s-1CGI\s0.pm does \fBnot\fR use |
| 768 | the standard Exporter syntax for specifying load symbols. This may |
| 769 | change in the future. |
| 770 | .PP |
| 771 | If you import any of the state-maintaining \s-1CGI\s0 or form-generating |
| 772 | methods, a default \s-1CGI\s0 object will be created and initialized |
| 773 | automatically the first time you use any of the methods that require |
| 774 | one to be present. This includes \fB\f(BIparam()\fB\fR, \fB\f(BItextfield()\fB\fR, |
| 775 | \&\fB\f(BIsubmit()\fB\fR and the like. (If you need direct access to the \s-1CGI\s0 |
| 776 | object, you can find it in the global variable \fB$CGI::Q\fR). By |
| 777 | importing \s-1CGI\s0.pm methods, you can create visually elegant scripts: |
| 778 | .PP |
| 779 | .Vb 17 |
| 780 | \& use CGI qw/:standard/; |
| 781 | \& print |
| 782 | \& header, |
| 783 | \& start_html('Simple Script'), |
| 784 | \& h1('Simple Script'), |
| 785 | \& start_form, |
| 786 | \& "What's your name? ",textfield('name'),p, |
| 787 | \& "What's the combination?", |
| 788 | \& checkbox_group(-name=>'words', |
| 789 | \& -values=>['eenie','meenie','minie','moe'], |
| 790 | \& -defaults=>['eenie','moe']),p, |
| 791 | \& "What's your favorite color?", |
| 792 | \& popup_menu(-name=>'color', |
| 793 | \& -values=>['red','green','blue','chartreuse']),p, |
| 794 | \& submit, |
| 795 | \& end_form, |
| 796 | \& hr,"\en"; |
| 797 | .Ve |
| 798 | .PP |
| 799 | .Vb 7 |
| 800 | \& if (param) { |
| 801 | \& print |
| 802 | \& "Your name is ",em(param('name')),p, |
| 803 | \& "The keywords are: ",em(join(", ",param('words'))),p, |
| 804 | \& "Your favorite color is ",em(param('color')),".\en"; |
| 805 | \& } |
| 806 | \& print end_html; |
| 807 | .Ve |
| 808 | .Sh "\s-1PRAGMAS\s0" |
| 809 | .IX Subsection "PRAGMAS" |
| 810 | In addition to the function sets, there are a number of pragmas that |
| 811 | you can import. Pragmas, which are always preceded by a hyphen, |
| 812 | change the way that \s-1CGI\s0.pm functions in various ways. Pragmas, |
| 813 | function sets, and individual functions can all be imported in the |
| 814 | same \fIuse()\fR line. For example, the following use statement imports the |
| 815 | standard set of functions and enables debugging mode (pragma |
| 816 | \&\-debug): |
| 817 | .PP |
| 818 | .Vb 1 |
| 819 | \& use CGI qw/:standard -debug/; |
| 820 | .Ve |
| 821 | .PP |
| 822 | The current list of pragmas is as follows: |
| 823 | .IP "\-any" 4 |
| 824 | .IX Item "-any" |
| 825 | When you \fIuse \s-1CGI\s0 \-any\fR, then any method that the query object |
| 826 | doesn't recognize will be interpreted as a new \s-1HTML\s0 tag. This allows |
| 827 | you to support the next \fIad hoc\fR Netscape or Microsoft \s-1HTML\s0 |
| 828 | extension. This lets you go wild with new and unsupported tags: |
| 829 | .Sp |
| 830 | .Vb 3 |
| 831 | \& use CGI qw(-any); |
| 832 | \& $q=new CGI; |
| 833 | \& print $q->gradient({speed=>'fast',start=>'red',end=>'blue'}); |
| 834 | .Ve |
| 835 | .Sp |
| 836 | Since using <cite>any</cite> causes any mistyped method name |
| 837 | to be interpreted as an \s-1HTML\s0 tag, use it with care or not at |
| 838 | all. |
| 839 | .IP "\-compile" 4 |
| 840 | .IX Item "-compile" |
| 841 | This causes the indicated autoloaded methods to be compiled up front, |
| 842 | rather than deferred to later. This is useful for scripts that run |
| 843 | for an extended period of time under FastCGI or mod_perl, and for |
| 844 | those destined to be crunched by Malcom Beattie's Perl compiler. Use |
| 845 | it in conjunction with the methods or method families you plan to use. |
| 846 | .Sp |
| 847 | .Vb 1 |
| 848 | \& use CGI qw(-compile :standard :html3); |
| 849 | .Ve |
| 850 | .Sp |
| 851 | or even |
| 852 | .Sp |
| 853 | .Vb 1 |
| 854 | \& use CGI qw(-compile :all); |
| 855 | .Ve |
| 856 | .Sp |
| 857 | Note that using the \-compile pragma in this way will always have |
| 858 | the effect of importing the compiled functions into the current |
| 859 | namespace. If you want to compile without importing use the |
| 860 | \&\fIcompile()\fR method instead (see below). |
| 861 | .IP "\-nosticky" 4 |
| 862 | .IX Item "-nosticky" |
| 863 | This makes \s-1CGI\s0.pm not generating the hidden fields .submit |
| 864 | and .cgifields. It is very useful if you don't want to |
| 865 | have the hidden fields appear in the querystring in a \s-1GET\s0 method. |
| 866 | For example, a search script generated this way will have |
| 867 | a very nice url with search parameters for bookmarking. |
| 868 | .IP "\-no_undef_params" 4 |
| 869 | .IX Item "-no_undef_params" |
| 870 | This keeps \s-1CGI\s0.pm from including undef params in the parameter list. |
| 871 | .IP "\-no_xhtml" 4 |
| 872 | .IX Item "-no_xhtml" |
| 873 | By default, \s-1CGI\s0.pm versions 2.69 and higher emit \s-1XHTML\s0 |
| 874 | (http://www.w3.org/TR/xhtml1/). The \-no_xhtml pragma disables this |
| 875 | feature. Thanks to Michalis Kabrianis <kabrianis@hellug.gr> for this |
| 876 | feature. |
| 877 | .IP "\-nph" 4 |
| 878 | .IX Item "-nph" |
| 879 | This makes \s-1CGI\s0.pm produce a header appropriate for an \s-1NPH\s0 (no |
| 880 | parsed header) script. You may need to do other things as well |
| 881 | to tell the server that the script is \s-1NPH\s0. See the discussion |
| 882 | of \s-1NPH\s0 scripts below. |
| 883 | .IP "\-newstyle_urls" 4 |
| 884 | .IX Item "-newstyle_urls" |
| 885 | Separate the name=value pairs in \s-1CGI\s0 parameter query strings with |
| 886 | semicolons rather than ampersands. For example: |
| 887 | .Sp |
| 888 | .Vb 1 |
| 889 | \& ?name=fred;age=24;favorite_color=3 |
| 890 | .Ve |
| 891 | .Sp |
| 892 | Semicolon-delimited query strings are always accepted, but will not be |
| 893 | emitted by \fIself_url()\fR and \fIquery_string()\fR unless the \-newstyle_urls |
| 894 | pragma is specified. |
| 895 | .Sp |
| 896 | This became the default in version 2.64. |
| 897 | .IP "\-oldstyle_urls" 4 |
| 898 | .IX Item "-oldstyle_urls" |
| 899 | Separate the name=value pairs in \s-1CGI\s0 parameter query strings with |
| 900 | ampersands rather than semicolons. This is no longer the default. |
| 901 | .IP "\-autoload" 4 |
| 902 | .IX Item "-autoload" |
| 903 | This overrides the autoloader so that any function in your program |
| 904 | that is not recognized is referred to \s-1CGI\s0.pm for possible evaluation. |
| 905 | This allows you to use all the \s-1CGI\s0.pm functions without adding them to |
| 906 | your symbol table, which is of concern for mod_perl users who are |
| 907 | worried about memory consumption. \fIWarning:\fR when |
| 908 | \&\fI\-autoload\fR is in effect, you cannot use \*(L"poetry mode\*(R" |
| 909 | (functions without the parenthesis). Use \fI\fIhr()\fI\fR rather |
| 910 | than \fIhr\fR, or add something like \fIuse subs qw/hr p header/\fR |
| 911 | to the top of your script. |
| 912 | .IP "\-no_debug" 4 |
| 913 | .IX Item "-no_debug" |
| 914 | This turns off the command-line processing features. If you want to |
| 915 | run a \s-1CGI\s0.pm script from the command line to produce \s-1HTML\s0, and you |
| 916 | don't want it to read \s-1CGI\s0 parameters from the command line or \s-1STDIN\s0, |
| 917 | then use this pragma: |
| 918 | .Sp |
| 919 | .Vb 1 |
| 920 | \& use CGI qw(-no_debug :standard); |
| 921 | .Ve |
| 922 | .IP "\-debug" 4 |
| 923 | .IX Item "-debug" |
| 924 | This turns on full debugging. In addition to reading \s-1CGI\s0 arguments |
| 925 | from the command-line processing, \s-1CGI\s0.pm will pause and try to read |
| 926 | arguments from \s-1STDIN\s0, producing the message \*(L"(offline mode: enter |
| 927 | name=value pairs on standard input)\*(R" features. |
| 928 | .Sp |
| 929 | See the section on debugging for more details. |
| 930 | .IP "\-private_tempfiles" 4 |
| 931 | .IX Item "-private_tempfiles" |
| 932 | \&\s-1CGI\s0.pm can process uploaded file. Ordinarily it spools the uploaded |
| 933 | file to a temporary directory, then deletes the file when done. |
| 934 | However, this opens the risk of eavesdropping as described in the file |
| 935 | upload section. Another \s-1CGI\s0 script author could peek at this data |
| 936 | during the upload, even if it is confidential information. On Unix |
| 937 | systems, the \-private_tempfiles pragma will cause the temporary file |
| 938 | to be unlinked as soon as it is opened and before any data is written |
| 939 | into it, reducing, but not eliminating the risk of eavesdropping |
| 940 | (there is still a potential race condition). To make life harder for |
| 941 | the attacker, the program chooses tempfile names by calculating a 32 |
| 942 | bit checksum of the incoming \s-1HTTP\s0 headers. |
| 943 | .Sp |
| 944 | To ensure that the temporary file cannot be read by other \s-1CGI\s0 scripts, |
| 945 | use suEXEC or a \s-1CGI\s0 wrapper program to run your script. The temporary |
| 946 | file is created with mode 0600 (neither world nor group readable). |
| 947 | .Sp |
| 948 | The temporary directory is selected using the following algorithm: |
| 949 | .Sp |
| 950 | .Vb 2 |
| 951 | \& 1. if the current user (e.g. "nobody") has a directory named |
| 952 | \& "tmp" in its home directory, use that (Unix systems only). |
| 953 | .Ve |
| 954 | .Sp |
| 955 | .Vb 2 |
| 956 | \& 2. if the environment variable TMPDIR exists, use the location |
| 957 | \& indicated. |
| 958 | .Ve |
| 959 | .Sp |
| 960 | .Vb 2 |
| 961 | \& 3. Otherwise try the locations /usr/tmp, /var/tmp, C:\etemp, |
| 962 | \& /tmp, /temp, ::Temporary Items, and \eWWW_ROOT. |
| 963 | .Ve |
| 964 | .Sp |
| 965 | Each of these locations is checked that it is a directory and is |
| 966 | writable. If not, the algorithm tries the next choice. |
| 967 | .Sh "\s-1SPECIAL\s0 \s-1FORMS\s0 \s-1FOR\s0 \s-1IMPORTING\s0 HTML-TAG \s-1FUNCTIONS\s0" |
| 968 | .IX Subsection "SPECIAL FORMS FOR IMPORTING HTML-TAG FUNCTIONS" |
| 969 | Many of the methods generate \s-1HTML\s0 tags. As described below, tag |
| 970 | functions automatically generate both the opening and closing tags. |
| 971 | For example: |
| 972 | .PP |
| 973 | .Vb 1 |
| 974 | \& print h1('Level 1 Header'); |
| 975 | .Ve |
| 976 | .PP |
| 977 | produces |
| 978 | .PP |
| 979 | .Vb 1 |
| 980 | \& <h1>Level 1 Header</h1> |
| 981 | .Ve |
| 982 | .PP |
| 983 | There will be some times when you want to produce the start and end |
| 984 | tags yourself. In this case, you can use the form start_\fItag_name\fR |
| 985 | and end_\fItag_name\fR, as in: |
| 986 | .PP |
| 987 | .Vb 1 |
| 988 | \& print start_h1,'Level 1 Header',end_h1; |
| 989 | .Ve |
| 990 | .PP |
| 991 | With a few exceptions (described below), start_\fItag_name\fR and |
| 992 | end_\fItag_name\fR functions are not generated automatically when you |
| 993 | \&\fIuse \s-1CGI\s0\fR. However, you can specify the tags you want to generate |
| 994 | \&\fIstart/end\fR functions for by putting an asterisk in front of their |
| 995 | name, or, alternatively, requesting either "start_\fItag_name\fR\*(L" or |
| 996 | \&\*(R"end_\fItag_name\fR" in the import list. |
| 997 | .PP |
| 998 | Example: |
| 999 | .PP |
| 1000 | .Vb 1 |
| 1001 | \& use CGI qw/:standard *table start_ul/; |
| 1002 | .Ve |
| 1003 | .PP |
| 1004 | In this example, the following functions are generated in addition to |
| 1005 | the standard ones: |
| 1006 | .IP "1. \fIstart_table()\fR (generates a <table> tag)" 4 |
| 1007 | .IX Item "1. start_table() (generates a <table> tag)" |
| 1008 | .PD 0 |
| 1009 | .IP "2. \fIend_table()\fR (generates a </table> tag)" 4 |
| 1010 | .IX Item "2. end_table() (generates a </table> tag)" |
| 1011 | .IP "3. \fIstart_ul()\fR (generates a <ul> tag)" 4 |
| 1012 | .IX Item "3. start_ul() (generates a <ul> tag)" |
| 1013 | .IP "4. \fIend_ul()\fR (generates a </ul> tag)" 4 |
| 1014 | .IX Item "4. end_ul() (generates a </ul> tag)" |
| 1015 | .PD |
| 1016 | .SH "GENERATING DYNAMIC DOCUMENTS" |
| 1017 | .IX Header "GENERATING DYNAMIC DOCUMENTS" |
| 1018 | Most of \s-1CGI\s0.pm's functions deal with creating documents on the fly. |
| 1019 | Generally you will produce the \s-1HTTP\s0 header first, followed by the |
| 1020 | document itself. \s-1CGI\s0.pm provides functions for generating \s-1HTTP\s0 |
| 1021 | headers of various types as well as for generating \s-1HTML\s0. For creating |
| 1022 | \&\s-1GIF\s0 images, see the \s-1GD\s0.pm module. |
| 1023 | .PP |
| 1024 | Each of these functions produces a fragment of \s-1HTML\s0 or \s-1HTTP\s0 which you |
| 1025 | can print out directly so that it displays in the browser window, |
| 1026 | append to a string, or save to a file for later use. |
| 1027 | .Sh "\s-1CREATING\s0 A \s-1STANDARD\s0 \s-1HTTP\s0 \s-1HEADER:\s0" |
| 1028 | .IX Subsection "CREATING A STANDARD HTTP HEADER:" |
| 1029 | Normally the first thing you will do in any \s-1CGI\s0 script is print out an |
| 1030 | \&\s-1HTTP\s0 header. This tells the browser what type of document to expect, |
| 1031 | and gives other optional information, such as the language, expiration |
| 1032 | date, and whether to cache the document. The header can also be |
| 1033 | manipulated for special purposes, such as server push and pay per view |
| 1034 | pages. |
| 1035 | .PP |
| 1036 | .Vb 1 |
| 1037 | \& print $query->header; |
| 1038 | .Ve |
| 1039 | .PP |
| 1040 | .Vb 1 |
| 1041 | \& -or- |
| 1042 | .Ve |
| 1043 | .PP |
| 1044 | .Vb 1 |
| 1045 | \& print $query->header('image/gif'); |
| 1046 | .Ve |
| 1047 | .PP |
| 1048 | .Vb 1 |
| 1049 | \& -or- |
| 1050 | .Ve |
| 1051 | .PP |
| 1052 | .Vb 1 |
| 1053 | \& print $query->header('text/html','204 No response'); |
| 1054 | .Ve |
| 1055 | .PP |
| 1056 | .Vb 1 |
| 1057 | \& -or- |
| 1058 | .Ve |
| 1059 | .PP |
| 1060 | .Vb 8 |
| 1061 | \& print $query->header(-type=>'image/gif', |
| 1062 | \& -nph=>1, |
| 1063 | \& -status=>'402 Payment required', |
| 1064 | \& -expires=>'+3d', |
| 1065 | \& -cookie=>$cookie, |
| 1066 | \& -charset=>'utf-7', |
| 1067 | \& -attachment=>'foo.gif', |
| 1068 | \& -Cost=>'$2.00'); |
| 1069 | .Ve |
| 1070 | .PP |
| 1071 | \&\fIheader()\fR returns the Content\-type: header. You can provide your own |
| 1072 | \&\s-1MIME\s0 type if you choose, otherwise it defaults to text/html. An |
| 1073 | optional second parameter specifies the status code and a human-readable |
| 1074 | message. For example, you can specify 204, \*(L"No response\*(R" to create a |
| 1075 | script that tells the browser to do nothing at all. |
| 1076 | .PP |
| 1077 | The last example shows the named argument style for passing arguments |
| 1078 | to the \s-1CGI\s0 methods using named parameters. Recognized parameters are |
| 1079 | \&\fB\-type\fR, \fB\-status\fR, \fB\-expires\fR, and \fB\-cookie\fR. Any other named |
| 1080 | parameters will be stripped of their initial hyphens and turned into |
| 1081 | header fields, allowing you to specify any \s-1HTTP\s0 header you desire. |
| 1082 | Internal underscores will be turned into hyphens: |
| 1083 | .PP |
| 1084 | .Vb 1 |
| 1085 | \& print $query->header(-Content_length=>3002); |
| 1086 | .Ve |
| 1087 | .PP |
| 1088 | Most browsers will not cache the output from \s-1CGI\s0 scripts. Every time |
| 1089 | the browser reloads the page, the script is invoked anew. You can |
| 1090 | change this behavior with the \fB\-expires\fR parameter. When you specify |
| 1091 | an absolute or relative expiration interval with this parameter, some |
| 1092 | browsers and proxy servers will cache the script's output until the |
| 1093 | indicated expiration date. The following forms are all valid for the |
| 1094 | \&\-expires field: |
| 1095 | .PP |
| 1096 | .Vb 8 |
| 1097 | \& +30s 30 seconds from now |
| 1098 | \& +10m ten minutes from now |
| 1099 | \& +1h one hour from now |
| 1100 | \& -1d yesterday (i.e. "ASAP!") |
| 1101 | \& now immediately |
| 1102 | \& +3M in three months |
| 1103 | \& +10y in ten years time |
| 1104 | \& Thursday, 25-Apr-1999 00:40:33 GMT at the indicated time & date |
| 1105 | .Ve |
| 1106 | .PP |
| 1107 | The \fB\-cookie\fR parameter generates a header that tells the browser to provide |
| 1108 | a \*(L"magic cookie\*(R" during all subsequent transactions with your script. |
| 1109 | Netscape cookies have a special format that includes interesting attributes |
| 1110 | such as expiration time. Use the \fIcookie()\fR method to create and retrieve |
| 1111 | session cookies. |
| 1112 | .PP |
| 1113 | The \fB\-nph\fR parameter, if set to a true value, will issue the correct |
| 1114 | headers to work with an \s-1NPH\s0 (no\-parse\-header) script. This is important |
| 1115 | to use with certain servers that expect all their scripts to be \s-1NPH\s0. |
| 1116 | .PP |
| 1117 | The \fB\-charset\fR parameter can be used to control the character set |
| 1118 | sent to the browser. If not provided, defaults to \s-1ISO\-8859\-1\s0. As a |
| 1119 | side effect, this sets the \fIcharset()\fR method as well. |
| 1120 | .PP |
| 1121 | The \fB\-attachment\fR parameter can be used to turn the page into an |
| 1122 | attachment. Instead of displaying the page, some browsers will prompt |
| 1123 | the user to save it to disk. The value of the argument is the |
| 1124 | suggested name for the saved file. In order for this to work, you may |
| 1125 | have to set the \fB\-type\fR to \*(L"application/octet\-stream\*(R". |
| 1126 | .Sh "\s-1GENERATING\s0 A \s-1REDIRECTION\s0 \s-1HEADER\s0" |
| 1127 | .IX Subsection "GENERATING A REDIRECTION HEADER" |
| 1128 | .Vb 1 |
| 1129 | \& print $query->redirect('http://somewhere.else/in/movie/land'); |
| 1130 | .Ve |
| 1131 | .PP |
| 1132 | Sometimes you don't want to produce a document yourself, but simply |
| 1133 | redirect the browser elsewhere, perhaps choosing a \s-1URL\s0 based on the |
| 1134 | time of day or the identity of the user. |
| 1135 | .PP |
| 1136 | The \fIredirect()\fR function redirects the browser to a different \s-1URL\s0. If |
| 1137 | you use redirection like this, you should \fBnot\fR print out a header as |
| 1138 | well. |
| 1139 | .PP |
| 1140 | One hint I can offer is that relative links may not work correctly |
| 1141 | when you generate a redirection to another document on your site. |
| 1142 | This is due to a well-intentioned optimization that some servers use. |
| 1143 | The solution to this is to use the full \s-1URL\s0 (including the http: part) |
| 1144 | of the document you are redirecting to. |
| 1145 | .PP |
| 1146 | You can also use named arguments: |
| 1147 | .PP |
| 1148 | .Vb 2 |
| 1149 | \& print $query->redirect(-uri=>'http://somewhere.else/in/movie/land', |
| 1150 | \& -nph=>1); |
| 1151 | .Ve |
| 1152 | .PP |
| 1153 | The \fB\-nph\fR parameter, if set to a true value, will issue the correct |
| 1154 | headers to work with an \s-1NPH\s0 (no\-parse\-header) script. This is important |
| 1155 | to use with certain servers, such as Microsoft Internet Explorer, which |
| 1156 | expect all their scripts to be \s-1NPH\s0. |
| 1157 | .Sh "\s-1CREATING\s0 \s-1THE\s0 \s-1HTML\s0 \s-1DOCUMENT\s0 \s-1HEADER\s0" |
| 1158 | .IX Subsection "CREATING THE HTML DOCUMENT HEADER" |
| 1159 | .Vb 8 |
| 1160 | \& print $query->start_html(-title=>'Secrets of the Pyramids', |
| 1161 | \& -author=>'fred@capricorn.org', |
| 1162 | \& -base=>'true', |
| 1163 | \& -target=>'_blank', |
| 1164 | \& -meta=>{'keywords'=>'pharaoh secret mummy', |
| 1165 | \& 'copyright'=>'copyright 1996 King Tut'}, |
| 1166 | \& -style=>{'src'=>'/styles/style1.css'}, |
| 1167 | \& -BGCOLOR=>'blue'); |
| 1168 | .Ve |
| 1169 | .PP |
| 1170 | After creating the \s-1HTTP\s0 header, most \s-1CGI\s0 scripts will start writing |
| 1171 | out an \s-1HTML\s0 document. The \fIstart_html()\fR routine creates the top of the |
| 1172 | page, along with a lot of optional information that controls the |
| 1173 | page's appearance and behavior. |
| 1174 | .PP |
| 1175 | This method returns a canned \s-1HTML\s0 header and the opening <body> tag. |
| 1176 | All parameters are optional. In the named parameter form, recognized |
| 1177 | parameters are \-title, \-author, \-base, \-xbase, \-dtd, \-lang and \-target |
| 1178 | (see below for the explanation). Any additional parameters you |
| 1179 | provide, such as the Netscape unofficial \s-1BGCOLOR\s0 attribute, are added |
| 1180 | to the <body> tag. Additional parameters must be proceeded by a |
| 1181 | hyphen. |
| 1182 | .PP |
| 1183 | The argument \fB\-xbase\fR allows you to provide an \s-1HREF\s0 for the <base> tag |
| 1184 | different from the current location, as in |
| 1185 | .PP |
| 1186 | .Vb 1 |
| 1187 | \& -xbase=>"http://home.mcom.com/" |
| 1188 | .Ve |
| 1189 | .PP |
| 1190 | All relative links will be interpreted relative to this tag. |
| 1191 | .PP |
| 1192 | The argument \fB\-target\fR allows you to provide a default target frame |
| 1193 | for all the links and fill-out forms on the page. \fBThis is a |
| 1194 | non-standard \s-1HTTP\s0 feature which only works with Netscape browsers!\fR |
| 1195 | See the Netscape documentation on frames for details of how to |
| 1196 | manipulate this. |
| 1197 | .PP |
| 1198 | .Vb 1 |
| 1199 | \& -target=>"answer_window" |
| 1200 | .Ve |
| 1201 | .PP |
| 1202 | All relative links will be interpreted relative to this tag. |
| 1203 | You add arbitrary meta information to the header with the \fB\-meta\fR |
| 1204 | argument. This argument expects a reference to an associative array |
| 1205 | containing name/value pairs of meta information. These will be turned |
| 1206 | into a series of header <meta> tags that look something like this: |
| 1207 | .PP |
| 1208 | .Vb 2 |
| 1209 | \& <meta name="keywords" content="pharaoh secret mummy"> |
| 1210 | \& <meta name="description" content="copyright 1996 King Tut"> |
| 1211 | .Ve |
| 1212 | .PP |
| 1213 | To create an HTTP-EQUIV type of <meta> tag, use \fB\-head\fR, described |
| 1214 | below. |
| 1215 | .PP |
| 1216 | The \fB\-style\fR argument is used to incorporate cascading stylesheets |
| 1217 | into your code. See the section on \s-1CASCADING\s0 \s-1STYLESHEETS\s0 for more |
| 1218 | information. |
| 1219 | .PP |
| 1220 | The \fB\-lang\fR argument is used to incorporate a language attribute into |
| 1221 | the <html> tag. The default if not specified is \*(L"en\-US\*(R" for \s-1US\s0 |
| 1222 | English. For example: |
| 1223 | .PP |
| 1224 | .Vb 1 |
| 1225 | \& print $q->start_html(-lang=>'fr-CA'); |
| 1226 | .Ve |
| 1227 | .PP |
| 1228 | The \fB\-encoding\fR argument can be used to specify the character set for |
| 1229 | \&\s-1XHTML\s0. It defaults to iso\-8859\-1 if not specified. |
| 1230 | .PP |
| 1231 | You can place other arbitrary \s-1HTML\s0 elements to the <head> section with the |
| 1232 | \&\fB\-head\fR tag. For example, to place the rarely-used <link> element in the |
| 1233 | head section, use this: |
| 1234 | .PP |
| 1235 | .Vb 2 |
| 1236 | \& print start_html(-head=>Link({-rel=>'next', |
| 1237 | \& -href=>'http://www.capricorn.com/s2.html'})); |
| 1238 | .Ve |
| 1239 | .PP |
| 1240 | To incorporate multiple \s-1HTML\s0 elements into the <head> section, just pass an |
| 1241 | array reference: |
| 1242 | .PP |
| 1243 | .Vb 7 |
| 1244 | \& print start_html(-head=>[ |
| 1245 | \& Link({-rel=>'next', |
| 1246 | \& -href=>'http://www.capricorn.com/s2.html'}), |
| 1247 | \& Link({-rel=>'previous', |
| 1248 | \& -href=>'http://www.capricorn.com/s1.html'}) |
| 1249 | \& ] |
| 1250 | \& ); |
| 1251 | .Ve |
| 1252 | .PP |
| 1253 | And here's how to create an HTTP-EQUIV <meta> tag: |
| 1254 | .PP |
| 1255 | .Vb 2 |
| 1256 | \& print start_html(-head=>meta({-http_equiv => 'Content-Type', |
| 1257 | \& -content => 'text/html'})) |
| 1258 | .Ve |
| 1259 | .PP |
| 1260 | \&\s-1JAVASCRIPTING:\s0 The \fB\-script\fR, \fB\-noScript\fR, \fB\-onLoad\fR, |
| 1261 | \&\fB\-onMouseOver\fR, \fB\-onMouseOut\fR and \fB\-onUnload\fR parameters are used |
| 1262 | to add Netscape JavaScript calls to your pages. \fB\-script\fR should |
| 1263 | point to a block of text containing JavaScript function definitions. |
| 1264 | This block will be placed within a <script> block inside the \s-1HTML\s0 (not |
| 1265 | \&\s-1HTTP\s0) header. The block is placed in the header in order to give your |
| 1266 | page a fighting chance of having all its JavaScript functions in place |
| 1267 | even if the user presses the stop button before the page has loaded |
| 1268 | completely. \s-1CGI\s0.pm attempts to format the script in such a way that |
| 1269 | JavaScript-naive browsers will not choke on the code: unfortunately |
| 1270 | there are some browsers, such as Chimera for Unix, that get confused |
| 1271 | by it nevertheless. |
| 1272 | .PP |
| 1273 | The \fB\-onLoad\fR and \fB\-onUnload\fR parameters point to fragments of JavaScript |
| 1274 | code to execute when the page is respectively opened and closed by the |
| 1275 | browser. Usually these parameters are calls to functions defined in the |
| 1276 | \&\fB\-script\fR field: |
| 1277 | .PP |
| 1278 | .Vb 20 |
| 1279 | \& $query = new CGI; |
| 1280 | \& print $query->header; |
| 1281 | \& $JSCRIPT=<<END; |
| 1282 | \& // Ask a silly question |
| 1283 | \& function riddle_me_this() { |
| 1284 | \& var r = prompt("What walks on four legs in the morning, " + |
| 1285 | \& "two legs in the afternoon, " + |
| 1286 | \& "and three legs in the evening?"); |
| 1287 | \& response(r); |
| 1288 | \& } |
| 1289 | \& // Get a silly answer |
| 1290 | \& function response(answer) { |
| 1291 | \& if (answer == "man") |
| 1292 | \& alert("Right you are!"); |
| 1293 | \& else |
| 1294 | \& alert("Wrong! Guess again."); |
| 1295 | \& } |
| 1296 | \& END |
| 1297 | \& print $query->start_html(-title=>'The Riddle of the Sphinx', |
| 1298 | \& -script=>$JSCRIPT); |
| 1299 | .Ve |
| 1300 | .PP |
| 1301 | Use the \fB\-noScript\fR parameter to pass some \s-1HTML\s0 text that will be displayed on |
| 1302 | browsers that do not have JavaScript (or browsers where JavaScript is turned |
| 1303 | off). |
| 1304 | .PP |
| 1305 | Netscape 3.0 recognizes several attributes of the <script> tag, |
| 1306 | including \s-1LANGUAGE\s0 and \s-1SRC\s0. The latter is particularly interesting, |
| 1307 | as it allows you to keep the JavaScript code in a file or \s-1CGI\s0 script |
| 1308 | rather than cluttering up each page with the source. To use these |
| 1309 | attributes pass a \s-1HASH\s0 reference in the \fB\-script\fR parameter containing |
| 1310 | one or more of \-language, \-src, or \-code: |
| 1311 | .PP |
| 1312 | .Vb 4 |
| 1313 | \& print $q->start_html(-title=>'The Riddle of the Sphinx', |
| 1314 | \& -script=>{-language=>'JAVASCRIPT', |
| 1315 | \& -src=>'/javascript/sphinx.js'} |
| 1316 | \& ); |
| 1317 | .Ve |
| 1318 | .PP |
| 1319 | .Vb 4 |
| 1320 | \& print $q->(-title=>'The Riddle of the Sphinx', |
| 1321 | \& -script=>{-language=>'PERLSCRIPT', |
| 1322 | \& -code=>'print "hello world!\en;"'} |
| 1323 | \& ); |
| 1324 | .Ve |
| 1325 | .PP |
| 1326 | A final feature allows you to incorporate multiple <script> sections into the |
| 1327 | header. Just pass the list of script sections as an array reference. |
| 1328 | this allows you to specify different source files for different dialects |
| 1329 | of JavaScript. Example: |
| 1330 | .PP |
| 1331 | .Vb 16 |
| 1332 | \& print $q->start_html(-title=>'The Riddle of the Sphinx', |
| 1333 | \& -script=>[ |
| 1334 | \& { -language => 'JavaScript1.0', |
| 1335 | \& -src => '/javascript/utilities10.js' |
| 1336 | \& }, |
| 1337 | \& { -language => 'JavaScript1.1', |
| 1338 | \& -src => '/javascript/utilities11.js' |
| 1339 | \& }, |
| 1340 | \& { -language => 'JavaScript1.2', |
| 1341 | \& -src => '/javascript/utilities12.js' |
| 1342 | \& }, |
| 1343 | \& { -language => 'JavaScript28.2', |
| 1344 | \& -src => '/javascript/utilities219.js' |
| 1345 | \& } |
| 1346 | \& ] |
| 1347 | \& ); |
| 1348 | .Ve |
| 1349 | .PP |
| 1350 | If this looks a bit extreme, take my advice and stick with straight \s-1CGI\s0 scripting. |
| 1351 | .PP |
| 1352 | See |
| 1353 | .PP |
| 1354 | .Vb 1 |
| 1355 | \& http://home.netscape.com/eng/mozilla/2.0/handbook/javascript/ |
| 1356 | .Ve |
| 1357 | .PP |
| 1358 | for more information about JavaScript. |
| 1359 | .PP |
| 1360 | The old-style positional parameters are as follows: |
| 1361 | .IP "\fBParameters:\fR" 4 |
| 1362 | .IX Item "Parameters:" |
| 1363 | .PD 0 |
| 1364 | .IP "1." 4 |
| 1365 | .PD |
| 1366 | The title |
| 1367 | .IP "2." 4 |
| 1368 | The author's e\-mail address (will create a <link rev=\*(L"\s-1MADE\s0\*(R"> tag if present |
| 1369 | .IP "3." 4 |
| 1370 | A 'true' flag if you want to include a <base> tag in the header. This |
| 1371 | helps resolve relative addresses to absolute ones when the document is moved, |
| 1372 | but makes the document hierarchy non\-portable. Use with care! |
| 1373 | .IP "4, 5, 6..." 4 |
| 1374 | .IX Item "4, 5, 6..." |
| 1375 | Any other parameters you want to include in the <body> tag. This is a good |
| 1376 | place to put Netscape extensions, such as colors and wallpaper patterns. |
| 1377 | .Sh "\s-1ENDING\s0 \s-1THE\s0 \s-1HTML\s0 \s-1DOCUMENT:\s0" |
| 1378 | .IX Subsection "ENDING THE HTML DOCUMENT:" |
| 1379 | .Vb 1 |
| 1380 | \& print $query->end_html |
| 1381 | .Ve |
| 1382 | .PP |
| 1383 | This ends an \s-1HTML\s0 document by printing the </body></html> tags. |
| 1384 | .Sh "\s-1CREATING\s0 A SELF-REFERENCING \s-1URL\s0 \s-1THAT\s0 \s-1PRESERVES\s0 \s-1STATE\s0 \s-1INFORMATION:\s0" |
| 1385 | .IX Subsection "CREATING A SELF-REFERENCING URL THAT PRESERVES STATE INFORMATION:" |
| 1386 | .Vb 2 |
| 1387 | \& $myself = $query->self_url; |
| 1388 | \& print q(<a href="$myself">I'm talking to myself.</a>); |
| 1389 | .Ve |
| 1390 | .PP |
| 1391 | \&\fIself_url()\fR will return a \s-1URL\s0, that, when selected, will reinvoke |
| 1392 | this script with all its state information intact. This is most |
| 1393 | useful when you want to jump around within the document using |
| 1394 | internal anchors but you don't want to disrupt the current contents |
| 1395 | of the form(s). Something like this will do the trick. |
| 1396 | .PP |
| 1397 | .Vb 4 |
| 1398 | \& $myself = $query->self_url; |
| 1399 | \& print "<a href=$myself#table1>See table 1</a>"; |
| 1400 | \& print "<a href=$myself#table2>See table 2</a>"; |
| 1401 | \& print "<a href=$myself#yourself>See for yourself</a>"; |
| 1402 | .Ve |
| 1403 | .PP |
| 1404 | If you want more control over what's returned, using the \fB\f(BIurl()\fB\fR |
| 1405 | method instead. |
| 1406 | .PP |
| 1407 | You can also retrieve the unprocessed query string with \fIquery_string()\fR: |
| 1408 | .PP |
| 1409 | .Vb 1 |
| 1410 | \& $the_string = $query->query_string; |
| 1411 | .Ve |
| 1412 | .Sh "\s-1OBTAINING\s0 \s-1THE\s0 \s-1SCRIPT\s0'S \s-1URL\s0" |
| 1413 | .IX Subsection "OBTAINING THE SCRIPT'S URL" |
| 1414 | .Vb 7 |
| 1415 | \& $full_url = $query->url(); |
| 1416 | \& $full_url = $query->url(-full=>1); #alternative syntax |
| 1417 | \& $relative_url = $query->url(-relative=>1); |
| 1418 | \& $absolute_url = $query->url(-absolute=>1); |
| 1419 | \& $url_with_path = $query->url(-path_info=>1); |
| 1420 | \& $url_with_path_and_query = $query->url(-path_info=>1,-query=>1); |
| 1421 | \& $netloc = $query->url(-base => 1); |
| 1422 | .Ve |
| 1423 | .PP |
| 1424 | \&\fB\f(BIurl()\fB\fR returns the script's \s-1URL\s0 in a variety of formats. Called |
| 1425 | without any arguments, it returns the full form of the \s-1URL\s0, including |
| 1426 | host name and port number |
| 1427 | .PP |
| 1428 | .Vb 1 |
| 1429 | \& http://your.host.com/path/to/script.cgi |
| 1430 | .Ve |
| 1431 | .PP |
| 1432 | You can modify this format with the following named arguments: |
| 1433 | .IP "\fB\-absolute\fR" 4 |
| 1434 | .IX Item "-absolute" |
| 1435 | If true, produce an absolute \s-1URL\s0, e.g. |
| 1436 | .Sp |
| 1437 | .Vb 1 |
| 1438 | \& /path/to/script.cgi |
| 1439 | .Ve |
| 1440 | .IP "\fB\-relative\fR" 4 |
| 1441 | .IX Item "-relative" |
| 1442 | Produce a relative \s-1URL\s0. This is useful if you want to reinvoke your |
| 1443 | script with different parameters. For example: |
| 1444 | .Sp |
| 1445 | .Vb 1 |
| 1446 | \& script.cgi |
| 1447 | .Ve |
| 1448 | .IP "\fB\-full\fR" 4 |
| 1449 | .IX Item "-full" |
| 1450 | Produce the full \s-1URL\s0, exactly as if called without any arguments. |
| 1451 | This overrides the \-relative and \-absolute arguments. |
| 1452 | .IP "\fB\-path\fR (\fB\-path_info\fR)" 4 |
| 1453 | .IX Item "-path (-path_info)" |
| 1454 | Append the additional path information to the \s-1URL\s0. This can be |
| 1455 | combined with \fB\-full\fR, \fB\-absolute\fR or \fB\-relative\fR. \fB\-path_info\fR |
| 1456 | is provided as a synonym. |
| 1457 | .IP "\fB\-query\fR (\fB\-query_string\fR)" 4 |
| 1458 | .IX Item "-query (-query_string)" |
| 1459 | Append the query string to the \s-1URL\s0. This can be combined with |
| 1460 | \&\fB\-full\fR, \fB\-absolute\fR or \fB\-relative\fR. \fB\-query_string\fR is provided |
| 1461 | as a synonym. |
| 1462 | .IP "\fB\-base\fR" 4 |
| 1463 | .IX Item "-base" |
| 1464 | Generate just the protocol and net location, as in http://www.foo.com:8000 |
| 1465 | .Sh "\s-1MIXING\s0 \s-1POST\s0 \s-1AND\s0 \s-1URL\s0 \s-1PARAMETERS\s0" |
| 1466 | .IX Subsection "MIXING POST AND URL PARAMETERS" |
| 1467 | .Vb 1 |
| 1468 | \& $color = $query->url_param('color'); |
| 1469 | .Ve |
| 1470 | .PP |
| 1471 | It is possible for a script to receive \s-1CGI\s0 parameters in the \s-1URL\s0 as |
| 1472 | well as in the fill-out form by creating a form that POSTs to a \s-1URL\s0 |
| 1473 | containing a query string (a \*(L"?\*(R" mark followed by arguments). The |
| 1474 | \&\fB\f(BIparam()\fB\fR method will always return the contents of the POSTed |
| 1475 | fill-out form, ignoring the \s-1URL\s0's query string. To retrieve \s-1URL\s0 |
| 1476 | parameters, call the \fB\f(BIurl_param()\fB\fR method. Use it in the same way as |
| 1477 | \&\fB\f(BIparam()\fB\fR. The main difference is that it allows you to read the |
| 1478 | parameters, but not set them. |
| 1479 | .PP |
| 1480 | Under no circumstances will the contents of the \s-1URL\s0 query string |
| 1481 | interfere with similarly-named \s-1CGI\s0 parameters in POSTed forms. If you |
| 1482 | try to mix a \s-1URL\s0 query string with a form submitted with the \s-1GET\s0 |
| 1483 | method, the results will not be what you expect. |
| 1484 | .SH "CREATING STANDARD HTML ELEMENTS:" |
| 1485 | .IX Header "CREATING STANDARD HTML ELEMENTS:" |
| 1486 | \&\s-1CGI\s0.pm defines general \s-1HTML\s0 shortcut methods for most, if not all of |
| 1487 | the \s-1HTML\s0 3 and \s-1HTML\s0 4 tags. \s-1HTML\s0 shortcuts are named after a single |
| 1488 | \&\s-1HTML\s0 element and return a fragment of \s-1HTML\s0 text that you can then |
| 1489 | print or manipulate as you like. Each shortcut returns a fragment of |
| 1490 | \&\s-1HTML\s0 code that you can append to a string, save to a file, or, most |
| 1491 | commonly, print out so that it displays in the browser window. |
| 1492 | .PP |
| 1493 | This example shows how to use the \s-1HTML\s0 methods: |
| 1494 | .PP |
| 1495 | .Vb 8 |
| 1496 | \& $q = new CGI; |
| 1497 | \& print $q->blockquote( |
| 1498 | \& "Many years ago on the island of", |
| 1499 | \& $q->a({href=>"http://crete.org/"},"Crete"), |
| 1500 | \& "there lived a Minotaur named", |
| 1501 | \& $q->strong("Fred."), |
| 1502 | \& ), |
| 1503 | \& $q->hr; |
| 1504 | .Ve |
| 1505 | .PP |
| 1506 | This results in the following \s-1HTML\s0 code (extra newlines have been |
| 1507 | added for readability): |
| 1508 | .PP |
| 1509 | .Vb 6 |
| 1510 | \& <blockquote> |
| 1511 | \& Many years ago on the island of |
| 1512 | \& <a href="http://crete.org/">Crete</a> there lived |
| 1513 | \& a minotaur named <strong>Fred.</strong> |
| 1514 | \& </blockquote> |
| 1515 | \& <hr> |
| 1516 | .Ve |
| 1517 | .PP |
| 1518 | If you find the syntax for calling the \s-1HTML\s0 shortcuts awkward, you can |
| 1519 | import them into your namespace and dispense with the object syntax |
| 1520 | completely (see the next section for more details): |
| 1521 | .PP |
| 1522 | .Vb 8 |
| 1523 | \& use CGI ':standard'; |
| 1524 | \& print blockquote( |
| 1525 | \& "Many years ago on the island of", |
| 1526 | \& a({href=>"http://crete.org/"},"Crete"), |
| 1527 | \& "there lived a minotaur named", |
| 1528 | \& strong("Fred."), |
| 1529 | \& ), |
| 1530 | \& hr; |
| 1531 | .Ve |
| 1532 | .Sh "\s-1PROVIDING\s0 \s-1ARGUMENTS\s0 \s-1TO\s0 \s-1HTML\s0 \s-1SHORTCUTS\s0" |
| 1533 | .IX Subsection "PROVIDING ARGUMENTS TO HTML SHORTCUTS" |
| 1534 | The \s-1HTML\s0 methods will accept zero, one or multiple arguments. If you |
| 1535 | provide no arguments, you get a single tag: |
| 1536 | .PP |
| 1537 | .Vb 1 |
| 1538 | \& print hr; # <hr> |
| 1539 | .Ve |
| 1540 | .PP |
| 1541 | If you provide one or more string arguments, they are concatenated |
| 1542 | together with spaces and placed between opening and closing tags: |
| 1543 | .PP |
| 1544 | .Vb 1 |
| 1545 | \& print h1("Chapter","1"); # <h1>Chapter 1</h1>" |
| 1546 | .Ve |
| 1547 | .PP |
| 1548 | If the first argument is an associative array reference, then the keys |
| 1549 | and values of the associative array become the \s-1HTML\s0 tag's attributes: |
| 1550 | .PP |
| 1551 | .Vb 2 |
| 1552 | \& print a({-href=>'fred.html',-target=>'_new'}, |
| 1553 | \& "Open a new frame"); |
| 1554 | .Ve |
| 1555 | .PP |
| 1556 | .Vb 1 |
| 1557 | \& <a href="fred.html",target="_new">Open a new frame</a> |
| 1558 | .Ve |
| 1559 | .PP |
| 1560 | You may dispense with the dashes in front of the attribute names if |
| 1561 | you prefer: |
| 1562 | .PP |
| 1563 | .Vb 1 |
| 1564 | \& print img {src=>'fred.gif',align=>'LEFT'}; |
| 1565 | .Ve |
| 1566 | .PP |
| 1567 | .Vb 1 |
| 1568 | \& <img align="LEFT" src="fred.gif"> |
| 1569 | .Ve |
| 1570 | .PP |
| 1571 | Sometimes an \s-1HTML\s0 tag attribute has no argument. For example, ordered |
| 1572 | lists can be marked as \s-1COMPACT\s0. The syntax for this is an argument |
| 1573 | that points to an undef string: |
| 1574 | .PP |
| 1575 | .Vb 1 |
| 1576 | \& print ol({compact=>undef},li('one'),li('two'),li('three')); |
| 1577 | .Ve |
| 1578 | .PP |
| 1579 | Prior to \s-1CGI\s0.pm version 2.41, providing an empty ('') string as an |
| 1580 | attribute argument was the same as providing undef. However, this has |
| 1581 | changed in order to accommodate those who want to create tags of the form |
| 1582 | <img alt="">. The difference is shown in these two pieces of code: |
| 1583 | .PP |
| 1584 | .Vb 3 |
| 1585 | \& CODE RESULT |
| 1586 | \& img({alt=>undef}) <img alt> |
| 1587 | \& img({alt=>''}) <img alt=""> |
| 1588 | .Ve |
| 1589 | .Sh "\s-1THE\s0 \s-1DISTRIBUTIVE\s0 \s-1PROPERTY\s0 \s-1OF\s0 \s-1HTML\s0 \s-1SHORTCUTS\s0" |
| 1590 | .IX Subsection "THE DISTRIBUTIVE PROPERTY OF HTML SHORTCUTS" |
| 1591 | One of the cool features of the \s-1HTML\s0 shortcuts is that they are |
| 1592 | distributive. If you give them an argument consisting of a |
| 1593 | \&\fBreference\fR to a list, the tag will be distributed across each |
| 1594 | element of the list. For example, here's one way to make an ordered |
| 1595 | list: |
| 1596 | .PP |
| 1597 | .Vb 3 |
| 1598 | \& print ul( |
| 1599 | \& li({-type=>'disc'},['Sneezy','Doc','Sleepy','Happy']) |
| 1600 | \& ); |
| 1601 | .Ve |
| 1602 | .PP |
| 1603 | This example will result in \s-1HTML\s0 output that looks like this: |
| 1604 | .PP |
| 1605 | .Vb 6 |
| 1606 | \& <ul> |
| 1607 | \& <li type="disc">Sneezy</li> |
| 1608 | \& <li type="disc">Doc</li> |
| 1609 | \& <li type="disc">Sleepy</li> |
| 1610 | \& <li type="disc">Happy</li> |
| 1611 | \& </ul> |
| 1612 | .Ve |
| 1613 | .PP |
| 1614 | This is extremely useful for creating tables. For example: |
| 1615 | .PP |
| 1616 | .Vb 11 |
| 1617 | \& print table({-border=>undef}, |
| 1618 | \& caption('When Should You Eat Your Vegetables?'), |
| 1619 | \& Tr({-align=>CENTER,-valign=>TOP}, |
| 1620 | \& [ |
| 1621 | \& th(['Vegetable', 'Breakfast','Lunch','Dinner']), |
| 1622 | \& td(['Tomatoes' , 'no', 'yes', 'yes']), |
| 1623 | \& td(['Broccoli' , 'no', 'no', 'yes']), |
| 1624 | \& td(['Onions' , 'yes','yes', 'yes']) |
| 1625 | \& ] |
| 1626 | \& ) |
| 1627 | \& ); |
| 1628 | .Ve |
| 1629 | .Sh "\s-1HTML\s0 \s-1SHORTCUTS\s0 \s-1AND\s0 \s-1LIST\s0 \s-1INTERPOLATION\s0" |
| 1630 | .IX Subsection "HTML SHORTCUTS AND LIST INTERPOLATION" |
| 1631 | Consider this bit of code: |
| 1632 | .PP |
| 1633 | .Vb 1 |
| 1634 | \& print blockquote(em('Hi'),'mom!')); |
| 1635 | .Ve |
| 1636 | .PP |
| 1637 | It will ordinarily return the string that you probably expect, namely: |
| 1638 | .PP |
| 1639 | .Vb 1 |
| 1640 | \& <blockquote><em>Hi</em> mom!</blockquote> |
| 1641 | .Ve |
| 1642 | .PP |
| 1643 | Note the space between the element \*(L"Hi\*(R" and the element \*(L"mom!\*(R". |
| 1644 | \&\s-1CGI\s0.pm puts the extra space there using array interpolation, which is |
| 1645 | controlled by the magic $\*(L" variable. Sometimes this extra space is |
| 1646 | not what you want, for example, when you are trying to align a series |
| 1647 | of images. In this case, you can simply change the value of $\*(R" to an |
| 1648 | empty string. |
| 1649 | .PP |
| 1650 | .Vb 4 |
| 1651 | \& { |
| 1652 | \& local($") = ''; |
| 1653 | \& print blockquote(em('Hi'),'mom!')); |
| 1654 | \& } |
| 1655 | .Ve |
| 1656 | .PP |
| 1657 | I suggest you put the code in a block as shown here. Otherwise the |
| 1658 | change to $" will affect all subsequent code until you explicitly |
| 1659 | reset it. |
| 1660 | .Sh "NON-STANDARD \s-1HTML\s0 \s-1SHORTCUTS\s0" |
| 1661 | .IX Subsection "NON-STANDARD HTML SHORTCUTS" |
| 1662 | A few \s-1HTML\s0 tags don't follow the standard pattern for various |
| 1663 | reasons. |
| 1664 | .PP |
| 1665 | \&\fB\f(BIcomment()\fB\fR generates an \s-1HTML\s0 comment (<!\-\- comment \-\->). Call it |
| 1666 | like |
| 1667 | .PP |
| 1668 | .Vb 1 |
| 1669 | \& print comment('here is my comment'); |
| 1670 | .Ve |
| 1671 | .PP |
| 1672 | Because of conflicts with built-in Perl functions, the following functions |
| 1673 | begin with initial caps: |
| 1674 | .PP |
| 1675 | .Vb 6 |
| 1676 | \& Select |
| 1677 | \& Tr |
| 1678 | \& Link |
| 1679 | \& Delete |
| 1680 | \& Accept |
| 1681 | \& Sub |
| 1682 | .Ve |
| 1683 | .PP |
| 1684 | In addition, \fIstart_html()\fR, \fIend_html()\fR, \fIstart_form()\fR, \fIend_form()\fR, |
| 1685 | \&\fIstart_multipart_form()\fR and all the fill-out form tags are special. |
| 1686 | See their respective sections. |
| 1687 | .Sh "\s-1AUTOESCAPING\s0 \s-1HTML\s0" |
| 1688 | .IX Subsection "AUTOESCAPING HTML" |
| 1689 | By default, all \s-1HTML\s0 that is emitted by the form-generating functions |
| 1690 | is passed through a function called \fIescapeHTML()\fR: |
| 1691 | .ie n .IP "$escaped_string = escapeHTML(""unescaped string"");" 4 |
| 1692 | .el .IP "$escaped_string = escapeHTML(``unescaped string'');" 4 |
| 1693 | .IX Item "$escaped_string = escapeHTML(unescaped string);" |
| 1694 | Escape \s-1HTML\s0 formatting characters in a string. |
| 1695 | .PP |
| 1696 | Provided that you have specified a character set of \s-1ISO\-8859\-1\s0 (the |
| 1697 | default), the standard \s-1HTML\s0 escaping rules will be used. The \*(L"<\*(R" |
| 1698 | character becomes \*(L"<\*(R", \*(L">\*(R" becomes \*(L">\*(R", \*(L"&\*(R" becomes \*(L"&\*(R", and |
| 1699 | the quote character becomes \*(L""\*(R". In addition, the hexadecimal |
| 1700 | 0x8b and 0x9b characters, which many windows-based browsers interpret |
| 1701 | as the left and right angle-bracket characters, are replaced by their |
| 1702 | numeric \s-1HTML\s0 entities (\*(L"‹\*(R" and \*(L"›\*(R"). If you manually change |
| 1703 | the charset, either by calling the \fIcharset()\fR method explicitly or by |
| 1704 | passing a \-charset argument to \fIheader()\fR, then \fBall\fR characters will |
| 1705 | be replaced by their numeric entities, since \s-1CGI\s0.pm has no lookup |
| 1706 | table for all the possible encodings. |
| 1707 | .PP |
| 1708 | The automatic escaping does not apply to other shortcuts, such as |
| 1709 | \&\fIh1()\fR. You should call \fIescapeHTML()\fR yourself on untrusted data in |
| 1710 | order to protect your pages against nasty tricks that people may enter |
| 1711 | into guestbooks, etc.. To change the character set, use \fIcharset()\fR. |
| 1712 | To turn autoescaping off completely, use \fIautoescape()\fR: |
| 1713 | .IP "$charset = charset([$charset]);" 4 |
| 1714 | .IX Item "$charset = charset([$charset]);" |
| 1715 | Get or set the current character set. |
| 1716 | .IP "$flag = autoEscape([$flag]);" 4 |
| 1717 | .IX Item "$flag = autoEscape([$flag]);" |
| 1718 | Get or set the value of the autoescape flag. |
| 1719 | .Sh "PRETTY-PRINTING \s-1HTML\s0" |
| 1720 | .IX Subsection "PRETTY-PRINTING HTML" |
| 1721 | By default, all the \s-1HTML\s0 produced by these functions comes out as one |
| 1722 | long line without carriage returns or indentation. This is yuck, but |
| 1723 | it does reduce the size of the documents by 10\-20%. To get |
| 1724 | pretty-printed output, please use CGI::Pretty, a subclass |
| 1725 | contributed by Brian Paulsen. |
| 1726 | .SH "CREATING FILL-OUT FORMS:" |
| 1727 | .IX Header "CREATING FILL-OUT FORMS:" |
| 1728 | \&\fIGeneral note\fR The various form-creating methods all return strings |
| 1729 | to the caller, containing the tag or tags that will create the requested |
| 1730 | form element. You are responsible for actually printing out these strings. |
| 1731 | It's set up this way so that you can place formatting tags |
| 1732 | around the form elements. |
| 1733 | .PP |
| 1734 | \&\fIAnother note\fR The default values that you specify for the forms are only |
| 1735 | used the \fBfirst\fR time the script is invoked (when there is no query |
| 1736 | string). On subsequent invocations of the script (when there is a query |
| 1737 | string), the former values are used even if they are blank. |
| 1738 | .PP |
| 1739 | If you want to change the value of a field from its previous value, you have two |
| 1740 | choices: |
| 1741 | .PP |
| 1742 | (1) call the \fIparam()\fR method to set it. |
| 1743 | .PP |
| 1744 | (2) use the \-override (alias \-force) parameter (a new feature in version 2.15). |
| 1745 | This forces the default value to be used, regardless of the previous value: |
| 1746 | .PP |
| 1747 | .Vb 5 |
| 1748 | \& print $query->textfield(-name=>'field_name', |
| 1749 | \& -default=>'starting value', |
| 1750 | \& -override=>1, |
| 1751 | \& -size=>50, |
| 1752 | \& -maxlength=>80); |
| 1753 | .Ve |
| 1754 | .PP |
| 1755 | \&\fIYet another note\fR By default, the text and labels of form elements are |
| 1756 | escaped according to \s-1HTML\s0 rules. This means that you can safely use |
| 1757 | \&\*(L"<\s-1CLICK\s0 \s-1ME\s0>\*(R" as the label for a button. However, it also interferes with |
| 1758 | your ability to incorporate special \s-1HTML\s0 character sequences, such as Á, |
| 1759 | into your fields. If you wish to turn off automatic escaping, call the |
| 1760 | \&\fIautoEscape()\fR method with a false value immediately after creating the \s-1CGI\s0 object: |
| 1761 | .PP |
| 1762 | .Vb 2 |
| 1763 | \& $query = new CGI; |
| 1764 | \& $query->autoEscape(undef); |
| 1765 | .Ve |
| 1766 | .Sh "\s-1CREATING\s0 \s-1AN\s0 \s-1ISINDEX\s0 \s-1TAG\s0" |
| 1767 | .IX Subsection "CREATING AN ISINDEX TAG" |
| 1768 | .Vb 1 |
| 1769 | \& print $query->isindex(-action=>$action); |
| 1770 | .Ve |
| 1771 | .PP |
| 1772 | .Vb 1 |
| 1773 | \& -or- |
| 1774 | .Ve |
| 1775 | .PP |
| 1776 | .Vb 1 |
| 1777 | \& print $query->isindex($action); |
| 1778 | .Ve |
| 1779 | .PP |
| 1780 | Prints out an <isindex> tag. Not very exciting. The parameter |
| 1781 | \&\-action specifies the \s-1URL\s0 of the script to process the query. The |
| 1782 | default is to process the query with the current script. |
| 1783 | .Sh "\s-1STARTING\s0 \s-1AND\s0 \s-1ENDING\s0 A \s-1FORM\s0" |
| 1784 | .IX Subsection "STARTING AND ENDING A FORM" |
| 1785 | .Vb 5 |
| 1786 | \& print $query->start_form(-method=>$method, |
| 1787 | \& -action=>$action, |
| 1788 | \& -enctype=>$encoding); |
| 1789 | \& <... various form stuff ...> |
| 1790 | \& print $query->endform; |
| 1791 | .Ve |
| 1792 | .PP |
| 1793 | .Vb 1 |
| 1794 | \& -or- |
| 1795 | .Ve |
| 1796 | .PP |
| 1797 | .Vb 3 |
| 1798 | \& print $query->start_form($method,$action,$encoding); |
| 1799 | \& <... various form stuff ...> |
| 1800 | \& print $query->endform; |
| 1801 | .Ve |
| 1802 | .PP |
| 1803 | \&\fIstart_form()\fR will return a <form> tag with the optional method, |
| 1804 | action and form encoding that you specify. The defaults are: |
| 1805 | .PP |
| 1806 | .Vb 3 |
| 1807 | \& method: POST |
| 1808 | \& action: this script |
| 1809 | \& enctype: application/x-www-form-urlencoded |
| 1810 | .Ve |
| 1811 | .PP |
| 1812 | \&\fIendform()\fR returns the closing </form> tag. |
| 1813 | .PP |
| 1814 | \&\fIStart_form()\fR's enctype argument tells the browser how to package the various |
| 1815 | fields of the form before sending the form to the server. Two |
| 1816 | values are possible: |
| 1817 | .PP |
| 1818 | \&\fBNote:\fR This method was previously named \fIstartform()\fR, and \fIstartform()\fR |
| 1819 | is still recognized as an alias. |
| 1820 | .IP "\fBapplication/x\-www\-form\-urlencoded\fR" 4 |
| 1821 | .IX Item "application/x-www-form-urlencoded" |
| 1822 | This is the older type of encoding used by all browsers prior to |
| 1823 | Netscape 2.0. It is compatible with many \s-1CGI\s0 scripts and is |
| 1824 | suitable for short fields containing text data. For your |
| 1825 | convenience, \s-1CGI\s0.pm stores the name of this encoding |
| 1826 | type in \fB&CGI::URL_ENCODED\fR. |
| 1827 | .IP "\fBmultipart/form\-data\fR" 4 |
| 1828 | .IX Item "multipart/form-data" |
| 1829 | This is the newer type of encoding introduced by Netscape 2.0. |
| 1830 | It is suitable for forms that contain very large fields or that |
| 1831 | are intended for transferring binary data. Most importantly, |
| 1832 | it enables the \*(L"file upload\*(R" feature of Netscape 2.0 forms. For |
| 1833 | your convenience, \s-1CGI\s0.pm stores the name of this encoding type |
| 1834 | in \fB&CGI::MULTIPART\fR |
| 1835 | .Sp |
| 1836 | Forms that use this type of encoding are not easily interpreted |
| 1837 | by \s-1CGI\s0 scripts unless they use \s-1CGI\s0.pm or another library designed |
| 1838 | to handle them. |
| 1839 | .PP |
| 1840 | For compatibility, the \fIstart_form()\fR method uses the older form of |
| 1841 | encoding by default. If you want to use the newer form of encoding |
| 1842 | by default, you can call \fB\f(BIstart_multipart_form()\fB\fR instead of |
| 1843 | \&\fB\f(BIstart_form()\fB\fR. |
| 1844 | .PP |
| 1845 | \&\s-1JAVASCRIPTING:\s0 The \fB\-name\fR and \fB\-onSubmit\fR parameters are provided |
| 1846 | for use with JavaScript. The \-name parameter gives the |
| 1847 | form a name so that it can be identified and manipulated by |
| 1848 | JavaScript functions. \-onSubmit should point to a JavaScript |
| 1849 | function that will be executed just before the form is submitted to your |
| 1850 | server. You can use this opportunity to check the contents of the form |
| 1851 | for consistency and completeness. If you find something wrong, you |
| 1852 | can put up an alert box or maybe fix things up yourself. You can |
| 1853 | abort the submission by returning false from this function. |
| 1854 | .PP |
| 1855 | Usually the bulk of JavaScript functions are defined in a <script> |
| 1856 | block in the \s-1HTML\s0 header and \-onSubmit points to one of these function |
| 1857 | call. See \fIstart_html()\fR for details. |
| 1858 | .Sh "\s-1CREATING\s0 A \s-1TEXT\s0 \s-1FIELD\s0" |
| 1859 | .IX Subsection "CREATING A TEXT FIELD" |
| 1860 | .Vb 5 |
| 1861 | \& print $query->textfield(-name=>'field_name', |
| 1862 | \& -default=>'starting value', |
| 1863 | \& -size=>50, |
| 1864 | \& -maxlength=>80); |
| 1865 | \& -or- |
| 1866 | .Ve |
| 1867 | .PP |
| 1868 | .Vb 1 |
| 1869 | \& print $query->textfield('field_name','starting value',50,80); |
| 1870 | .Ve |
| 1871 | .PP |
| 1872 | \&\fItextfield()\fR will return a text input field. |
| 1873 | .IP "\fBParameters\fR" 4 |
| 1874 | .IX Item "Parameters" |
| 1875 | .PD 0 |
| 1876 | .IP "1." 4 |
| 1877 | .PD |
| 1878 | The first parameter is the required name for the field (\-name). |
| 1879 | .IP "2." 4 |
| 1880 | The optional second parameter is the default starting value for the field |
| 1881 | contents (\-default). |
| 1882 | .IP "3." 4 |
| 1883 | The optional third parameter is the size of the field in |
| 1884 | characters (\-size). |
| 1885 | .IP "4." 4 |
| 1886 | The optional fourth parameter is the maximum number of characters the |
| 1887 | field will accept (\-maxlength). |
| 1888 | .PP |
| 1889 | As with all these methods, the field will be initialized with its |
| 1890 | previous contents from earlier invocations of the script. |
| 1891 | When the form is processed, the value of the text field can be |
| 1892 | retrieved with: |
| 1893 | .PP |
| 1894 | .Vb 1 |
| 1895 | \& $value = $query->param('foo'); |
| 1896 | .Ve |
| 1897 | .PP |
| 1898 | If you want to reset it from its initial value after the script has been |
| 1899 | called once, you can do so like this: |
| 1900 | .PP |
| 1901 | .Vb 1 |
| 1902 | \& $query->param('foo',"I'm taking over this value!"); |
| 1903 | .Ve |
| 1904 | .PP |
| 1905 | \&\s-1NEW\s0 \s-1AS\s0 \s-1OF\s0 \s-1VERSION\s0 2.15: If you don't want the field to take on its previous |
| 1906 | value, you can force its current value by using the \-override (alias \-force) |
| 1907 | parameter: |
| 1908 | .PP |
| 1909 | .Vb 5 |
| 1910 | \& print $query->textfield(-name=>'field_name', |
| 1911 | \& -default=>'starting value', |
| 1912 | \& -override=>1, |
| 1913 | \& -size=>50, |
| 1914 | \& -maxlength=>80); |
| 1915 | .Ve |
| 1916 | .PP |
| 1917 | \&\s-1JAVASCRIPTING:\s0 You can also provide \fB\-onChange\fR, \fB\-onFocus\fR, |
| 1918 | \&\fB\-onBlur\fR, \fB\-onMouseOver\fR, \fB\-onMouseOut\fR and \fB\-onSelect\fR |
| 1919 | parameters to register JavaScript event handlers. The onChange |
| 1920 | handler will be called whenever the user changes the contents of the |
| 1921 | text field. You can do text validation if you like. onFocus and |
| 1922 | onBlur are called respectively when the insertion point moves into and |
| 1923 | out of the text field. onSelect is called when the user changes the |
| 1924 | portion of the text that is selected. |
| 1925 | .Sh "\s-1CREATING\s0 A \s-1BIG\s0 \s-1TEXT\s0 \s-1FIELD\s0" |
| 1926 | .IX Subsection "CREATING A BIG TEXT FIELD" |
| 1927 | .Vb 4 |
| 1928 | \& print $query->textarea(-name=>'foo', |
| 1929 | \& -default=>'starting value', |
| 1930 | \& -rows=>10, |
| 1931 | \& -columns=>50); |
| 1932 | .Ve |
| 1933 | .PP |
| 1934 | .Vb 1 |
| 1935 | \& -or |
| 1936 | .Ve |
| 1937 | .PP |
| 1938 | .Vb 1 |
| 1939 | \& print $query->textarea('foo','starting value',10,50); |
| 1940 | .Ve |
| 1941 | .PP |
| 1942 | \&\fItextarea()\fR is just like textfield, but it allows you to specify |
| 1943 | rows and columns for a multiline text entry box. You can provide |
| 1944 | a starting value for the field, which can be long and contain |
| 1945 | multiple lines. |
| 1946 | .PP |
| 1947 | \&\s-1JAVASCRIPTING:\s0 The \fB\-onChange\fR, \fB\-onFocus\fR, \fB\-onBlur\fR , |
| 1948 | \&\fB\-onMouseOver\fR, \fB\-onMouseOut\fR, and \fB\-onSelect\fR parameters are |
| 1949 | recognized. See \fItextfield()\fR. |
| 1950 | .Sh "\s-1CREATING\s0 A \s-1PASSWORD\s0 \s-1FIELD\s0" |
| 1951 | .IX Subsection "CREATING A PASSWORD FIELD" |
| 1952 | .Vb 5 |
| 1953 | \& print $query->password_field(-name=>'secret', |
| 1954 | \& -value=>'starting value', |
| 1955 | \& -size=>50, |
| 1956 | \& -maxlength=>80); |
| 1957 | \& -or- |
| 1958 | .Ve |
| 1959 | .PP |
| 1960 | .Vb 1 |
| 1961 | \& print $query->password_field('secret','starting value',50,80); |
| 1962 | .Ve |
| 1963 | .PP |
| 1964 | \&\fIpassword_field()\fR is identical to \fItextfield()\fR, except that its contents |
| 1965 | will be starred out on the web page. |
| 1966 | .PP |
| 1967 | \&\s-1JAVASCRIPTING:\s0 The \fB\-onChange\fR, \fB\-onFocus\fR, \fB\-onBlur\fR, |
| 1968 | \&\fB\-onMouseOver\fR, \fB\-onMouseOut\fR and \fB\-onSelect\fR parameters are |
| 1969 | recognized. See \fItextfield()\fR. |
| 1970 | .Sh "\s-1CREATING\s0 A \s-1FILE\s0 \s-1UPLOAD\s0 \s-1FIELD\s0" |
| 1971 | .IX Subsection "CREATING A FILE UPLOAD FIELD" |
| 1972 | .Vb 5 |
| 1973 | \& print $query->filefield(-name=>'uploaded_file', |
| 1974 | \& -default=>'starting value', |
| 1975 | \& -size=>50, |
| 1976 | \& -maxlength=>80); |
| 1977 | \& -or- |
| 1978 | .Ve |
| 1979 | .PP |
| 1980 | .Vb 1 |
| 1981 | \& print $query->filefield('uploaded_file','starting value',50,80); |
| 1982 | .Ve |
| 1983 | .PP |
| 1984 | \&\fIfilefield()\fR will return a file upload field for Netscape 2.0 browsers. |
| 1985 | In order to take full advantage of this \fIyou must use the new |
| 1986 | multipart encoding scheme\fR for the form. You can do this either |
| 1987 | by calling \fB\f(BIstart_form()\fB\fR with an encoding type of \fB&CGI::MULTIPART\fR, |
| 1988 | or by calling the new method \fB\f(BIstart_multipart_form()\fB\fR instead of |
| 1989 | vanilla \fB\f(BIstart_form()\fB\fR. |
| 1990 | .IP "\fBParameters\fR" 4 |
| 1991 | .IX Item "Parameters" |
| 1992 | .PD 0 |
| 1993 | .IP "1." 4 |
| 1994 | .PD |
| 1995 | The first parameter is the required name for the field (\-name). |
| 1996 | .IP "2." 4 |
| 1997 | The optional second parameter is the starting value for the field contents |
| 1998 | to be used as the default file name (\-default). |
| 1999 | .Sp |
| 2000 | For security reasons, browsers don't pay any attention to this field, |
| 2001 | and so the starting value will always be blank. Worse, the field |
| 2002 | loses its \*(L"sticky\*(R" behavior and forgets its previous contents. The |
| 2003 | starting value field is called for in the \s-1HTML\s0 specification, however, |
| 2004 | and possibly some browser will eventually provide support for it. |
| 2005 | .IP "3." 4 |
| 2006 | The optional third parameter is the size of the field in |
| 2007 | characters (\-size). |
| 2008 | .IP "4." 4 |
| 2009 | The optional fourth parameter is the maximum number of characters the |
| 2010 | field will accept (\-maxlength). |
| 2011 | .PP |
| 2012 | When the form is processed, you can retrieve the entered filename |
| 2013 | by calling \fIparam()\fR: |
| 2014 | .PP |
| 2015 | .Vb 1 |
| 2016 | \& $filename = $query->param('uploaded_file'); |
| 2017 | .Ve |
| 2018 | .PP |
| 2019 | Different browsers will return slightly different things for the |
| 2020 | name. Some browsers return the filename only. Others return the full |
| 2021 | path to the file, using the path conventions of the user's machine. |
| 2022 | Regardless, the name returned is always the name of the file on the |
| 2023 | \&\fIuser's\fR machine, and is unrelated to the name of the temporary file |
| 2024 | that \s-1CGI\s0.pm creates during upload spooling (see below). |
| 2025 | .PP |
| 2026 | The filename returned is also a file handle. You can read the contents |
| 2027 | of the file using standard Perl file reading calls: |
| 2028 | .PP |
| 2029 | .Vb 4 |
| 2030 | \& # Read a text file and print it out |
| 2031 | \& while (<$filename>) { |
| 2032 | \& print; |
| 2033 | \& } |
| 2034 | .Ve |
| 2035 | .PP |
| 2036 | .Vb 5 |
| 2037 | \& # Copy a binary file to somewhere safe |
| 2038 | \& open (OUTFILE,">>/usr/local/web/users/feedback"); |
| 2039 | \& while ($bytesread=read($filename,$buffer,1024)) { |
| 2040 | \& print OUTFILE $buffer; |
| 2041 | \& } |
| 2042 | .Ve |
| 2043 | .PP |
| 2044 | However, there are problems with the dual nature of the upload fields. |
| 2045 | If you \f(CW\*(C`use strict\*(C'\fR, then Perl will complain when you try to use a |
| 2046 | string as a filehandle. You can get around this by placing the file |
| 2047 | reading code in a block containing the \f(CW\*(C`no strict\*(C'\fR pragma. More |
| 2048 | seriously, it is possible for the remote user to type garbage into the |
| 2049 | upload field, in which case what you get from \fIparam()\fR is not a |
| 2050 | filehandle at all, but a string. |
| 2051 | .PP |
| 2052 | To be safe, use the \fI\fIupload()\fI\fR function (new in version 2.47). When |
| 2053 | called with the name of an upload field, \fI\fIupload()\fI\fR returns a |
| 2054 | filehandle, or undef if the parameter is not a valid filehandle. |
| 2055 | .PP |
| 2056 | .Vb 4 |
| 2057 | \& $fh = $query->upload('uploaded_file'); |
| 2058 | \& while (<$fh>) { |
| 2059 | \& print; |
| 2060 | \& } |
| 2061 | .Ve |
| 2062 | .PP |
| 2063 | In an array context, \fIupload()\fR will return an array of filehandles. |
| 2064 | This makes it possible to create forms that use the same name for |
| 2065 | multiple upload fields. |
| 2066 | .PP |
| 2067 | This is the recommended idiom. |
| 2068 | .PP |
| 2069 | When a file is uploaded the browser usually sends along some |
| 2070 | information along with it in the format of headers. The information |
| 2071 | usually includes the \s-1MIME\s0 content type. Future browsers may send |
| 2072 | other information as well (such as modification date and size). To |
| 2073 | retrieve this information, call \fIuploadInfo()\fR. It returns a reference to |
| 2074 | an associative array containing all the document headers. |
| 2075 | .PP |
| 2076 | .Vb 5 |
| 2077 | \& $filename = $query->param('uploaded_file'); |
| 2078 | \& $type = $query->uploadInfo($filename)->{'Content-Type'}; |
| 2079 | \& unless ($type eq 'text/html') { |
| 2080 | \& die "HTML FILES ONLY!"; |
| 2081 | \& } |
| 2082 | .Ve |
| 2083 | .PP |
| 2084 | If you are using a machine that recognizes \*(L"text\*(R" and \*(L"binary\*(R" data |
| 2085 | modes, be sure to understand when and how to use them (see the Camel book). |
| 2086 | Otherwise you may find that binary files are corrupted during file |
| 2087 | uploads. |
| 2088 | .PP |
| 2089 | There are occasionally problems involving parsing the uploaded file. |
| 2090 | This usually happens when the user presses \*(L"Stop\*(R" before the upload is |
| 2091 | finished. In this case, \s-1CGI\s0.pm will return undef for the name of the |
| 2092 | uploaded file and set \fI\fIcgi_error()\fI\fR to the string \*(L"400 Bad request |
| 2093 | (malformed multipart \s-1POST\s0)\*(R". This error message is designed so that |
| 2094 | you can incorporate it into a status code to be sent to the browser. |
| 2095 | Example: |
| 2096 | .PP |
| 2097 | .Vb 5 |
| 2098 | \& $file = $query->upload('uploaded_file'); |
| 2099 | \& if (!$file && $query->cgi_error) { |
| 2100 | \& print $query->header(-status=>$query->cgi_error); |
| 2101 | \& exit 0; |
| 2102 | \& } |
| 2103 | .Ve |
| 2104 | .PP |
| 2105 | You are free to create a custom \s-1HTML\s0 page to complain about the error, |
| 2106 | if you wish. |
| 2107 | .PP |
| 2108 | If you are using \s-1CGI\s0.pm on a Windows platform and find that binary |
| 2109 | files get slightly larger when uploaded but that text files remain the |
| 2110 | same, then you have forgotten to activate binary mode on the output |
| 2111 | filehandle. Be sure to call \fIbinmode()\fR on any handle that you create |
| 2112 | to write the uploaded file to disk. |
| 2113 | .PP |
| 2114 | \&\s-1JAVASCRIPTING:\s0 The \fB\-onChange\fR, \fB\-onFocus\fR, \fB\-onBlur\fR, |
| 2115 | \&\fB\-onMouseOver\fR, \fB\-onMouseOut\fR and \fB\-onSelect\fR parameters are |
| 2116 | recognized. See \fItextfield()\fR for details. |
| 2117 | .Sh "\s-1CREATING\s0 A \s-1POPUP\s0 \s-1MENU\s0" |
| 2118 | .IX Subsection "CREATING A POPUP MENU" |
| 2119 | .Vb 3 |
| 2120 | \& print $query->popup_menu('menu_name', |
| 2121 | \& ['eenie','meenie','minie'], |
| 2122 | \& 'meenie'); |
| 2123 | .Ve |
| 2124 | .PP |
| 2125 | .Vb 1 |
| 2126 | \& -or- |
| 2127 | .Ve |
| 2128 | .PP |
| 2129 | .Vb 6 |
| 2130 | \& %labels = ('eenie'=>'your first choice', |
| 2131 | \& 'meenie'=>'your second choice', |
| 2132 | \& 'minie'=>'your third choice'); |
| 2133 | \& print $query->popup_menu('menu_name', |
| 2134 | \& ['eenie','meenie','minie'], |
| 2135 | \& 'meenie',\e%labels); |
| 2136 | .Ve |
| 2137 | .PP |
| 2138 | .Vb 1 |
| 2139 | \& -or (named parameter style)- |
| 2140 | .Ve |
| 2141 | .PP |
| 2142 | .Vb 4 |
| 2143 | \& print $query->popup_menu(-name=>'menu_name', |
| 2144 | \& -values=>['eenie','meenie','minie'], |
| 2145 | \& -default=>'meenie', |
| 2146 | \& -labels=>\e%labels); |
| 2147 | .Ve |
| 2148 | .PP |
| 2149 | \&\fIpopup_menu()\fR creates a menu. |
| 2150 | .IP "1." 4 |
| 2151 | The required first argument is the menu's name (\-name). |
| 2152 | .IP "2." 4 |
| 2153 | The required second argument (\-values) is an array \fBreference\fR |
| 2154 | containing the list of menu items in the menu. You can pass the |
| 2155 | method an anonymous array, as shown in the example, or a reference to |
| 2156 | a named array, such as \*(L"\e@foo\*(R". |
| 2157 | .IP "3." 4 |
| 2158 | The optional third parameter (\-default) is the name of the default |
| 2159 | menu choice. If not specified, the first item will be the default. |
| 2160 | The values of the previous choice will be maintained across queries. |
| 2161 | .IP "4." 4 |
| 2162 | The optional fourth parameter (\-labels) is provided for people who |
| 2163 | want to use different values for the user-visible label inside the |
| 2164 | popup menu nd the value returned to your script. It's a pointer to an |
| 2165 | associative array relating menu values to user-visible labels. If you |
| 2166 | leave this parameter blank, the menu values will be displayed by |
| 2167 | default. (You can also leave a label undefined if you want to). |
| 2168 | .PP |
| 2169 | When the form is processed, the selected value of the popup menu can |
| 2170 | be retrieved using: |
| 2171 | .PP |
| 2172 | .Vb 1 |
| 2173 | \& $popup_menu_value = $query->param('menu_name'); |
| 2174 | .Ve |
| 2175 | .PP |
| 2176 | \&\s-1JAVASCRIPTING:\s0 \fIpopup_menu()\fR recognizes the following event handlers: |
| 2177 | \&\fB\-onChange\fR, \fB\-onFocus\fR, \fB\-onMouseOver\fR, \fB\-onMouseOut\fR, and |
| 2178 | \&\fB\-onBlur\fR. See the \fItextfield()\fR section for details on when these |
| 2179 | handlers are called. |
| 2180 | .Sh "\s-1CREATING\s0 A \s-1SCROLLING\s0 \s-1LIST\s0" |
| 2181 | .IX Subsection "CREATING A SCROLLING LIST" |
| 2182 | .Vb 4 |
| 2183 | \& print $query->scrolling_list('list_name', |
| 2184 | \& ['eenie','meenie','minie','moe'], |
| 2185 | \& ['eenie','moe'],5,'true'); |
| 2186 | \& -or- |
| 2187 | .Ve |
| 2188 | .PP |
| 2189 | .Vb 4 |
| 2190 | \& print $query->scrolling_list('list_name', |
| 2191 | \& ['eenie','meenie','minie','moe'], |
| 2192 | \& ['eenie','moe'],5,'true', |
| 2193 | \& \e%labels); |
| 2194 | .Ve |
| 2195 | .PP |
| 2196 | .Vb 1 |
| 2197 | \& -or- |
| 2198 | .Ve |
| 2199 | .PP |
| 2200 | .Vb 6 |
| 2201 | \& print $query->scrolling_list(-name=>'list_name', |
| 2202 | \& -values=>['eenie','meenie','minie','moe'], |
| 2203 | \& -default=>['eenie','moe'], |
| 2204 | \& -size=>5, |
| 2205 | \& -multiple=>'true', |
| 2206 | \& -labels=>\e%labels); |
| 2207 | .Ve |
| 2208 | .PP |
| 2209 | \&\fIscrolling_list()\fR creates a scrolling list. |
| 2210 | .IP "\fBParameters:\fR" 4 |
| 2211 | .IX Item "Parameters:" |
| 2212 | .PD 0 |
| 2213 | .IP "1." 4 |
| 2214 | .PD |
| 2215 | The first and second arguments are the list name (\-name) and values |
| 2216 | (\-values). As in the popup menu, the second argument should be an |
| 2217 | array reference. |
| 2218 | .IP "2." 4 |
| 2219 | The optional third argument (\-default) can be either a reference to a |
| 2220 | list containing the values to be selected by default, or can be a |
| 2221 | single value to select. If this argument is missing or undefined, |
| 2222 | then nothing is selected when the list first appears. In the named |
| 2223 | parameter version, you can use the synonym \*(L"\-defaults\*(R" for this |
| 2224 | parameter. |
| 2225 | .IP "3." 4 |
| 2226 | The optional fourth argument is the size of the list (\-size). |
| 2227 | .IP "4." 4 |
| 2228 | The optional fifth argument can be set to true to allow multiple |
| 2229 | simultaneous selections (\-multiple). Otherwise only one selection |
| 2230 | will be allowed at a time. |
| 2231 | .IP "5." 4 |
| 2232 | The optional sixth argument is a pointer to an associative array |
| 2233 | containing long user-visible labels for the list items (\-labels). |
| 2234 | If not provided, the values will be displayed. |
| 2235 | .Sp |
| 2236 | When this form is processed, all selected list items will be returned as |
| 2237 | a list under the parameter name 'list_name'. The values of the |
| 2238 | selected items can be retrieved with: |
| 2239 | .Sp |
| 2240 | .Vb 1 |
| 2241 | \& @selected = $query->param('list_name'); |
| 2242 | .Ve |
| 2243 | .PP |
| 2244 | \&\s-1JAVASCRIPTING:\s0 \fIscrolling_list()\fR recognizes the following event |
| 2245 | handlers: \fB\-onChange\fR, \fB\-onFocus\fR, \fB\-onMouseOver\fR, \fB\-onMouseOut\fR |
| 2246 | and \fB\-onBlur\fR. See \fItextfield()\fR for the description of when these |
| 2247 | handlers are called. |
| 2248 | .Sh "\s-1CREATING\s0 A \s-1GROUP\s0 \s-1OF\s0 \s-1RELATED\s0 \s-1CHECKBOXES\s0" |
| 2249 | .IX Subsection "CREATING A GROUP OF RELATED CHECKBOXES" |
| 2250 | .Vb 5 |
| 2251 | \& print $query->checkbox_group(-name=>'group_name', |
| 2252 | \& -values=>['eenie','meenie','minie','moe'], |
| 2253 | \& -default=>['eenie','moe'], |
| 2254 | \& -linebreak=>'true', |
| 2255 | \& -labels=>\e%labels); |
| 2256 | .Ve |
| 2257 | .PP |
| 2258 | .Vb 3 |
| 2259 | \& print $query->checkbox_group('group_name', |
| 2260 | \& ['eenie','meenie','minie','moe'], |
| 2261 | \& ['eenie','moe'],'true',\e%labels); |
| 2262 | .Ve |
| 2263 | .PP |
| 2264 | .Vb 1 |
| 2265 | \& HTML3-COMPATIBLE BROWSERS ONLY: |
| 2266 | .Ve |
| 2267 | .PP |
| 2268 | .Vb 3 |
| 2269 | \& print $query->checkbox_group(-name=>'group_name', |
| 2270 | \& -values=>['eenie','meenie','minie','moe'], |
| 2271 | \& -rows=2,-columns=>2); |
| 2272 | .Ve |
| 2273 | .PP |
| 2274 | \&\fIcheckbox_group()\fR creates a list of checkboxes that are related |
| 2275 | by the same name. |
| 2276 | .IP "\fBParameters:\fR" 4 |
| 2277 | .IX Item "Parameters:" |
| 2278 | .PD 0 |
| 2279 | .IP "1." 4 |
| 2280 | .PD |
| 2281 | The first and second arguments are the checkbox name and values, |
| 2282 | respectively (\-name and \-values). As in the popup menu, the second |
| 2283 | argument should be an array reference. These values are used for the |
| 2284 | user-readable labels printed next to the checkboxes as well as for the |
| 2285 | values passed to your script in the query string. |
| 2286 | .IP "2." 4 |
| 2287 | The optional third argument (\-default) can be either a reference to a |
| 2288 | list containing the values to be checked by default, or can be a |
| 2289 | single value to checked. If this argument is missing or undefined, |
| 2290 | then nothing is selected when the list first appears. |
| 2291 | .IP "3." 4 |
| 2292 | The optional fourth argument (\-linebreak) can be set to true to place |
| 2293 | line breaks between the checkboxes so that they appear as a vertical |
| 2294 | list. Otherwise, they will be strung together on a horizontal line. |
| 2295 | .IP "4." 4 |
| 2296 | The optional fifth argument is a pointer to an associative array |
| 2297 | relating the checkbox values to the user-visible labels that will |
| 2298 | be printed next to them (\-labels). If not provided, the values will |
| 2299 | be used as the default. |
| 2300 | .IP "5." 4 |
| 2301 | \&\fBHTML3\-compatible browsers\fR (such as Netscape) can take advantage of |
| 2302 | the optional parameters \fB\-rows\fR, and \fB\-columns\fR. These parameters |
| 2303 | cause \fIcheckbox_group()\fR to return an \s-1HTML3\s0 compatible table containing |
| 2304 | the checkbox group formatted with the specified number of rows and |
| 2305 | columns. You can provide just the \-columns parameter if you wish; |
| 2306 | checkbox_group will calculate the correct number of rows for you. |
| 2307 | .Sp |
| 2308 | To include row and column headings in the returned table, you |
| 2309 | can use the \fB\-rowheaders\fR and \fB\-colheaders\fR parameters. Both |
| 2310 | of these accept a pointer to an array of headings to use. |
| 2311 | The headings are just decorative. They don't reorganize the |
| 2312 | interpretation of the checkboxes \*(-- they're still a single named |
| 2313 | unit. |
| 2314 | .PP |
| 2315 | When the form is processed, all checked boxes will be returned as |
| 2316 | a list under the parameter name 'group_name'. The values of the |
| 2317 | \&\*(L"on\*(R" checkboxes can be retrieved with: |
| 2318 | .PP |
| 2319 | .Vb 1 |
| 2320 | \& @turned_on = $query->param('group_name'); |
| 2321 | .Ve |
| 2322 | .PP |
| 2323 | The value returned by \fIcheckbox_group()\fR is actually an array of button |
| 2324 | elements. You can capture them and use them within tables, lists, |
| 2325 | or in other creative ways: |
| 2326 | .PP |
| 2327 | .Vb 2 |
| 2328 | \& @h = $query->checkbox_group(-name=>'group_name',-values=>\e@values); |
| 2329 | \& &use_in_creative_way(@h); |
| 2330 | .Ve |
| 2331 | .PP |
| 2332 | \&\s-1JAVASCRIPTING:\s0 \fIcheckbox_group()\fR recognizes the \fB\-onClick\fR |
| 2333 | parameter. This specifies a JavaScript code fragment or |
| 2334 | function call to be executed every time the user clicks on |
| 2335 | any of the buttons in the group. You can retrieve the identity |
| 2336 | of the particular button clicked on using the \*(L"this\*(R" variable. |
| 2337 | .Sh "\s-1CREATING\s0 A \s-1STANDALONE\s0 \s-1CHECKBOX\s0" |
| 2338 | .IX Subsection "CREATING A STANDALONE CHECKBOX" |
| 2339 | .Vb 4 |
| 2340 | \& print $query->checkbox(-name=>'checkbox_name', |
| 2341 | \& -checked=>1, |
| 2342 | \& -value=>'ON', |
| 2343 | \& -label=>'CLICK ME'); |
| 2344 | .Ve |
| 2345 | .PP |
| 2346 | .Vb 1 |
| 2347 | \& -or- |
| 2348 | .Ve |
| 2349 | .PP |
| 2350 | .Vb 1 |
| 2351 | \& print $query->checkbox('checkbox_name','checked','ON','CLICK ME'); |
| 2352 | .Ve |
| 2353 | .PP |
| 2354 | \&\fIcheckbox()\fR is used to create an isolated checkbox that isn't logically |
| 2355 | related to any others. |
| 2356 | .IP "\fBParameters:\fR" 4 |
| 2357 | .IX Item "Parameters:" |
| 2358 | .PD 0 |
| 2359 | .IP "1." 4 |
| 2360 | .PD |
| 2361 | The first parameter is the required name for the checkbox (\-name). It |
| 2362 | will also be used for the user-readable label printed next to the |
| 2363 | checkbox. |
| 2364 | .IP "2." 4 |
| 2365 | The optional second parameter (\-checked) specifies that the checkbox |
| 2366 | is turned on by default. Synonyms are \-selected and \-on. |
| 2367 | .IP "3." 4 |
| 2368 | The optional third parameter (\-value) specifies the value of the |
| 2369 | checkbox when it is checked. If not provided, the word \*(L"on\*(R" is |
| 2370 | assumed. |
| 2371 | .IP "4." 4 |
| 2372 | The optional fourth parameter (\-label) is the user-readable label to |
| 2373 | be attached to the checkbox. If not provided, the checkbox name is |
| 2374 | used. |
| 2375 | .PP |
| 2376 | The value of the checkbox can be retrieved using: |
| 2377 | .PP |
| 2378 | .Vb 1 |
| 2379 | \& $turned_on = $query->param('checkbox_name'); |
| 2380 | .Ve |
| 2381 | .PP |
| 2382 | \&\s-1JAVASCRIPTING:\s0 \fIcheckbox()\fR recognizes the \fB\-onClick\fR |
| 2383 | parameter. See \fIcheckbox_group()\fR for further details. |
| 2384 | .Sh "\s-1CREATING\s0 A \s-1RADIO\s0 \s-1BUTTON\s0 \s-1GROUP\s0" |
| 2385 | .IX Subsection "CREATING A RADIO BUTTON GROUP" |
| 2386 | .Vb 5 |
| 2387 | \& print $query->radio_group(-name=>'group_name', |
| 2388 | \& -values=>['eenie','meenie','minie'], |
| 2389 | \& -default=>'meenie', |
| 2390 | \& -linebreak=>'true', |
| 2391 | \& -labels=>\e%labels); |
| 2392 | .Ve |
| 2393 | .PP |
| 2394 | .Vb 1 |
| 2395 | \& -or- |
| 2396 | .Ve |
| 2397 | .PP |
| 2398 | .Vb 2 |
| 2399 | \& print $query->radio_group('group_name',['eenie','meenie','minie'], |
| 2400 | \& 'meenie','true',\e%labels); |
| 2401 | .Ve |
| 2402 | .PP |
| 2403 | .Vb 1 |
| 2404 | \& HTML3-COMPATIBLE BROWSERS ONLY: |
| 2405 | .Ve |
| 2406 | .PP |
| 2407 | .Vb 3 |
| 2408 | \& print $query->radio_group(-name=>'group_name', |
| 2409 | \& -values=>['eenie','meenie','minie','moe'], |
| 2410 | \& -rows=2,-columns=>2); |
| 2411 | .Ve |
| 2412 | .PP |
| 2413 | \&\fIradio_group()\fR creates a set of logically-related radio buttons |
| 2414 | (turning one member of the group on turns the others off) |
| 2415 | .IP "\fBParameters:\fR" 4 |
| 2416 | .IX Item "Parameters:" |
| 2417 | .PD 0 |
| 2418 | .IP "1." 4 |
| 2419 | .PD |
| 2420 | The first argument is the name of the group and is required (\-name). |
| 2421 | .IP "2." 4 |
| 2422 | The second argument (\-values) is the list of values for the radio |
| 2423 | buttons. The values and the labels that appear on the page are |
| 2424 | identical. Pass an array \fIreference\fR in the second argument, either |
| 2425 | using an anonymous array, as shown, or by referencing a named array as |
| 2426 | in \*(L"\e@foo\*(R". |
| 2427 | .IP "3." 4 |
| 2428 | The optional third parameter (\-default) is the name of the default |
| 2429 | button to turn on. If not specified, the first item will be the |
| 2430 | default. You can provide a nonexistent button name, such as \*(L"\-\*(R" to |
| 2431 | start up with no buttons selected. |
| 2432 | .IP "4." 4 |
| 2433 | The optional fourth parameter (\-linebreak) can be set to 'true' to put |
| 2434 | line breaks between the buttons, creating a vertical list. |
| 2435 | .IP "5." 4 |
| 2436 | The optional fifth parameter (\-labels) is a pointer to an associative |
| 2437 | array relating the radio button values to user-visible labels to be |
| 2438 | used in the display. If not provided, the values themselves are |
| 2439 | displayed. |
| 2440 | .IP "6." 4 |
| 2441 | \&\fBHTML3\-compatible browsers\fR (such as Netscape) can take advantage |
| 2442 | of the optional |
| 2443 | parameters \fB\-rows\fR, and \fB\-columns\fR. These parameters cause |
| 2444 | \&\fIradio_group()\fR to return an \s-1HTML3\s0 compatible table containing |
| 2445 | the radio group formatted with the specified number of rows |
| 2446 | and columns. You can provide just the \-columns parameter if you |
| 2447 | wish; radio_group will calculate the correct number of rows |
| 2448 | for you. |
| 2449 | .Sp |
| 2450 | To include row and column headings in the returned table, you |
| 2451 | can use the \fB\-rowheader\fR and \fB\-colheader\fR parameters. Both |
| 2452 | of these accept a pointer to an array of headings to use. |
| 2453 | The headings are just decorative. They don't reorganize the |
| 2454 | interpretation of the radio buttons \*(-- they're still a single named |
| 2455 | unit. |
| 2456 | .PP |
| 2457 | When the form is processed, the selected radio button can |
| 2458 | be retrieved using: |
| 2459 | .PP |
| 2460 | .Vb 1 |
| 2461 | \& $which_radio_button = $query->param('group_name'); |
| 2462 | .Ve |
| 2463 | .PP |
| 2464 | The value returned by \fIradio_group()\fR is actually an array of button |
| 2465 | elements. You can capture them and use them within tables, lists, |
| 2466 | or in other creative ways: |
| 2467 | .PP |
| 2468 | .Vb 2 |
| 2469 | \& @h = $query->radio_group(-name=>'group_name',-values=>\e@values); |
| 2470 | \& &use_in_creative_way(@h); |
| 2471 | .Ve |
| 2472 | .Sh "\s-1CREATING\s0 A \s-1SUBMIT\s0 \s-1BUTTON\s0" |
| 2473 | .IX Subsection "CREATING A SUBMIT BUTTON" |
| 2474 | .Vb 2 |
| 2475 | \& print $query->submit(-name=>'button_name', |
| 2476 | \& -value=>'value'); |
| 2477 | .Ve |
| 2478 | .PP |
| 2479 | .Vb 1 |
| 2480 | \& -or- |
| 2481 | .Ve |
| 2482 | .PP |
| 2483 | .Vb 1 |
| 2484 | \& print $query->submit('button_name','value'); |
| 2485 | .Ve |
| 2486 | .PP |
| 2487 | \&\fIsubmit()\fR will create the query submission button. Every form |
| 2488 | should have one of these. |
| 2489 | .IP "\fBParameters:\fR" 4 |
| 2490 | .IX Item "Parameters:" |
| 2491 | .PD 0 |
| 2492 | .IP "1." 4 |
| 2493 | .PD |
| 2494 | The first argument (\-name) is optional. You can give the button a |
| 2495 | name if you have several submission buttons in your form and you want |
| 2496 | to distinguish between them. The name will also be used as the |
| 2497 | user-visible label. Be aware that a few older browsers don't deal with this correctly and |
| 2498 | \&\fBnever\fR send back a value from a button. |
| 2499 | .IP "2." 4 |
| 2500 | The second argument (\-value) is also optional. This gives the button |
| 2501 | a value that will be passed to your script in the query string. |
| 2502 | .PP |
| 2503 | You can figure out which button was pressed by using different |
| 2504 | values for each one: |
| 2505 | .PP |
| 2506 | .Vb 1 |
| 2507 | \& $which_one = $query->param('button_name'); |
| 2508 | .Ve |
| 2509 | .PP |
| 2510 | \&\s-1JAVASCRIPTING:\s0 \fIradio_group()\fR recognizes the \fB\-onClick\fR |
| 2511 | parameter. See \fIcheckbox_group()\fR for further details. |
| 2512 | .Sh "\s-1CREATING\s0 A \s-1RESET\s0 \s-1BUTTON\s0" |
| 2513 | .IX Subsection "CREATING A RESET BUTTON" |
| 2514 | .Vb 1 |
| 2515 | \& print $query->reset |
| 2516 | .Ve |
| 2517 | .PP |
| 2518 | \&\fIreset()\fR creates the \*(L"reset\*(R" button. Note that it restores the |
| 2519 | form to its value from the last time the script was called, |
| 2520 | \&\s-1NOT\s0 necessarily to the defaults. |
| 2521 | .PP |
| 2522 | Note that this conflicts with the Perl \fIreset()\fR built\-in. Use |
| 2523 | \&\fICORE::reset()\fR to get the original reset function. |
| 2524 | .Sh "\s-1CREATING\s0 A \s-1DEFAULT\s0 \s-1BUTTON\s0" |
| 2525 | .IX Subsection "CREATING A DEFAULT BUTTON" |
| 2526 | .Vb 1 |
| 2527 | \& print $query->defaults('button_label') |
| 2528 | .Ve |
| 2529 | .PP |
| 2530 | \&\fIdefaults()\fR creates a button that, when invoked, will cause the |
| 2531 | form to be completely reset to its defaults, wiping out all the |
| 2532 | changes the user ever made. |
| 2533 | .Sh "\s-1CREATING\s0 A \s-1HIDDEN\s0 \s-1FIELD\s0" |
| 2534 | .IX Subsection "CREATING A HIDDEN FIELD" |
| 2535 | .Vb 2 |
| 2536 | \& print $query->hidden(-name=>'hidden_name', |
| 2537 | \& -default=>['value1','value2'...]); |
| 2538 | .Ve |
| 2539 | .PP |
| 2540 | .Vb 1 |
| 2541 | \& -or- |
| 2542 | .Ve |
| 2543 | .PP |
| 2544 | .Vb 1 |
| 2545 | \& print $query->hidden('hidden_name','value1','value2'...); |
| 2546 | .Ve |
| 2547 | .PP |
| 2548 | \&\fIhidden()\fR produces a text field that can't be seen by the user. It |
| 2549 | is useful for passing state variable information from one invocation |
| 2550 | of the script to the next. |
| 2551 | .IP "\fBParameters:\fR" 4 |
| 2552 | .IX Item "Parameters:" |
| 2553 | .PD 0 |
| 2554 | .IP "1." 4 |
| 2555 | .PD |
| 2556 | The first argument is required and specifies the name of this |
| 2557 | field (\-name). |
| 2558 | .IP "2." 4 |
| 2559 | The second argument is also required and specifies its value |
| 2560 | (\-default). In the named parameter style of calling, you can provide |
| 2561 | a single value here or a reference to a whole list |
| 2562 | .PP |
| 2563 | Fetch the value of a hidden field this way: |
| 2564 | .PP |
| 2565 | .Vb 1 |
| 2566 | \& $hidden_value = $query->param('hidden_name'); |
| 2567 | .Ve |
| 2568 | .PP |
| 2569 | Note, that just like all the other form elements, the value of a |
| 2570 | hidden field is \*(L"sticky\*(R". If you want to replace a hidden field with |
| 2571 | some other values after the script has been called once you'll have to |
| 2572 | do it manually: |
| 2573 | .PP |
| 2574 | .Vb 1 |
| 2575 | \& $query->param('hidden_name','new','values','here'); |
| 2576 | .Ve |
| 2577 | .Sh "\s-1CREATING\s0 A \s-1CLICKABLE\s0 \s-1IMAGE\s0 \s-1BUTTON\s0" |
| 2578 | .IX Subsection "CREATING A CLICKABLE IMAGE BUTTON" |
| 2579 | .Vb 3 |
| 2580 | \& print $query->image_button(-name=>'button_name', |
| 2581 | \& -src=>'/source/URL', |
| 2582 | \& -align=>'MIDDLE'); |
| 2583 | .Ve |
| 2584 | .PP |
| 2585 | .Vb 1 |
| 2586 | \& -or- |
| 2587 | .Ve |
| 2588 | .PP |
| 2589 | .Vb 1 |
| 2590 | \& print $query->image_button('button_name','/source/URL','MIDDLE'); |
| 2591 | .Ve |
| 2592 | .PP |
| 2593 | \&\fIimage_button()\fR produces a clickable image. When it's clicked on the |
| 2594 | position of the click is returned to your script as \*(L"button_name.x\*(R" |
| 2595 | and \*(L"button_name.y\*(R", where \*(L"button_name\*(R" is the name you've assigned |
| 2596 | to it. |
| 2597 | .PP |
| 2598 | \&\s-1JAVASCRIPTING:\s0 \fIimage_button()\fR recognizes the \fB\-onClick\fR |
| 2599 | parameter. See \fIcheckbox_group()\fR for further details. |
| 2600 | .IP "\fBParameters:\fR" 4 |
| 2601 | .IX Item "Parameters:" |
| 2602 | .PD 0 |
| 2603 | .IP "1." 4 |
| 2604 | .PD |
| 2605 | The first argument (\-name) is required and specifies the name of this |
| 2606 | field. |
| 2607 | .IP "2." 4 |
| 2608 | The second argument (\-src) is also required and specifies the \s-1URL\s0 |
| 2609 | .IP "3." 4 |
| 2610 | The third option (\-align, optional) is an alignment type, and may be |
| 2611 | \&\s-1TOP\s0, \s-1BOTTOM\s0 or \s-1MIDDLE\s0 |
| 2612 | .PP |
| 2613 | Fetch the value of the button this way: |
| 2614 | \f(CW$x\fR = \f(CW$query\fR\->param('button_name.x'); |
| 2615 | \f(CW$y\fR = \f(CW$query\fR\->param('button_name.y'); |
| 2616 | .Sh "\s-1CREATING\s0 A \s-1JAVASCRIPT\s0 \s-1ACTION\s0 \s-1BUTTON\s0" |
| 2617 | .IX Subsection "CREATING A JAVASCRIPT ACTION BUTTON" |
| 2618 | .Vb 3 |
| 2619 | \& print $query->button(-name=>'button_name', |
| 2620 | \& -value=>'user visible label', |
| 2621 | \& -onClick=>"do_something()"); |
| 2622 | .Ve |
| 2623 | .PP |
| 2624 | .Vb 1 |
| 2625 | \& -or- |
| 2626 | .Ve |
| 2627 | .PP |
| 2628 | .Vb 1 |
| 2629 | \& print $query->button('button_name',"do_something()"); |
| 2630 | .Ve |
| 2631 | .PP |
| 2632 | \&\fIbutton()\fR produces a button that is compatible with Netscape 2.0's |
| 2633 | JavaScript. When it's pressed the fragment of JavaScript code |
| 2634 | pointed to by the \fB\-onClick\fR parameter will be executed. On |
| 2635 | non-Netscape browsers this form element will probably not even |
| 2636 | display. |
| 2637 | .SH "HTTP COOKIES" |
| 2638 | .IX Header "HTTP COOKIES" |
| 2639 | Netscape browsers versions 1.1 and higher, and all versions of |
| 2640 | Internet Explorer, support a so-called \*(L"cookie\*(R" designed to help |
| 2641 | maintain state within a browser session. \s-1CGI\s0.pm has several methods |
| 2642 | that support cookies. |
| 2643 | .PP |
| 2644 | A cookie is a name=value pair much like the named parameters in a \s-1CGI\s0 |
| 2645 | query string. \s-1CGI\s0 scripts create one or more cookies and send |
| 2646 | them to the browser in the \s-1HTTP\s0 header. The browser maintains a list |
| 2647 | of cookies that belong to a particular Web server, and returns them |
| 2648 | to the \s-1CGI\s0 script during subsequent interactions. |
| 2649 | .PP |
| 2650 | In addition to the required name=value pair, each cookie has several |
| 2651 | optional attributes: |
| 2652 | .IP "1. an expiration time" 4 |
| 2653 | .IX Item "1. an expiration time" |
| 2654 | This is a time/date string (in a special \s-1GMT\s0 format) that indicates |
| 2655 | when a cookie expires. The cookie will be saved and returned to your |
| 2656 | script until this expiration date is reached if the user exits |
| 2657 | the browser and restarts it. If an expiration date isn't specified, the cookie |
| 2658 | will remain active until the user quits the browser. |
| 2659 | .IP "2. a domain" 4 |
| 2660 | .IX Item "2. a domain" |
| 2661 | This is a partial or complete domain name for which the cookie is |
| 2662 | valid. The browser will return the cookie to any host that matches |
| 2663 | the partial domain name. For example, if you specify a domain name |
| 2664 | of \*(L".capricorn.com\*(R", then the browser will return the cookie to |
| 2665 | Web servers running on any of the machines \*(L"www.capricorn.com\*(R", |
| 2666 | \&\*(L"www2.capricorn.com\*(R", \*(L"feckless.capricorn.com\*(R", etc. Domain names |
| 2667 | must contain at least two periods to prevent attempts to match |
| 2668 | on top level domains like \*(L".edu\*(R". If no domain is specified, then |
| 2669 | the browser will only return the cookie to servers on the host the |
| 2670 | cookie originated from. |
| 2671 | .IP "3. a path" 4 |
| 2672 | .IX Item "3. a path" |
| 2673 | If you provide a cookie path attribute, the browser will check it |
| 2674 | against your script's \s-1URL\s0 before returning the cookie. For example, |
| 2675 | if you specify the path \*(L"/cgi\-bin\*(R", then the cookie will be returned |
| 2676 | to each of the scripts \*(L"/cgi\-bin/tally.pl\*(R", \*(L"/cgi\-bin/order.pl\*(R", |
| 2677 | and \*(L"/cgi\-bin/customer_service/complain.pl\*(R", but not to the script |
| 2678 | \&\*(L"/cgi\-private/site_admin.pl\*(R". By default, path is set to \*(L"/\*(R", which |
| 2679 | causes the cookie to be sent to any \s-1CGI\s0 script on your site. |
| 2680 | .ie n .IP "4. a ""secure"" flag" 4 |
| 2681 | .el .IP "4. a ``secure'' flag" 4 |
| 2682 | .IX Item "4. a secure flag" |
| 2683 | If the \*(L"secure\*(R" attribute is set, the cookie will only be sent to your |
| 2684 | script if the \s-1CGI\s0 request is occurring on a secure channel, such as \s-1SSL\s0. |
| 2685 | .PP |
| 2686 | The interface to \s-1HTTP\s0 cookies is the \fB\f(BIcookie()\fB\fR method: |
| 2687 | .PP |
| 2688 | .Vb 7 |
| 2689 | \& $cookie = $query->cookie(-name=>'sessionID', |
| 2690 | \& -value=>'xyzzy', |
| 2691 | \& -expires=>'+1h', |
| 2692 | \& -path=>'/cgi-bin/database', |
| 2693 | \& -domain=>'.capricorn.org', |
| 2694 | \& -secure=>1); |
| 2695 | \& print $query->header(-cookie=>$cookie); |
| 2696 | .Ve |
| 2697 | .PP |
| 2698 | \&\fB\f(BIcookie()\fB\fR creates a new cookie. Its parameters include: |
| 2699 | .IP "\fB\-name\fR" 4 |
| 2700 | .IX Item "-name" |
| 2701 | The name of the cookie (required). This can be any string at all. |
| 2702 | Although browsers limit their cookie names to non-whitespace |
| 2703 | alphanumeric characters, \s-1CGI\s0.pm removes this restriction by escaping |
| 2704 | and unescaping cookies behind the scenes. |
| 2705 | .IP "\fB\-value\fR" 4 |
| 2706 | .IX Item "-value" |
| 2707 | The value of the cookie. This can be any scalar value, |
| 2708 | array reference, or even associative array reference. For example, |
| 2709 | you can store an entire associative array into a cookie this way: |
| 2710 | .Sp |
| 2711 | .Vb 2 |
| 2712 | \& $cookie=$query->cookie(-name=>'family information', |
| 2713 | \& -value=>\e%childrens_ages); |
| 2714 | .Ve |
| 2715 | .IP "\fB\-path\fR" 4 |
| 2716 | .IX Item "-path" |
| 2717 | The optional partial path for which this cookie will be valid, as described |
| 2718 | above. |
| 2719 | .IP "\fB\-domain\fR" 4 |
| 2720 | .IX Item "-domain" |
| 2721 | The optional partial domain for which this cookie will be valid, as described |
| 2722 | above. |
| 2723 | .IP "\fB\-expires\fR" 4 |
| 2724 | .IX Item "-expires" |
| 2725 | The optional expiration date for this cookie. The format is as described |
| 2726 | in the section on the \fB\f(BIheader()\fB\fR method: |
| 2727 | .Sp |
| 2728 | .Vb 1 |
| 2729 | \& "+1h" one hour from now |
| 2730 | .Ve |
| 2731 | .IP "\fB\-secure\fR" 4 |
| 2732 | .IX Item "-secure" |
| 2733 | If set to true, this cookie will only be used within a secure |
| 2734 | \&\s-1SSL\s0 session. |
| 2735 | .PP |
| 2736 | The cookie created by \fIcookie()\fR must be incorporated into the \s-1HTTP\s0 |
| 2737 | header within the string returned by the \fIheader()\fR method: |
| 2738 | .PP |
| 2739 | .Vb 1 |
| 2740 | \& print $query->header(-cookie=>$my_cookie); |
| 2741 | .Ve |
| 2742 | .PP |
| 2743 | To create multiple cookies, give \fIheader()\fR an array reference: |
| 2744 | .PP |
| 2745 | .Vb 5 |
| 2746 | \& $cookie1 = $query->cookie(-name=>'riddle_name', |
| 2747 | \& -value=>"The Sphynx's Question"); |
| 2748 | \& $cookie2 = $query->cookie(-name=>'answers', |
| 2749 | \& -value=>\e%answers); |
| 2750 | \& print $query->header(-cookie=>[$cookie1,$cookie2]); |
| 2751 | .Ve |
| 2752 | .PP |
| 2753 | To retrieve a cookie, request it by name by calling \fIcookie()\fR method |
| 2754 | without the \fB\-value\fR parameter: |
| 2755 | .PP |
| 2756 | .Vb 4 |
| 2757 | \& use CGI; |
| 2758 | \& $query = new CGI; |
| 2759 | \& $riddle = $query->cookie('riddle_name'); |
| 2760 | \& %answers = $query->cookie('answers'); |
| 2761 | .Ve |
| 2762 | .PP |
| 2763 | Cookies created with a single scalar value, such as the \*(L"riddle_name\*(R" |
| 2764 | cookie, will be returned in that form. Cookies with array and hash |
| 2765 | values can also be retrieved. |
| 2766 | .PP |
| 2767 | The cookie and \s-1CGI\s0 namespaces are separate. If you have a parameter |
| 2768 | named 'answers' and a cookie named 'answers', the values retrieved by |
| 2769 | \&\fIparam()\fR and \fIcookie()\fR are independent of each other. However, it's |
| 2770 | simple to turn a \s-1CGI\s0 parameter into a cookie, and vice\-versa: |
| 2771 | .PP |
| 2772 | .Vb 4 |
| 2773 | \& # turn a CGI parameter into a cookie |
| 2774 | \& $c=$q->cookie(-name=>'answers',-value=>[$q->param('answers')]); |
| 2775 | \& # vice-versa |
| 2776 | \& $q->param(-name=>'answers',-value=>[$q->cookie('answers')]); |
| 2777 | .Ve |
| 2778 | .PP |
| 2779 | See the \fBcookie.cgi\fR example script for some ideas on how to use |
| 2780 | cookies effectively. |
| 2781 | .SH "WORKING WITH FRAMES" |
| 2782 | .IX Header "WORKING WITH FRAMES" |
| 2783 | It's possible for \s-1CGI\s0.pm scripts to write into several browser panels |
| 2784 | and windows using the \s-1HTML\s0 4 frame mechanism. There are three |
| 2785 | techniques for defining new frames programmatically: |
| 2786 | .IP "1. Create a <Frameset> document" 4 |
| 2787 | .IX Item "1. Create a <Frameset> document" |
| 2788 | After writing out the \s-1HTTP\s0 header, instead of creating a standard |
| 2789 | \&\s-1HTML\s0 document using the \fIstart_html()\fR call, create a <frameset> |
| 2790 | document that defines the frames on the page. Specify your script(s) |
| 2791 | (with appropriate parameters) as the \s-1SRC\s0 for each of the frames. |
| 2792 | .Sp |
| 2793 | There is no specific support for creating <frameset> sections |
| 2794 | in \s-1CGI\s0.pm, but the \s-1HTML\s0 is very simple to write. See the frame |
| 2795 | documentation in Netscape's home pages for details |
| 2796 | .Sp |
| 2797 | .Vb 1 |
| 2798 | \& http://home.netscape.com/assist/net_sites/frames.html |
| 2799 | .Ve |
| 2800 | .IP "2. Specify the destination for the document in the \s-1HTTP\s0 header" 4 |
| 2801 | .IX Item "2. Specify the destination for the document in the HTTP header" |
| 2802 | You may provide a \fB\-target\fR parameter to the \fIheader()\fR method: |
| 2803 | .Sp |
| 2804 | .Vb 1 |
| 2805 | \& print $q->header(-target=>'ResultsWindow'); |
| 2806 | .Ve |
| 2807 | .Sp |
| 2808 | This will tell the browser to load the output of your script into the |
| 2809 | frame named \*(L"ResultsWindow\*(R". If a frame of that name doesn't already |
| 2810 | exist, the browser will pop up a new window and load your script's |
| 2811 | document into that. There are a number of magic names that you can |
| 2812 | use for targets. See the frame documents on Netscape's home pages for |
| 2813 | details. |
| 2814 | .IP "3. Specify the destination for the document in the <form> tag" 4 |
| 2815 | .IX Item "3. Specify the destination for the document in the <form> tag" |
| 2816 | You can specify the frame to load in the \s-1FORM\s0 tag itself. With |
| 2817 | \&\s-1CGI\s0.pm it looks like this: |
| 2818 | .Sp |
| 2819 | .Vb 1 |
| 2820 | \& print $q->start_form(-target=>'ResultsWindow'); |
| 2821 | .Ve |
| 2822 | .Sp |
| 2823 | When your script is reinvoked by the form, its output will be loaded |
| 2824 | into the frame named \*(L"ResultsWindow\*(R". If one doesn't already exist |
| 2825 | a new window will be created. |
| 2826 | .PP |
| 2827 | The script \*(L"frameset.cgi\*(R" in the examples directory shows one way to |
| 2828 | create pages in which the fill-out form and the response live in |
| 2829 | side-by-side frames. |
| 2830 | .SH "LIMITED SUPPORT FOR CASCADING STYLE SHEETS" |
| 2831 | .IX Header "LIMITED SUPPORT FOR CASCADING STYLE SHEETS" |
| 2832 | \&\s-1CGI\s0.pm has limited support for \s-1HTML3\s0's cascading style sheets (css). |
| 2833 | To incorporate a stylesheet into your document, pass the |
| 2834 | \&\fIstart_html()\fR method a \fB\-style\fR parameter. The value of this |
| 2835 | parameter may be a scalar, in which case it is incorporated directly |
| 2836 | into a <style> section, or it may be a hash reference. In the latter |
| 2837 | case you should provide the hash with one or more of \fB\-src\fR or |
| 2838 | \&\fB\-code\fR. \fB\-src\fR points to a \s-1URL\s0 where an externally-defined |
| 2839 | stylesheet can be found. \fB\-code\fR points to a scalar value to be |
| 2840 | incorporated into a <style> section. Style definitions in \fB\-code\fR |
| 2841 | override similarly-named ones in \fB\-src\fR, hence the name \*(L"cascading.\*(R" |
| 2842 | .PP |
| 2843 | You may also specify the type of the stylesheet by adding the optional |
| 2844 | \&\fB\-type\fR parameter to the hash pointed to by \fB\-style\fR. If not |
| 2845 | specified, the style defaults to 'text/css'. |
| 2846 | .PP |
| 2847 | To refer to a style within the body of your document, add the |
| 2848 | \&\fB\-class\fR parameter to any \s-1HTML\s0 element: |
| 2849 | .PP |
| 2850 | .Vb 1 |
| 2851 | \& print h1({-class=>'Fancy'},'Welcome to the Party'); |
| 2852 | .Ve |
| 2853 | .PP |
| 2854 | Or define styles on the fly with the \fB\-style\fR parameter: |
| 2855 | .PP |
| 2856 | .Vb 1 |
| 2857 | \& print h1({-style=>'Color: red;'},'Welcome to Hell'); |
| 2858 | .Ve |
| 2859 | .PP |
| 2860 | You may also use the new \fB\f(BIspan()\fB\fR element to apply a style to a |
| 2861 | section of text: |
| 2862 | .PP |
| 2863 | .Vb 4 |
| 2864 | \& print span({-style=>'Color: red;'}, |
| 2865 | \& h1('Welcome to Hell'), |
| 2866 | \& "Where did that handbasket get to?" |
| 2867 | \& ); |
| 2868 | .Ve |
| 2869 | .PP |
| 2870 | Note that you must import the \*(L":html3\*(R" definitions to have the |
| 2871 | \&\fB\f(BIspan()\fB\fR method available. Here's a quick and dirty example of using |
| 2872 | \&\s-1CSS\s0's. See the \s-1CSS\s0 specification at |
| 2873 | http://www.w3.org/pub/WWW/TR/Wd\-css\-1.html for more information. |
| 2874 | .PP |
| 2875 | .Vb 1 |
| 2876 | \& use CGI qw/:standard :html3/; |
| 2877 | .Ve |
| 2878 | .PP |
| 2879 | .Vb 29 |
| 2880 | \& #here's a stylesheet incorporated directly into the page |
| 2881 | \& $newStyle=<<END; |
| 2882 | \& <!-- |
| 2883 | \& P.Tip { |
| 2884 | \& margin-right: 50pt; |
| 2885 | \& margin-left: 50pt; |
| 2886 | \& color: red; |
| 2887 | \& } |
| 2888 | \& P.Alert { |
| 2889 | \& font-size: 30pt; |
| 2890 | \& font-family: sans-serif; |
| 2891 | \& color: red; |
| 2892 | \& } |
| 2893 | \& --> |
| 2894 | \& END |
| 2895 | \& print header(); |
| 2896 | \& print start_html( -title=>'CGI with Style', |
| 2897 | \& -style=>{-src=>'http://www.capricorn.com/style/st1.css', |
| 2898 | \& -code=>$newStyle} |
| 2899 | \& ); |
| 2900 | \& print h1('CGI with Style'), |
| 2901 | \& p({-class=>'Tip'}, |
| 2902 | \& "Better read the cascading style sheet spec before playing with this!"), |
| 2903 | \& span({-style=>'color: magenta'}, |
| 2904 | \& "Look Mom, no hands!", |
| 2905 | \& p(), |
| 2906 | \& "Whooo wee!" |
| 2907 | \& ); |
| 2908 | \& print end_html; |
| 2909 | .Ve |
| 2910 | .PP |
| 2911 | Pass an array reference to \fB\-style\fR in order to incorporate multiple |
| 2912 | stylesheets into your document. |
| 2913 | .SH "DEBUGGING" |
| 2914 | .IX Header "DEBUGGING" |
| 2915 | If you are running the script from the command line or in the perl |
| 2916 | debugger, you can pass the script a list of keywords or |
| 2917 | parameter=value pairs on the command line or from standard input (you |
| 2918 | don't have to worry about tricking your script into reading from |
| 2919 | environment variables). You can pass keywords like this: |
| 2920 | .PP |
| 2921 | .Vb 1 |
| 2922 | \& your_script.pl keyword1 keyword2 keyword3 |
| 2923 | .Ve |
| 2924 | .PP |
| 2925 | or this: |
| 2926 | .PP |
| 2927 | .Vb 1 |
| 2928 | \& your_script.pl keyword1+keyword2+keyword3 |
| 2929 | .Ve |
| 2930 | .PP |
| 2931 | or this: |
| 2932 | .PP |
| 2933 | .Vb 1 |
| 2934 | \& your_script.pl name1=value1 name2=value2 |
| 2935 | .Ve |
| 2936 | .PP |
| 2937 | or this: |
| 2938 | .PP |
| 2939 | .Vb 1 |
| 2940 | \& your_script.pl name1=value1&name2=value2 |
| 2941 | .Ve |
| 2942 | .PP |
| 2943 | To turn off this feature, use the \-no_debug pragma. |
| 2944 | .PP |
| 2945 | To test the \s-1POST\s0 method, you may enable full debugging with the \-debug |
| 2946 | pragma. This will allow you to feed newline-delimited name=value |
| 2947 | pairs to the script on standard input. |
| 2948 | .PP |
| 2949 | When debugging, you can use quotes and backslashes to escape |
| 2950 | characters in the familiar shell manner, letting you place |
| 2951 | spaces and other funny characters in your parameter=value |
| 2952 | pairs: |
| 2953 | .PP |
| 2954 | .Vb 1 |
| 2955 | \& your_script.pl "name1='I am a long value'" "name2=two\e words" |
| 2956 | .Ve |
| 2957 | .Sh "\s-1DUMPING\s0 \s-1OUT\s0 \s-1ALL\s0 \s-1THE\s0 \s-1NAME/VALUE\s0 \s-1PAIRS\s0" |
| 2958 | .IX Subsection "DUMPING OUT ALL THE NAME/VALUE PAIRS" |
| 2959 | The \fIDump()\fR method produces a string consisting of all the query's |
| 2960 | name/value pairs formatted nicely as a nested list. This is useful |
| 2961 | for debugging purposes: |
| 2962 | .PP |
| 2963 | .Vb 1 |
| 2964 | \& print $query->Dump |
| 2965 | .Ve |
| 2966 | .PP |
| 2967 | Produces something that looks like: |
| 2968 | .PP |
| 2969 | .Vb 11 |
| 2970 | \& <ul> |
| 2971 | \& <li>name1 |
| 2972 | \& <ul> |
| 2973 | \& <li>value1 |
| 2974 | \& <li>value2 |
| 2975 | \& </ul> |
| 2976 | \& <li>name2 |
| 2977 | \& <ul> |
| 2978 | \& <li>value1 |
| 2979 | \& </ul> |
| 2980 | \& </ul> |
| 2981 | .Ve |
| 2982 | .PP |
| 2983 | As a shortcut, you can interpolate the entire \s-1CGI\s0 object into a string |
| 2984 | and it will be replaced with the a nice \s-1HTML\s0 dump shown above: |
| 2985 | .PP |
| 2986 | .Vb 2 |
| 2987 | \& $query=new CGI; |
| 2988 | \& print "<h2>Current Values</h2> $query\en"; |
| 2989 | .Ve |
| 2990 | .SH "FETCHING ENVIRONMENT VARIABLES" |
| 2991 | .IX Header "FETCHING ENVIRONMENT VARIABLES" |
| 2992 | Some of the more useful environment variables can be fetched |
| 2993 | through this interface. The methods are as follows: |
| 2994 | .IP "\fB\f(BIAccept()\fB\fR" 4 |
| 2995 | .IX Item "Accept()" |
| 2996 | Return a list of \s-1MIME\s0 types that the remote browser accepts. If you |
| 2997 | give this method a single argument corresponding to a \s-1MIME\s0 type, as in |
| 2998 | \&\f(CW$query\fR\->Accept('text/html'), it will return a floating point value |
| 2999 | corresponding to the browser's preference for this type from 0.0 |
| 3000 | (don't want) to 1.0. Glob types (e.g. text/*) in the browser's accept |
| 3001 | list are handled correctly. |
| 3002 | .Sp |
| 3003 | Note that the capitalization changed between version 2.43 and 2.44 in |
| 3004 | order to avoid conflict with Perl's \fIaccept()\fR function. |
| 3005 | .IP "\fB\f(BIraw_cookie()\fB\fR" 4 |
| 3006 | .IX Item "raw_cookie()" |
| 3007 | Returns the \s-1HTTP_COOKIE\s0 variable, an \s-1HTTP\s0 extension implemented by |
| 3008 | Netscape browsers version 1.1 and higher, and all versions of Internet |
| 3009 | Explorer. Cookies have a special format, and this method call just |
| 3010 | returns the raw form (?cookie dough). See \fIcookie()\fR for ways of |
| 3011 | setting and retrieving cooked cookies. |
| 3012 | .Sp |
| 3013 | Called with no parameters, \fIraw_cookie()\fR returns the packed cookie |
| 3014 | structure. You can separate it into individual cookies by splitting |
| 3015 | on the character sequence \*(L"; \*(R". Called with the name of a cookie, |
| 3016 | retrieves the \fBunescaped\fR form of the cookie. You can use the |
| 3017 | regular \fIcookie()\fR method to get the names, or use the \fIraw_fetch()\fR |
| 3018 | method from the CGI::Cookie module. |
| 3019 | .IP "\fB\f(BIuser_agent()\fB\fR" 4 |
| 3020 | .IX Item "user_agent()" |
| 3021 | Returns the \s-1HTTP_USER_AGENT\s0 variable. If you give |
| 3022 | this method a single argument, it will attempt to |
| 3023 | pattern match on it, allowing you to do something |
| 3024 | like \f(CW$query\fR\->user_agent(netscape); |
| 3025 | .IP "\fB\f(BIpath_info()\fB\fR" 4 |
| 3026 | .IX Item "path_info()" |
| 3027 | Returns additional path information from the script \s-1URL\s0. |
| 3028 | E.G. fetching /cgi\-bin/your_script/additional/stuff will result in |
| 3029 | \&\f(CW$query\fR\->\fIpath_info()\fR returning \*(L"/additional/stuff\*(R". |
| 3030 | .Sp |
| 3031 | \&\s-1NOTE:\s0 The Microsoft Internet Information Server |
| 3032 | is broken with respect to additional path information. If |
| 3033 | you use the Perl \s-1DLL\s0 library, the \s-1IIS\s0 server will attempt to |
| 3034 | execute the additional path information as a Perl script. |
| 3035 | If you use the ordinary file associations mapping, the |
| 3036 | path information will be present in the environment, |
| 3037 | but incorrect. The best thing to do is to avoid using additional |
| 3038 | path information in \s-1CGI\s0 scripts destined for use with \s-1IIS\s0. |
| 3039 | .IP "\fB\f(BIpath_translated()\fB\fR" 4 |
| 3040 | .IX Item "path_translated()" |
| 3041 | As per \fIpath_info()\fR but returns the additional |
| 3042 | path information translated into a physical path, e.g. |
| 3043 | \&\*(L"/usr/local/etc/httpd/htdocs/additional/stuff\*(R". |
| 3044 | .Sp |
| 3045 | The Microsoft \s-1IIS\s0 is broken with respect to the translated |
| 3046 | path as well. |
| 3047 | .IP "\fB\f(BIremote_host()\fB\fR" 4 |
| 3048 | .IX Item "remote_host()" |
| 3049 | Returns either the remote host name or \s-1IP\s0 address. |
| 3050 | if the former is unavailable. |
| 3051 | .IP "\fB\f(BIscript_name()\fB\fR" 4 |
| 3052 | .IX Item "script_name()" |
| 3053 | Return the script name as a partial \s-1URL\s0, for self-refering |
| 3054 | scripts. |
| 3055 | .IP "\fB\f(BIreferer()\fB\fR" 4 |
| 3056 | .IX Item "referer()" |
| 3057 | Return the \s-1URL\s0 of the page the browser was viewing |
| 3058 | prior to fetching your script. Not available for all |
| 3059 | browsers. |
| 3060 | .IP "\fBauth_type ()\fR" 4 |
| 3061 | .IX Item "auth_type ()" |
| 3062 | Return the authorization/verification method in use for this |
| 3063 | script, if any. |
| 3064 | .IP "\fBserver_name ()\fR" 4 |
| 3065 | .IX Item "server_name ()" |
| 3066 | Returns the name of the server, usually the machine's host |
| 3067 | name. |
| 3068 | .IP "\fBvirtual_host ()\fR" 4 |
| 3069 | .IX Item "virtual_host ()" |
| 3070 | When using virtual hosts, returns the name of the host that |
| 3071 | the browser attempted to contact |
| 3072 | .IP "\fBserver_port ()\fR" 4 |
| 3073 | .IX Item "server_port ()" |
| 3074 | Return the port that the server is listening on. |
| 3075 | .IP "\fBserver_software ()\fR" 4 |
| 3076 | .IX Item "server_software ()" |
| 3077 | Returns the server software and version number. |
| 3078 | .IP "\fBremote_user ()\fR" 4 |
| 3079 | .IX Item "remote_user ()" |
| 3080 | Return the authorization/verification name used for user |
| 3081 | verification, if this script is protected. |
| 3082 | .IP "\fBuser_name ()\fR" 4 |
| 3083 | .IX Item "user_name ()" |
| 3084 | Attempt to obtain the remote user's name, using a variety of different |
| 3085 | techniques. This only works with older browsers such as Mosaic. |
| 3086 | Newer browsers do not report the user name for privacy reasons! |
| 3087 | .IP "\fB\f(BIrequest_method()\fB\fR" 4 |
| 3088 | .IX Item "request_method()" |
| 3089 | Returns the method used to access your script, usually |
| 3090 | one of '\s-1POST\s0', '\s-1GET\s0' or '\s-1HEAD\s0'. |
| 3091 | .IP "\fB\f(BIcontent_type()\fB\fR" 4 |
| 3092 | .IX Item "content_type()" |
| 3093 | Returns the content_type of data submitted in a \s-1POST\s0, generally |
| 3094 | multipart/form\-data or application/x\-www\-form\-urlencoded |
| 3095 | .IP "\fB\f(BIhttp()\fB\fR" 4 |
| 3096 | .IX Item "http()" |
| 3097 | Called with no arguments returns the list of \s-1HTTP\s0 environment |
| 3098 | variables, including such things as \s-1HTTP_USER_AGENT\s0, |
| 3099 | \&\s-1HTTP_ACCEPT_LANGUAGE\s0, and \s-1HTTP_ACCEPT_CHARSET\s0, corresponding to the |
| 3100 | like-named \s-1HTTP\s0 header fields in the request. Called with the name of |
| 3101 | an \s-1HTTP\s0 header field, returns its value. Capitalization and the use |
| 3102 | of hyphens versus underscores are not significant. |
| 3103 | .Sp |
| 3104 | For example, all three of these examples are equivalent: |
| 3105 | .Sp |
| 3106 | .Vb 3 |
| 3107 | \& $requested_language = $q->http('Accept-language'); |
| 3108 | \& $requested_language = $q->http('Accept_language'); |
| 3109 | \& $requested_language = $q->http('HTTP_ACCEPT_LANGUAGE'); |
| 3110 | .Ve |
| 3111 | .IP "\fB\f(BIhttps()\fB\fR" 4 |
| 3112 | .IX Item "https()" |
| 3113 | The same as \fI\fIhttp()\fI\fR, but operates on the \s-1HTTPS\s0 environment variables |
| 3114 | present when the \s-1SSL\s0 protocol is in effect. Can be used to determine |
| 3115 | whether \s-1SSL\s0 is turned on. |
| 3116 | .SH "USING NPH SCRIPTS" |
| 3117 | .IX Header "USING NPH SCRIPTS" |
| 3118 | \&\s-1NPH\s0, or \*(L"no\-parsed\-header\*(R", scripts bypass the server completely by |
| 3119 | sending the complete \s-1HTTP\s0 header directly to the browser. This has |
| 3120 | slight performance benefits, but is of most use for taking advantage |
| 3121 | of \s-1HTTP\s0 extensions that are not directly supported by your server, |
| 3122 | such as server push and \s-1PICS\s0 headers. |
| 3123 | .PP |
| 3124 | Servers use a variety of conventions for designating \s-1CGI\s0 scripts as |
| 3125 | \&\s-1NPH\s0. Many Unix servers look at the beginning of the script's name for |
| 3126 | the prefix \*(L"nph\-\*(R". The Macintosh WebSTAR server and Microsoft's |
| 3127 | Internet Information Server, in contrast, try to decide whether a |
| 3128 | program is an \s-1NPH\s0 script by examining the first line of script output. |
| 3129 | .PP |
| 3130 | \&\s-1CGI\s0.pm supports \s-1NPH\s0 scripts with a special \s-1NPH\s0 mode. When in this |
| 3131 | mode, \s-1CGI\s0.pm will output the necessary extra header information when |
| 3132 | the \fIheader()\fR and \fIredirect()\fR methods are |
| 3133 | called. |
| 3134 | .PP |
| 3135 | The Microsoft Internet Information Server requires \s-1NPH\s0 mode. As of |
| 3136 | version 2.30, \s-1CGI\s0.pm will automatically detect when the script is |
| 3137 | running under \s-1IIS\s0 and put itself into this mode. You do not need to |
| 3138 | do this manually, although it won't hurt anything if you do. However, |
| 3139 | note that if you have applied Service Pack 6, much of the |
| 3140 | functionality of \s-1NPH\s0 scripts, including the ability to redirect while |
| 3141 | setting a cookie, b<do not work at all> on \s-1IIS\s0 without a special patch |
| 3142 | from Microsoft. See |
| 3143 | http://support.microsoft.com/support/kb/articles/Q280/3/41.ASP: |
| 3144 | Non-Parsed Headers Stripped From \s-1CGI\s0 Applications That Have nph\- |
| 3145 | Prefix in Name. |
| 3146 | .IP "In the \fBuse\fR statement" 4 |
| 3147 | .IX Item "In the use statement" |
| 3148 | Simply add the \*(L"\-nph\*(R" pragmato the list of symbols to be imported into |
| 3149 | your script: |
| 3150 | .Sp |
| 3151 | .Vb 1 |
| 3152 | \& use CGI qw(:standard -nph) |
| 3153 | .Ve |
| 3154 | .IP "By calling the \fB\f(BInph()\fB\fR method:" 4 |
| 3155 | .IX Item "By calling the nph() method:" |
| 3156 | Call \fB\f(BInph()\fB\fR with a non-zero parameter at any point after using \s-1CGI\s0.pm in your program. |
| 3157 | .Sp |
| 3158 | .Vb 1 |
| 3159 | \& CGI->nph(1) |
| 3160 | .Ve |
| 3161 | .IP "By using \fB\-nph\fR parameters" 4 |
| 3162 | .IX Item "By using -nph parameters" |
| 3163 | in the \fB\f(BIheader()\fB\fR and \fB\f(BIredirect()\fB\fR statements: |
| 3164 | .Sp |
| 3165 | .Vb 1 |
| 3166 | \& print $q->header(-nph=>1); |
| 3167 | .Ve |
| 3168 | .SH "Server Push" |
| 3169 | .IX Header "Server Push" |
| 3170 | \&\s-1CGI\s0.pm provides four simple functions for producing multipart |
| 3171 | documents of the type needed to implement server push. These |
| 3172 | functions were graciously provided by Ed Jordan <ed@fidalgo.net>. To |
| 3173 | import these into your namespace, you must import the \*(L":push\*(R" set. |
| 3174 | You are also advised to put the script into \s-1NPH\s0 mode and to set $| to |
| 3175 | 1 to avoid buffering problems. |
| 3176 | .PP |
| 3177 | Here is a simple script that demonstrates server push: |
| 3178 | .PP |
| 3179 | .Vb 14 |
| 3180 | \& #!/usr/local/bin/perl |
| 3181 | \& use CGI qw/:push -nph/; |
| 3182 | \& $| = 1; |
| 3183 | \& print multipart_init(-boundary=>'----here we go!'); |
| 3184 | \& foreach (0 .. 4) { |
| 3185 | \& print multipart_start(-type=>'text/plain'), |
| 3186 | \& "The current time is ",scalar(localtime),"\en"; |
| 3187 | \& if ($_ < 4) { |
| 3188 | \& print multipart_end; |
| 3189 | \& } else { |
| 3190 | \& print multipart_final; |
| 3191 | \& } |
| 3192 | \& sleep 1; |
| 3193 | \& } |
| 3194 | .Ve |
| 3195 | .PP |
| 3196 | This script initializes server push by calling \fB\f(BImultipart_init()\fB\fR. |
| 3197 | It then enters a loop in which it begins a new multipart section by |
| 3198 | calling \fB\f(BImultipart_start()\fB\fR, prints the current local time, |
| 3199 | and ends a multipart section with \fB\f(BImultipart_end()\fB\fR. It then sleeps |
| 3200 | a second, and begins again. On the final iteration, it ends the |
| 3201 | multipart section with \fB\f(BImultipart_final()\fB\fR rather than with |
| 3202 | \&\fB\f(BImultipart_end()\fB\fR. |
| 3203 | .IP "\fImultipart_init()\fR" 4 |
| 3204 | .IX Item "multipart_init()" |
| 3205 | .Vb 1 |
| 3206 | \& multipart_init(-boundary=>$boundary); |
| 3207 | .Ve |
| 3208 | .Sp |
| 3209 | Initialize the multipart system. The \-boundary argument specifies |
| 3210 | what \s-1MIME\s0 boundary string to use to separate parts of the document. |
| 3211 | If not provided, \s-1CGI\s0.pm chooses a reasonable boundary for you. |
| 3212 | .IP "\fImultipart_start()\fR" 4 |
| 3213 | .IX Item "multipart_start()" |
| 3214 | .Vb 1 |
| 3215 | \& multipart_start(-type=>$type) |
| 3216 | .Ve |
| 3217 | .Sp |
| 3218 | Start a new part of the multipart document using the specified \s-1MIME\s0 |
| 3219 | type. If not specified, text/html is assumed. |
| 3220 | .IP "\fImultipart_end()\fR" 4 |
| 3221 | .IX Item "multipart_end()" |
| 3222 | .Vb 1 |
| 3223 | \& multipart_end() |
| 3224 | .Ve |
| 3225 | .Sp |
| 3226 | End a part. You must remember to call \fImultipart_end()\fR once for each |
| 3227 | \&\fImultipart_start()\fR, except at the end of the last part of the multipart |
| 3228 | document when \fImultipart_final()\fR should be called instead of \fImultipart_end()\fR. |
| 3229 | .IP "\fImultipart_final()\fR" 4 |
| 3230 | .IX Item "multipart_final()" |
| 3231 | .Vb 1 |
| 3232 | \& multipart_final() |
| 3233 | .Ve |
| 3234 | .Sp |
| 3235 | End all parts. You should call \fImultipart_final()\fR rather than |
| 3236 | \&\fImultipart_end()\fR at the end of the last part of the multipart document. |
| 3237 | .PP |
| 3238 | Users interested in server push applications should also have a look |
| 3239 | at the CGI::Push module. |
| 3240 | .PP |
| 3241 | Only Netscape Navigator supports server push. Internet Explorer |
| 3242 | browsers do not. |
| 3243 | .SH "Avoiding Denial of Service Attacks" |
| 3244 | .IX Header "Avoiding Denial of Service Attacks" |
| 3245 | A potential problem with \s-1CGI\s0.pm is that, by default, it attempts to |
| 3246 | process form POSTings no matter how large they are. A wily hacker |
| 3247 | could attack your site by sending a \s-1CGI\s0 script a huge \s-1POST\s0 of many |
| 3248 | megabytes. \s-1CGI\s0.pm will attempt to read the entire \s-1POST\s0 into a |
| 3249 | variable, growing hugely in size until it runs out of memory. While |
| 3250 | the script attempts to allocate the memory the system may slow down |
| 3251 | dramatically. This is a form of denial of service attack. |
| 3252 | .PP |
| 3253 | Another possible attack is for the remote user to force \s-1CGI\s0.pm to |
| 3254 | accept a huge file upload. \s-1CGI\s0.pm will accept the upload and store it |
| 3255 | in a temporary directory even if your script doesn't expect to receive |
| 3256 | an uploaded file. \s-1CGI\s0.pm will delete the file automatically when it |
| 3257 | terminates, but in the meantime the remote user may have filled up the |
| 3258 | server's disk space, causing problems for other programs. |
| 3259 | .PP |
| 3260 | The best way to avoid denial of service attacks is to limit the amount |
| 3261 | of memory, \s-1CPU\s0 time and disk space that \s-1CGI\s0 scripts can use. Some Web |
| 3262 | servers come with built-in facilities to accomplish this. In other |
| 3263 | cases, you can use the shell \fIlimit\fR or \fIulimit\fR |
| 3264 | commands to put ceilings on \s-1CGI\s0 resource usage. |
| 3265 | .PP |
| 3266 | \&\s-1CGI\s0.pm also has some simple built-in protections against denial of |
| 3267 | service attacks, but you must activate them before you can use them. |
| 3268 | These take the form of two global variables in the \s-1CGI\s0 name space: |
| 3269 | .IP "\fB$CGI::POST_MAX\fR" 4 |
| 3270 | .IX Item "$CGI::POST_MAX" |
| 3271 | If set to a non-negative integer, this variable puts a ceiling |
| 3272 | on the size of POSTings, in bytes. If \s-1CGI\s0.pm detects a \s-1POST\s0 |
| 3273 | that is greater than the ceiling, it will immediately exit with an error |
| 3274 | message. This value will affect both ordinary POSTs and |
| 3275 | multipart POSTs, meaning that it limits the maximum size of file |
| 3276 | uploads as well. You should set this to a reasonably high |
| 3277 | value, such as 1 megabyte. |
| 3278 | .IP "\fB$CGI::DISABLE_UPLOADS\fR" 4 |
| 3279 | .IX Item "$CGI::DISABLE_UPLOADS" |
| 3280 | If set to a non-zero value, this will disable file uploads |
| 3281 | completely. Other fill-out form values will work as usual. |
| 3282 | .PP |
| 3283 | You can use these variables in either of two ways. |
| 3284 | .IP "\fB1. On a script-by-script basis\fR" 4 |
| 3285 | .IX Item "1. On a script-by-script basis" |
| 3286 | Set the variable at the top of the script, right after the \*(L"use\*(R" statement: |
| 3287 | .Sp |
| 3288 | .Vb 4 |
| 3289 | \& use CGI qw/:standard/; |
| 3290 | \& use CGI::Carp 'fatalsToBrowser'; |
| 3291 | \& $CGI::POST_MAX=1024 * 100; # max 100K posts |
| 3292 | \& $CGI::DISABLE_UPLOADS = 1; # no uploads |
| 3293 | .Ve |
| 3294 | .IP "\fB2. Globally for all scripts\fR" 4 |
| 3295 | .IX Item "2. Globally for all scripts" |
| 3296 | Open up \s-1CGI\s0.pm, find the definitions for \f(CW$POST_MAX\fR and |
| 3297 | \&\f(CW$DISABLE_UPLOADS\fR, and set them to the desired values. You'll |
| 3298 | find them towards the top of the file in a subroutine named |
| 3299 | \&\fIinitialize_globals()\fR. |
| 3300 | .PP |
| 3301 | An attempt to send a \s-1POST\s0 larger than \f(CW$POST_MAX\fR bytes will cause |
| 3302 | \&\fI\fIparam()\fI\fR to return an empty \s-1CGI\s0 parameter list. You can test for |
| 3303 | this event by checking \fI\fIcgi_error()\fI\fR, either after you create the \s-1CGI\s0 |
| 3304 | object or, if you are using the function-oriented interface, call |
| 3305 | <\fIparam()\fR> for the first time. If the \s-1POST\s0 was intercepted, then |
| 3306 | \&\fIcgi_error()\fR will return the message \*(L"413 \s-1POST\s0 too large\*(R". |
| 3307 | .PP |
| 3308 | This error message is actually defined by the \s-1HTTP\s0 protocol, and is |
| 3309 | designed to be returned to the browser as the \s-1CGI\s0 script's status |
| 3310 | code. For example: |
| 3311 | .PP |
| 3312 | .Vb 5 |
| 3313 | \& $uploaded_file = param('upload'); |
| 3314 | \& if (!$uploaded_file && cgi_error()) { |
| 3315 | \& print header(-status=>cgi_error()); |
| 3316 | \& exit 0; |
| 3317 | \& } |
| 3318 | .Ve |
| 3319 | .PP |
| 3320 | However it isn't clear that any browser currently knows what to do |
| 3321 | with this status code. It might be better just to create an |
| 3322 | \&\s-1HTML\s0 page that warns the user of the problem. |
| 3323 | .SH "COMPATIBILITY WITH CGI\-LIB.PL" |
| 3324 | .IX Header "COMPATIBILITY WITH CGI-LIB.PL" |
| 3325 | To make it easier to port existing programs that use cgi\-lib.pl the |
| 3326 | compatibility routine \*(L"ReadParse\*(R" is provided. Porting is simple: |
| 3327 | .PP |
| 3328 | \&\s-1OLD\s0 \s-1VERSION\s0 |
| 3329 | require \*(L"cgi\-lib.pl\*(R"; |
| 3330 | &ReadParse; |
| 3331 | print \*(L"The value of the antique is \f(CW$in\fR{antique}.\en\*(R"; |
| 3332 | .PP |
| 3333 | \&\s-1NEW\s0 \s-1VERSION\s0 |
| 3334 | use \s-1CGI\s0; |
| 3335 | CGI::ReadParse |
| 3336 | print \*(L"The value of the antique is \f(CW$in\fR{antique}.\en\*(R"; |
| 3337 | .PP |
| 3338 | \&\s-1CGI\s0.pm's \fIReadParse()\fR routine creates a tied variable named \f(CW%in\fR, |
| 3339 | which can be accessed to obtain the query variables. Like |
| 3340 | ReadParse, you can also provide your own variable. Infrequently |
| 3341 | used features of ReadParse, such as the creation of \f(CW@in\fR and \f(CW$in\fR |
| 3342 | variables, are not supported. |
| 3343 | .PP |
| 3344 | Once you use ReadParse, you can retrieve the query object itself |
| 3345 | this way: |
| 3346 | .PP |
| 3347 | .Vb 3 |
| 3348 | \& $q = $in{CGI}; |
| 3349 | \& print $q->textfield(-name=>'wow', |
| 3350 | \& -value=>'does this really work?'); |
| 3351 | .Ve |
| 3352 | .PP |
| 3353 | This allows you to start using the more interesting features |
| 3354 | of \s-1CGI\s0.pm without rewriting your old scripts from scratch. |
| 3355 | .SH "AUTHOR INFORMATION" |
| 3356 | .IX Header "AUTHOR INFORMATION" |
| 3357 | Copyright 1995\-1998, Lincoln D. Stein. All rights reserved. |
| 3358 | .PP |
| 3359 | This library is free software; you can redistribute it and/or modify |
| 3360 | it under the same terms as Perl itself. |
| 3361 | .PP |
| 3362 | Address bug reports and comments to: lstein@cshl.org. When sending |
| 3363 | bug reports, please provide the version of \s-1CGI\s0.pm, the version of |
| 3364 | Perl, the name and version of your Web server, and the name and |
| 3365 | version of the operating system you are using. If the problem is even |
| 3366 | remotely browser dependent, please provide information about the |
| 3367 | affected browers as well. |
| 3368 | .SH "CREDITS" |
| 3369 | .IX Header "CREDITS" |
| 3370 | Thanks very much to: |
| 3371 | .IP "Matt Heffron (heffron@falstaff.css.beckman.com)" 4 |
| 3372 | .IX Item "Matt Heffron (heffron@falstaff.css.beckman.com)" |
| 3373 | .PD 0 |
| 3374 | .IP "James Taylor (james.taylor@srs.gov)" 4 |
| 3375 | .IX Item "James Taylor (james.taylor@srs.gov)" |
| 3376 | .IP "Scott Anguish <sanguish@digifix.com>" 4 |
| 3377 | .IX Item "Scott Anguish <sanguish@digifix.com>" |
| 3378 | .IP "Mike Jewell (mlj3u@virginia.edu)" 4 |
| 3379 | .IX Item "Mike Jewell (mlj3u@virginia.edu)" |
| 3380 | .IP "Timothy Shimmin (tes@kbs.citri.edu.au)" 4 |
| 3381 | .IX Item "Timothy Shimmin (tes@kbs.citri.edu.au)" |
| 3382 | .IP "Joergen Haegg (jh@axis.se)" 4 |
| 3383 | .IX Item "Joergen Haegg (jh@axis.se)" |
| 3384 | .IP "Laurent Delfosse (delfosse@delfosse.com)" 4 |
| 3385 | .IX Item "Laurent Delfosse (delfosse@delfosse.com)" |
| 3386 | .IP "Richard Resnick (applepi1@aol.com)" 4 |
| 3387 | .IX Item "Richard Resnick (applepi1@aol.com)" |
| 3388 | .IP "Craig Bishop (csb@barwonwater.vic.gov.au)" 4 |
| 3389 | .IX Item "Craig Bishop (csb@barwonwater.vic.gov.au)" |
| 3390 | .IP "Tony Curtis (tc@vcpc.univie.ac.at)" 4 |
| 3391 | .IX Item "Tony Curtis (tc@vcpc.univie.ac.at)" |
| 3392 | .IP "Tim Bunce (Tim.Bunce@ig.co.uk)" 4 |
| 3393 | .IX Item "Tim Bunce (Tim.Bunce@ig.co.uk)" |
| 3394 | .IP "Tom Christiansen (tchrist@convex.com)" 4 |
| 3395 | .IX Item "Tom Christiansen (tchrist@convex.com)" |
| 3396 | .IP "Andreas Koenig (k@franz.ww.TU\-Berlin.DE)" 4 |
| 3397 | .IX Item "Andreas Koenig (k@franz.ww.TU-Berlin.DE)" |
| 3398 | .IP "Tim MacKenzie (Tim.MacKenzie@fulcrum.com.au)" 4 |
| 3399 | .IX Item "Tim MacKenzie (Tim.MacKenzie@fulcrum.com.au)" |
| 3400 | .IP "Kevin B. Hendricks (kbhend@dogwood.tyler.wm.edu)" 4 |
| 3401 | .IX Item "Kevin B. Hendricks (kbhend@dogwood.tyler.wm.edu)" |
| 3402 | .IP "Stephen Dahmen (joyfire@inxpress.net)" 4 |
| 3403 | .IX Item "Stephen Dahmen (joyfire@inxpress.net)" |
| 3404 | .IP "Ed Jordan (ed@fidalgo.net)" 4 |
| 3405 | .IX Item "Ed Jordan (ed@fidalgo.net)" |
| 3406 | .IP "David Alan Pisoni (david@cnation.com)" 4 |
| 3407 | .IX Item "David Alan Pisoni (david@cnation.com)" |
| 3408 | .IP "Doug MacEachern (dougm@opengroup.org)" 4 |
| 3409 | .IX Item "Doug MacEachern (dougm@opengroup.org)" |
| 3410 | .IP "Robin Houston (robin@oneworld.org)" 4 |
| 3411 | .IX Item "Robin Houston (robin@oneworld.org)" |
| 3412 | .IP "...and many many more..." 4 |
| 3413 | .IX Item "...and many many more..." |
| 3414 | .PD |
| 3415 | for suggestions and bug fixes. |
| 3416 | .SH "A COMPLETE EXAMPLE OF A SIMPLE FORM-BASED SCRIPT" |
| 3417 | .IX Header "A COMPLETE EXAMPLE OF A SIMPLE FORM-BASED SCRIPT" |
| 3418 | .Vb 1 |
| 3419 | \& #!/usr/local/bin/perl |
| 3420 | .Ve |
| 3421 | .PP |
| 3422 | .Vb 1 |
| 3423 | \& use CGI; |
| 3424 | .Ve |
| 3425 | .PP |
| 3426 | .Vb 1 |
| 3427 | \& $query = new CGI; |
| 3428 | .Ve |
| 3429 | .PP |
| 3430 | .Vb 7 |
| 3431 | \& print $query->header; |
| 3432 | \& print $query->start_html("Example CGI.pm Form"); |
| 3433 | \& print "<h1> Example CGI.pm Form</h1>\en"; |
| 3434 | \& &print_prompt($query); |
| 3435 | \& &do_work($query); |
| 3436 | \& &print_tail; |
| 3437 | \& print $query->end_html; |
| 3438 | .Ve |
| 3439 | .PP |
| 3440 | .Vb 2 |
| 3441 | \& sub print_prompt { |
| 3442 | \& my($query) = @_; |
| 3443 | .Ve |
| 3444 | .PP |
| 3445 | .Vb 4 |
| 3446 | \& print $query->start_form; |
| 3447 | \& print "<em>What's your name?</em><br>"; |
| 3448 | \& print $query->textfield('name'); |
| 3449 | \& print $query->checkbox('Not my real name'); |
| 3450 | .Ve |
| 3451 | .PP |
| 3452 | .Vb 6 |
| 3453 | \& print "<p><em>Where can you find English Sparrows?</em><br>"; |
| 3454 | \& print $query->checkbox_group( |
| 3455 | \& -name=>'Sparrow locations', |
| 3456 | \& -values=>[England,France,Spain,Asia,Hoboken], |
| 3457 | \& -linebreak=>'yes', |
| 3458 | \& -defaults=>[England,Asia]); |
| 3459 | .Ve |
| 3460 | .PP |
| 3461 | .Vb 5 |
| 3462 | \& print "<p><em>How far can they fly?</em><br>", |
| 3463 | \& $query->radio_group( |
| 3464 | \& -name=>'how far', |
| 3465 | \& -values=>['10 ft','1 mile','10 miles','real far'], |
| 3466 | \& -default=>'1 mile'); |
| 3467 | .Ve |
| 3468 | .PP |
| 3469 | .Vb 4 |
| 3470 | \& print "<p><em>What's your favorite color?</em> "; |
| 3471 | \& print $query->popup_menu(-name=>'Color', |
| 3472 | \& -values=>['black','brown','red','yellow'], |
| 3473 | \& -default=>'red'); |
| 3474 | .Ve |
| 3475 | .PP |
| 3476 | .Vb 1 |
| 3477 | \& print $query->hidden('Reference','Monty Python and the Holy Grail'); |
| 3478 | .Ve |
| 3479 | .PP |
| 3480 | .Vb 7 |
| 3481 | \& print "<p><em>What have you got there?</em><br>"; |
| 3482 | \& print $query->scrolling_list( |
| 3483 | \& -name=>'possessions', |
| 3484 | \& -values=>['A Coconut','A Grail','An Icon', |
| 3485 | \& 'A Sword','A Ticket'], |
| 3486 | \& -size=>5, |
| 3487 | \& -multiple=>'true'); |
| 3488 | .Ve |
| 3489 | .PP |
| 3490 | .Vb 4 |
| 3491 | \& print "<p><em>Any parting comments?</em><br>"; |
| 3492 | \& print $query->textarea(-name=>'Comments', |
| 3493 | \& -rows=>10, |
| 3494 | \& -columns=>50); |
| 3495 | .Ve |
| 3496 | .PP |
| 3497 | .Vb 6 |
| 3498 | \& print "<p>",$query->reset; |
| 3499 | \& print $query->submit('Action','Shout'); |
| 3500 | \& print $query->submit('Action','Scream'); |
| 3501 | \& print $query->endform; |
| 3502 | \& print "<hr>\en"; |
| 3503 | \& } |
| 3504 | .Ve |
| 3505 | .PP |
| 3506 | .Vb 3 |
| 3507 | \& sub do_work { |
| 3508 | \& my($query) = @_; |
| 3509 | \& my(@values,$key); |
| 3510 | .Ve |
| 3511 | .PP |
| 3512 | .Vb 1 |
| 3513 | \& print "<h2>Here are the current settings in this form</h2>"; |
| 3514 | .Ve |
| 3515 | .PP |
| 3516 | .Vb 6 |
| 3517 | \& foreach $key ($query->param) { |
| 3518 | \& print "<strong>$key</strong> -> "; |
| 3519 | \& @values = $query->param($key); |
| 3520 | \& print join(", ",@values),"<br>\en"; |
| 3521 | \& } |
| 3522 | \& } |
| 3523 | .Ve |
| 3524 | .PP |
| 3525 | .Vb 7 |
| 3526 | \& sub print_tail { |
| 3527 | \& print <<END; |
| 3528 | \& <hr> |
| 3529 | \& <address>Lincoln D. Stein</address><br> |
| 3530 | \& <a href="/">Home Page</a> |
| 3531 | \& END |
| 3532 | \& } |
| 3533 | .Ve |
| 3534 | .SH "BUGS" |
| 3535 | .IX Header "BUGS" |
| 3536 | This module has grown large and monolithic. Furthermore it's doing many |
| 3537 | things, such as handling URLs, parsing \s-1CGI\s0 input, writing \s-1HTML\s0, etc., that |
| 3538 | are also done in the \s-1LWP\s0 modules. It should be discarded in favor of |
| 3539 | the CGI::* modules, but somehow I continue to work on it. |
| 3540 | .PP |
| 3541 | Note that the code is truly contorted in order to avoid spurious |
| 3542 | warnings when programs are run with the \fB\-w\fR switch. |
| 3543 | .SH "SEE ALSO" |
| 3544 | .IX Header "SEE ALSO" |
| 3545 | CGI::Carp, CGI::Fast, CGI::Pretty |