CGI-MxScreen
view release on metacpan or search on metacpan
README The main README file
MANIFEST This shupping list
ChangeLog List of changes
Makefile.PL Builds Makefile
MxScreen.pm Manager object
MxScreen/Action_Env.pm Environment for action callbacks
MxScreen/Config.pm Dynamic configuration
MxScreen/Constant.pm Internal constants
MxScreen/Error.pm Action callback return codes
MxScreen/Exception.pm Ancestor for exception classes
MxScreen/Exception/Bounce.pm A screen bounce exception
MxScreen/Form/Button.pm A recorded button
MxScreen/Form/Field.pm A recorded fields
MxScreen/Form/Utils.pm Repository of field callbacks
MxScreen/HTML.pm Extra HTML generating subs
MxScreen/Layout.pm Hooks for layout control
MxScreen/Screen.pm Ancestor of all user-defined screens
MxScreen/Serializer.pm Ancestor of all serializers
MxScreen/Serializer/Storable.pm The Storable serializer
MxScreen/Session.pm Session management object
MxScreen/Session/Medium.pm Abstract session medium
MxScreen/Session/Medium/Browser.pm Session saved within browser
MxScreen/Session/Medium/File.pm Session saved to a file
MxScreen/Session/Medium/Raw_File.pm Session saved via raw Storable calls
MxScreen/Tie/Buffered_Output.pm Buffers STDOUT output until completion
MxScreen/Tie/Read_Checked.pm Checks key access to global hash
MxScreen/Tie/Sinkable.pm Ancestor to sinkable tied filehandles
MxScreen/Tie/Stdout.pm Discards STDOUT until display() time
t/action.t Tests -action callbacks
t/basic.t Tests basic processing
t/buffering.t Tests STDOUT buffering
t/cgi/action CGI for -action testing
t/cgi/basic CGI for basic testing
t/cgi/bounce CGI for state bounce testing
t/cgi/config CGI for configuration testing
t/cgi/config_nobuf CGI for config with no buffering
t/cgi/config_sup CGI for superseded configuration test
t/cgi/dyn_target CGI for -dyn_target testing
t/cgi/early_write CGI for testing STDOUT discards
MxScreen.pm view on Meta::CPAN
$layout->postamble;
$layout->end_HTML;
return DVOID;
}
#
# ->compute_screen
#
# Compute target screen, and run and enter/leave hooks if we change screens.
# This routine does not display anything, but runs all the action callbacks.
#
# Returns new screen object, and a ref to the argument list.
#
sub compute_screen {
DFEATURE my $f_;
my $self = shift;
my ($current_state, $previous_state, $new_state);
my ($origin_name, $target_name, @arg_list);
my $screen;
my $errors = 0;
MxScreen.pm view on Meta::CPAN
All error logging is done via C<Log::Agent>, and application logging is
done via C<Log::Agent::Logger>, which ensures the maximum flexibility.
Logfile rotation is also supported via C<Log::Agent::Rotate>.
Configuration of the various logging parameters is done via the
C<CGI::MxScreen::Config> interface.
=item *
C<CGI::MxScreen> uses C<Carp::Datum> internally. If you have chosen to
install a non-stripped version, you may trace parts of the module to better
understand what is going on with the various callbacks you register.
=back
=head2 Flow
Here is a high-level description of the processing flow when issuing requests
to a C<CGI::MxScreen> script:
=over 4
MxScreen.pm view on Meta::CPAN
the HTML header has already been generated, and that includes the title.
The act of creating the manager object raises some underlying processing:
the session context is retrieved, incoming parameters are processed and
silently validated.
86 $manager->play();
87
This finally launches the state machine: the next state is computed, action
callbacks are fired, and the target screen is displayed.
=head2 More Readings
To learn about the interface of the C<CGI::MxScreen> manager object,
see L<"INTERFACE"> below.
To learn about the screen interface, i.e. what you must implement when you
derive your own objects, what you can redefine, what you should not override
(the other features that you cannot redefine, so to speak), please
read L<CGI::MxScreen::Screen>.
MxScreen.pm view on Meta::CPAN
in L<CGI::MxScreen::Layout>.
Finally, the extra HTML-generating routines that are not implemented by
the C<CGI> module are presented in L<CGI::MxScreen::HMTL>.
=head1 SPECIFIC DATA TYPES
This sections documents in a central place the I<state> and I<callback>
representations that can be used throughout the C<CGI::MxScreen> framework.
Those specifications must be serializable, therefore all callbacks
are expressed in various symbolic forms, avoiding code references.
Do not forget that I<all> the arguments you specify in callbacks and screens
get serialized into the context. Therefore, you must make sure your
objects are indeed serializable by the serializer (which is C<Storable>
by default, well, actually C<CGI::MxScreen::Serializer::Storable>, which is
wrapping the C<Storable> interface to something C<CGI::MxScreen> understands).
See L<CGI::MxScreen::Config> to learn how to change the
serializer, and L<CGI::MxScreen::Serializer> for the interface it must
follow.
=head2 States
MxScreen.pm view on Meta::CPAN
The entry point that dispatches the state machine handling. Upon return,
the whole HTML has been generated and sent back to the browser.
=back
=head2 Utility Path
The concept of I<utility path> stems from the need to keep all callback
specification serializable. Since C<Storable> cannot handle CODE references,
C<CGI::MxScreen> uses function names. In some cases, we have a default
object to call the method on (e.g. during action callbacks), or one can
specify an object. In some other case, a plain name must be used, and you
must tell C<CGI::MxScreen> in which packages it should look to find that name.
This is analogous to the PATH search done by the shell. Unless you specify
an absolute path, the shell looks throughout your defined PATH directories,
stopping at the first match.
Here, we're looking through package namespaces. For instance, given the
name "is_num", we could check C<main::is_num>, then C<Your::Module::is_num>,
etc... That's what the utility path is.
The routine C<CGI::MxScreen::add_utils_path> must be used I<before> the
creation of the C<CGI::MxScreen> manager, and takes a list of strings,
which define the package namespaces to look through for field validation
callbacks and patching routines. The reason it must be done I<before>
is that incoming CGI parameters are currently processed during the
manager's creation routine.
=head1 LOGGING
During its operation, C<CGI::MxScreen> can emit application logs. The
amount emitted depends on the configuration, as described in
L<CGI::MxScreen::Config>.
Logs are emitted with the session number prefixed, for instance:
MxScreen/Action_Env.pm view on Meta::CPAN
my $env = pop @_; # the Action_Env error context
my @args = @_;
return CGI_MX_OK if $env->error_count;
...
return CGI_MX_OK;
}
=head1 DESCRIPTION
Instances of this class are used to record failed actions during the
processing of button callbacks. They are given as the I<last> parameter
of each action callback, and must therefore be retrieved with:
my $env = pop @_;
This object can be queried for the C<error_count> (to avoid any further
action processing if an error was detected, for instance), or for the
full C<error_list>, wich tracks a list of
[$object, $routine, [args]]
Those are the callbacks that were called and which returned an error condition
(see L<CGI::MxScreen::Error> for a list of allowed returned values).
This object is also passed as last argument to dynamic error trapping
callbacks, so that a proper screen destination can be derived from the errors,
if needed.
See L<CGI::MxScreen::Form::Button> for more information on action callback
and dynamic error trapping.
=head1 AUTHORS
The original authors are
Raphael Manfredi F<E<lt>Raphael_Manfredi@pobox.comE<gt>>
and
MxScreen/Error.pm view on Meta::CPAN
#
sub is_mx_errcode {
my ($err) = @_;
return exists $ERRORS{$err} ? 1 : 0;
}
1;
=head1 NAME
CGI::MxScreen::Error - Error return codes for action callbacks
=head1 SYNOPSIS
use CGI::MxScreen::Error;
sub action { # action callback
...
return CGI_MX_ABORT; # for instance
}
=head1 DESCRIPTION
This module exports the return codes to use in action callbacks:
=over 4
=item C<CGI_MX_OK>
Signals everything went fine.
=item C<CGI_MX_ABORT>
An error was detected, and the action callback chain should be immediately
exited. No further callbacks will be invoked.
=item C<CGI_MX_ERROR>
An error was detected, but further action callbacks may still execute.
The error condition is remembered and will be raised at the end of the
callback chain.
=back
=head1 AUTHORS
The original authors are
Raphael Manfredi F<E<lt>Raphael_Manfredi@pobox.comE<gt>>
and
MxScreen/Form/Button.pm view on Meta::CPAN
wish to perform validation of control fields, or any other processing
attached to the pressing of that button.
=head1 INTERFACE
=head2 Creation Arguments
Some of the arguments below expect I<callback> arguments.
The callback representation rules are documented in L<CGI::MxScreen/Callbacks>.
Some of the callbacks or arguments below are expected to yield I<states>.
See L<CGI::MxScreen/States> for state representation rules.
The following named arguments may be given to C<record_button()>.
Any other argument is simply recorded and will be propagated via
C<properties()>. Arguments are all optional but for C<-name>, and one
of C<-target> or C<-dyn_target> must be supplied:
=over 4
=item C<-action> => [I<callback1>, I<callback2>, ...]
The list of action callbacks that should be run when the button is pressed.
Those will be run before any state change, since failure of one of those
callbacks could mean we stay in the same state.
A trailing C<CGI::MxScreen::Action_Env> object is appended to the list
of callback arguments. It can be used to check whether any action callback
in the chain as already reported an error. In the last action callback
listed, this could be used to execute some processing only if we're about
to change state, i.e. when no error occured.
B<Note>: when using the second form of callback specification (i.e. an array
ref), double brackets must be used, since the list of callback actions must
itself be within brackets:
MxScreen/Form/Button.pm view on Meta::CPAN
$screen->callback($env); # $env is the Action_Env
$screen->$arg1($env);
which will usually not be what you intended.
Each callback must return a success/error status, as documented
in L<CGI::MxScreen::Error>.
=item C<-dyn_on_error> => I<callback>
When any of the C<-action> callbacks returns a non-OK status, an error flag
is raised. By default, the same screen will be re-displayed. When a
C<-dyn_on_error> callback is specified, the screen to display is computed
dynamically. You may not use this option in conjunction with C<-on_error>.
A trailing C<CGI::MxScreen::Action_Env> object is appended to the callback
argument list. This object records the failed action callbacks, in case
that could help determine the state to move to.
See L<CGI::MxScreen::Action_Env>.
The I<callback> is expected to return a new state specification: it can
be a single scalar (the state name), or an array ref (state name as
first item, remaining values being C<display()> parameters).
See L<CGI::MxScreen/States> for details.
=item C<-dyn_target> => I<callback>
MxScreen/Form/Button.pm view on Meta::CPAN
See L<CGI::MxScreen/States> for details.
=item C<-name> => I<name>
Madantory parameter, giving the name of the button. This is the CGI parameter
name. The displayed button will be labeled with I<name>, unless there is
also a C<-value> given.
=item C<-on_error> => I<target_state>
When any of the C<-action> callbacks returns a non-OK status, an error flag
is raised. By default, the same screen will be re-displayed. When an
C<-on_error> trap is specified, the screen to display is given by
I<target_state>. You cannot use C<-dyn_on_error> in conjunction with
this argument.
The I<target_state> can be a single scalar (the state name), or an
array ref (state name as first item, remaining values being C<display()>
parameters). See L<CGI::MxScreen/States>.
=item C<-target> => I<target_state>
MxScreen/Form/Field.pm view on Meta::CPAN
print popup_menu($menu->properties);
=head1 DESCRIPTION
This class models a recorded CGI control field. One does not manually create
objects from this class, they are created by C<CGI::MxScreen> when the
C<record_field()> routine is called on a screen object to declare a new
field.
In order to attach application-specific storage information and validating
or patching callbacks to a CGI field, it is necessary to declare them
within the screen they belong, usually before generating the HTML code
for those fields. The declaration routine takes a set of meaningful
arguments, and lets the others pass through verbatim (they are recorded
to be given back when C<properties()> is called).
You must at least supply the C<-name> argument. You will probably supply
C<-verify> as well if you wish to perform validation of control fields,
and C<-storage> to be able to store the value in some place, or perform
any other processing on it.
MxScreen/Screen.pm view on Meta::CPAN
DREQUIRE $self->manager == $manager;
$self->_init;
return DVAL $self;
}
#
# ->relink_to_manager
#
# Partial initialization routine which links _manager and _context
# to the new manager. This allows callbacks referring to a screen to
# still use $screen->vars for instance and get something useful.
#
# This routine is systematically called on all the screens present in
# the context.
#
sub relink_to_manager {
DFEATURE my $f_;
my $self = shift;
my ($manager) = @_;
MxScreen/Screen.pm view on Meta::CPAN
#
# That method is a good candidate to be put in a list of actions
# associated to a button.
#
# If a state is given, the context of that state is deleted instead of the
# one for the current screen.
#
sub clear_context {
DFEATURE my $f_;
my $self = shift;
pop @_; # any action callbacks receive an extra parameter
my ($state) = @_;
VERIFY implies(defined $state, $self->manager->is_valid_state($state)),
"valid state '$state'";
$state = $self->name unless defined $state;
my $cgi_ctxt = $self->manager->context(CGI_PARAM);
return DVAL CGI_MX_OK unless defined (my $ctxt = $cgi_ctxt->{$state});
MxScreen/Screen.pm view on Meta::CPAN
the same name as one present in the ancestors (i.e. redefinition is automatic,
which is dangerous here). And redefining routines as essential as
C<validate()> or C<name()> would lead to havoc.
=head2 Listing
Before detailing the interface, here is a compact list of all the public
features, to make it easier to see what is provided (and know which routine
names are forbidden to you... A trailing + indicates a routine that you
may choose to redefine, a trailing * indicates a deferred routine, which you
must define. Functions listed between (parenthesis) are action callbacks,
not meant to be called directly.
The following interface is public, i.e. you may safely use those features
on screen objects:
(abort_on_error)
bgcolor
bounce
(clear_context)
current_screen
MxScreen/Screen.pm view on Meta::CPAN
a form, without pressing one of the submit buttons. Usually, browsers allow
this when there is only one CGI input field in the form.
If there is no default button specified, C<CGI::MxScreen> will remain in
the current state and redisplay the screen.
=item C<error>
The error information, recorded vi C<set_error>. This is a user-defined
field, i.e. it is not used by C<CGI::MxScreen>. It is meant to be filled
by action callbacks, when an error is detected. Since it will be used by
your own screens, you may put whatever you wish.
=item C<error_env>
When an action callback failed, this attribute holds the
C<CGI::MxScreen::Action_Env> object used during the execution of the callback
chain. See L<CGI::MxScreen::Action_Env> for its access interface.
The attribute is otherwise C<undef>, so you may test it boolean-wise to
determine whether an error did occur or not.
MxScreen/Screen.pm view on Meta::CPAN
L<CGI::MxScreen::Layout>.
A screen is given the opportunity to redirect itself to another state, by
sending a bounce execption to the manager via C<bounce()>. However, it may
do so only if it has not already emitted anything. If you left
C<$mx_buffer_stdout> to its default I<true> setting
(see L<CGI::MxScreen::Config>), anything you output before bouncing will be
discarded for you.
Usually, your screens will define fields and submit buttons. You should
record them to be able to attach validation routines or action callbacks,
but you may choose not to and use plain raw C<CGI> routines, with manual
hidden context propagation. However, note that it would be a waste, because
C<CGI::MxScreen> is supposed to handle that for you, and also the only
C<display()> routine called is the one for the visible screen. Any other
parameters defined on other screens would not even have the opportunity to
hide themselves... As for buttons, not recording them means you won't be
able to make use of the state machine features.
To record fields and buttons, use C<record_field()> and C<record_button()>.
MxScreen/Screen.pm view on Meta::CPAN
Records a control field, and returns a C<CGI::MxScreen::Form::Field> object.
Please see L<CGI::MxScreen::Form::Field> for the interface, and the
description of what I<args> can be.
=back
=head2 Action Callbacks
Those features are not meant to be used directly, but are provided so that
they can be used as action callbacks attached to buttons, as described in
L<CGI::MxScreen::Form::Button>.
The most important one is C<'validate'> (spelled as a string because this
is how it should be used: see L<CGI::MxScreen/"Callbacks">), which will
trigger all the field verfication and patching callbacks.
=over 4
=item C<abort_on_error>
This callback returns C<CGI_MX_ABORT> to immediately abort the callback
chain if there is an error already in one of the preceding callbacks.
See L<CGI::MxScreen::Error>.
=item C<clear_context> [I<screen_name>]
Clears a specific section of the overal context where I<orphan> CGI parameters
are saved. A CGI parameter is B<orphan> if there was no C<record_field()>
done for it.
If I<screen_name> is not specified, this applies to the current screen.
This callback is useful if you wish to discard the state of orphan CGI
parameters, so that the next time they are created, they get their default
value.
=item C<validate> [I<continue>]
Runs the validation and patching callbacks on all the recorded fields for
this screen. If I<continue> is I<true>, any error will not be fatal
immediately, i.e. C<CGI_MX_ERROR> will be returned, so that other action
callbacks may execute. If not specified, it defaults to I<false>, meaning
a failed validation immediately triggers the error and the end of the
action callback sequence.
=back
Here is an example of action callback settings for a submit button:
my $ok = $self->record_button(
-name => "OK",
-target => "Next",
CGI::MxScreen::Config manpage for details.
* All error logging is done via `Log::Agent', and application logging is
done via `Log::Agent::Logger', which ensures the maximum
flexibility. Logfile rotation is also supported via
`Log::Agent::Rotate'. Configuration of the various logging
parameters is done via the `CGI::MxScreen::Config' interface.
* `CGI::MxScreen' uses `Carp::Datum' internally. If you have chosen to
install a non-stripped version, you may trace parts of the module to
better understand what is going on with the various callbacks you
register.
Here is a high-level description of the processing flow when issuing
requests to a `CGI::MxScreen' script:
* An initial log tracing the user (if HTTP authentication is used), the
time since the session started, the elapsed time since the previous
display, and the CGI query string is emitted.
* The session context is retrieved if any, otherwise a new one is created.
( run in 4.226 seconds using v1.01-cache-2.11-cpan-9b1e4054eb1 )