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 appro‐
68 priate JavaScript validation routine for that field. This is useful at
69 the top of your form rendering, when you are printing out the leading
70 "<head>" section of your HTML document. It is called by the $form
71 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 refer‐
79 ence to the top-level $form object, for callbacks. The remaining argu‐
80 ments should be hash, of which one "key/value" pair must specify the
81 "name" of the field. Normally you should not touch this method. Ever.
82 field(%args)
84 This is a delegated field call. This is how FormBuilder tweaks its
86 fields. Once you have a $field object, you call this method the exact
87 same way that you would call the main "field()" method, minus the field
88 name. Again you should use the top-level call instead.
89 inflate($subref)
91 This sets the inflate attribute: subroutine reference used to inflate
93 values returned by value() into objects or whatever you want. If no
94 parameter, returns the inflate subroutine reference that is set. For
95 example:
96 use DateTime::Format::Strptime;
98 my $date_format = DateTime::Format::Strptime->new(
99 pattern => '%D', # for MM/DD/YYYY american dates
100 locale => 'en_US',
101 time_zone => 'America/Los_Angeles',
102 );
103 $field->inflate( sub { return $date_format->format_datetime(shift) } );
104 invalid
106 This returns the opposite value that "validate()" would return, with
108 some extra magic that keeps state for form rendering purposes.
109 jsfunc()
111 Returns the appropriate JavaScript validation code (see above).
113 label($str)
115 This sets and returns the field's label. If unset, it will be generated
117 from the name of the field.
118 tag($type)
120 Returns an XHTML form input tag (see above). By default it renders the
122 tag based on the type set from the top-level field method:
123 $form->field(name => 'poetry', type => 'textarea');
125 However, if you are doing custom rendering you can override this tempo‐
127 rarily by passing in the type explicitly. This is usually not useful
128 unless you have a custom rendering module that forcibly overrides types
129 for certain fields.
130 type($type)
132 This sets and returns the field's type. If unset, it will automatically
134 generate the appropriate field type, depending on the number of options
135 and whether multiple values are allowed:
136 Field options?
138 No = text (done)
139 Yes:
140 Less than 'selectnum' setting?
141 No = select (done)
142 Yes:
143 Is the 'multiple' option set?
144 Yes = checkbox (done)
145 No:
146 Have just one single option?
147 Yes = checkbox (done)
148 No = radio (done)
149 For an example, view the inside guts of this module.
151 validate($pattern)
153 This returns 1 if the field passes the validation pattern(s) and
155 "required" status previously set via required() and (possibly) the top-
156 level new() call in FormBuilder. Usually running per-field validate()
157 calls is not what you want. Instead, you want to run the one on $form,
158 which in turn calls each individual field's and saves some temp state.
159 value($val)
161 This sets the field's value. It also returns the appropriate value: CGI
163 if set, otherwise the manual default value. Same as using "field()" to
164 retrieve values.
165 tag_value()
167 This obeys the "sticky" flag to give a different interpretation of CGI
169 values. Use this to get the value if generating your own tag. Other‐
170 wise, ignore it completely.
171 cgi_value()
173 This always returns the CGI value, regardless of "sticky".
175 def_value()
177 This always returns the default value, regardless of "sticky".
179 tag_name()
181 This returns the tag name of the current item. This was added so you
183 could subclass, say, "CGI::FormBuilder::Field::select" and change the
184 HTML tag to "<b:select>" instead. This is an experimental feature and
185 subject to change wildly (suggestions welcome).
186 accessors
188 In addition to the above methods, accessors are provided for directly
190 manipulating values as if from a "field()" call:
191 Accessor Same as...
193 ----------------------- -----------------------------------
194 $f->force(0⎪1) $form->field(force => 0⎪1)
195 $f->options(\@opt) $form->field(options => \@opt)
196 $f->multiple(0⎪1) $form->field(multiple => 0⎪1)
197 $f->message($mesg) $form->field(message => $mesg)
198 $f->jsmessage($mesg) $form->field(jsmessage => $mesg)
199 $f->jsclick($code) $form->field(jsclick => $code)
200 $f->sticky(0⎪1) $form->field(sticky => 0⎪1);
201 $f->force(0⎪1) $form->field(force => 0⎪1);
202 $f->growable(0⎪1) $form->field(growable => 0⎪1);
203 $f->other(0⎪1) $form->field(other => 0⎪1);
204
206 CGI::FormBuilder
207
209 $Id: Field.pm 100 2007-03-02 18:13:13Z nwiger $
210
212 Copyright (c) 2000-2006 Nate Wiger <nate@wiger.org>. All Rights
213 Reserved.
214 This module is free software; you may copy this under the terms of the
216 GNU General Public License, or the Artistic License, copies of which
217 should have accompanied your Perl kit.
218perl v5.8.8 2007-03-02 CGI::FormBuilder::Field(3)