1CGI::HTML::Functions(3)User Contributed Perl DocumentatioCnGI::HTML::Functions(3)
2
6 CGI::HTML::Functions - Documentation for CGI.pm Legacy HTML
7 Functionality
8
10 Nothing here - please do not use this functionality, it is considered
11 to be legacy and essentially deprecated. This documentation exists
12 solely to aid in maintenance and migration of legacy code using this
13 functionality and you are strongly encouraged to migrate away from it.
14 If you are working on new code you should be using a template engine.
15 For more information see CGI::Alternatives.
16 If you really want to continue using the HTML generation functionality
18 of CGI.pm then you should take a look at HTML::Tiny instead, which may
19 give you a migration path away from CGI.pm's html generation functions;
20 i strongly encourage you to move towards template driven page
21 generation for anything involving markup as it will make porting your
22 app to other frameworks much easier in the long run.
23
25 The documentation here should be considered an addendum to the sections
26 in the CGI documentation - the sections here are named the same as
27 those within the CGI perldoc.
28
30 HTML tag functions have both attributes (the attribute="value" pairs
31 within the tag itself) and contents (the part between the opening and
32 closing pairs). To distinguish between attributes and contents, CGI.pm
33 uses the convention of passing HTML attributes as a hash reference as
34 the first argument, and the contents, if any, as any subsequent
35 arguments. It works out like this:
36 Code Generated HTML
38 ---- --------------
39 h1() <h1 />
40 h1('some','contents'); <h1>some contents</h1>
41 h1({-align=>left}); <h1 align="LEFT">
42 h1({-align=>left},'contents'); <h1 align="LEFT">contents</h1>
43 Many newcomers to CGI.pm are puzzled by the difference between the
45 calling conventions for the HTML shortcuts, which require curly braces
46 around the HTML tag attributes, and the calling conventions for other
47 routines, which manage to generate attributes without the curly
48 brackets. Don't be confused. As a convenience the curly braces are
49 optional in all but the HTML shortcuts. If you like, you can use curly
50 braces when calling any routine that takes named arguments. For
51 example:
52 print $q->header( { -type => 'image/gif', -expires => '+3d' } );
54 If you use warnings, you will be warned that some CGI.pm argument names
56 conflict with built-in perl functions. The most frequent of these is
57 the -values argument, used to create multi-valued menus, radio button
58 clusters and the like. To get around this warning, you have several
59 choices:
60 1. Use another name for the argument, if one is available. For
62 example, -value is an alias for -values.
63 2. Change the capitalization, e.g. -Values
65 3. Put quotes around the argument name, e.g. '-values'
67 Function-oriented interface HTML exports
69 Here is a list of the HTML related function sets you can import:
70 :form
72 Import all fill-out form generating methods, such as textfield().
73 :html2
75 Import all methods that generate HTML 2.0 standard elements.
76 :html3
78 Import all methods that generate HTML 3.0 elements (such as
79 <table>, <super> and <sub>).
80 :html4
82 Import all methods that generate HTML 4 elements (such as <abbrev>,
83 <acronym> and <thead>).
84 :netscape
86 Import the <blink>, <fontsize> and <center> tags.
87 :html
89 Import all HTML-generating shortcuts (i.e. 'html2', 'html3',
90 'html4' and 'netscape')
91 :standard
93 Import "standard" features, 'html2', 'html3', 'html4', 'ssl',
94 'form' and 'cgi'.
95 If you import any of the state-maintaining CGI or form-generating
97 methods, a default CGI object will be created and initialized
98 automatically the first time you use any of the methods that require
99 one to be present. This includes param(), textfield(), submit() and the
100 like. (If you need direct access to the CGI object, you can find it in
101 the global variable $CGI::Q).
102 Pragmas
104 Additional HTML generation related pragms:
105 -nosticky
107 By default the CGI module implements a state-preserving behavior
108 called "sticky" fields. The way this works is that if you are
109 regenerating a form, the methods that generate the form field
110 values will interrogate param() to see if similarly-named
111 parameters are present in the query string. If they find a like-
112 named parameter, they will use it to set their default values.
113 Sometimes this isn't what you want. The -nosticky pragma prevents
115 this behavior. You can also selectively change the sticky behavior
116 in each element that you generate.
117 -tabindex
119 Automatically add tab index attributes to each form field. With
120 this option turned off, you can still add tab indexes manually by
121 passing a -tabindex option to each field-generating method.
122 -no_xhtml
124 By default, CGI.pm versions 2.69 and higher emit XHTML
125 (http://www.w3.org/TR/xhtml1/). The -no_xhtml pragma disables this
126 feature. Thanks to Michalis Kabrianis <kabrianis@hellug.gr> for
127 this feature.
128 If start_html()'s -dtd parameter specifies an HTML 2.0, 3.2, 4.0 or
130 4.01 DTD, XHTML will automatically be disabled without needing to
131 use this pragma.
132 Special forms for importing HTML-tag functions
134 Many of the methods generate HTML tags. As described below, tag
135 functions automatically generate both the opening and closing tags. For
136 example:
137 print h1('Level 1 Header');
139 produces
141 <h1>Level 1 Header</h1>
143 There will be some times when you want to produce the start and end
145 tags yourself. In this case, you can use the form start_tag_name and
146 end_tag_name, as in:
147 print start_h1,'Level 1 Header',end_h1;
149 Creating the HTML document header
151 print start_html(
152 -title => 'Secrets of the Pyramids',
153 -author => 'fred@capricorn.org',
154 -base => 'true',
155 -target => '_blank',
156 -meta => {'keywords'=>'pharaoh secret mummy',
157 'copyright' => 'copyright 1996 King Tut'},
158 -style => {'src'=>'/styles/style1.css'},
159 -BGCOLOR => 'blue'
160 );
161 The start_html() routine creates the top of the page, along with a lot
163 of optional information that controls the page's appearance and
164 behavior.
165 This method returns a canned HTML header and the opening <body> tag.
167 All parameters are optional. In the named parameter form, recognized
168 parameters are -title, -author, -base, -xbase, -dtd, -lang and -target
169 (see below for the explanation). Any additional parameters you provide,
170 such as the unofficial BGCOLOR attribute, are added to the <body> tag.
171 Additional parameters must be proceeded by a hyphen.
172 The argument -xbase allows you to provide an HREF for the <base> tag
174 different from the current location, as in
175 -xbase => "http://home.mcom.com/"
177 All relative links will be interpreted relative to this tag.
179 The argument -target allows you to provide a default target frame for
181 all the links and fill-out forms on the page. This is a non-standard
182 HTTP feature which only works with some browsers!
183 -target => "answer_window"
185 All relative links will be interpreted relative to this tag. You add
187 arbitrary meta information to the header with the -meta argument. This
188 argument expects a reference to a hash containing name/value pairs of
189 meta information. These will be turned into a series of header <meta>
190 tags that look something like this:
191 <meta name="keywords" content="pharaoh secret mummy">
193 <meta name="description" content="copyright 1996 King Tut">
194 To create an HTTP-EQUIV type of <meta> tag, use -head, described below.
196 The -style argument is used to incorporate cascading stylesheets into
198 your code. See the section on CASCADING STYLESHEETS for more
199 information.
200 The -lang argument is used to incorporate a language attribute into the
202 <html> tag. For example:
203 print $q->start_html( -lang => 'fr-CA' );
205 The default if not specified is "en-US" for US English, unless the -dtd
207 parameter specifies an HTML 2.0 or 3.2 DTD, in which case the lang
208 attribute is left off. You can force the lang attribute to left off in
209 other cases by passing an empty string (-lang=>'').
210 The -encoding argument can be used to specify the character set for
212 XHTML. It defaults to iso-8859-1 if not specified.
213 The -dtd argument can be used to specify a public DTD identifier
215 string. For example:
216 -dtd => '-//W3C//DTD HTML 4.01 Transitional//EN')
218 Alternatively, it can take public and system DTD identifiers as an
220 array:
221 -dtd => [
223 '-//W3C//DTD HTML 4.01 Transitional//EN',
224 'http://www.w3.org/TR/html4/loose.dtd'
225 ]
226 For the public DTD identifier to be considered, it must be valid.
228 Otherwise it will be replaced by the default DTD. If the public DTD
229 contains 'XHTML', CGI.pm will emit XML.
230 The -declare_xml argument, when used in conjunction with XHTML, will
232 put a <?xml> declaration at the top of the HTML header. The sole
233 purpose of this declaration is to declare the character set encoding.
234 In the absence of -declare_xml, the output HTML will contain a <meta>
235 tag that specifies the encoding, allowing the HTML to pass most
236 validators. The default for -declare_xml is false.
237 You can place other arbitrary HTML elements to the <head> section with
239 the -head tag. For example, to place a <link> element in the head
240 section, use this:
241 print start_html(
243 -head => Link({
244 -rel => 'shortcut icon',
245 -href => 'favicon.ico'
246 })
247 );
248 To incorporate multiple HTML elements into the <head> section, just
250 pass an array reference:
251 print start_html(
253 -head => [
254 Link({
255 -rel => 'next',
256 -href => 'http://www.capricorn.com/s2.html'
257 }),
258 Link({
259 -rel => 'previous',
260 -href => 'http://www.capricorn.com/s1.html'
261 })
262 ]
263 );
264 And here's how to create an HTTP-EQUIV <meta> tag:
266 print start_html(
268 -head => meta({
269 -http_equiv => 'Content-Type',
270 -content => 'text/html'
271 })
272 );
273 JAVASCRIPTING: The -script, -noScript, -onLoad, -onMouseOver,
275 -onMouseOut and -onUnload parameters are used to add JavaScript calls
276 to your pages. -script should point to a block of text containing
277 JavaScript function definitions. This block will be placed within a
278 <script> block inside the HTML (not HTTP) header. The block is placed
279 in the header in order to give your page a fighting chance of having
280 all its JavaScript functions in place even if the user presses the stop
281 button before the page has loaded completely. CGI.pm attempts to format
282 the script in such a way that JavaScript-naive browsers will not choke
283 on the code: unfortunately there are some browsers that get confused by
284 it nevertheless.
285 The -onLoad and -onUnload parameters point to fragments of JavaScript
287 code to execute when the page is respectively opened and closed by the
288 browser. Usually these parameters are calls to functions defined in
289 the -script field:
290 $q = CGI->new;
292 print header;
293 $JSCRIPT = <<END;
294 // Ask a silly question
295 function riddle_me_this() {
296 var r = prompt(
297 "What walks on four legs in the morning, " +
298 "two legs in the afternoon, " +
299 "and three legs in the evening?"
300 );
301 response(r);
302 }
303 // Get a silly answer
304 function response(answer) {
305 if (answer == "man")
306 alert("Right you are!");
307 else
308 alert("Wrong! Guess again.");
309 }
310 END
311 print start_html(
312 -title => 'The Riddle of the Sphinx',
313 -script => $JSCRIPT
314 );
315 Use the -noScript parameter to pass some HTML text that will be
317 displayed on browsers that do not have JavaScript (or browsers where
318 JavaScript is turned off).
319 The <script> tag, has several attributes including "type", "charset"
321 and "src". "src" allows you to keep JavaScript code in an external
322 file. To use these attributes pass a HASH reference in the -script
323 parameter containing one or more of -type, -src, or -code:
324 print $q->start_html(
326 -title => 'The Riddle of the Sphinx',
327 -script => {
328 -type => 'JAVASCRIPT',
329 -src => '/javascript/sphinx.js'}
330 );
331 print $q->(
333 -title => 'The Riddle of the Sphinx',
334 -script => {
335 -type => 'PERLSCRIPT',
336 -code => 'print "hello world!\n;"'
337 }
338 );
339 A final feature allows you to incorporate multiple <script> sections
341 into the header. Just pass the list of script sections as an array
342 reference. This allows you to specify different source files for
343 different dialects of JavaScript. Example:
344 print $q->start_html(
346 -title => 'The Riddle of the Sphinx',
347 -script => [
348 {
349 -type => 'text/javascript',
350 -src => '/javascript/utilities10.js'
351 },
352 {
353 -type => 'text/javascript',
354 -src => '/javascript/utilities11.js'
355 },
356 {
357 -type => 'text/jscript',
358 -src => '/javascript/utilities12.js'
359 },
360 {
361 -type => 'text/ecmascript',
362 -src => '/javascript/utilities219.js'
363 }
364 ]
365 );
366 The option "-language" is a synonym for -type, and is supported for
368 backwards compatibility.
369 The old-style positional parameters are as follows:
371 Parameters:
373 1. The title
375 2. The author's e-mail address (will create a <link rev="MADE"> tag if
377 present
378 3. A 'true' flag if you want to include a <base> tag in the header.
380 This helps resolve relative addresses to absolute ones when the
381 document is moved, but makes the document hierarchy non-portable.
382 Use with care!
383 Other parameters you want to include in the <body> tag may be appended
385 to these. This is a good place to put HTML extensions, such as colors
386 and wallpaper patterns.
387 Ending the Html document:
389 print $q->end_html;
390 This ends an HTML document by printing the </body></html> tags.
392
394 CGI.pm defines general HTML shortcut methods for many HTML tags. HTML
395 shortcuts are named after a single HTML element and return a fragment
396 of HTML text. Example:
397 print $q->blockquote(
399 "Many years ago on the island of",
400 $q->a({href=>"http://crete.org/"},"Crete"),
401 "there lived a Minotaur named",
402 $q->strong("Fred."),
403 ),
404 $q->hr;
405 This results in the following HTML code (extra newlines have been added
407 for readability):
408 <blockquote>
410 Many years ago on the island of
411 <a href="http://crete.org/">Crete</a> there lived
412 a minotaur named <strong>Fred.</strong>
413 </blockquote>
414 <hr>
415 If you find the syntax for calling the HTML shortcuts awkward, you can
417 import them into your namespace and dispense with the object syntax
418 completely (see the next section for more details):
419 use CGI ':standard';
421 print blockquote(
422 "Many years ago on the island of",
423 a({href=>"http://crete.org/"},"Crete"),
424 "there lived a minotaur named",
425 strong("Fred."),
426 ),
427 hr;
428 Providing arguments to HTML shortcuts
430 The HTML methods will accept zero, one or multiple arguments. If you
431 provide no arguments, you get a single tag:
432 print hr; # <hr>
434 If you provide one or more string arguments, they are concatenated
436 together with spaces and placed between opening and closing tags:
437 print h1("Chapter","1"); # <h1>Chapter 1</h1>"
439 If the first argument is a hash reference, then the keys and values of
441 the hash become the HTML tag's attributes:
442 print a({-href=>'fred.html',-target=>'_new'},
444 "Open a new frame");
445 <a href="fred.html",target="_new">Open a new frame</a>
447 You may dispense with the dashes in front of the attribute names if you
449 prefer:
450 print img {src=>'fred.gif',align=>'LEFT'};
452 <img align="LEFT" src="fred.gif">
454 Sometimes an HTML tag attribute has no argument. For example, ordered
456 lists can be marked as COMPACT. The syntax for this is an argument
457 that that points to an undef string:
458 print ol({compact=>undef},li('one'),li('two'),li('three'));
460 Prior to CGI.pm version 2.41, providing an empty ('') string as an
462 attribute argument was the same as providing undef. However, this has
463 changed in order to accommodate those who want to create tags of the
464 form <img alt="">. The difference is shown in these two pieces of
465 code:
466 CODE RESULT
468 img({alt=>undef}) <img alt>
469 img({alt=>''}) <img alt="">
470 The distributive property of HTML shortcuts
472 One of the cool features of the HTML shortcuts is that they are
473 distributive. If you give them an argument consisting of a reference
474 to a list, the tag will be distributed across each element of the list.
475 For example, here's one way to make an ordered list:
476 print ul(
478 li({-type=>'disc'},['Sneezy','Doc','Sleepy','Happy'])
479 );
480 This example will result in HTML output that looks like this:
482 <ul>
484 <li type="disc">Sneezy</li>
485 <li type="disc">Doc</li>
486 <li type="disc">Sleepy</li>
487 <li type="disc">Happy</li>
488 </ul>
489 This is extremely useful for creating tables. For example:
491 print table({-border=>undef},
493 caption('When Should You Eat Your Vegetables?'),
494 Tr({-align=>'CENTER',-valign=>'TOP'},
495 [
496 th(['Vegetable', 'Breakfast','Lunch','Dinner']),
497 td(['Tomatoes' , 'no', 'yes', 'yes']),
498 td(['Broccoli' , 'no', 'no', 'yes']),
499 td(['Onions' , 'yes','yes', 'yes'])
500 ]
501 )
502 );
503 HTML shortcuts and list interpolation
505 Consider this bit of code:
506 print blockquote(em('Hi'),'mom!'));
508 It will ordinarily return the string that you probably expect, namely:
510 <blockquote><em>Hi</em> mom!</blockquote>
512 Note the space between the element "Hi" and the element "mom!". CGI.pm
514 puts the extra space there using array interpolation, which is
515 controlled by the magic $" variable. Sometimes this extra space is not
516 what you want, for example, when you are trying to align a series of
517 images. In this case, you can simply change the value of $" to an
518 empty string.
519 {
521 local($") = '';
522 print blockquote(em('Hi'),'mom!'));
523 }
524 I suggest you put the code in a block as shown here. Otherwise the
526 change to $" will affect all subsequent code until you explicitly reset
527 it.
528 Non-standard HTML shortcuts
530 A few HTML tags don't follow the standard pattern for various reasons.
531 comment() generates an HTML comment (<!-- comment -->). Call it like
533 print comment('here is my comment');
535 Because of conflicts with built-in perl functions, the following
537 functions begin with initial caps:
538 Select
540 Tr
541 Link
542 Delete
543 Accept
544 Sub
545 In addition, start_html(), end_html(), start_form(), end_form(),
547 start_multipart_form() and all the fill-out form tags are special. See
548 their respective sections.
549 Autoescaping HTML
551 By default, all HTML that is emitted by the form-generating functions
552 is passed through a function called escapeHTML():
553 $escaped_string = escapeHTML("unescaped string");
555 Escape HTML formatting characters in a string. Internally this
556 calls HTML::Entities (encode_entities) so really you should just
557 use that instead - the default list of chars that will be encoded
558 (passed to the HTML::Entities encode_entities method) is:
559 & < > " \x8b \x9b '
561 you can control this list by setting the value of
563 $CGI::ENCODE_ENTITIES:
564 # only encode < >
566 $CGI::ENCODE_ENTITIES = q{<>}
567 if you want to encode all entities then undef
569 $CGI::ENCODE_ENTITIES:
570 # encode all entities
572 $CGI::ENCODE_ENTITIES = undef;
573 The automatic escaping does not apply to other shortcuts, such as h1().
575 You should call escapeHTML() yourself on untrusted data in order to
576 protect your pages against nasty tricks that people may enter into
577 guestbooks, etc.. To change the character set, use charset(). To turn
578 autoescaping off completely, use autoEscape(0):
579 $charset = charset([$charset]);
581 Get or set the current character set.
582 $flag = autoEscape([$flag]);
584 Get or set the value of the autoescape flag.
585
587 General note The various form-creating methods all return strings to
588 the caller, containing the tag or tags that will create the requested
589 form element. You are responsible for actually printing out these
590 strings. It's set up this way so that you can place formatting tags
591 around the form elements.
592 Another note The default values that you specify for the forms are only
594 used the first time the script is invoked (when there is no query
595 string). On subsequent invocations of the script (when there is a
596 query string), the former values are used even if they are blank.
597 If you want to change the value of a field from its previous value, you
599 have two choices:
600 (1) call the param() method to set it.
602 (2) use the -override (alias -force) parameter (a new feature in
604 version 2.15). This forces the default value to be used, regardless of
605 the previous value:
606 print textfield(-name=>'field_name',
608 -default=>'starting value',
609 -override=>1,
610 -size=>50,
611 -maxlength=>80);
612 Yet another note By default, the text and labels of form elements are
614 escaped according to HTML rules. This means that you can safely use
615 "<CLICK ME>" as the label for a button. However, it also interferes
616 with your ability to incorporate special HTML character sequences, such
617 as Á, into your fields. If you wish to turn off automatic
618 escaping, call the autoEscape() method with a false value immediately
619 after creating the CGI object:
620 $q = CGI->new;
622 $q->autoEscape(0);
623 Note that autoEscape() is exclusively used to effect the behavior of
625 how some CGI.pm HTML generation functions handle escaping. Calling
626 escapeHTML() explicitly will always escape the HTML.
627 A Lurking Trap! Some of the form-element generating methods return
629 multiple tags. In a scalar context, the tags will be concatenated
630 together with spaces, or whatever is the current value of the $"
631 global. In a list context, the methods will return a list of elements,
632 allowing you to modify them if you wish. Usually you will not notice
633 this behavior, but beware of this:
634 printf("%s\n",end_form())
636 end_form() produces several tags, and only the first of them will be
638 printed because the format only expects one value.
639 <p>
641 Creating an isindex tag
643 print isindex(-action=>$action);
644 -or-
646 print isindex($action);
648 Prints out an <isindex> tag. Not very exciting. The parameter -action
650 specifies the URL of the script to process the query. The default is
651 to process the query with the current script.
652 Starting and ending a form
654 print start_form(-method=>$method,
655 -action=>$action,
656 -enctype=>$encoding);
657 <... various form stuff ...>
658 print end_form;
659 -or-
661 print start_form($method,$action,$encoding);
663 <... various form stuff ...>
664 print end_form;
665 start_form() will return a <form> tag with the optional method, action
667 and form encoding that you specify. The defaults are:
668 method: POST
670 action: this script
671 enctype: application/x-www-form-urlencoded for non-XHTML
672 multipart/form-data for XHTML, see multipart/form-data below.
673 end_form() returns the closing </form> tag.
675 start_form()'s enctype argument tells the browser how to package the
677 various fields of the form before sending the form to the server. Two
678 values are possible:
679 application/x-www-form-urlencoded
681 This is the older type of encoding. It is compatible with many CGI
682 scripts and is suitable for short fields containing text data. For
683 your convenience, CGI.pm stores the name of this encoding type in
684 &CGI::URL_ENCODED.
685 multipart/form-data
687 This is the newer type of encoding. It is suitable for forms that
688 contain very large fields or that are intended for transferring
689 binary data. Most importantly, it enables the "file upload"
690 feature. For your convenience, CGI.pm stores the name of this
691 encoding type in &CGI::MULTIPART
692 Forms that use this type of encoding are not easily interpreted by
694 CGI scripts unless they use CGI.pm or another library designed to
695 handle them.
696 If XHTML is activated (the default), then forms will be
698 automatically created using this type of encoding.
699 The start_form() method uses the older form of encoding by default
701 unless XHTML is requested. If you want to use the newer form of
702 encoding by default, you can call start_multipart_form() instead of
703 start_form(). The method end_multipart_form() is an alias to
704 end_form().
705 JAVASCRIPTING: The -name and -onSubmit parameters are provided for use
707 with JavaScript. The -name parameter gives the form a name so that it
708 can be identified and manipulated by JavaScript functions. -onSubmit
709 should point to a JavaScript function that will be executed just before
710 the form is submitted to your server. You can use this opportunity to
711 check the contents of the form for consistency and completeness. If
712 you find something wrong, you can put up an alert box or maybe fix
713 things up yourself. You can abort the submission by returning false
714 from this function.
715 Usually the bulk of JavaScript functions are defined in a <script>
717 block in the HTML header and -onSubmit points to one of these function
718 call. See start_html() for details.
719 Form elements
721 After starting a form, you will typically create one or more
722 textfields, popup menus, radio groups and other form elements. Each of
723 these elements takes a standard set of named arguments. Some elements
724 also have optional arguments. The standard arguments are as follows:
725 -name
727 The name of the field. After submission this name can be used to
728 retrieve the field's value using the param() method.
729 -value, -values
731 The initial value of the field which will be returned to the script
732 after form submission. Some form elements, such as text fields,
733 take a single scalar -value argument. Others, such as popup menus,
734 take a reference to an array of values. The two arguments are
735 synonyms.
736 -tabindex
738 A numeric value that sets the order in which the form element
739 receives focus when the user presses the tab key. Elements with
740 lower values receive focus first.
741 -id A string identifier that can be used to identify this element to
743 JavaScript and DHTML.
744 -override
746 A boolean, which, if true, forces the element to take on the value
747 specified by -value, overriding the sticky behavior described
748 earlier for the -nosticky pragma.
749 -onChange, -onFocus, -onBlur, -onMouseOver, -onMouseOut, -onSelect
751 These are used to assign JavaScript event handlers. See the
752 JavaScripting section for more details.
753 Other common arguments are described in the next section. In addition
755 to these, all attributes described in the HTML specifications are
756 supported.
757 Creating a text field
759 print textfield(-name=>'field_name',
760 -value=>'starting value',
761 -size=>50,
762 -maxlength=>80);
763 -or-
764 print textfield('field_name','starting value',50,80);
766 textfield() will return a text input field.
768 Parameters
770 1. The first parameter is the required name for the field (-name).
772 2. The optional second parameter is the default starting value for the
774 field contents (-value, formerly known as -default).
775 3. The optional third parameter is the size of the field in
777 characters (-size).
778 4. The optional fourth parameter is the maximum number of characters
780 the
781 field will accept (-maxlength).
782 As with all these methods, the field will be initialized with its
784 previous contents from earlier invocations of the script. When the
785 form is processed, the value of the text field can be retrieved with:
786 $value = param('foo');
788 If you want to reset it from its initial value after the script has
790 been called once, you can do so like this:
791 param('foo',"I'm taking over this value!");
793 Creating a big text field
795 print textarea(-name=>'foo',
796 -default=>'starting value',
797 -rows=>10,
798 -columns=>50);
799 -or
801 print textarea('foo','starting value',10,50);
803 textarea() is just like textfield, but it allows you to specify rows
805 and columns for a multiline text entry box. You can provide a starting
806 value for the field, which can be long and contain multiple lines.
807 Creating a password field
809 print password_field(-name=>'secret',
810 -value=>'starting value',
811 -size=>50,
812 -maxlength=>80);
813 -or-
814 print password_field('secret','starting value',50,80);
816 password_field() is identical to textfield(), except that its contents
818 will be starred out on the web page.
819 Creating a file upload field
821 print filefield(-name=>'uploaded_file',
822 -default=>'starting value',
823 -size=>50,
824 -maxlength=>80);
825 -or-
826 print filefield('uploaded_file','starting value',50,80);
828 filefield() will return a file upload field. In order to take full
830 advantage of this you must use the new multipart encoding scheme for
831 the form. You can do this either by calling start_form() with an
832 encoding type of &CGI::MULTIPART, or by calling the new method
833 start_multipart_form() instead of vanilla start_form().
834 Parameters
836 1. The first parameter is the required name for the field (-name).
838 2. The optional second parameter is the starting value for the field
840 contents to be used as the default file name (-default).
841 For security reasons, browsers don't pay any attention to this
843 field, and so the starting value will always be blank. Worse, the
844 field loses its "sticky" behavior and forgets its previous
845 contents. The starting value field is called for in the HTML
846 specification, however, and possibly some browser will eventually
847 provide support for it.
848 3. The optional third parameter is the size of the field in characters
850 (-size).
851 4. The optional fourth parameter is the maximum number of characters
853 the field will accept (-maxlength).
854 JAVASCRIPTING: The -onChange, -onFocus, -onBlur, -onMouseOver,
856 -onMouseOut and -onSelect parameters are recognized. See textfield()
857 for details.
858 Creating a popup menu
860 print popup_menu('menu_name',
861 ['eenie','meenie','minie'],
862 'meenie');
863 -or-
865 %labels = ('eenie'=>'your first choice',
867 'meenie'=>'your second choice',
868 'minie'=>'your third choice');
869 %attributes = ('eenie'=>{'class'=>'class of first choice'});
870 print popup_menu('menu_name',
871 ['eenie','meenie','minie'],
872 'meenie',\%labels,\%attributes);
873 -or (named parameter style)-
875 print popup_menu(-name=>'menu_name',
877 -values=>['eenie','meenie','minie'],
878 -default=>['meenie','minie'],
879 -labels=>\%labels,
880 -attributes=>\%attributes);
881 popup_menu() creates a menu. Please note that the -multiple option will
883 be ignored if passed - use scrolling_list() if you want to create a
884 menu that supports multiple selections
885 1. The required first argument is the menu's name (-name).
887 2. The required second argument (-values) is an array reference
889 containing the list of menu items in the menu. You can pass the
890 method an anonymous array, as shown in the example, or a reference
891 to a named array, such as "\@foo".
892 3. The optional third parameter (-default) is the name of the default
894 menu choice. If not specified, the first item will be the default.
895 The values of the previous choice will be maintained across
896 queries. Pass an array reference to select multiple defaults.
897 4. The optional fourth parameter (-labels) is provided for people who
899 want to use different values for the user-visible label inside the
900 popup menu and the value returned to your script. It's a pointer
901 to an hash relating menu values to user-visible labels. If you
902 leave this parameter blank, the menu values will be displayed by
903 default. (You can also leave a label undefined if you want to).
904 5. The optional fifth parameter (-attributes) is provided to assign
906 any of the common HTML attributes to an individual menu item. It's
907 a pointer to a hash relating menu values to another hash with the
908 attribute's name as the key and the attribute's value as the value.
909 When the form is processed, the selected value of the popup menu can be
911 retrieved using:
912 $popup_menu_value = param('menu_name');
914 Creating an option group
916 Named parameter style
917 print popup_menu(-name=>'menu_name',
919 -values=>[qw/eenie meenie minie/,
920 optgroup(-name=>'optgroup_name',
921 -values => ['moe','catch'],
922 -attributes=>{'catch'=>{'class'=>'red'}})],
923 -labels=>{'eenie'=>'one',
924 'meenie'=>'two',
925 'minie'=>'three'},
926 -default=>'meenie');
927 Old style
929 print popup_menu('menu_name',
930 ['eenie','meenie','minie',
931 optgroup('optgroup_name', ['moe', 'catch'],
932 {'catch'=>{'class'=>'red'}})],'meenie',
933 {'eenie'=>'one','meenie'=>'two','minie'=>'three'});
934 optgroup() creates an option group within a popup menu.
936 1. The required first argument (-name) is the label attribute of the
938 optgroup and is not inserted in the parameter list of the query.
939 2. The required second argument (-values) is an array reference
941 containing the list of menu items in the menu. You can pass the
942 method an anonymous array, as shown in the example, or a reference
943 to a named array, such as \@foo. If you pass a HASH reference, the
944 keys will be used for the menu values, and the values will be used
945 for the menu labels (see -labels below).
946 3. The optional third parameter (-labels) allows you to pass a
948 reference to a hash containing user-visible labels for one or more
949 of the menu items. You can use this when you want the user to see
950 one menu string, but have the browser return your program a
951 different one. If you don't specify this, the value string will be
952 used instead ("eenie", "meenie" and "minie" in this example). This
953 is equivalent to using a hash reference for the -values parameter.
954 4. An optional fourth parameter (-labeled) can be set to a true value
956 and indicates that the values should be used as the label attribute
957 for each option element within the optgroup.
958 5. An optional fifth parameter (-novals) can be set to a true value
960 and indicates to suppress the val attribute in each option element
961 within the optgroup.
962 See the discussion on optgroup at W3C
964 (http://www.w3.org/TR/REC-html40/interact/forms.html#edef-OPTGROUP)
965 for details.
966 6. An optional sixth parameter (-attributes) is provided to assign any
968 of the common HTML attributes to an individual menu item. It's a
969 pointer to a hash relating menu values to another hash with the
970 attribute's name as the key and the attribute's value as the value.
971 Creating a scrolling list
973 print scrolling_list('list_name',
974 ['eenie','meenie','minie','moe'],
975 ['eenie','moe'],5,'true',{'moe'=>{'class'=>'red'}});
976 -or-
977 print scrolling_list('list_name',
979 ['eenie','meenie','minie','moe'],
980 ['eenie','moe'],5,'true',
981 \%labels,%attributes);
982 -or-
984 print scrolling_list(-name=>'list_name',
986 -values=>['eenie','meenie','minie','moe'],
987 -default=>['eenie','moe'],
988 -size=>5,
989 -multiple=>'true',
990 -labels=>\%labels,
991 -attributes=>\%attributes);
992 scrolling_list() creates a scrolling list.
994 Parameters:
996 1. The first and second arguments are the list name (-name) and values
998 (-values). As in the popup menu, the second argument should be an
999 array reference.
1000 2. The optional third argument (-default) can be either a reference to
1002 a list containing the values to be selected by default, or can be a
1003 single value to select. If this argument is missing or undefined,
1004 then nothing is selected when the list first appears. In the named
1005 parameter version, you can use the synonym "-defaults" for this
1006 parameter.
1007 3. The optional fourth argument is the size of the list (-size).
1009 4. The optional fifth argument can be set to true to allow multiple
1011 simultaneous selections (-multiple). Otherwise only one selection
1012 will be allowed at a time.
1013 5. The optional sixth argument is a pointer to a hash containing long
1015 user-visible labels for the list items (-labels). If not provided,
1016 the values will be displayed.
1017 6. The optional sixth parameter (-attributes) is provided to assign
1019 any of the common HTML attributes to an individual menu item. It's
1020 a pointer to a hash relating menu values to another hash with the
1021 attribute's name as the key and the attribute's value as the value.
1022 When this form is processed, all selected list items will be
1024 returned as a list under the parameter name 'list_name'. The
1025 values of the selected items can be retrieved with:
1026 @selected = param('list_name');
1028 Creating a group of related checkboxes
1030 print checkbox_group(-name=>'group_name',
1031 -values=>['eenie','meenie','minie','moe'],
1032 -default=>['eenie','moe'],
1033 -linebreak=>'true',
1034 -disabled => ['moe'],
1035 -labels=>\%labels,
1036 -attributes=>\%attributes);
1037 print checkbox_group('group_name',
1039 ['eenie','meenie','minie','moe'],
1040 ['eenie','moe'],'true',\%labels,
1041 {'moe'=>{'class'=>'red'}});
1042 HTML3-COMPATIBLE BROWSERS ONLY:
1044 print checkbox_group(-name=>'group_name',
1046 -values=>['eenie','meenie','minie','moe'],
1047 -rows=2,-columns=>2);
1048 checkbox_group() creates a list of checkboxes that are related by the
1050 same name.
1051 Parameters:
1053 1. The first and second arguments are the checkbox name and values,
1055 respectively (-name and -values). As in the popup menu, the second
1056 argument should be an array reference. These values are used for
1057 the user-readable labels printed next to the checkboxes as well as
1058 for the values passed to your script in the query string.
1059 2. The optional third argument (-default) can be either a reference to
1061 a list containing the values to be checked by default, or can be a
1062 single value to checked. If this argument is missing or undefined,
1063 then nothing is selected when the list first appears.
1064 3. The optional fourth argument (-linebreak) can be set to true to
1066 place line breaks between the checkboxes so that they appear as a
1067 vertical list. Otherwise, they will be strung together on a
1068 horizontal line.
1069 The optional -labels argument is a pointer to a hash relating the
1071 checkbox values to the user-visible labels that will be printed next to
1072 them. If not provided, the values will be used as the default.
1073 The optional parameters -rows, and -columns cause checkbox_group() to
1075 return an HTML3 compatible table containing the checkbox group
1076 formatted with the specified number of rows and columns. You can
1077 provide just the -columns parameter if you wish; checkbox_group will
1078 calculate the correct number of rows for you.
1079 The option -disabled takes an array of checkbox values and disables
1081 them by greying them out (this may not be supported by all browsers).
1082 The optional -attributes argument is provided to assign any of the
1084 common HTML attributes to an individual menu item. It's a pointer to a
1085 hash relating menu values to another hash with the attribute's name as
1086 the key and the attribute's value as the value.
1087 The optional -tabindex argument can be used to control the order in
1089 which radio buttons receive focus when the user presses the tab button.
1090 If passed a scalar numeric value, the first element in the group will
1091 receive this tab index and subsequent elements will be incremented by
1092 one. If given a reference to an array of radio button values, then the
1093 indexes will be jiggered so that the order specified in the array will
1094 correspond to the tab order. You can also pass a reference to a hash
1095 in which the hash keys are the radio button values and the values are
1096 the tab indexes of each button. Examples:
1097 -tabindex => 100 # this group starts at index 100 and counts up
1099 -tabindex => ['moe','minie','eenie','meenie'] # tab in this order
1100 -tabindex => {meenie=>100,moe=>101,minie=>102,eenie=>200} # tab in this order
1101 The optional -labelattributes argument will contain attributes attached
1103 to the <label> element that surrounds each button.
1104 When the form is processed, all checked boxes will be returned as a
1106 list under the parameter name 'group_name'. The values of the "on"
1107 checkboxes can be retrieved with:
1108 @turned_on = param('group_name');
1110 The value returned by checkbox_group() is actually an array of button
1112 elements. You can capture them and use them within tables, lists, or
1113 in other creative ways:
1114 @h = checkbox_group(-name=>'group_name',-values=>\@values);
1116 &use_in_creative_way(@h);
1117 Creating a standalone checkbox
1119 print checkbox(-name=>'checkbox_name',
1120 -checked=>1,
1121 -value=>'ON',
1122 -label=>'CLICK ME');
1123 -or-
1125 print checkbox('checkbox_name','checked','ON','CLICK ME');
1127 checkbox() is used to create an isolated checkbox that isn't logically
1129 related to any others.
1130 Parameters:
1132 1. The first parameter is the required name for the checkbox (-name).
1134 It will also be used for the user-readable label printed next to
1135 the checkbox.
1136 2. The optional second parameter (-checked) specifies that the
1138 checkbox is turned on by default. Synonyms are -selected and -on.
1139 3. The optional third parameter (-value) specifies the value of the
1141 checkbox when it is checked. If not provided, the word "on" is
1142 assumed.
1143 4. The optional fourth parameter (-label) is the user-readable label
1145 to be attached to the checkbox. If not provided, the checkbox name
1146 is used.
1147 The value of the checkbox can be retrieved using:
1149 $turned_on = param('checkbox_name');
1151 Creating a radio button group
1153 print radio_group(-name=>'group_name',
1154 -values=>['eenie','meenie','minie'],
1155 -default=>'meenie',
1156 -linebreak=>'true',
1157 -labels=>\%labels,
1158 -attributes=>\%attributes);
1159 -or-
1161 print radio_group('group_name',['eenie','meenie','minie'],
1163 'meenie','true',\%labels,\%attributes);
1164 HTML3-COMPATIBLE BROWSERS ONLY:
1167 print radio_group(-name=>'group_name',
1169 -values=>['eenie','meenie','minie','moe'],
1170 -rows=2,-columns=>2);
1171 radio_group() creates a set of logically-related radio buttons (turning
1173 one member of the group on turns the others off)
1174 Parameters:
1176 1. The first argument is the name of the group and is required
1178 (-name).
1179 2. The second argument (-values) is the list of values for the radio
1181 buttons. The values and the labels that appear on the page are
1182 identical. Pass an array reference in the second argument, either
1183 using an anonymous array, as shown, or by referencing a named array
1184 as in "\@foo".
1185 3. The optional third parameter (-default) is the name of the default
1187 button to turn on. If not specified, the first item will be the
1188 default. You can provide a nonexistent button name, such as "-" to
1189 start up with no buttons selected.
1190 4. The optional fourth parameter (-linebreak) can be set to 'true' to
1192 put line breaks between the buttons, creating a vertical list.
1193 5. The optional fifth parameter (-labels) is a pointer to an
1195 associative array relating the radio button values to user-visible
1196 labels to be used in the display. If not provided, the values
1197 themselves are displayed.
1198 All modern browsers can take advantage of the optional parameters
1200 -rows, and -columns. These parameters cause radio_group() to return an
1201 HTML3 compatible table containing the radio group formatted with the
1202 specified number of rows and columns. You can provide just the
1203 -columns parameter if you wish; radio_group will calculate the correct
1204 number of rows for you.
1205 To include row and column headings in the returned table, you can use
1207 the -rowheaders and -colheaders parameters. Both of these accept a
1208 pointer to an array of headings to use. The headings are just
1209 decorative. They don't reorganize the interpretation of the radio
1210 buttons -- they're still a single named unit.
1211 The optional -tabindex argument can be used to control the order in
1213 which radio buttons receive focus when the user presses the tab button.
1214 If passed a scalar numeric value, the first element in the group will
1215 receive this tab index and subsequent elements will be incremented by
1216 one. If given a reference to an array of radio button values, then the
1217 indexes will be jiggered so that the order specified in the array will
1218 correspond to the tab order. You can also pass a reference to a hash
1219 in which the hash keys are the radio button values and the values are
1220 the tab indexes of each button. Examples:
1221 -tabindex => 100 # this group starts at index 100 and counts up
1223 -tabindex => ['moe','minie','eenie','meenie'] # tab in this order
1224 -tabindex => {meenie=>100,moe=>101,minie=>102,eenie=>200} # tab in this order
1225 The optional -attributes argument is provided to assign any of the
1227 common HTML attributes to an individual menu item. It's a pointer to a
1228 hash relating menu values to another hash with the attribute's name as
1229 the key and the attribute's value as the value.
1230 The optional -labelattributes argument will contain attributes attached
1232 to the <label> element that surrounds each button.
1233 When the form is processed, the selected radio button can be retrieved
1235 using:
1236 $which_radio_button = param('group_name');
1238 The value returned by radio_group() is actually an array of button
1240 elements. You can capture them and use them within tables, lists, or
1241 in other creative ways:
1242 @h = radio_group(-name=>'group_name',-values=>\@values);
1244 &use_in_creative_way(@h);
1245 Creating a submit button
1247 print submit(-name=>'button_name',
1248 -value=>'value');
1249 -or-
1251 print submit('button_name','value');
1253 submit() will create the query submission button. Every form should
1255 have one of these.
1256 Parameters:
1258 1. The first argument (-name) is optional. You can give the button a
1260 name if you have several submission buttons in your form and you
1261 want to distinguish between them.
1262 2. The second argument (-value) is also optional. This gives the
1264 button a value that will be passed to your script in the query
1265 string. The name will also be used as the user-visible label.
1266 3. You can use -label as an alias for -value. I always get confused
1268 about which of -name and -value changes the user-visible label on
1269 the button.
1270 You can figure out which button was pressed by using different values
1272 for each one:
1273 $which_one = param('button_name');
1275 Creating a reset button
1277 print reset
1278 reset() creates the "reset" button. Note that it restores the form to
1280 its value from the last time the script was called, NOT necessarily to
1281 the defaults.
1282 Note that this conflicts with the perl reset() built-in. Use
1284 CORE::reset() to get the original reset function.
1285 Creating a default button
1287 print defaults('button_label')
1288 defaults() creates a button that, when invoked, will cause the form to
1290 be completely reset to its defaults, wiping out all the changes the
1291 user ever made.
1292 Creating a hidden field
1294 print hidden(-name=>'hidden_name',
1295 -default=>['value1','value2'...]);
1296 -or-
1298 print hidden('hidden_name','value1','value2'...);
1300 hidden() produces a text field that can't be seen by the user. It is
1302 useful for passing state variable information from one invocation of
1303 the script to the next.
1304 Parameters:
1306 1. The first argument is required and specifies the name of this field
1308 (-name).
1309 2. The second argument is also required and specifies its value
1311 (-default). In the named parameter style of calling, you can
1312 provide a single value here or a reference to a whole list
1313 Fetch the value of a hidden field this way:
1315 $hidden_value = param('hidden_name');
1317 Note, that just like all the other form elements, the value of a hidden
1319 field is "sticky". If you want to replace a hidden field with some
1320 other values after the script has been called once you'll have to do it
1321 manually:
1322 param('hidden_name','new','values','here');
1324 Creating a clickable image button
1326 print image_button(-name=>'button_name',
1327 -src=>'/source/URL',
1328 -align=>'MIDDLE');
1329 -or-
1331 print image_button('button_name','/source/URL','MIDDLE');
1333 image_button() produces a clickable image. When it's clicked on the
1335 position of the click is returned to your script as "button_name.x" and
1336 "button_name.y", where "button_name" is the name you've assigned to it.
1337 Parameters:
1339 1. The first argument (-name) is required and specifies the name of
1341 this field.
1342 2. The second argument (-src) is also required and specifies the URL
1344 3. The third option (-align, optional) is an alignment type, and may
1346 be TOP, BOTTOM or MIDDLE
1347 Fetch the value of the button this way:
1349 $x = param('button_name.x');
1350 $y = param('button_name.y');
1351 Creating a javascript action button
1353 print button(-name=>'button_name',
1354 -value=>'user visible label',
1355 -onClick=>"do_something()");
1356 -or-
1358 print button('button_name',"user visible value","do_something()");
1360 button() produces an "<input>" tag with "type="button"". When it's
1362 pressed the fragment of JavaScript code pointed to by the -onClick
1363 parameter will be executed.
1364
1366 It's possible for CGI.pm scripts to write into several browser panels
1367 and windows using the HTML 4 frame mechanism. There are three
1368 techniques for defining new frames programmatically:
1369 1. Create a <Frameset> document
1371 After writing out the HTTP header, instead of creating a standard
1372 HTML document using the start_html() call, create a <frameset>
1373 document that defines the frames on the page. Specify your
1374 script(s) (with appropriate parameters) as the SRC for each of the
1375 frames.
1376 There is no specific support for creating <frameset> sections in
1378 CGI.pm, but the HTML is very simple to write.
1379 2. Specify the destination for the document in the HTTP header
1381 You may provide a -target parameter to the header() method:
1382 print header(-target=>'ResultsWindow');
1384 This will tell the browser to load the output of your script into
1386 the frame named "ResultsWindow". If a frame of that name doesn't
1387 already exist, the browser will pop up a new window and load your
1388 script's document into that. There are a number of magic names
1389 that you can use for targets. See the HTML "<frame>" documentation
1390 for details.
1391 3. Specify the destination for the document in the <form> tag
1393 You can specify the frame to load in the FORM tag itself. With
1394 CGI.pm it looks like this:
1395 print start_form(-target=>'ResultsWindow');
1397 When your script is reinvoked by the form, its output will be
1399 loaded into the frame named "ResultsWindow". If one doesn't
1400 already exist a new window will be created.
1401 The script "frameset.cgi" in the examples directory shows one way to
1403 create pages in which the fill-out form and the response live in side-
1404 by-side frames.
1405
1407 The usual way to use JavaScript is to define a set of functions in a
1408 <SCRIPT> block inside the HTML header and then to register event
1409 handlers in the various elements of the page. Events include such
1410 things as the mouse passing over a form element, a button being
1411 clicked, the contents of a text field changing, or a form being
1412 submitted. When an event occurs that involves an element that has
1413 registered an event handler, its associated JavaScript code gets
1414 called.
1415 The elements that can register event handlers include the <BODY> of an
1417 HTML document, hypertext links, all the various elements of a fill-out
1418 form, and the form itself. There are a large number of events, and each
1419 applies only to the elements for which it is relevant. Here is a
1420 partial list:
1421 onLoad
1423 The browser is loading the current document. Valid in:
1424 + The HTML <BODY> section only.
1426 onUnload
1428 The browser is closing the current page or frame. Valid for:
1429 + The HTML <BODY> section only.
1431 onSubmit
1433 The user has pressed the submit button of a form. This event
1434 happens just before the form is submitted, and your function can
1435 return a value of false in order to abort the submission. Valid
1436 for:
1437 + Forms only.
1439 onClick
1441 The mouse has clicked on an item in a fill-out form. Valid for:
1442 + Buttons (including submit, reset, and image buttons)
1444 + Checkboxes
1445 + Radio buttons
1446 onChange
1448 The user has changed the contents of a field. Valid for:
1449 + Text fields
1451 + Text areas
1452 + Password fields
1453 + File fields
1454 + Popup Menus
1455 + Scrolling lists
1456 onFocus
1458 The user has selected a field to work with. Valid for:
1459 + Text fields
1461 + Text areas
1462 + Password fields
1463 + File fields
1464 + Popup Menus
1465 + Scrolling lists
1466 onBlur
1468 The user has deselected a field (gone to work somewhere else).
1469 Valid for:
1470 + Text fields
1472 + Text areas
1473 + Password fields
1474 + File fields
1475 + Popup Menus
1476 + Scrolling lists
1477 onSelect
1479 The user has changed the part of a text field that is selected.
1480 Valid for:
1481 + Text fields
1483 + Text areas
1484 + Password fields
1485 + File fields
1486 onMouseOver
1488 The mouse has moved over an element.
1489 + Text fields
1491 + Text areas
1492 + Password fields
1493 + File fields
1494 + Popup Menus
1495 + Scrolling lists
1496 onMouseOut
1498 The mouse has moved off an element.
1499 + Text fields
1501 + Text areas
1502 + Password fields
1503 + File fields
1504 + Popup Menus
1505 + Scrolling lists
1506 In order to register a JavaScript event handler with an HTML element,
1508 just use the event name as a parameter when you call the corresponding
1509 CGI method. For example, to have your validateAge() JavaScript code
1510 executed every time the textfield named "age" changes, generate the
1511 field like this:
1512 print textfield(-name=>'age',-onChange=>"validateAge(this)");
1514 This example assumes that you've already declared the validateAge()
1516 function by incorporating it into a <SCRIPT> block. The CGI.pm
1517 start_html() method provides a convenient way to create this section.
1518 Similarly, you can create a form that checks itself over for
1520 consistency and alerts the user if some essential value is missing by
1521 creating it this way:
1522 print start_form(-onSubmit=>"validateMe(this)");
1523 See the javascript.cgi script for a demonstration of how this all
1525 works.
1526
1528 CGI.pm has limited support for HTML3's cascading style sheets (css).
1529 To incorporate a stylesheet into your document, pass the start_html()
1530 method a -style parameter. The value of this parameter may be a
1531 scalar, in which case it is treated as the source URL for the
1532 stylesheet, or it may be a hash reference. In the latter case you
1533 should provide the hash with one or more of -src or -code. -src points
1534 to a URL where an externally-defined stylesheet can be found. -code
1535 points to a scalar value to be incorporated into a <style> section.
1536 Style definitions in -code override similarly-named ones in -src, hence
1537 the name "cascading."
1538 You may also specify the type of the stylesheet by adding the optional
1540 -type parameter to the hash pointed to by -style. If not specified,
1541 the style defaults to 'text/css'.
1542 To refer to a style within the body of your document, add the -class
1544 parameter to any HTML element:
1545 print h1({-class=>'Fancy'},'Welcome to the Party');
1547 Or define styles on the fly with the -style parameter:
1549 print h1({-style=>'Color: red;'},'Welcome to Hell');
1551 You may also use the new span() element to apply a style to a section
1553 of text:
1554 print span({-style=>'Color: red;'},
1556 h1('Welcome to Hell'),
1557 "Where did that handbasket get to?"
1558 );
1559 Note that you must import the ":html3" definitions to have the span()
1561 method available. Here's a quick and dirty example of using CSS's.
1562 See the CSS specification at http://www.w3.org/Style/CSS/ for more
1563 information.
1564 use CGI qw/:standard :html3/;
1566 #here's a stylesheet incorporated directly into the page
1568 $newStyle=<<END;
1569 <!--
1570 P.Tip {
1571 margin-right: 50pt;
1572 margin-left: 50pt;
1573 color: red;
1574 }
1575 P.Alert {
1576 font-size: 30pt;
1577 font-family: sans-serif;
1578 color: red;
1579 }
1580 -->
1581 END
1582 print header();
1583 print start_html( -title=>'CGI with Style',
1584 -style=>{-src=>'http://www.capricorn.com/style/st1.css',
1585 -code=>$newStyle}
1586 );
1587 print h1('CGI with Style'),
1588 p({-class=>'Tip'},
1589 "Better read the cascading style sheet spec before playing with this!"),
1590 span({-style=>'color: magenta'},
1591 "Look Mom, no hands!",
1592 p(),
1593 "Whooo wee!"
1594 );
1595 print end_html;
1596 Pass an array reference to -code or -src in order to incorporate
1598 multiple stylesheets into your document.
1599 Should you wish to incorporate a verbatim stylesheet that includes
1601 arbitrary formatting in the header, you may pass a -verbatim tag to the
1602 -style hash, as follows:
1603 print start_html (-style => {-verbatim => '@import
1605 url("/server-common/css/'.$cssFile.'");',
1606 -src => '/server-common/css/core.css'});
1607 This will generate an HTML header that contains this:
1609 <link rel="stylesheet" type="text/css" href="/server-common/css/core.css">
1611 <style type="text/css">
1612 @import url("/server-common/css/main.css");
1613 </style>
1614 Any additional arguments passed in the -style value will be
1616 incorporated into the <link> tag. For example:
1617 start_html(-style=>{-src=>['/styles/print.css','/styles/layout.css'],
1619 -media => 'all'});
1620 This will give:
1622 <link rel="stylesheet" type="text/css" href="/styles/print.css" media="all"/>
1624 <link rel="stylesheet" type="text/css" href="/styles/layout.css" media="all"/>
1625 <p>
1627 To make more complicated <link> tags, use the Link() function and pass
1629 it to start_html() in the -head argument, as in:
1630 @h = (Link({-rel=>'stylesheet',-type=>'text/css',-src=>'/ss/ss.css',-media=>'all'}),
1632 Link({-rel=>'stylesheet',-type=>'text/css',-src=>'/ss/fred.css',-media=>'paper'}));
1633 print start_html({-head=>\@h})
1634 To create primary and "alternate" stylesheet, use the -alternate
1636 option:
1637 start_html(-style=>{-src=>[
1639 {-src=>'/styles/print.css'},
1640 {-src=>'/styles/alt.css',-alternate=>1}
1641 ]
1642 });
1643 Dumping out all the name/value pairs
1645 The Dump() method produces a string consisting of all the query's
1646 name/value pairs formatted nicely as a nested list. This is useful for
1647 debugging purposes:
1648 print Dump
1650 Produces something that looks like:
1652 <ul>
1654 <li>name1
1655 <ul>
1656 <li>value1
1657 <li>value2
1658 </ul>
1659 <li>name2
1660 <ul>
1661 <li>value1
1662 </ul>
1663 </ul>
1664 As a shortcut, you can interpolate the entire CGI object into a string
1666 and it will be replaced with the a nice HTML dump shown above:
1667 $q=CGI->new;
1669 print "<h2>Current Values</h2> $q\n";
1670
1672 Address bug reports and comments to:
1673 <https://github.com/leejo/CGI.pm/issues>
1674 See the <https://github.com/leejo/CGI.pm/blob/master/CONTRIBUTING.md>
1676 file for information on raising issues and contributing
1677 The original bug tracker can be found at:
1679 <https://rt.cpan.org/Public/Dist/Display.html?Queue=CGI.pm>
1680
1682 CGI - The original source of this documentation / functionality
1683perl v5.34.0 2021-07-22 CGI::HTML::Functions(3)