1CGI::FormBuilder::FieldU(s3e)r Contributed Perl DocumentaCtGiIo:n:FormBuilder::Field(3)
2
6 CGI::FormBuilder::Field - Base class for FormBuilder fields
7
9 use CGI::FormBuilder::Field;
10 # delegated straight from FormBuilder
12 my $f = CGI::FormBuilder::Field->new($form, name => 'whatever');
13 # attribute functions
15 my $n = $f->name; # name of field
16 my $n = "$f"; # stringify to $f->name
17 my $t = $f->type; # auto-type
19 my @v = $f->value; # auto-stickiness
20 my @o = $f->options; # options, aligned and sorted
21 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 my $m = $f->message; # error message if invalid
27 my $m = $f->jsmessage; # JavaScript error message
28 my $r = $f->required; # required?
30 my $k = $f->validate; # run validation check
31 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 $f->field(opt => 'val'); # FormBuilder field() call
37
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 To do so, you will want to loop through the fields in order:
46 for my $field ($form->field) {
48 # $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 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 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 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 The following methods are provided for each $field object.
74
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 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 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 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 invalid
104 This returns the opposite value that validate() would return, with some
105 extra magic that keeps state for form rendering purposes.
106 jsfunc()
108 Returns the appropriate JavaScript validation code (see above).
109 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 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 $form->field(name => 'poetry', type => 'textarea');
119 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 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 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 For an example, view the inside guts of this module.
144 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 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 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 cgi_value()
163 This always returns the CGI value, regardless of "sticky".
164 def_value()
166 This always returns the default value, regardless of "sticky".
167 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 accessors
175 In addition to the above methods, accessors are provided for directly
176 manipulating values as if from a field() call:
177 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
192 CGI::FormBuilder
193
195 $Id: Field.pm 100 2007-03-02 18:13:13Z nwiger $
196
198 Copyright (c) Nate Wiger <http://nateware.com>. All Rights Reserved.
199 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.
203perl v5.36.0 2023-01-20 CGI::FormBuilder::Field(3)