Commit | Line | Data |
---|---|---|
86530b38 AT |
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 | ||
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 | ||
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 |