CGI
view release on metacpan or search on metacpan
lib/CGI/HTML/Functions.pod view on Meta::CPAN
For the public DTD identifier to be considered, it must be valid. Otherwise it
will be replaced by the default DTD. If the public DTD contains 'XHTML', CGI.pm
will emit XML.
The B<-declare_xml> argument, when used in conjunction with XHTML, will put a
<?xml> declaration at the top of the HTML header. The sole purpose of this
declaration is to declare the character set encoding. In the absence of
-declare_xml, the output HTML will contain a <meta> tag that specifies the
encoding, allowing the HTML to pass most validators. The default for -declare_xml
is false.
You can place other arbitrary HTML elements to the <head> section with the
B<-head> tag. For example, to place a <link> element in the head section, use
this:
print start_html(
-head => Link({
-rel => 'shortcut icon',
-href => 'favicon.ico'
})
);
To incorporate multiple HTML elements into the <head> section, just pass an
array reference:
print start_html(
-head => [
Link({
-rel => 'next',
-href => 'http://www.capricorn.com/s2.html'
}),
Link({
-rel => 'previous',
-href => 'http://www.capricorn.com/s1.html'
})
]
);
And here's how to create an HTTP-EQUIV <meta> tag:
print start_html(
-head => meta({
-http_equiv => 'Content-Type',
-content => 'text/html'
})
);
JAVASCRIPTING: The B<-script>, B<-noScript>, B<-onLoad>, B<-onMouseOver>,
B<-onMouseOut> and B<-onUnload> parameters are used to add JavaScript calls to
your pages. B<-script> should point to a block of text containing JavaScript
function definitions. This block will be placed within a <script> block inside
the HTML (not HTTP) header. The block is placed in the header in order to give
your page a fighting chance of having all its JavaScript functions in place even
if the user presses the stop button before the page has loaded completely. CGI.pm
attempts to format the script in such a way that JavaScript-naive browsers will
not choke on the code: unfortunately there are some browsers that get confused by
it nevertheless.
The B<-onLoad> and B<-onUnload> parameters point to fragments of JavaScript code
to execute when the page is respectively opened and closed by the browser.
Usually these parameters are calls to functions defined in the B<-script> field:
$q = CGI->new;
print header;
$JSCRIPT = <<END;
// Ask a silly question
function riddle_me_this() {
var r = prompt(
"What walks on four legs in the morning, " +
"two legs in the afternoon, " +
"and three legs in the evening?"
);
response(r);
}
// Get a silly answer
function response(answer) {
if (answer == "man")
alert("Right you are!");
else
alert("Wrong! Guess again.");
}
END
print start_html(
-title => 'The Riddle of the Sphinx',
-script => $JSCRIPT
);
Use the B<-noScript> parameter to pass some HTML text that will be displayed on
browsers that do not have JavaScript (or browsers where JavaScript is turned
off).
The <script> tag, has several attributes including "type", "charset" and "src".
"src" allows you to keep JavaScript code in an external file. To use these
attributes pass a HASH reference in the B<-script> parameter containing one or
more of -type, -src, or -code:
print $q->start_html(
-title => 'The Riddle of the Sphinx',
-script => {
-type => 'JAVASCRIPT',
-src => '/javascript/sphinx.js'}
);
print $q->(
-title => 'The Riddle of the Sphinx',
-script => {
-type => 'PERLSCRIPT',
-code => 'print "hello world!\n;"'
}
);
A final feature allows you to incorporate multiple <script> sections into the
header. Just pass the list of script sections as an array reference. This allows
you to specify different source files for different dialects of JavaScript.
Example:
print $q->start_html(
-title => 'The Riddle of the Sphinx',
-script => [
{
-type => 'text/javascript',
-src => '/javascript/utilities10.js'
},
{
-type => 'text/javascript',
-src => '/javascript/utilities11.js'
},
{
-type => 'text/jscript',
-src => '/javascript/utilities12.js'
},
{
-type => 'text/ecmascript',
-src => '/javascript/utilities219.js'
}
]
);
The option "-language" is a synonym for -type, and is supported for backwards
compatibility.
The old-style positional parameters are as follows:
B<Parameters:>
=over 4
=item 1.
The title
=item 2.
The author's e-mail address (will create a <link rev="MADE"> tag if present
=item 3.
A 'true' flag if you want to include a <base> tag in the header. This helps
resolve relative addresses to absolute ones when the document is moved, but
makes the document hierarchy non-portable. Use with care!
=back
Other parameters you want to include in the <body> tag may be appended to these.
This is a good place to put HTML extensions, such as colors and wallpaper
patterns.
=head2 Ending the Html document:
print $q->end_html;
This ends an HTML document by printing the </body></html> tags.
=head1 CREATING STANDARD HTML ELEMENTS:
CGI.pm defines general HTML shortcut methods for many HTML tags. HTML shortcuts are named after a single
HTML element and return a fragment of HTML text. Example:
print $q->blockquote(
"Many years ago on the island of",
$q->a({href=>"http://crete.org/"},"Crete"),
"there lived a Minotaur named",
$q->strong("Fred."),
),
$q->hr;
This results in the following HTML code (extra newlines have been
added for readability):
<blockquote>
Many years ago on the island of
<a href="http://crete.org/">Crete</a> there lived
a minotaur named <strong>Fred.</strong>
</blockquote>
<hr>
If you find the syntax for calling the HTML shortcuts awkward, you can
import them into your namespace and dispense with the object syntax
completely (see the next section for more details):
use CGI ':standard';
print blockquote(
"Many years ago on the island of",
a({href=>"http://crete.org/"},"Crete"),
"there lived a minotaur named",
strong("Fred."),
),
hr;
=head2 Providing arguments to HTML shortcuts
The HTML methods will accept zero, one or multiple arguments. If you
provide no arguments, you get a single tag:
print hr; # <hr>
If you provide one or more string arguments, they are concatenated
together with spaces and placed between opening and closing tags:
print h1("Chapter","1"); # <h1>Chapter 1</h1>"
If the first argument is a hash reference, then the keys
and values of the hash become the HTML tag's attributes:
print a({-href=>'fred.html',-target=>'_new'},
"Open a new frame");
<a href="fred.html",target="_new">Open a new frame</a>
You may dispense with the dashes in front of the attribute names if
you prefer:
print img {src=>'fred.gif',align=>'LEFT'};
<img align="LEFT" src="fred.gif">
Sometimes an HTML tag attribute has no argument. For example, ordered
lib/CGI/HTML/Functions.pod view on Meta::CPAN
$hidden_value = param('hidden_name');
Note, that just like all the other form elements, the value of a
hidden field is "sticky". If you want to replace a hidden field with
some other values after the script has been called once you'll have to
do it manually:
param('hidden_name','new','values','here');
=head2 Creating a clickable image button
print image_button(-name=>'button_name',
-src=>'/source/URL',
-align=>'MIDDLE');
-or-
print image_button('button_name','/source/URL','MIDDLE');
image_button() produces a clickable image. When it's clicked on the
position of the click is returned to your script as "button_name.x"
and "button_name.y", where "button_name" is the name you've assigned
to it.
B<Parameters:>
=over 4
=item 1.
The first argument (-name) is required and specifies the name of this
field.
=item 2.
The second argument (-src) is also required and specifies the URL
=item 3.
The third option (-align, optional) is an alignment type, and may be
TOP, BOTTOM or MIDDLE
=back
Fetch the value of the button this way:
$x = param('button_name.x');
$y = param('button_name.y');
=head2 Creating a javascript action button
print button(-name=>'button_name',
-value=>'user visible label',
-onClick=>"do_something()");
-or-
print button('button_name',"user visible value","do_something()");
button() produces an C<< <input> >> tag with C<type="button">. When it's
pressed the fragment of JavaScript code pointed to by the B<-onClick> parameter
will be executed.
=head1 WORKING WITH FRAMES
It's possible for CGI.pm scripts to write into several browser panels
and windows using the HTML 4 frame mechanism. There are three
techniques for defining new frames programmatically:
=over 4
=item 1. Create a <Frameset> document
After writing out the HTTP header, instead of creating a standard
HTML document using the start_html() call, create a <frameset>
document that defines the frames on the page. Specify your script(s)
(with appropriate parameters) as the SRC for each of the frames.
There is no specific support for creating <frameset> sections
in CGI.pm, but the HTML is very simple to write.
=item 2. Specify the destination for the document in the HTTP header
You may provide a B<-target> parameter to the header() method:
print header(-target=>'ResultsWindow');
This will tell the browser to load the output of your script into the
frame named "ResultsWindow". If a frame of that name doesn't already
exist, the browser will pop up a new window and load your script's
document into that. There are a number of magic names that you can
use for targets. See the HTML C<< <frame> >> documentation for details.
=item 3. Specify the destination for the document in the <form> tag
You can specify the frame to load in the FORM tag itself. With
CGI.pm it looks like this:
print start_form(-target=>'ResultsWindow');
When your script is reinvoked by the form, its output will be loaded
into the frame named "ResultsWindow". If one doesn't already exist
a new window will be created.
=back
The script "frameset.cgi" in the examples directory shows one way to
create pages in which the fill-out form and the response live in
side-by-side frames.
=head1 SUPPORT FOR JAVASCRIPT
The usual way to use JavaScript is to define a set of functions in a
<SCRIPT> block inside the HTML header and then to register event
handlers in the various elements of the page. Events include such
things as the mouse passing over a form element, a button being
clicked, the contents of a text field changing, or a form being
submitted. When an event occurs that involves an element that has
registered an event handler, its associated JavaScript code gets
called.
( run in 0.730 second using v1.01-cache-2.11-cpan-364913b4093 )