1CGI::FormBuilder::FieldU(s3e)r Contributed Perl DocumentaCtGiIo:n:FormBuilder::Field(3)
2
3
4

NAME

6       CGI::FormBuilder::Field - Base class for FormBuilder fields
7

SYNOPSIS

9           use CGI::FormBuilder::Field;
10
11           # delegated straight from FormBuilder
12           my $f = CGI::FormBuilder::Field->new($form, name => 'whatever');
13
14           # attribute functions
15           my $n = $f->name;         # name of field
16           my $n = "$f";             # stringify to $f->name
17
18           my $t = $f->type;         # auto-type
19           my @v = $f->value;        # auto-stickiness
20           my @o = $f->options;      # options, aligned and sorted
21
22           my $l = $f->label;        # auto-label
23           my $h = $f->tag;          # field XHTML tag (name/type/value)
24           my $s = $f->script;       # per-field JS validation script
25
26           my $m = $f->message;      # error message if invalid
27           my $m = $f->jsmessage;    # JavaScript error message
28
29           my $r = $f->required;     # required?
30           my $k = $f->validate;     # run validation check
31
32           my $v = $f->tag_value;    # value in tag (stickiness handling)
33           my $v = $f->cgi_value;    # CGI value if any
34           my $v = $f->def_value;    # manually-specified value
35
36           $f->field(opt => 'val');  # FormBuilder field() call
37

DESCRIPTION

39       This module is internally used by FormBuilder to create and maintain
40       field information. Usually, you will not want to directly access this
41       set of data structures. However, one big exception is if you are going
42       to micro-control form rendering. In this case, you will need to access
43       the field objects directly.
44
45       To do so, you will want to loop through the fields in order:
46
47           for my $field ($form->field) {
48
49               # $field holds an object stringified to a field name
50               if ($field =~ /_date$/) {
51                   $field->sticky(0);  # clear CGI value
52                   print "Enter $field here:", $field->tag;
53               } else {
54                   print $field->label, ': ', $field->tag;
55               }
56           }
57
58       As illustrated, each $field variable actually holds a stringifiable
59       object. This means if you print them out, you will get the field name,
60       allowing you to check for certain fields. However, since it is an
61       object, you can then run accessor methods directly on that object.
62
63       The most useful method is "tag()". It generates the HTML input tag for
64       the field, including all option and type handling, and returns a string
65       which you can then print out or manipulate appropriately.
66
67       Second to this method is the "script" method, which returns the
68       appropriate JavaScript validation routine for that field. This is
69       useful at the top of your form rendering, when you are printing out the
70       leading "<head>" section of your HTML document. It is called by the
71       $form method of the same name.
72
73       The following methods are provided for each $field object.
74

METHODS

76   new($form, %args)
77       This creates a new $field object. The first argument must be a
78       reference to the top-level $form object, for callbacks. The remaining
79       arguments should be hash, of which one "key/value" pair must specify
80       the "name" of the field. Normally you should not touch this method.
81       Ever.
82
83   field(%args)
84       This is a delegated field call. This is how FormBuilder tweaks its
85       fields.  Once you have a $field object, you call this method the exact
86       same way that you would call the main "field()" method, minus the field
87       name. Again you should use the top-level call instead.
88
89   inflate($subref)
90       This sets the inflate attribute: subroutine reference used to inflate
91       values returned by value() into objects or whatever you want.  If no
92       parameter, returns the inflate subroutine reference that is set.  For
93       example:
94
95        use DateTime::Format::Strptime;
96        my $date_format = DateTime::Format::Strptime->new(
97           pattern   => '%D',    # for MM/DD/YYYY american dates
98           locale    => 'en_US',
99           time_zone => 'America/Los_Angeles',
100        );
101        $field->inflate( sub { return $date_format->format_datetime(shift) } );
102
103   invalid
104       This returns the opposite value that "validate()" would return, with
105       some extra magic that keeps state for form rendering purposes.
106
107   jsfunc()
108       Returns the appropriate JavaScript validation code (see above).
109
110   label($str)
111       This sets and returns the field's label. If unset, it will be generated
112       from the name of the field.
113
114   tag($type)
115       Returns an XHTML form input tag (see above). By default it renders the
116       tag based on the type set from the top-level field method:
117
118           $form->field(name => 'poetry', type => 'textarea');
119
120       However, if you are doing custom rendering you can override this
121       temporarily by passing in the type explicitly. This is usually not
122       useful unless you have a custom rendering module that forcibly
123       overrides types for certain fields.
124
125   type($type)
126       This sets and returns the field's type. If unset, it will automatically
127       generate the appropriate field type, depending on the number of options
128       and whether multiple values are allowed:
129
130           Field options?
131               No = text (done)
132               Yes:
133                   Less than 'selectnum' setting?
134                       No = select (done)
135                       Yes:
136                           Is the 'multiple' option set?
137                           Yes = checkbox (done)
138                           No:
139                               Have just one single option?
140                                   Yes = checkbox (done)
141                                   No = radio (done)
142
143       For an example, view the inside guts of this module.
144
145   validate($pattern)
146       This returns 1 if the field passes the validation pattern(s) and
147       "required" status previously set via required() and (possibly) the top-
148       level new() call in FormBuilder. Usually running per-field validate()
149       calls is not what you want. Instead, you want to run the one on $form,
150       which in turn calls each individual field's and saves some temp state.
151
152   value($val)
153       This sets the field's value. It also returns the appropriate value: CGI
154       if set, otherwise the manual default value. Same as using "field()" to
155       retrieve values.
156
157   tag_value()
158       This obeys the "sticky" flag to give a different interpretation of CGI
159       values. Use this to get the value if generating your own tag.
160       Otherwise, ignore it completely.
161
162   cgi_value()
163       This always returns the CGI value, regardless of "sticky".
164
165   def_value()
166       This always returns the default value, regardless of "sticky".
167
168   tag_name()
169       This returns the tag name of the current item. This was added so you
170       could subclass, say, "CGI::FormBuilder::Field::select" and change the
171       HTML tag to "<b:select>" instead. This is an experimental feature and
172       subject to change wildly (suggestions welcome).
173
174   accessors
175       In addition to the above methods, accessors are provided for directly
176       manipulating values as if from a "field()" call:
177
178           Accessor                Same as...
179           ----------------------- -----------------------------------
180           $f->force(0|1)          $form->field(force => 0|1)
181           $f->options(\@opt)      $form->field(options => \@opt)
182           $f->multiple(0|1)       $form->field(multiple => 0|1)
183           $f->message($mesg)      $form->field(message => $mesg)
184           $f->jsmessage($mesg)    $form->field(jsmessage => $mesg)
185           $f->jsclick($code)      $form->field(jsclick => $code)
186           $f->sticky(0|1)         $form->field(sticky => 0|1);
187           $f->force(0|1)          $form->field(force => 0|1);
188           $f->growable(0|1)       $form->field(growable => 0|1);
189           $f->other(0|1)          $form->field(other => 0|1);
190

SEE ALSO

192       CGI::FormBuilder
193

REVISION

195       $Id: Field.pm 100 2007-03-02 18:13:13Z nwiger $
196

AUTHOR

198       Copyright (c) Nate Wiger <http://nateware.com>. All Rights Reserved.
199
200       This module is free software; you may copy this under the terms of the
201       GNU General Public License, or the Artistic License, copies of which
202       should have accompanied your Perl kit.
203
204
205
206perl v5.30.1                      2020-01-29        CGI::FormBuilder::Field(3)
Impressum