view release on metacpan or  search on metacpan

MxScreen/Form/Field.pm  view on Meta::CPAN

        else {
            # handle scalar setting : -verify => 'is_num'
            $routine = $ref;
        }

		require CGI::MxScreen::Form::Utils;

        my $coderef = CGI::MxScreen::Form::Utils::lookup($routine);
		logdie "validation routine '$routine' not found for the \"%s\" field",
			$self->name unless defined $coderef;

        my $error = &{$coderef}($self->value, @arg);
        $self->set_error($error) if $error;
        return DVAL !$error;
    }
    
    return DVAL 1; # there is no error
}


#
# is_blessed
#
# check whether a reference points onto an blessed object
#
# Return:
#   a boolean value.   
#
sub is_blessed { UNIVERSAL::isa($_[0], "UNIVERSAL") }

1;

=head1 NAME

CGI::MxScreen::Form::Field - A recorded field

=head1 SYNOPSIS

 # $self is a CGI::MxScreen::Screen

 use CGI qw/:standard/;

 my $amount = $self->record_field(
     -name       => "price",
     -storage    => [$order, 'set_amount'],
     -default    => $order->amount,
     -override   => 1,
     -verify     => 'is_positive',
     -mandatory  => 1,
     -patch      => 'strip_spurious_zeros',
     -size       => 10,
     -maxlength  => 10,
 );
 print textfield($amount->properties);

 my $menu = $self->record_field(
     -name       => "mode",
     -values     => ['replace', 'append', 'prepend'],
     -default    => 'append',
 );
 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.

=head1 INTERFACE

Some of the arguments below take a plain I<routine> argument as a scalar.
This I<routine> is not a code reference but a name that will be looked up
in various packages unless it is already qualified, such as C<'main::f'>.
See L<CGI::MxScreen/Utility Path> for information about how to specify
the searching I<path>, so to speak.

=head2 Creation Arguments

The following named arguments may be given to C<record_field()>.
They are all optional but for C<-name>.  Any argument not listed below
will be simply recorded and propagated via C<properties()>:

=over 4

=item C<-default> => I<value>

Sets the default value, for the first time the field is shown.
Since C<CGI> routines create stateful fields, you may need to say:

    -default  => $value,
    -override => 1,

to force the value of the field to C<$value>.  That is, if you use the
C<CGI> routines to ultimately generate your field.

This parameter is propagated via C<properties()>, but is intercepted
by. C<record_field> to set the C<value> attribute of the object.  If no
C<-default> is given, then the value will be that of the CGI parameter
bearing the name you give via C<-name>.

=item C<-mandatory> => I<flag>

By default, fields are not mandatory.  Setting I<flag> to true tells
C<CGI::MxScreen> that this parameter should be filled.  However, this checking
only occurs when you list C<'validate'> as an action callback in the submit
buttons of your screen.  See L<CGI::MxScreen::Form::Button>.

=item C<-name> => I<name>

MxScreen/Form/Field.pm  view on Meta::CPAN

    if (exists $vars->{user_array}) {
        $array = $vars->{user_array};
    } else {
        $array = $vars->{user_array} = [];
    }

    my $field = $self->record_field(
        -name       => "id",
        -storage    => [$array, 2],
    );

The C<exists()> check is there because by default, keys within the global
hash context are protected: it is a fatal error to access a non-existent
key (see L<CGI::MxScreen::Config> to learn how to disable that check).

All the code examples given above were simplified, assuming the value
within the context was already properly initialized.

=item C<-verify> => I<routine>

Specifies a validation I<routine> to be run.  The routine will not be
actually run unless the C<'validate'> action callback is not recorded
in the pressed submit button (see L<CGI::MxScreen::Form::Button>).

The I<routine> can be specified as a single scalar, or as an array ref:

    ['is_greater', 4]

The validation routine is passed the parameter value as a first argument,
and it must return C<0> if OK, an error message otherwise, which will be
stored in the C<error> field.  In the example above,

    is_greater($value, 4);

would be called, assuming C<$value> is the value of the field.

=back

Any other argument will be recorded as-is and passed through when
C<properties()> is called on the field object.

=head2 Features

Once created via C<record_field>, the following features may be called
on the object:

=over 4

=item C<error>

The error message returned by the validation routine.  If it evaluates to
I<false>, there is no error condition for this field.

=item C<name>

Returns the field name.

=item C<properties>

Generates the list of CGI arguments suitable to use with the routines
in the C<CGI> modules.  An easy way to generate a popup menu is to
do:

    print popup_menu($menu->properties);

assuming C<$menu> was obtained through a C<record_field()> call and
included such things as C<-values>.  Otherwise, you may add those
additional switches now, like in:

    print popup_menu($menu->properties, -values => ['a', 'b']);

but it might be better to group properties at the same place, i.e. when
C<record_field()> is called.

=item C<value>

Returns the recorded field value.

When recording a field within a screen, the C<value> attribute is
automatically set to the CGI parameter value.

=back

=head1 AUTHORS

The original authors are
Raphael Manfredi F<E<lt>Raphael_Manfredi@pobox.comE<gt>>
and
Christophe Dehaudt F<E<lt>Christophe.Dehaudt@teamlog.frE<gt>>.

Send bug reports, suggestions, problems or questions to
Jason Purdy F<E<lt>Jason@Purdy.INFOE<gt>>

=head1 SEE ALSO

CGI::MxScreen(3), CGI::MxScreen::Form::Button(3),
CGI::MxScreen::Form::Utils(3).

=cut