and tags are not formatted. If these tags were
formatted, the user would see the extra indentation on the web browser
causing the page to look different than what would be expected. If you
wish to add more tags to the list of tags that are not to be touched, push
them onto the `@AS_IS' array:
push @CGI::Pretty::AS_IS,qw(CODE XMP);
Customizing the Indenting
-------------------------
If you wish to have your own personal style of indenting, you can
change the `$INDENT' variable:
$CGI::Pretty::INDENT = "\t\t";
would cause the indents to be two tabs.
Similarly, if you wish to have more space between lines, you may change
the `$LINEBREAK' variable:
$CGI::Pretty::LINEBREAK = "\n\n";
would create two carriage returns between lines.
If you decide you want to use the regular CGI indenting, you can easily
do the following:
$CGI::Pretty::INDENT = $CGI::Pretty::LINEBREAK = "";
BUGS
====
This section intentionally left blank.
AUTHOR
======
Brian Paulsen , with minor modifications by
Lincoln Stein for incorporation into the CGI.pm
distribution.
Copyright 1999, Brian Paulsen. All rights reserved.
This library is free software; you can redistribute it and/or modify it
under the same terms as Perl itself.
Bug reports and comments to Brian@ThePaulsens.com. You can also write
to lstein@cshl.org, but this code looks pretty hairy to me and I'm not
sure I understand it!
SEE ALSO
========
*Note CGI: CGI,
File: pm.info, Node: CGI/PrintWrapper, Next: CGI/Push, Prev: CGI/Pretty, Up: Module List
CGI methods output to a print handle
************************************
NAME
====
CGI::PrintWrapper - CGI methods output to a print handle
SYNOPSIS
========
use CGI::PrintHandle;
use IO::Scalar; # just an example
use HTML::Stream; # continuing the example
# Fine, there really is no such tag as "WEAK":
HTML::Stream->accept_tag ('WEAK');
my $content = '';
my $handle = IO::Scalar->new (\$content);
my $cgi = CGI::PrintHandle ($handle);
my $html = HTML::Stream->new ($handle);
# Not a very exciting example:
$cgi->start_form;
$html->WEAK->t ('I am form: hear me submit.')->_WEAK;
$cgi->submit;
$cgi->end_form;
print "$content\n";
DESCRIPTION
===========
*CGI::PrintWrapper* arranges for CGI methods to output their results by
printing onto an arbitrary handle. This gets around the problem that the
CGI's subs return strings, which may be inconvient when you wish to use
CGI for something besides CGI script processing.
You could just call print yourself on the appropriate file handle, but
there are many contexts in which it is cleaner to provide the extra
abstraction (such as mixing CGI with *HTML::Stream*, the problem which
prompted my solution, illustrated above).
*CGI::PrintWrapper* creates the necessary callbacks for printing
dynamically, updating the symbol table as it encounters a new CGI method.
CONSTRUCTOR
===========
`new ($h)'
Creates a new *CGI::PrintWrapper*, printing the results of CGI
methods onto the print handle object, $h.
`new ($h, @cgi_args)'
Creates a new *CGI::PrintWrapper*, printing the results of CGI
methods onto the print handle object, $h, and using the additional
arguments to construct the CGI object.
METHODS
=======
`cgi ( )'
Returns the underlying CGI object. This is handy for invoking methods
on the object whose result you do not wish to print, such as param().
`io ( )'
Returns the underlying print handle object.
AUTOLOAD
Initially, *CGI::PrintWrapper* has no methods (except as mentioned
above). As the caller invokes CGI methods, AUTOLOAD creates
anonymous subroutines to perform the actual CGI method call
indirection and print the results with the print handle object. It
also updates the symbol table for *CGI::PrintWrapper* so that future
calls can bypass AUTOLOAD. This makes a *CGI::PrintWrapper* object
transparently a CGI object, usable as a drop-in replacement.
SEE ALSO
========
*Note CGI: CGI,, *Note IO/Scalar: IO/Scalar,, *Note HTML/Stream:
HTML/Stream,, `print', *Note Perlfunc: (perl.info)perlfunc,
CGI is the canonical package for working with fill-out forms on the
web. It is particularly useful for generating HTML for such forms.
*IO::Scalar* is a handy package for treating a string as an object
supporting IO handle semantics.
*HTML::Stream* is a nice package for writing HTML markup and content
into an IO handle with stream semantics. It's main drawback is lack of
support for HTML 4.0.
DIAGNOSTICS
===========
The following are the diagnostics generated by *Class::Class*. Items
marked "(W)" are non-fatal (invoke `Carp::carp'); those marked "(F)" are
fatal (invoke `Carp::croak').
No print handle
(F) The caller tried to create a new `CGI::PrintWrapper' without
supplying the mandatory first argument, a print handle:
$cgi = CGI::PrintWrapper->new;
'%s' is not a print handle
(F) The caller tried to create a new `CGI::PrintWrapper' using an
object which does not support print as the mandatory first argument.
Couldn't create CGI object because %s
(F) The caller tried to create a new `CGI::PrintWrapper' using bad
addtional arguments to the constructor for CGI.
BUGS AND CAVEATS
================
There is no way of controlling now to use CGI, for example, if you
wished to precompile all the methods. Instead, you should make the
appropriate call to use yourself for CGI, in addition to that for
*CGI::PrintWrapper*, thus:
use CGI qw(:compile);
use CGI::PrintWrapper;
AUTHORS
=======
B. K. Oxley (binkley) at Home . I am grateful to
my employer, DataCraft, Inc., for time spent preparing this package for
public consumption.
COPYRIGHT
=========
$Id: PrintWrapper.pm,v 1.8 1999/12/30 13:38:06 binkley Exp $
Copyright 1999, B. K. Oxley (binkley).
This library is free software; you may redistribute it and/or modify it
under the same terms as Perl itself.
File: pm.info, Node: CGI/Push, Next: CGI/QuickForm, Prev: CGI/PrintWrapper, Up: Module List
Simple Interface to Server Push
*******************************
NAME
====
CGI::Push - Simple Interface to Server Push
SYNOPSIS
========
use CGI::Push qw(:standard);
do_push(-next_page=>\&next_page,
-last_page=>\&last_page,
-delay=>0.5);
sub next_page {
my($q,$counter) = @_;
return undef if $counter >= 10;
return start_html('Test'),
h1('Visible'),"\n",
"This page has been called ", strong($counter)," times",
end_html();
}
sub last_page {
my($q,$counter) = @_;
return start_html('Done'),
h1('Finished'),
strong($counter - 1),' iterations.',
end_html;
}
DESCRIPTION
===========
CGI::Push is a subclass of the CGI object created by CGI.pm. It is
specialized for server push operations, which allow you to create animated
pages whose content changes at regular intervals.
You provide CGI::Push with a pointer to a subroutine that will draw one
page. Every time your subroutine is called, it generates a new page. The
contents of the page will be transmitted to the browser in such a way that
it will replace what was there beforehand. The technique will work with
HTML pages as well as with graphics files, allowing you to create animated
GIFs.
Only Netscape Navigator supports server push. Internet Explorer
browsers do not.
USING CGI::Push
===============
CGI::Push adds one new method to the standard CGI suite, do_push().
When you call this method, you pass it a reference to a subroutine that is
responsible for drawing each new page, an interval delay, and an optional
subroutine for drawing the last page. Other optional parameters include
most of those recognized by the CGI header() method.
You may call do_push() in the object oriented manner or not, as you
prefer:
use CGI::Push;
$q = new CGI::Push;
$q->do_push(-next_page=>\&draw_a_page);
-or-
use CGI::Push qw(:standard);
do_push(-next_page=>\&draw_a_page);
Parameters are as follows:
-next_page
do_push(-next_page=>\&my_draw_routine);
This required parameter points to a reference to a subroutine
responsible for drawing each new page. The subroutine should expect
two parameters consisting of the CGI object and a counter indicating
the number of times the subroutine has been called. It should return
the contents of the page as an array of one or more items to print.
It can return a false value (or an empty array) in order to abort the
redrawing loop and print out the final page (if any)
sub my_draw_routine {
my($q,$counter) = @_;
return undef if $counter > 100;
return start_html('testing'),
h1('testing'),
"This page called $counter times";
}
You are of course free to refer to create and use global variables
within your draw routine in order to achieve special effects.
-last_page
This optional parameter points to a reference to the subroutine
responsible for drawing the last page of the series. It is called
after the -next_page routine returns a false value. The subroutine
itself should have exactly the same calling conventions as the
-next_page routine.
-type
This optional parameter indicates the content type of each page. It
defaults to "text/html". Normally the module assumes that each page
is of a homogenous MIME type. However if you provide either of the
magic values "heterogeneous" or "dynamic" (the latter provided for the
convenience of those who hate long parameter names), you can specify
the MIME type - and other header fields - on a per-page basis. See
"heterogeneous pages" for more details.
-delay
This indicates the delay, in seconds, between frames. Smaller delays
refresh the page faster. Fractional values are allowed.
*If not specified, -delay will default to 1 second*
-cookie, -target, -expires, -nph
These have the same meaning as the like-named parameters in
CGI::header().
If not specified, -nph will default to 1 (as needed for many servers,
see below).
Heterogeneous Pages
-------------------
Ordinarily all pages displayed by CGI::Push share a common MIME type.
However by providing a value of "heterogeneous" or "dynamic" in the
do_push() -type parameter, you can specify the MIME type of each page on a
case-by-case basis.
If you use this option, you will be responsible for producing the HTTP
header for each page. Simply modify your draw routine to look like this:
sub my_draw_routine {
my($q,$counter) = @_;
return header('text/html'), # note we're producing the header here
start_html('testing'),
h1('testing'),
"This page called $counter times";
}
You can add any header fields that you like, but some (cookies and
status fields included) may not be interpreted by the browser. One
interesting effect is to display a series of pages, then, after the last
page, to redirect the browser to a new URL. Because redirect() does
b work, the easiest way is with a -refresh header field, as shown
below:
sub my_draw_routine {
my($q,$counter) = @_;
return undef if $counter > 10;
return header('text/html'), # note we're producing the header here
start_html('testing'),
h1('testing'),
"This page called $counter times";
}
sub my_last_page {
return header(-refresh=>'5; URL=http://somewhere.else/finished.html',
-type=>'text/html'),
start_html('Moved'),
h1('This is the last page'),
'Goodbye!'
hr,
end_html;
}
Changing the Page Delay on the Fly
----------------------------------
If you would like to control the delay between pages on a page-by-page
basis, call push_delay() from within your draw routine. push_delay()
takes a single numeric argument representing the number of seconds you
wish to delay after the current page is displayed and before displaying
the next one. The delay may be fractional. Without parameters,
push_delay() just returns the current delay.
INSTALLING CGI::Push SCRIPTS
============================
Server push scripts must be installed as no-parsed-header (NPH) scripts
in order to work correctly on many servers. On Unix systems, this is most
often accomplished by prefixing the script's name with "nph-".
Recognition of NPH scripts happens automatically with WebSTAR and
Microsoft IIS. Users of other servers should see their documentation for
help.
Apache web server from version 1.3b2 on does not need server push
scripts installed as NPH scripts: the -nph parameter to do_push() may be
set to a false value to disable the extra headers needed by an NPH script.
AUTHOR INFORMATION
==================
Copyright 1995-1998, Lincoln D. Stein. All rights reserved.
This library is free software; you can redistribute it and/or modify it
under the same terms as Perl itself.
Address bug reports and comments to: lstein@cshl.org
BUGS
====
This section intentionally left blank.
SEE ALSO
========
*Note CGI/Carp: CGI/Carp,, *Note CGI: CGI,
File: pm.info, Node: CGI/QuickForm, Next: CGI/Request, Prev: CGI/Push, Up: Module List
Perl module to provide quick CGI forms.
***************************************
NAME
====
CGI::QuickForm - Perl module to provide quick CGI forms.
SYNOPSIS
========
# Minimal example. (Insecure no error checking.)
#!/usr/bin/perl -w
use strict ;
use CGI qw( :standard :html3 ) ;
use CGI::QuickForm ;
show_form(
-ACCEPT => \&on_valid_form, # You must supply this subroutine.
-TITLE => 'Test Form',
-FIELDS => [
{ -LABEL => 'Name', }, # Default field type is textfield.
{ -LABEL => 'Age', }, # Stored in param( 'Age' ).
],
) ;
sub on_valid_form {
my $name = param( 'Name' ) ;
my $age = param( 'Age' ) ;
open PEOPLE, ">>people.tab" ;
print PEOPLE "$name\t$age\n" ;
close PEOPLE ;
print header, start_html( 'Test Form Acceptance' ),
h3( 'Test Form Data Accepted' ),
p( "Thank you $name for your data." ), end_html ;
}
# All QuickForm options (aide memoir)
#!/usr/bin/perl -w
use strict ;
use CGI qw( :standard :html3 ) ;
use CGI::QuickForm ;
show_form(
-ACCEPT => \&on_valid_form,
-BORDER => 0,
-FOOTER => undef,
-HEADER => undef,
-INTRO => undef,
-LANGUAGE => 'en',
-USER_REQUIRED => undef,
-USER_INVALID => undef,
-TITLE => 'Test Form',
-REQUIRED_HTML => '+',
-INVALID_HTML => '*',
-VALIDATE => undef, # Set this to validate the entire record
-SIZE => undef,
-MAXLENGTH => undef,
-ROWS => undef,
-COLUMNS => undef,
-CHECK => 1,
-SPACE => 0, # Output some newlines to assist debugging if 1
-MULTI_COLUMN => 0,
-NAME => undef,
-ONSUBMIT => undef,
-JSCRIPT => {},
-STYLE_FIELDNAME => '',
-STYLE_FIELDVALUE => '',
-STYLE_BUTTONS => '',
-STYLE_ROW => '',
-STYLE_WHY => '',
-TABLE_OPTIONS => '',
-FIELDS => [
{
-LABEL => 'Personal Details',
-HEADLINE => 1,
-STYLE_FIELDNAME => '',
-COLSPAN => 2,
-END_ROW => 1,
},
{
-LABEL => 'Name',
-START_ROW => 1,
-END_ROW => 1,
-COLSPAN => 1,
-REQUIRED => undef,
-TYPE => 'textfield',
-VALIDATE => undef, # Set this to validate the field
-CLEAN => undef, # Set this to clean up valid data
-DESC => undef,
-STYLE_FIELDNAME => '', # If set over-rides form-level setting
-STYLE_FIELDVALUE => '', # If set over-rides form-level setting
-STYLE_ROW => '', # If set over-rides form-level setting
# Lowercase options are those supplied by CGI.pm
-name => undef, # Defaults to -LABEL's value.
-default => undef,
-size => 30,
-maxlength => undef,
},
# For all others: same QuickForm options as above
# and all CGI.pm options (which vary with -TYPE) available
{
-LABEL => 'Address',
-TYPE => 'textarea',
-rows => 3,
-columns => 40,
},
{
-LABEL => 'Password',
-TYPE => 'password_field',
},
{
-LABEL => 'Hair colour',
-TYPE => 'scrolling_list',
'-values' => [ qw( Red Black Brown Grey White ) ],
-size => 1,
-multiples => undef,
},
{
-LABEL => 'Worst Sport',
-TYPE => 'radio_group',
-values => [ qw( Boxing Cricket Golf ) ],
-default => 'Golf',
},
# Any other CGI.pm field can be used in the same way.
],
-BUTTONS => [
{ -name => 'Add' },
{ -name => 'Edit' },
{ -name => 'List' },
{ -name => 'Remove' },
{ -name => 'Clear', -DEFAULTS => 1 },
],
) ;
DESCRIPTION
===========
`show_form', provides a quick and simple mechanism for providing
on-line CGI forms.
When `show_form' executes it presents the form with the fields
requested. As you can see from the minimal example at the beginning of
the synopsis it will default everything it possibly can to get you up and
running as quickly as possible.
If you have specified any validation it will validate when the user
presses the submit button. If there is an error it will re-present the
form with the erroneous fields marked and with all the data entered in
tact. This is repeated as often as needed. Once the user has corrected all
errors and the data is valid then your `&on_valid_form' subroutine will be
called so that you can process the valid data in any way you wish.
Note that EXAMPLE #1 and EXAMPLE #2 are in this pod; `example1',
`example2', etc. are supplied as files.
QuickForm form-level (record-level) options
-------------------------------------------
`-ACCEPT'
Required subroutine reference. This is a reference to the subroutine
to execute when the form is successfully completed, i.e. once all the
fields and the whole record are valid (either because no validation
was requested or because every validation subroutine called returned
true). The parameters are accessible via `CGI.pm', so your
`&on_valid_form' may look something like this:
sub on_valid_form {
my $first_param = param( 'first' ) ;
my $second_param = param( 'second' ) ;
my $third_param = param( 'third' ) ;
# Process, e.g. send an email or write a record to a file or database.
# Give the user a thank you.
}
`-BORDER'
Optional integer. This is the border width. Default is zero. You would
normally set this to 1 if you are using `-DESC' to add textual
descriptions to your fields.
`-BUTTONS'
Optional array reference. This is an array of submit buttons. The
buttons appear at the bottom of the form, after all the fields. Each
button is defined as an anonymous hash, e.g.
-BUTTONS => [
{ -name => 'New' },
{ -name => 'Update' },
],
although any other legitimate `CGI.pm' options may also be given, e.g.
-BUTTONS => [
{ -name => 'New', -value => 'BUTTON_NEW' },
{ -name => 'Update', -value => 'BUTTON_UPDATE' },
],
If you want a button which resets the form to its default values then
create an entry like this:
{ -name => 'Clear', -DEFAULTS => 1 },
If no `-BUTTONS' option array reference is given it will be created
with `{ -name =< 'Submit' }' by default. Note that this option
replaces the `-BUTTONLABEL' option. If `-BUTTONLABEL' is used it will
be converted into the new form automatically so old scripts will not
be broken. However use of `-BUTTONS' is recommended for all new work.
To see which button has been pressed you might use code like this in
your on_valid_form subroutine:
if( param( 'New' ) ) {
# New pressed
}
elsif( param( 'Update' ) ) {
# Update pressed
}
# etc.
`-CHECK'
Optional boolean, default is true. When `show_form' is called it will
check (i.e. do validation) providing there are parameters (i.e. the
user has filled in the form) and if `-CHECK' is true. This option
would not normally be used. However if you have links which call your
form with some parameters (e.g. default values), you will want the
form to be displayed with the defaults but *without* any validation
taking place in the first instance. In this situation you would set
`-CHECK' to false. Thus we must cope with the following scenarios:
1. Form is called with no params - must display blank form and
validate when the user presses a button;
2. Form is called with params (e.g. by clicking a link we've
provided) - must display form with any defaults and not validate
until the user presses a button;
3. Form is called with params (as the result of the user pressing a
button) - validation must take place.
To achieve the above we need to add an extra field=value pair to
the URL we provide and if that is present then skip validation. The
field's name must not be one of the form's fields! e.g.
# If it is to be called from one of our own URLs with something like
# www.mysite.com/cgi-bin/myscript?colour=green&size=large
# then we must add in the extra field=value and write the preceeding link
# for example as:
# www.mysite.com/cgi-bin/myscript?QFCHK=0&colour=green&size=large
# We then use query_string() to set -CHECK to 0 and show the form with the
# defaults without validating - we'll validate when they press a button.
# If its been called as something like www.mysite.com/cgi-bin/myscript
# then set -CHECK to 1 which gives us standard behaviour:
# i.e. if there are params then show_form will validate; otherwise it will
# show the blank form.
show_form(
-CHECK => ( query_string() =~ /QFCHK=0/o ? 0 : 1 ),
# etc
) ;
# Or more verbosely:
my $Check = 1 ;
$Check = 0 if query_string() =~ /QFCHK=0/o ;
show_form(
-CHECK => $Check,
# etc
) ;
Note that QuickForm discards any query string if it reinvokes itself
because of invalid data. This is useful because it means you can use
the query string to distinguish between a 'first time' call and
subsequent calls as we do here with -CHECK. However if you want a
query string parameter to survive these calls we must extract them
and pass them ourselves, e.g. via a hidden field.
`-FOOTER'
Optional string. This is used to present any text following the form
and if used it must include everything up to and including final
"