CGI::MxScreen::Form::Button - A recorded button
# $self is a CGI::MxScreen::Screen use CGI qw/:standard/; my $ok = $self->record_button( -name => "ok", -value => "OK to Continue", -action => ['validate', [$obj, 'do_something', @args]], -target => "next_screen", -on_error => "error_screen", ); print submit($ok->properties);
This class models a recorded button. One does not manually create objects from this class, they are created by CGI::MxScreen when the record_button() routine is called on a screen object to declare a new button.
CGI::MxScreen
record_button()
In order to use the state machine features from CGI::MxScreen, it is necessary to declare all the submit buttons you are going to generate. The declaration routine takes a set of meaningful arguments, and lets the others pass through verbatim (they are recorded to be given back when properties() is called).
properties()
The minimal set of arguments to supply are -name and -target (or -dyn_target). You will probably supply -action as well if you wish to perform validation of control fields, or any other processing attached to the pressing of that button.
-name
-target
-dyn_target
-action
Some of the arguments below expect callback arguments. The callback representation rules are documented in "Callbacks" in CGI::MxScreen.
Some of the callbacks or arguments below are expected to yield states. See "States" in CGI::MxScreen for state representation rules.
The following named arguments may be given to record_button(). Any other argument is simply recorded and will be propagated via properties(). Arguments are all optional but for -name, and one of -target or -dyn_target must be supplied:
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 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.
CGI::MxScreen::Action_Env
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:
-action => [['callback', $arg1]], # RIGHT
If you were to write by mistake:
-action => ['callback', $arg1], # WRONG
then that would result in the following actions ($screen is the current screen object where the button is recorded):
$screen
$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 CGI::MxScreen::Error.
-dyn_on_error
When any of the -action callbacks returns a non-OK status, an error flag is raised. By default, the same screen will be re-displayed. When a -dyn_on_error callback is specified, the screen to display is computed dynamically. You may not use this option in conjunction with -on_error.
-on_error
A trailing 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 CGI::MxScreen::Action_Env.
The 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 display() parameters). See "States" in CGI::MxScreen for details.
display()
When a -dyn_target callback is specified, the next target state is computed dynamically. You may not use this option in conjunction with -target.
Madantory parameter, giving the name of the button. This is the CGI parameter name. The displayed button will be labeled with name, unless there is also a -value given.
-value
When any of the -action callbacks returns a non-OK status, an error flag is raised. By default, the same screen will be re-displayed. When an -on_error trap is specified, the screen to display is given by target_state. You cannot use -dyn_on_error in conjunction with this argument.
The target_state can be a single scalar (the state name), or an array ref (state name as first item, remaining values being display() parameters). See "States" in CGI::MxScreen.
This argument defines the target state to move to when all action callabacks (if any) returned an OK status. Either this argument or -dyn_target must be specified when recording a button.
This specifies the button's value, which will be displayed by browser instead of the parameter name.
Any other argument will be recorded as-is and passed through when properties() is called on the button object.
Once created via record_button, the following features may be called on the object:
record_button
has_error_trap
Returns true when there is an -on_error or -dyn_on_error argument.
name
Returns the button name.
properties
Generates the list of CGI arguments suitable to use with the routines in the CGI modules. An easy way to generate a submit button is to do:
CGI
print submit($b->properties);
assuming $b was obtained through a record_button() call.
$b
value
Returns the recorded button value, or the name if no value was given. When referring to a button, this is the feature to use, as in:
print p("Once done, press the", b($done->value), "button.");
which lets you factorize the button's value (aka label) in one place, making things easier if you decide to change it later on.
Raphael Manfredi <Raphael_Manfredi@pobox.com> and Christophe Dehaudt <Christophe.Dehaudt@teamlog.fr>.
CGI::MxScreen(3), CGI::MxScreen::Form::Field(3).
To install CGI::MxScreen, copy and paste the appropriate command in to your terminal.
cpanm
cpanm CGI::MxScreen
CPAN shell
perl -MCPAN -e shell install CGI::MxScreen
For more information on module installation, please visit the detailed CPAN module installation guide.