view release on metacpan or  search on metacpan

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

        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>

Madantory parameter, giving the name of the field.
This is the CGI parameter name.

=item C<-nostorage> => 1

This directs C<CGI::MxScreen> to not handle the storage of the
parameter, at submit time.  No trail will be left anywhere in the context.
This parameter is ignored when C<-storage> is also given.