• NAME
• SYNOPSIS
• WARNING
• DESCRIPTION
  • The constructor new
  • Adding Screens
  • Moving between screens
  • The callbacks
  • Authentication
  • Customizing the Title
  • Customizing the Headline
  • Customizing the Trailer
  • Multiple Forms
  • Non HTML screens
  • Keeping parameter values
• AUTHOR
• SEE ALSO
• ACKNOWLEDGEMENTS
• Copyright

NAME

SYNOPSIS

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

  my $query = __PACKAGE__->new;

  $query->dispatch;

WARNING

DESCRIPTION

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_*, user and passwd to dispatch the different screens the script implements. The user and passwd fields are used if you use 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

Adding Screens

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

  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.

The callbacks

application

The application 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 user and 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.

AUTHOR

Ulrich Pfeifer <pfeifer@wait.de>

SEE ALSO

The CGI(3) manual and the demo CGI script screen included in the distribution.

ACKNOWLEDGEMENTS

I wish to thank Andreas Koenig koenig@kulturbox.de for the fruitfully discussion about the design of this module.

Copyright

The CGI::Screen module is Copyright (c) 1997 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.