.\" Automatically generated by Pod::Man 4.10 (Pod::Simple 3.35)
.\"
.\" Standard preamble:
.\" ========================================================================
.de Sp \" Vertical space (when we can't use .PP)
.if t .sp .5v
.if n .sp
..
.de Vb \" Begin verbatim text
.ft CW
.nf
.ne \\$1
..
.de Ve \" End verbatim text
.ft R
.fi
..
.\" Set up some character translations and predefined strings.  \*(-- will
.\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left
.\" double quote, and \*(R" will give a right double quote.  \*(C+ will
.\" give a nicer C++.  Capital omega is used to do unbreakable dashes and
.\" therefore won't be available.  \*(C` and \*(C' expand to `' in nroff,
.\" nothing in troff, for use with C<>.
.tr \(*W-
.ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p'
.ie n \{\
.    ds -- \(*W-
.    ds PI pi
.    if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch
.    if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\"  diablo 12 pitch
.    ds L" ""
.    ds R" ""
.    ds C` ""
.    ds C' ""
'br\}
.el\{\
.    ds -- \|\(em\|
.    ds PI \(*p
.    ds L" ``
.    ds R" ''
.    ds C`
.    ds C'
'br\}
.\"
.\" Escape single quotes in literal strings from groff's Unicode transform.
.ie \n(.g .ds Aq \(aq
.el       .ds Aq '
.\"
.\" If the F register is >0, we'll generate index entries on stderr for
.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index
.\" entries marked with X<> in POD.  Of course, you'll have to process the
.\" output yourself in some meaningful fashion.
.\"
.\" Avoid warning from groff about undefined register 'F'.
.de IX
..
.nr rF 0
.if \n(.g .if rF .nr rF 1
.if (\n(rF:(\n(.g==0)) \{\
.    if \nF \{\
.        de IX
.        tm Index:\\$1\t\\n%\t"\\$2"
..
.        if !\nF==2 \{\
.            nr % 0
.            nr F 2
.        \}
.    \}
.\}
.rr rF
.\" ========================================================================
.\"
.IX Title "CGI::FormBuilder::Field 3pm"
.TH CGI::FormBuilder::Field 3pm "2019-01-19" "perl v5.28.1" "User Contributed Perl Documentation"
.\" For nroff, turn off justification.  Always turn off hyphenation; it makes
.\" way too many mistakes in technical documents.
.if n .ad l
.nh
.SH "NAME"
CGI::FormBuilder::Field \- Base class for FormBuilder fields
.SH "SYNOPSIS"
.IX Header "SYNOPSIS"
.Vb 1
\&    use CGI::FormBuilder::Field;
\&
\&    # delegated straight from FormBuilder
\&    my $f = CGI::FormBuilder::Field\->new($form, name => \*(Aqwhatever\*(Aq);
\&
\&    # attribute functions
\&    my $n = $f\->name;         # name of field
\&    my $n = "$f";             # stringify to $f\->name
\&
\&    my $t = $f\->type;         # auto\-type
\&    my @v = $f\->value;        # auto\-stickiness
\&    my @o = $f\->options;      # options, aligned and sorted
\&
\&    my $l = $f\->label;        # auto\-label
\&    my $h = $f\->tag;          # field XHTML tag (name/type/value)
\&    my $s = $f\->script;       # per\-field JS validation script
\&
\&    my $m = $f\->message;      # error message if invalid
\&    my $m = $f\->jsmessage;    # JavaScript error message
\&
\&    my $r = $f\->required;     # required?
\&    my $k = $f\->validate;     # run validation check
\&
\&    my $v = $f\->tag_value;    # value in tag (stickiness handling)
\&    my $v = $f\->cgi_value;    # CGI value if any
\&    my $v = $f\->def_value;    # manually\-specified value
\&
\&    $f\->field(opt => \*(Aqval\*(Aq);  # FormBuilder field() call
.Ve
.SH "DESCRIPTION"
.IX Header "DESCRIPTION"
This module is internally used by \fBFormBuilder\fR to create and maintain
field information. Usually, you will not want to directly access this
set of data structures. However, one big exception is if you are going
to micro-control form rendering. In this case, you will need to access
the field objects directly.
.PP
To do so, you will want to loop through the fields in order:
.PP
.Vb 1
\&    for my $field ($form\->field) {
\&
\&        # $field holds an object stringified to a field name
\&        if ($field =~ /_date$/) {
\&            $field\->sticky(0);  # clear CGI value
\&            print "Enter $field here:", $field\->tag;
\&        } else {
\&            print $field\->label, \*(Aq: \*(Aq, $field\->tag;
\&        }
\&    }
.Ve
.PP
As illustrated, each \f(CW$field\fR variable actually holds a stringifiable
object. This means if you print them out, you will get the field name,
allowing you to check for certain fields. However, since it is an object,
you can then run accessor methods directly on that object.
.PP
The most useful method is \f(CW\*(C`tag()\*(C'\fR. It generates the \s-1HTML\s0 input tag
for the field, including all option and type handling, and returns a 
string which you can then print out or manipulate appropriately.
.PP
Second to this method is the \f(CW\*(C`script\*(C'\fR method, which returns the appropriate
JavaScript validation routine for that field. This is useful at the top of
your form rendering, when you are printing out the leading \f(CW\*(C`<head>\*(C'\fR section
of your \s-1HTML\s0 document. It is called by the \f(CW$form\fR method of the same name.
.PP
The following methods are provided for each \f(CW$field\fR object.
.SH "METHODS"
.IX Header "METHODS"
.ie n .SS "new($form, %args)"
.el .SS "new($form, \f(CW%args\fP)"
.IX Subsection "new($form, %args)"
This creates a new \f(CW$field\fR object. The first argument must be a reference
to the top-level \f(CW$form\fR object, for callbacks. The remaining arguments
should be hash, of which one \f(CW\*(C`key/value\*(C'\fR pair must specify the \f(CW\*(C`name\*(C'\fR of
the field. Normally you should not touch this method. Ever.
.SS "field(%args)"
.IX Subsection "field(%args)"
This is a delegated field call. This is how \fBFormBuilder\fR tweaks its fields.
Once you have a \f(CW$field\fR object, you call this method the exact same way
that you would call the main \f(CW\*(C`field()\*(C'\fR method, minus the field name. Again
you should use the top-level call instead.
.SS "inflate($subref)"
.IX Subsection "inflate($subref)"
This sets the inflate attribute: subroutine reference used to inflate values 
returned by \fBvalue()\fR into objects or whatever you want.  If no parameter, 
returns the inflate subroutine reference that is set.  For example:
.PP
.Vb 7
\& use DateTime::Format::Strptime;
\& my $date_format = DateTime::Format::Strptime\->new(
\&    pattern   => \*(Aq%D\*(Aq,    # for MM/DD/YYYY american dates
\&    locale    => \*(Aqen_US\*(Aq,
\&    time_zone => \*(AqAmerica/Los_Angeles\*(Aq,
\& );
\& $field\->inflate( sub { return $date_format\->format_datetime(shift) } );
.Ve
.SS "invalid"
.IX Subsection "invalid"
This returns the opposite value that \f(CW\*(C`validate()\*(C'\fR would return, with
some extra magic that keeps state for form rendering purposes.
.SS "\fBjsfunc()\fP"
.IX Subsection "jsfunc()"
Returns the appropriate JavaScript validation code (see above).
.SS "label($str)"
.IX Subsection "label($str)"
This sets and returns the field's label. If unset, it will be generated
from the name of the field.
.SS "tag($type)"
.IX Subsection "tag($type)"
Returns an \s-1XHTML\s0 form input tag (see above). By default it renders the
tag based on the type set from the top-level field method:
.PP
.Vb 1
\&    $form\->field(name => \*(Aqpoetry\*(Aq, type => \*(Aqtextarea\*(Aq);
.Ve
.PP
However, if you are doing custom rendering you can override this temporarily
by passing in the type explicitly. This is usually not useful unless you
have a custom rendering module that forcibly overrides types for certain
fields.
.SS "type($type)"
.IX Subsection "type($type)"
This sets and returns the field's type. If unset, it will automatically 
generate the appropriate field type, depending on the number of options and
whether multiple values are allowed:
.PP
.Vb 12
\&    Field options?
\&        No = text (done)
\&        Yes:
\&            Less than \*(Aqselectnum\*(Aq setting?
\&                No = select (done)
\&                Yes:
\&                    Is the \*(Aqmultiple\*(Aq option set?
\&                    Yes = checkbox (done)
\&                    No:
\&                        Have just one single option?
\&                            Yes = checkbox (done)
\&                            No = radio (done)
.Ve
.PP
For an example, view the inside guts of this module.
.SS "validate($pattern)"
.IX Subsection "validate($pattern)"
This returns 1 if the field passes the validation pattern(s) and \f(CW\*(C`required\*(C'\fR
status previously set via \fBrequired()\fR and (possibly) the top-level \fBnew()\fR
call in FormBuilder. Usually running per-field \fBvalidate()\fR calls is not
what you want. Instead, you want to run the one on \f(CW$form\fR, which in
turn calls each individual field's and saves some temp state.
.SS "value($val)"
.IX Subsection "value($val)"
This sets the field's value. It also returns the appropriate value: \s-1CGI\s0 if
set, otherwise the manual default value. Same as using \f(CW\*(C`field()\*(C'\fR to
retrieve values.
.SS "\fBtag_value()\fP"
.IX Subsection "tag_value()"
This obeys the \f(CW\*(C`sticky\*(C'\fR flag to give a different interpretation of \s-1CGI\s0
values. \fBUse this to get the value if generating your own tag.\fR Otherwise,
ignore it completely.
.SS "\fBcgi_value()\fP"
.IX Subsection "cgi_value()"
This always returns the \s-1CGI\s0 value, regardless of \f(CW\*(C`sticky\*(C'\fR.
.SS "\fBdef_value()\fP"
.IX Subsection "def_value()"
This always returns the default value, regardless of \f(CW\*(C`sticky\*(C'\fR.
.SS "\fBtag_name()\fP"
.IX Subsection "tag_name()"
This returns the tag name of the current item. This was added so you could
subclass, say, \f(CW\*(C`CGI::FormBuilder::Field::select\*(C'\fR and change the \s-1HTML\s0 tag
to \f(CW\*(C`<b:select>\*(C'\fR instead. This is an experimental feature and subject
to change wildly (suggestions welcome).
.SS "accessors"
.IX Subsection "accessors"
In addition to the above methods, accessors are provided for directly 
manipulating values as if from a \f(CW\*(C`field()\*(C'\fR call:
.PP
.Vb 12
\&    Accessor                Same as...                        
\&    \-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\- \-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-
\&    $f\->force(0|1)          $form\->field(force => 0|1)
\&    $f\->options(\e@opt)      $form\->field(options => \e@opt)
\&    $f\->multiple(0|1)       $form\->field(multiple => 0|1)
\&    $f\->message($mesg)      $form\->field(message => $mesg)
\&    $f\->jsmessage($mesg)    $form\->field(jsmessage => $mesg)
\&    $f\->jsclick($code)      $form\->field(jsclick => $code)
\&    $f\->sticky(0|1)         $form\->field(sticky => 0|1);
\&    $f\->force(0|1)          $form\->field(force => 0|1);
\&    $f\->growable(0|1)       $form\->field(growable => 0|1);
\&    $f\->other(0|1)          $form\->field(other => 0|1);
.Ve
.SH "SEE ALSO"
.IX Header "SEE ALSO"
CGI::FormBuilder
.SH "REVISION"
.IX Header "REVISION"
\&\f(CW$Id:\fR Field.pm 100 2007\-03\-02 18:13:13Z nwiger $
.SH "AUTHOR"
.IX Header "AUTHOR"
Copyright (c) Nate Wiger <http://nateware.com>. All Rights Reserved.
.PP
This module is free software; you may copy this under the terms of
the \s-1GNU\s0 General Public License, or the Artistic License, copies of
which should have accompanied your Perl kit.