NAME

CGI::MxScreen::Layout - ancestor for layout objects

SYNOPSIS

 use base qw(CGI::MxScreen::Layout);

 sub init {                  # redefine initialization
     my $self = shift;
     my ($screen) = @_;
     ...
 }

 sub preamble {              # redefine pre-amble
     my $self = shift;
     ...
 }

 sub postamble {             # redefine post-amble
     my $self = shift;
     ...
 }

DESCRIPTION

This class is meant to be the ancestor of all the layout objects that can be given to the CGI::MxScreen manager via the -layout argument.

In order to define your own layout, you must create a class inheriting from CGI::MxScreen::Layout and redefine the init(), preamble() and postamble() features, which do nothing by default.

Because this kind in inheritance is a specialization of some behaviour, you need to understand the various operations that get carried on, so that you may plug your layout properly.

It works as follows:

• The init() routine is called for each screen we are about to display. It is given one argument, the screen object. That object may be undef if we're displaying an internal error. See "INTERFACE" in CGI::MxScreen::Screen to know what can be done with a screen object.

  The display() routine of a screen may request bouncing to some other state, in which case init() will be called again with another screen object. Therefore, you must not assume that init() will be called only once.

• The start_HTML() routine is called with the following arguments:

      -title      => $screen->screen_title,
      -bgcolor    => $screen->bgcolor,

  when there is a screen object, or with simply a title for internal errors. The default start_HTML() routine does this:

      print CGI::header(-nph => 0);
      print CGI::start_html(@_);

  but you may choose to optionally redefine it.

• Immediately after, preamble() is called. It does nothing by default, but this is a feature you're likely to redefine.

  Since it is an object feature, it has access to everything you decided to initialize in init(), based on the screen or other internal variables.

  If your preamble() routine opens an HTML container tag, you must make sure it is able to contain everything that can be generated during display().

• Unless we're generating an internal error, the CGI form is started. Then $screen->display(...) is called. This is where the regular output is generated.
• Upon return from display(), the CGI form is closed, then postamble() is called.

  This is the opportunity to close any tag opened in preamble(), or to emit a common trailer to all your script outputs.

• Finally, the end_HTML() routine is called. It does

      print CGI::end_html;

  in case you would like to redefine that. Don't make the mistake to redefine end_HTML() simply to add a postamble before closing the HTML tags. You must use postamble() for that.

  You could conceivably need to redefine end_HTML() when you redefined start_HTML(), but then again, it's a possibility, not a certitude.

AUTHOR

Raphael Manfredi <Raphael_Manfredi@pobox.com>

SEE ALSO

CGI::MxScreen(3), CGI::MxScreen::Screen(3).