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";
<FORM METHOD="POST" ENCTYPE="application/x-www-form-urlencoded">
<WEAK>I am form: hear me submit.</WEAK><INPUT TYPE="submit" NAME=".submit"></FORM>
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'. Because of the semantics of
CGI's own `new' method, this form of new is mostly useful in CGI
scripts, as it will attempt to read from `STDIN'. To prevent this
behavior, call the next form of `new' with an empty string, thus:
my $cgi = CGI::PrintWrapper->new ($some_handle, '');
`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
the CGI manpage, the IO::Scalar manpage, the HTML::Stream manpage, the
print entry in the perlfunc manpage
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 <binkley@bigfoot.com>. I am grateful to my
employer, DataCraft, Inc., for time spent preparing this package for
public consumption.
COPYRIGHT
$Id: README,v 1.8 2000/01/07 16:43:55 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.