view release on metacpan or  search on metacpan

lib/CGI/PrintWrapper.pm  view on Meta::CPAN

  # calls from other instances don't reuse a previous handle (correct
  # scoping):
  *{$CGI::PrintWrapper::AUTOLOAD} = sub {
    my $self = shift;
    my $cgi_sub = "CGI::$sub";

    $self->[0]->print ($self->[1]->$cgi_sub (@_));

    return $self;
  };

  goto &$CGI::PrintWrapper::AUTOLOAD;
}

1;


__END__


=head1 NAME

CGI::PrintWrapper - CGI methods output to a print handle

=head1 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>

=head1 DESCRIPTION

B<CGI::PrintWrapper> arranges for CGI methods to output their results
by printing onto an arbitrary handle.  This gets around the problem
that the B<CGI>'s subs return strings, which may be inconvient when
you wish to use B<CGI> for something besides CGI script processing.

You could just call C<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 B<CGI> with B<HTML::Stream>, the
problem which prompted my solution, illustrated above).

B<CGI::PrintWrapper> creates the necessary callbacks for printing
dynamically, updating the symbol table as it encounters a new B<CGI>
method.

=head1 CONSTRUCTOR

=over

=item C<new ($h)>

Creates a new B<CGI::PrintWrapper>, printing the results of B<CGI>
methods onto the print handle object, C<$h>.

=item C<new ($h, @cgi_args)>

Creates a new B<CGI::PrintWrapper>, printing the results of B<CGI>
methods onto the print handle object, C<$h>, and using the additional
arguments to construct the B<CGI> object.

=back

=head1 METHODS

=over

=item C<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
C<param()>.

=item C<io ( )>

Returns the underlying print handle object.

=item C<AUTOLOAD>

Initially, B<CGI::PrintWrapper> has no methods (except as mentioned
above).  As the caller invokes B<CGI> methods, C<AUTOLOAD> creates
anonymous subroutines to perform the actual B<CGI> method call
indirection and print the results with the print handle object.  It
also updates the symbol table for B<CGI::PrintWrapper> so that future
calls can bypass C<AUTOLOAD>.  This makes a B<CGI::PrintWrapper>
object transparently a B<CGI> object, usable as a drop-in replacement.

=back

=head1 SEE ALSO

L<CGI>, L<IO::Scalar>, L<HTML::Stream>, L<perlfunc/print>

B<CGI> is the canonical package for working with fill-out forms on the
web.  It is particularly useful for generating HTML for such forms.

B<IO::Scalar> is a handy package for treating a string as an object
supporting IO handle semantics.

B<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.