NAME
   CGI::Screen - Perl extension for easy creation of multi screen
   CGI-scripts

SYNOPSIS
     use CGI::Screen;
     use vars qw(@ISA);
     @ISA = qw(CGI::Screen);

     my $query = __PACKAGE__->new;

     $query->dispatch;

WARNING
   This is *alpha* software. User visible changes can happen any
   time.

DESCRIPTION
   *CGI::Screen* is a subclass of `CGI' which allows the esay(TM)
   creation of simple multi screen CGI-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.

   To use *CGI::Screen*, you have to subclass it. For each screen
   you want to present to the user, you must create a method
   `screen_'_screen_name_. This method has to produce the HTML code
   for the screen. CGI::Screen does generate HTTP headers and an
   HTML framework for you. The HTML-framework already contains the
   `FORM' tags. You can customize the HTTP headers HTML framework
   by providing callback methods.

   CGI::Screen keeps track of the CGI parameters used in your
   screen and passes old parameters which are not used in the
   current screen.

   It highjacks the parameters `screen_'* to dispatch the different
   screens the script implements. The `screen_user' and
   `screen_passwd' fields are used if you enable the builtin simple
   authentication. In general you should advice your HTTP 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 yours servers configuration.

 The constructor `new'

   If the first parameter of `new' is the string `-screen' the
   second argument must be a hash reference specifying the options
   for the subclass. Other parameters are passed to the constructor
   of `CGI'.

   `-dont_cut_loops'
       Normaly the history of pages will not extended if the
       current page is the same as the last page. So looping on a
       page will not change the result of the `last_screen' method.
       If the option `-dont_cut_loops' is provided and true, the
       page will recorded twice. A third visit will be interpreted
       as jump back to the first visit.

       _That sounds weird. Will have to figure out a way to
       recognize back jumps independent of the history._

 Adding Screens

   All applications should provide a *main* screen by defining a
   method `main_screen'. 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 cause the jump to this
   page).

   So the minimal application looks like this:

     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('This is the Main Screen');
     }

   That is not too exiting. Let us add a second screen and allow
   navigation between the screens:

     sub main_screen {
       my $query = shift;

       print
         $query->p('This is the Main Screen'),
         $query->goto_screen('second', 'Another Screen');
     }
     sub second_screen {
       my $query = shift;

       print
         $query->p('This is the Other Screen'),
         $query->goto_screen('main', 'Back to Main Screen');

     }

 Moving between screens

   Use the method `goto_screen' to produce a button for switching
   to another screen. You can also produce an anchor instead of a
   button by calling `link_to_screen' instead of `goto_screen'. You
   may pass additional parameters to encode:

       for my $docid (keys %score) {
         print $query->link_to_screen('display', $title{$docid},
                                      'docid' => $docid,
                                      'score' => $score{$docid});
       }

   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:

     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");

   `last_screen' returns screen name and title in list context and
   screen name in scalar context. Do not use the CGI parameters
   `screen_last_*' since they are changed before you can get hold
   of them `;-P'

 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.

   `application'
   The `application' method returns a string which is used in the
   default `title' and `headline' callbacks. The Default method
   returns the string `"CGI::Screen Test"' and should definitely be
   overwritten by your application.

   `title'
   The result of the method is used in the HTTP header and in the
   default headline. It defaults to the _application_.

   `headline'
   The `headline' method should return a chunk of HTML code to
   start the Screen. It defaults to the _title_ enclosed in `H1'
   tags.

 Authentication

   To enable password authentication, define a method
   `check_auth_user'. 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 `login_screen' if the authentication
   failed.

     sub check_auth_user {
       my ($query, $user, $passwd) = @_;

       $user eq 'pfeifer';
     }

   For IP address based authentication define the method
   `check_auth_ip'.

     sub check_auth_ip {
       my ($query, $ipaddr) = @_;

      $ipaddr =~ /^(193\.96\.65\.|139\.4\.36\.)/;
     }

   If you do not like the default login screen, overwrite with your
   own `login_screen'. Use the CGI parameters `screen_user' and
   `screen_passwd'.

 Customizing the Title

   You may provide a custom `title' method to generate a title for
   your screens.

     sub title {
       my ($query, $screen)  = shift;

       $query->application . ': ' . $screen;
     }

 Customizing the Headline

   You may provide a custom `headline' method to generate a HTML
   chunk to start your screens.

     sub headline { $_[0]->h1(title(@_)) }

   You should overwrite the `application' method if you use the
   default title and headline.

     sub application { 'CGI::Screen Test' }

 Customizing the Trailer

   For a custom Trailer, define the `trailer' method.

     sub trailer {
       my ($query, $screen)  = shift;

       "End of Screen $screen";
     }

 Multiple Forms

   If you want to have multiple forms on one screen, call the
   method `new_form'.

     sub multi_screen {
        my $query = shift;

        print
          $query->p('This is the Main Screen'),
          $query->textfield('foo'),
          $query->goto('First'),
          $query->new_form,
          $query->textfield('foo'),
          $query->goto('Second');
     }

 Non HTML screens

   You can create non HTML screens by defining a _name_`_data'
   method instead of a <name>`_screen' method. For `data' screens
   you have to generate HTTP headers yourself.

     sub gif_data {
       my $query = shift;

       print $query->header(
                            -type    => 'image/gif',
                            -status  => '200 OK',
                            -expires => '+120s',
                           );
       my $font  = $query->param('font');
       my $w     = GD::Font->$font()->width;
       my $h     = GD::Font->$font()->height;
       my $im    = GD::Image->new((length($query->param('foo'))+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('foo'),$black);
       print $im->gif;
     }

 Keeping parameter values

   CGI::Screen keeps track of the CGI parameters used in the
   current form. It simply looks at the first parameter in any call
   to a CGI method. If the first parameter is `-name', the second
   parameter is marked as _used parameter_. 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 CGI calls to
   bypass this mechanism or you will end up with multiple values
   for the parameters.

   If you want to get rid of a parameter, you must explicitly call
   the `delete' method of CGI.

BUGS
   Support for importing from CGI.pm is incomplete.

AUTHOR
   Ulrich Pfeifer <[email protected]>

SEE ALSO
   The CGI(3) manual and the demo CGI script eg/screen included in
   the distribution.

ACKNOWLEDGEMENTS
   I wish to thank Andreas Koenig [email protected] for the
   fruitfully discussion about the design of this module.

Copyright
   The *CGI::Screen* module is Copyright (c) 1997,1998 Ulrich
   Pfeifer. Germany. All rights reserved.

   You may distribute under the terms of either the GNU General
   Public License or the Artistic License, as specified in the Perl
   README file.

You are viewing proxied material from ftp.icm.edu.pl. The copyright of proxied material belongs to its original authors. Any comments or complaints in relation to proxied material should be directed to the original authors of the content concerned. Please see the disclaimer for more details.