| Current File : //home/strato/chroot/opt/RZperl536/man/man3/CGI::Screen.3 |
.\" Automatically generated by Pod::Man 4.14 (Pod::Simple 3.43)
.\"
.\" Standard preamble:
.\" ========================================================================
.de Sp \" Vertical space (when we can't use .PP)
.if t .sp .5v
.if n .sp
..
.de Vb \" Begin verbatim text
.ft CW
.nf
.ne \\$1
..
.de Ve \" End verbatim text
.ft R
.fi
..
.\" Set up some character translations and predefined strings. \*(-- will
.\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left
.\" double quote, and \*(R" will give a right double quote. \*(C+ will
.\" give a nicer C++. Capital omega is used to do unbreakable dashes and
.\" therefore won't be available. \*(C` and \*(C' expand to `' in nroff,
.\" nothing in troff, for use with C<>.
.tr \(*W-
.ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p'
.ie n \{\
. ds -- \(*W-
. ds PI pi
. if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch
. if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\" diablo 12 pitch
. ds L" ""
. ds R" ""
. ds C` ""
. ds C' ""
'br\}
.el\{\
. ds -- \|\(em\|
. ds PI \(*p
. ds L" ``
. ds R" ''
. ds C`
. ds C'
'br\}
.\"
.\" Escape single quotes in literal strings from groff's Unicode transform.
.ie \n(.g .ds Aq \(aq
.el .ds Aq '
.\"
.\" If the F register is >0, we'll generate index entries on stderr for
.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index
.\" entries marked with X<> in POD. Of course, you'll have to process the
.\" output yourself in some meaningful fashion.
.\"
.\" Avoid warning from groff about undefined register 'F'.
.de IX
..
.nr rF 0
.if \n(.g .if rF .nr rF 1
.if (\n(rF:(\n(.g==0)) \{\
. if \nF \{\
. de IX
. tm Index:\\$1\t\\n%\t"\\$2"
..
. if !\nF==2 \{\
. nr % 0
. nr F 2
. \}
. \}
.\}
.rr rF
.\" ========================================================================
.\"
.IX Title "CGI::Screen 3"
.TH CGI::Screen 3 "1999-02-05" "perl v5.36.1" "User Contributed Perl Documentation"
.\" For nroff, turn off justification. Always turn off hyphenation; it makes
.\" way too many mistakes in technical documents.
.if n .ad l
.nh
.SH "NAME"
CGI::Screen \- Perl extension for easy creation of multi screen CGI scripts
.SH "SYNOPSIS"
.IX Header "SYNOPSIS"
.Vb 3
\& use CGI::Screen;
\& use vars qw(@ISA);
\& @ISA = qw(CGI::Screen);
\&
\& my $query = _\|_PACKAGE_\|_\->new;
\&
\& $query\->dispatch;
.Ve
.SH "WARNING"
.IX Header "WARNING"
This is \fBalpha\fR software. User visible changes can happen any time.
.SH "DESCRIPTION"
.IX Header "DESCRIPTION"
\&\fBCGI::Screen\fR is a subclass of \f(CW\*(C`CGI\*(C'\fR which allows the esay(\s-1TM\s0)
creation of simple multi screen \s-1CGI\s0 scripts. By 'multi screen' I mean
scripts which present different screens to the user when called with
different parameters. This is the common case for scripts linking to
themselves.
.PP
To use \fBCGI::Screen\fR, you have to subclass it. For each screen you
want to present to the user, you must create a method
\&\fIscreen_name\fR\f(CW\*(C`screen_\*(C'\fR. This method has to produce the \s-1HTML\s0 code for
the screen. CGI::Screen does generate \s-1HTTP\s0 headers and an \s-1HTML\s0
framework for you. The \s-1HTML\s0 framework already contains the \f(CW\*(C`FORM\*(C'\fR
tags. You can customize the \s-1HTTP\s0 headers and the \s-1HTML\s0 framework by
providing callback methods.
.PP
CGI::Screen keeps track of the \s-1CGI\s0 parameters used in your screen and
passes old parameters which are not used in the current screen.
.PP
It highjacks the parameters \f(CW\*(C`screen_\*(C'\fR* to dispatch the different
screens the script implements. The \f(CW\*(C`screen_user\*(C'\fR and \f(CW\*(C`screen_passwd\*(C'\fR
fields are used if you enable the builtin simple authentication. In
general you should advice your \s-1HTTP\s0 server to do authentication. But
sometimes it is convenient to check the authentication at the script
level. Especially if you do not have access to your server's
configuration.
.ie n .SS "The constructor ""new"""
.el .SS "The constructor \f(CWnew\fP"
.IX Subsection "The constructor new"
If the first parameter of \f(CW\*(C`new\*(C'\fR is the string \f(CW\*(C`\-screen\*(C'\fR the second
argument must be a hash reference specifying the options for the
subclass. Other parameters are passed to the constructor of \f(CW\*(C`CGI\*(C'\fR.
.ie n .IP """\-dont_cut_loops""" 4
.el .IP "\f(CW\-dont_cut_loops\fR" 4
.IX Item "-dont_cut_loops"
Normaly the history of pages will not be extended if the current page is
the same as the last page. So looping on a page will not change the
result of the \f(CW\*(C`last_screen\*(C'\fR method. If the option \f(CW\*(C`\-dont_cut_loops\*(C'\fR
is provided and true, the page will recorded twice. A third visit will
be interpreted as jump back to the first visit.
.Sp
\&\fIThat sounds weird. Will have to figure out a way to recognize back
jumps independent of the history.\fR
.SS "Adding Screens"
.IX Subsection "Adding Screens"
All applications should provide a \fBmain\fR screen by defining a method
\&\f(CW\*(C`main_screen\*(C'\fR. This method is called if no (existing) screen is
specified in the parameters. The method is called with three
arguments: The query object, the screen name and the screen title
(More precisely the third parameter, if present, is the text on the
button or anchor which caused the jump to this page).
.PP
So the minimal application looks like this:
.PP
.Vb 3
\& use CGI::Screen;
\& use vars qw(@ISA);
\& @ISA = qw(CGI::Screen);
\&
\& my $query = _\|_PACKAGE_\|_\->new;
\&
\& $query\->dispatch;
\&
\& sub main_screen {
\& my $query = shift;
\&
\& print $query\->p(\*(AqThis is the Main Screen\*(Aq);
\& }
.Ve
.PP
That is not too exciting. Let us add a second screen and allow
navigation between the screens:
.PP
.Vb 2
\& sub main_screen {
\& my $query = shift;
\&
\& print
\& $query\->p(\*(AqThis is the Main Screen\*(Aq),
\& $query\->goto_screen(\*(Aqsecond\*(Aq, \*(AqAnother Screen\*(Aq);
\& }
\& sub second_screen {
\& my $query = shift;
\&
\& print
\& $query\->p(\*(AqThis is the Other Screen\*(Aq),
\& $query\->goto_screen(\*(Aqmain\*(Aq, \*(AqBack to Main Screen\*(Aq);
\&
\& }
.Ve
.SS "Moving between screens"
.IX Subsection "Moving between screens"
Use the method \f(CW\*(C`goto_screen\*(C'\fR to produce a button for switching to
another screen. You can also produce an anchor instead of a button by
calling \f(CW\*(C`link_to_screen\*(C'\fR instead of \f(CW\*(C`goto_screen\*(C'\fR. You may pass
additional parameters to encode:
.PP
.Vb 5
\& for my $docid (keys %score) {
\& print $query\->link_to_screen(\*(Aqdisplay\*(Aq, $title{$docid},
\& \*(Aqdocid\*(Aq => $docid,
\& \*(Aqscore\*(Aq => $score{$docid});
\& }
.Ve
.PP
For convenience, CGI::Screen keeps track of the last screen for you so
that you can link to the previous page. Note that only the last seven
screens are saved:
.PP
.Vb 5
\& my $screen = $query\->last_screen;
\& print
\& $query\->p("You came from screen $screen. Press "),
\& $query\->goto_screen($query\->last_screen),
\& $query\->p(" to go back");
.Ve
.PP
\&\f(CW\*(C`last_screen\*(C'\fR returns screen name and title in list context and
screen name in scalar context. Do not use the \s-1CGI\s0 parameters
\&\f(CW\*(C`screen_last_*\*(C'\fR since they are changed before you can get hold of
them \f(CW\*(C`;\-P\*(C'\fR
.SS "The callbacks"
.IX Subsection "The callbacks"
All callbacks are called with three arguments: The query object, the
screen name and the screen title (= button/anchor text). Callbacks
should return a string.
.ie n .IP """application""" 4
.el .IP "\f(CWapplication\fR" 4
.IX Item "application"
The \f(CW\*(C`application\*(C'\fR method returns a string which is used
in the default \f(CW\*(C`title\*(C'\fR and \f(CW\*(C`headline\*(C'\fR callbacks. The Default method
returns the string \f(CW"CGI::Screen Test"\fR and should definitely be
overwritten by your application.
.ie n .IP """title""" 4
.el .IP "\f(CWtitle\fR" 4
.IX Item "title"
The result of the method is used in the \s-1HTTP\s0 header and in the default
headline. It defaults to the \fIapplication\fR.
.ie n .IP """headline""" 4
.el .IP "\f(CWheadline\fR" 4
.IX Item "headline"
The \f(CW\*(C`headline\*(C'\fR method should return a chunk of \s-1HTML\s0 code to start the
Screen. It defaults to the \fItitle\fR enclosed in \f(CW\*(C`H1\*(C'\fR tags.
.SS "Authentication"
.IX Subsection "Authentication"
To enable password authentication, define a method
\&\f(CW\*(C`check_auth_user\*(C'\fR. The dispatcher will call the method with the user
and password entered by the user. The method should return true if the
authentication succeeded and false otherwise. The dispatcher will
present the \f(CW\*(C`login_screen\*(C'\fR if the authentication failed.
.PP
.Vb 2
\& sub check_auth_user {
\& my ($query, $user, $passwd) = @_;
\&
\& $user eq \*(Aqpfeifer\*(Aq;
\& }
.Ve
.PP
For \s-1IP\s0 address based authentication define the method
\&\f(CW\*(C`check_auth_ip\*(C'\fR.
.PP
.Vb 2
\& sub check_auth_ip {
\& my ($query, $ipaddr) = @_;
\&
\& $ipaddr =~ /^(193\e.96\e.65\e.|139\e.4\e.36\e.)/;
\& }
.Ve
.PP
If you do not like the default login screen, overwrite with your own
\&\f(CW\*(C`login_screen\*(C'\fR. Use the \s-1CGI\s0 parameters \f(CW\*(C`screen_user\*(C'\fR and
\&\f(CW\*(C`screen_passwd\*(C'\fR.
.SS "Customizing the Title"
.IX Subsection "Customizing the Title"
You may provide a custom \f(CW\*(C`title\*(C'\fR method to generate a title for your
screens.
.PP
.Vb 2
\& sub title {
\& my ($query, $screen) = shift;
\&
\& $query\->application . \*(Aq: \*(Aq . $screen;
\& }
.Ve
.SS "Customizing the Headline"
.IX Subsection "Customizing the Headline"
You may provide a custom \f(CW\*(C`headline\*(C'\fR method to generate a \s-1HTML\s0 chunk
to start your screens.
.PP
.Vb 1
\& sub headline { $_[0]\->h1(title(@_)) }
.Ve
.PP
You should overwrite the \f(CW\*(C`application\*(C'\fR method if you use the default
title and headline.
.PP
.Vb 1
\& sub application { \*(AqCGI::Screen Test\*(Aq }
.Ve
.SS "Customizing the Trailer"
.IX Subsection "Customizing the Trailer"
For a custom Trailer, define the \f(CW\*(C`trailer\*(C'\fR method.
.PP
.Vb 2
\& sub trailer {
\& my ($query, $screen) = shift;
\&
\& "End of Screen $screen";
\& }
.Ve
.SS "Multiple Forms"
.IX Subsection "Multiple Forms"
If you want to have multiple forms on one screen, call the method
\&\f(CW\*(C`new_form\*(C'\fR.
.PP
.Vb 2
\& sub multi_screen {
\& my $query = shift;
\&
\& print
\& $query\->p(\*(AqThis is the Main Screen\*(Aq),
\& $query\->textfield(\*(Aqfoo\*(Aq),
\& $query\->goto(\*(AqFirst\*(Aq),
\& $query\->new_form,
\& $query\->textfield(\*(Aqfoo\*(Aq),
\& $query\->goto(\*(AqSecond\*(Aq);
\& }
.Ve
.SS "Non \s-1HTML\s0 screens"
.IX Subsection "Non HTML screens"
You can create non \s-1HTML\s0 screens by defining a \fIname\fR\f(CW\*(C`_data\*(C'\fR method
instead of a <name>\f(CW\*(C`_screen\*(C'\fR method. For \f(CW\*(C`data\*(C'\fR screens you have
to generate \s-1HTTP\s0 headers yourself.
.PP
.Vb 2
\& sub gif_data {
\& my $query = shift;
\&
\& print $query\->header(
\& \-type => \*(Aqimage/gif\*(Aq,
\& \-status => \*(Aq200 OK\*(Aq,
\& \-expires => \*(Aq+120s\*(Aq,
\& );
\& my $font = $query\->param(\*(Aqfont\*(Aq);
\& my $w = GD::Font\->$font()\->width;
\& my $h = GD::Font\->$font()\->height;
\& my $im = GD::Image\->new((length($query\->param(\*(Aqfoo\*(Aq))+2)*$w,$h);
\& my $white = $im\->colorAllocate(255,255,255);
\& my $red = $im\->colorAllocate(255,0,0);
\& my $black = $im\->colorAllocate(0,0,0);
\& $im\->transparent($white);
\& $im\->arc(8,8,5,5,0,360,$red);
\& $im\->string(GD::Font\->$font(),10,0,$query\->param(\*(Aqfoo\*(Aq),$black);
\& print $im\->gif;
\& }
.Ve
.SS "Keeping parameter values"
.IX Subsection "Keeping parameter values"
CGI::Screen keeps track of the \s-1CGI\s0 parameters used in the current
form. It simply looks at the first parameter in any call to a \s-1CGI\s0
method. If the first parameter is \f(CW\*(C`\-name\*(C'\fR, the second parameter is
marked as \fIused parameter\fR. CGI::Screen passed all current parameter
values not used in hidden fields or in the query string of an
anchor. So do not use old style \s-1CGI\s0 calls to bypass this mechanism or
you will end up with multiple values for the parameters.
.PP
If you want to get rid of a parameter, you must explicitly call the
\&\f(CW\*(C`delete\*(C'\fR method of \s-1CGI.\s0
.SH "BUGS"
.IX Header "BUGS"
Support for importing from \s-1CGI\s0.pm is incomplete.
.SH "AUTHOR"
.IX Header "AUTHOR"
Ulrich Pfeifer <\fIpfeifer@wait.de\fR>
.SH "SEE ALSO"
.IX Header "SEE ALSO"
The \s-1\fBCGI\s0\fR\|(3) manual and the demo \s-1CGI\s0 script \fIeg/screen\fR included in the
distribution.
.SH "ACKNOWLEDGEMENTS"
.IX Header "ACKNOWLEDGEMENTS"
I wish to thank Andreas Koenig \fIkoenig@kulturbox.de\fR for the
fruitful discussion about the design of this module.
.SH "Copyright"
.IX Header "Copyright"
The \fBCGI::Screen\fR module is Copyright (c) 1997,1998 Ulrich
Pfeifer. Germany. All rights reserved.
.PP
You may distribute under the terms of either the \s-1GNU\s0 General Public
License or the Artistic License, as specified in the Perl \s-1README\s0 file.
.SH "POD ERRORS"
.IX Header "POD ERRORS"
Hey! \fBThe above document had some coding errors, which are explained below:\fR
.IP "Around line 499:" 4
.IX Item "Around line 499:"
\&'=item' outside of any '=over'
.IP "Around line 516:" 4
.IX Item "Around line 516:"
You forgot a '=back' before '=head2'