NAME

CGI::MxScreen::Form::Button - A recorded button

SYNOPSIS

 # $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);

DESCRIPTION

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.

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).

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.

INTERFACE

Creation Arguments

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:

-action => [callback1, 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 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.

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->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 => callback

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.

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.

-dyn_target => callback

When a -dyn_target callback is specified, the next target state is computed dynamically. You may not use this option in conjunction with -target.

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.

-name => name

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.

-on_error => target_state

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.

-target => target_state

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.

-value => value

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.

Features

Once created via record_button, the following features may be called on the object:

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:

        print submit($b->properties);

assuming $b was obtained through a record_button() call.

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.

AUTHORS

The original authors are Raphael Manfredi <Raphael_Manfredi@pobox.com> and Christophe Dehaudt <Christophe.Dehaudt@teamlog.fr>.

Send bug reports, suggestions, problems or questions to Jason Purdy <Jason@Purdy.INFO>

SEE ALSO

CGI::MxScreen(3), CGI::MxScreen::Form::Field(3).