1HTML::FormHandler::ManuUasle:r:RCeonndterriibnugt(e3d)PHeTrMlL:D:oFcourmmeHnatnadtlieorn::Manual::Rendering(3)
2
3
4

NAME

6       HTML::FormHandler::Manual::Rendering - how to render with FormHandler
7

VERSION

9       version 0.40068
10

SYNOPSIS

12       Manual Index
13
14       Rendering can be done in many different ways, from forms rendered
15       entirely in templates with no information from FormHandler (except
16       possibly the fill-in-the-form values) to forms that are completely
17       rendered by FormHandler.
18

DESCRIPTION

20       For most situations, something in between hand-built and completely
21       generated will probably be the best solution. For admin forms that
22       don't need a lot of styling or special HTML, FormHandler's automatic
23       rendering may be appropriate.  FormHandler rendering may also be a good
24       solution if you have enough forms that putting time into creating
25       rendering widgets and themes is worthwhile.
26
27       The automatic rendering is also useful when developing a new form. You
28       can get an idea of what it looks like, and then customize it.
29
30       Another situation in which FormHandler rendering may be useful is when
31       the form is complex enough that working in Perl is a better idea than
32       putting lots of logic into templates.
33
34       All of the rendering is designed to be easily replaced with elements of
35       your own, or to be replaced entirely. You can create your own rendering
36       'widgets' and load them into the fields by designating the directory in
37       the 'widget_name_space'. You could also create a completely separate
38       renderer that's a separate object or class that takes a form object, or
39       a role that is applied to your form.
40
41       Note that unless you set 'no_widgets' in the form, the rendering roles
42       are automatically applied. You don't need to include anything else,
43       unless you want to use a different renderer.
44
45   Mostly templates
46       The names of your fields must match the names of your FormHandler
47       fields.  If you use compound fields, you must use the FormHandler
48       naming convention.
49
50       Form used in examples:
51
52           package MyApp::Form::Example;
53           use HTML::FormHandler::Moose;
54           extends 'HTML::FormHandler';
55
56           has_field 'foo';
57           has_field 'bar';
58           has_field 'save' => ( type => 'Submit' );
59
60       If you have existing forms in templates or just prefer them, you can
61       use the 'fill-in-form' values provided with the form's 'fif' function.
62
63           my $form = MyApp::Form::Example->new;
64           $form->process( params => $params );
65           $c->stash( fif => $form->fif );
66           ...
67           <form id="myform" action="/edit/example" method="post">
68           <label>Foo</label>
69           <input id="foo" name="foo" value="[% fif.foo %]">
70           <label>Bar</label>
71           <input id="bar" name="bar" value="[% fif.bar %]">
72           <input type="submit" name="submit" value="Save">
73           </form>
74
75       If you are looking for an easy way to get your fields to line up in an
76       evenly spaced manner, all uniformly aligned, and to do so without using
77       templates or tables, you can externally style the default FormHandler
78       output with the following CSS rule (not supported in internet explorer
79       6).
80
81       *This above is useful for simple forms.  Complex forms with fieldsets
82       and other extra features *will require further styling of the HTML.
83       The following rule is also HTML 5 compatible.
84
85          form#id_of_your_form div div label, form#id_of_your_form div div input {
86             float: left;
87             display: inline-block;
88             width: 40%
89          } /* make sure the parent element is sized appropriately.  700px is a good width */
90
91       Going a little bit farther in using FormHandler rendering, you can
92       render each of the fields individually, using 'render' or 'renderx':
93
94            <form id="myform" action="/edit/example" method="post">
95            <fieldset><legend>My Foo</legend>
96            [% form.field('foo').render %]
97            </fieldset>
98            [% form.field('bar').renderx(element_class => 'cb33')  %]
99            [% form.field('save').render %]
100            </form>
101
102       If you don't want the wrappers, use a widget_wrapper of 'None'.
103
104           has '+widget_wrapper' => ( default => 'None' );
105
106       Then you can provide the HTML in which the form elements are embedded:
107
108           <div class="my_class">
109           [% form.field('foo').render %]
110           </div>
111           <div class="another_class">
112           [% form.field('bar').renderx(element_class => 'cb33')  %]
113           </div>
114
115       You can also use the 'render_element' or 'render_elementx' methodx, if
116       you want to leave the wrapper in place, but sometimes render 'bare'
117       html elements:
118
119           <div class="my_class">
120           [% form.field('foo').render_element %]
121           </div>
122           <div class="my_class">
123           [% form.field('foo').render_elementx(element_class => 'cb33') %]
124           </div>
125
126       If you wish to loop through the fields yourself, use the
127       'sorted_fields' method, since it skips inactive fields and handles the
128       'order' attribute.
129
130       A set of Template Toolkit templates is also provided in the 'share'
131       directory. There are individual templates for each 'widget', such as a
132       checkbox, and there is also an all-in-one template that includes blocks
133       for the various 'widgets'. If you want to use these templates you can
134       just copy them to your template directory and specify the form template
135       in your controller.
136
137       See also HTML::FormHandler::Manual::Templates.
138
139   Automatic rendering
140       If you take all the defaults, you can simply render a form with
141       "$form->render".
142
143           [% form.render %]
144           or
145           [% form.renderx( form_element_class => ['xxx'] ) %]
146
147       This uses the HTML::FormHandler::Widget::Form::Simple role, which is
148       applied to the form by default. You can use a different form rendering
149       role by including it using 'with':
150
151           with 'HTML::FormHandler::Widget::Form::Table';
152           has '+widget_wrapper' => ( default => 'Table' );
153
154       For the 'Table' form widget, you will also need to set the matching
155       Table widget_wrapper.
156
157       A widget role, providing the 'render' method, and a widget wrapper
158       role, providing the 'wrap_field' method, are applied to each field when
159       the form is built.  Each field has a default widget, but you can change
160       that by setting 'widget' to a different widget role:
161
162           has_field 'foxy' => ( widget => 'MyWidget', widget_wrapper => 'MyWrapper' );
163
164       Often if you need custom rendering what you need to provide is a custom
165       widget_wrapper.  The 'widgets' render only the input elements, and that
166       often doesn't need to be changed. If you have standard HTML that is
167       used when rendering forms, making custom widget_wrappers is often the
168       way to go.
169
170       Default widget roles are found in the HTML::FormHandler::Widget
171       directory, in the 'Field', 'Form', and 'Wrapper subdirectories.  The
172       name space used to look for the widget roles can be specified on a form
173       or field basis by setting 'widget_name_space' to an arrayref of name
174       spaces:
175
176          has '+widget_name_space' => ( default => sub { ['MyApp::Form::Widget' ] } );
177
178       For the above widget ('MyWidget') and widget_name_space, you need to
179       have a package named 'MyApp::Form::Widget::Field::MyWidget'.
180
181       The HTML::FormHandler::Widget name space is always searched as the last
182       name space.  This means that you can set up an application or form
183       specific set of widgets.  Widgets in a widget directory (specified in
184       widget_name_space) are located in either a 'Field', 'Wrapper', or
185       'Form' subdirectory. (Blocks are in a 'Blocks' subdirectory.)
186
187       You can also create an 'all-in-one' type rendering role, using
188       HTML::FormHandler::Render::Simple as a basis. It used the method name
189       'render_field' on the form ( "$form->render_field('field_name')" )
190       instead of the 'render' method on the field.
191
192       In addition to the 'Simple' wrapper, there is a 'Bootstrap' wrapper
193       which creates HTML formatted to use the Twitter Bootstrap 2.0 CSS.
194       There's also a sample "theme",
195       HTML::FormHandler::Widget::Theme::Bootstrap, which is a role that sets
196       the widget_wrapper to 'Bootstrap', and provides Bootstrap-type
197       formatting of the form error message.
198
199       There are a lot of different settings that control the rendering. Some
200       of them are attributes in the form or field, and some of them are set
201       using the 'tags' hashref in the field or the 'form_tags' hashref in the
202       form.
203
204       You can make your own copy of an existing wrapper and add features to
205       it.  However, there are so many different ways to render the HTML
206       around a field, that it's very difficult to handle more than a short
207       list of standard presentations in one 'wrapper'. It may be better to
208       make a number of more atomic widget wrappers and use those rather than
209       complicate the already fairly complicated "Simple" and "Bootstrap"
210       wrappers more.
211
212   HTML attributes
213       Arbitrary HTML attributes on form elements (such as 'input' elements)
214       can be specified with 'element_attr' on the field. You can also set
215       attributes for the label with 'label_attr' and attributes for the
216       wrapper with 'wrapper_attr'. The 'class' attributes are handled
217       separately, and are arrayrefs (element_class, wrapper_class,
218       label_class):
219
220           has_field 'foo' => ( wrapper_class => ['form', 'special' ] );
221
222       See the documentation on "Attributes_for_creating_HTML" in
223       HTML::FormHandler::Field.
224
225   Form settings
226       widget_wrapper
227           The short name of the rendering wrapper widget to be applied to the
228           fields. When the fields are constructed this is merged into fields
229           that do not already set a widget wrapper.
230
231       do_form_wrapper
232           Flag set with 'sub build_do_form_wrapper{ 1 }'. Default is no form
233           wrapper.
234
235       form_tags
236           Hashref of various tags used in rendering code. See the
237           documentation for HTML::FormHandler::Widget::Form::Simple.
238
239       form_element_attr
240           Hashref of arbitrary HTML attributes to be included in the form
241           element.
242
243              sub build_form_element_attr { [ ... ] }
244
245       form_element_class
246           Arrayref of classes to be included in the form element.
247
248              form_element_class => ['hfh', 'admin']
249              -- or in your class --
250              sub build_form_element_class { ['hfh', 'admin'] }
251
252           The above class would produce a form element:
253
254              <form id="myform" method="post" class="hfh admin">
255
256       form_wrapper_attr
257           Hashref of arbitrary HTML attributes to be included in the form
258           wrapper
259
260              sub build_form_wrapper_attr { { name => 'formname' } }
261
262   Form messages
263       Some messages are rendered at the top of the form (inside the form tag)
264       by the 'render_form_messages' method, which is implemented in
265       HTML::FormHandler::Widget::Form::Simple and
266       HTML::FormHandler::Widget::Theme::BootstrapFormMessages (which is
267       included by the Bootstrap theme).
268
269       There are three types of form messages: 'error_message',
270       'success_message', and 'info_message'. The 'error_message' and
271       'success_message' are set inside the form:
272
273           has '+success_message' => ( default => 'Form successfully submitted' );
274           has '+error_message' => ( default => 'There were errors in your form.' );
275
276       And then are displayed after the form is validated.
277
278       The 'info_message' is cleared out when a form is re-processed, and so
279       would normally be set on the process call, or between new & process.
280
281           $form->process( params => {}, info_message => 'Fill in the form' );
282
283   Field settings
284           has_field 'foo' => ( widget => 'MyWidget', widget_wrapper => 'SpecialWrapper',
285               element_attr => { placeholder => 'enter a foo' }, element_class => 'important',
286               wrapper_class => ['label'], label_class => ['major'],
287               tags => { wrapper_tag => 'fieldset' } );
288
289       widget
290           Short name of the rendering widget for this field.
291
292       widget_wrapper
293           Short name of the wrapping widget for this field.
294
295       do_wrapper
296           Flag that indicates whether or not the 'wrapper' should be
297           rendered.
298
299       do_label
300           Flag that indicates whether or not a label should be rendered.
301
302       element_attr
303           Hashref of arbitrary HTML attributes to include in the element.
304           Note that this does not include the 'id' and 'type' attributes,
305           which are handled separately. The 'id' can be changed with the
306           field's 'id' attribute.
307
308       element_class
309           Arrayref of classes to include in the element.
310
311       wrapper_attr
312           Hashref of arbitrary HTML attributes to include in the wrapper.
313
314       wrapper_class
315           Arrayref of classes to include in the wrapper.
316
317       label_attr
318           Hashref of arbitrary HTML attributes to include in the label.
319
320       label_class
321           Arrayref of classes to include in the label.
322
323       build_id_method
324           Coderef to construct the 'id'. Useful if your javascript needs a
325           different format for the 'id'.
326
327       build_label_method
328           Coderef to construct the label.
329
330       wrap_label_method
331           Coderef to wrap the label. Used by the Simple and Bootstrap
332           wrappers.  Useful if your label contains HTML or a link. You must
333           do your own localization and filtering if you use a 'wrap_label'
334           method.
335
336   html_attributes callback
337       The form has an 'html_attributes' callback which can be used to
338       customize, localize, or modify the various attributes when used.
339       Types: element, wrapper, label, form_element, form_wrapper,
340       checkbox_label
341
342          sub html_attributes {
343              my ( $self, $obj, $type, $attrs, $result ) = @_;
344              # obj is either form or field
345              $attrs->{class} = 'label' if $type eq 'label';
346              $attrs->{placeholder} = $self->_localize($attrs->{placeholder})
347                  if exists $attrs->{placeholder};
348              return $attrs;
349          }
350
351       This callback is called in the methods that wrap the various '_attr'
352       attributes, i.e. element_attributes, label_attributes,
353       wrapper_attributes, form_element_attributes, form_wrapper_attributes.
354
355   Field tags
356       The 'tags' are settings and strings which may vary by the particular
357       widget that implements them. The best place to look for documentation
358       on them is in the field widget, field wrapper, and form widgets that
359       you are using.  The 'tags' allow customizing rendering behavior on a
360       per-field basis.  FormHandler has a number of flags/settings that it
361       uses; you can add your own for your custom rendering code.
362
363           wrapper_tag    -- the tag to use in the wrapper, default 'div'
364           label_tag      -- tag to use for label (default 'label')
365           label_after    -- string to append to label, for example ': ' to append a colon
366
367       Tags can be used to switch the Simple wrapper from divs to using
368       paragraphs instead, or to add a colon in label formatting:
369
370          has_field 'my_field' => (
371              tags => {wrapper_tag => 'p', label_after => ': '  } );
372
373       Most of the tags are implemented by the 'wrapper' widget, so see that
374       documentation for more details:
375       HTML::FormHandler::Widget::Wrapper::Simple,
376       HTML::FormHandler::Widget::Wrapper::Bootstrap.
377
378       Tag types
379
380       The 'get_tag' method will check for these three types of tags and
381       perform the appropriate action.
382
383       String
384           Standard, most common type of value for a tag.
385
386               has_field 'bar' => ( tags => { before_element => '<span>...</span>' } );
387
388           Some tags are true/false also:
389
390               has_field 'foo' => ( type => 'CheckBox',
391                   tags => { no_wrapped_label => 1 } );
392
393       CodeRef
394           You can supply a coderef to a tag, and it will be executed as a
395           method on the field. This is useful for localization or other sorts
396           of runtime changes.
397
398               has_field 'bar' => ( tags => { before_element => \&bar_element } );
399               sub bar_element {
400                   my $self = shift; # $self is the 'bar' field
401                   return '<div>In a Sub</div>';
402               }
403
404       Block
405           You can supply a block by giving a string that consists of a '%'
406           followed by the block name:
407
408               has_block 'comment' => ( tag => 'a', content => 'This is a comment from a block',
409                   class => ['comment' ] );
410               has_field 'foo' => ( tags => { before_element => '%comment' } );
411
412       Tags and other settings for all fields
413
414       Tags can be set for all fields in the form by using a
415       'build_update_subfields' sub, or 'widget_tags'. The 'update_subfields'
416       hashref takes general-purpose keys 'all', 'by_flag' (compound,
417       repeatable, contains), and 'by_type'.  You can also set specific field
418       attributes by using the field name as a key.  For example, if you don't
419       want errors to be displayed next to the fields, you need to set the
420       'no_errors' tag:
421
422          sub build_update_subfields {{
423              all => { tags => { no_errors => 1 }, wrapper_class => ['myapp'] },
424              by_type => { Text => { element_class => ['text'] } },
425              by_flag => { compound => { do_wrapper => 1 } },
426              foo => { label => 'My Foo' },
427          }}
428          -- or --
429          '+widget_tags' => ( default => sub { { no_errors => 1 } } );
430
431       The 'widget_tags' attribute only handles the 'tags' hashref, so if you
432       also want to set classes or attributes, then build_update_subfields is
433       more useful.  You can also use 'build_update_subfields' in a custom
434       compound field class.
435
436       If you have defaults that are set in 'build_update_subfields' in a base
437       class, in order to use hashrefs from both base and current classes, you
438       will need to merge the hashes:
439
440           use HTML::FormHandler::Merge ('merge');
441           sub build_update_subfields {
442               my $self = shift;
443               my $new = { all => { tags => { wrapper_tag => 'p' } } };
444               return merge( $new, $self->next::method(@_) );
445           }
446
447       In a role you would have to do the equivalent with an 'around' method
448       modifier.
449
450       Repeatable field instances
451
452       The repeatable field instances are constructed internally, so it's
453       trickier to set things like wrapper tags. There are two ways to do it,
454       using the 'init_contains' attribute on the repeatable field, and using
455       the 'update_subfields' builder:
456
457           has_field 'records' => ( type => 'Repeatable', num_when_empty => 2,
458               init_contains => { tags => { wrapper_tag => 'fieldset' } } );
459           -- or --
460           sub build_update_subfields { { by_flag => {
461               contains => { tags => { wrapper_tag => 'fieldset' }}}}}
462
463       The 'build_update_subfields' option is mainly useful if you have
464       multiple repeatable fields that you want to set, or if you want
465       defaults in a base class.
466
467       widget and widget_wrapper set to 'None'
468
469       If you want to implement the 'render' method in a custom field, you can
470       set 'widget' to 'None' and no widget will be applied. Setting the
471       'widget_wrapper' to 'None' will apply the 'None' wrapper, which simply
472       returns the widget rendering.
473
474       Error messages
475
476       The default is currently to display error messages next to the rendered
477       fields, if you're doing "$form->render". If you don't want messages
478       next to fields, you can set the 'no_errors' tag, as discussed in the
479       section on 'Tags and other settings...'.
480
481       Note that the 'None' widget wrapper, since it doesn't render anything
482       except the form element (input, select, etc), will not render errors
483       next to the field.  Setting the 'do_wrapper' and 'do_label' flags to 0
484       will still render errors.
485
486   Blocks
487       When rendering, FormHandler loops through the sorted fields in the form
488       and executes the 'render' method on each field. Fields in FormHandler
489       forms, particularly those that interface with a database, are usually
490       structured in a way that matches the data structure. This doesn't
491       always fit with the way that you want to display the form.
492
493       'Blocks' provide an alternative way of structuring the display. A
494       'block' is a fairly basic object that contains a 'render' method. The
495       standard block class, HTML::FormHandler::Widget::Block, has Moose
496       attributes to set the HTML tag, the label, the classes, etc, plus a
497       'render_list' which contains the names of a list of fields or other
498       blocks to render.
499
500       Here is the definition of a fieldset block that contains two fields:
501
502          has_field 'foo';
503          has_field 'bar';
504          has_block 'first_fset' => ( tag => 'fieldset, label => 'Two Fields',
505              render_list => ['foo', 'bar'] );
506
507       The 'first_fset' block will render like this:
508
509           <fieldset><legend>Two Fields</legend>
510               <div>
511                  <label>Foo</label>
512                  <input type="text" name="foo" id="foo" value="" />
513               <div>
514               <div>
515                  <label>Bar</label>
516                  <input type="text" name="bar" id="bar" value="" />
517               <div>
518           </fieldset>
519
520       You can also provide a method to 'build' the block's render list
521
522          has_block 'first_fset' => ( tag => 'fieldset, label => 'Two Fields',
523              build_render_list_method => \&build_render_list_first_fset );
524          sub build_render_list_first_fset { ['foo', 'bar'] }
525
526       In order to actually get this block to be used when you render with
527       "$form->render", you need to supply a 'render_list' on the form level:
528
529          sub build_render_list { ['first_fset', 'submit_btn'] }
530
531       You could also render it with "$form->block('first_fset')->render".
532
533       Blocks should be located in a widget name space, in a 'Block'
534       directory, or else the name should be prefixed with a '+'.
535
536           has '+widget_name_space' => ( default => sub { ['MyApp::Form::Widget'] };
537           has_block 'first' => ( type => 'MyBlock', ... );
538
539       The 'MyBlock' above will be found in
540       'MyApp::Form::Widget::Block::MyBlock'.
541
542           has_block 'intro' => ( type => '+MyApp::Form::Component::Intro' );
543
544       A block can inherit from HTML::FormHandler::Widget::Block, but it
545       doesn't have to. At a minimum it must provide 'new' and 'render'
546       methods. If no 'type' is specified, the block is created from the
547       HTML::FormHandler::Widget::Block package.
548
549       The following package provides a functional block:
550
551           package MyApp::Component::Section;
552           sub new {
553               my ( $class, %args ) = @_;
554               return bless \%args, $class;
555           }
556           sub form {
557               my $self = shift;
558               return $self->{form};
559           }
560           sub render {
561               return
562               '<div class="intro">
563                 <h3>Please enter the relevant details</h3>
564               </div>';
565           }
566           1;
567
568       When a form is rendered, it will either loop through all of the
569       sorted_fields OR loop through the fields and blocks listed in the
570       'render_list'. A render_list can contain a mix of fields and blocks.
571
572       Note that you must be rendering with widgets to use block rendering.
573
574   Twitter Bootstrap 2.0 rendering
575       The main component of Bootstrap rendering is
576       HTML::FormHandler::Widget::Wrapper::Bootstrap.  It produces the
577       standard Bootstrap-style HTML such as:
578
579           <div class="control-group">
580             <label class="control-label" for="input01">Text input</label>
581             <div class="controls">
582               <input type="text" class="input-xlarge" id="input01" name="input01" value="" />
583             </div>
584           </div>
585
586       These are the standard 'control' blocks for Bootstrap vertical and
587       horizontal forms.  You can apply this wrapper to all of your fields by
588       setting the widget_wrapper in the form:
589
590          has '+widget_wrapper' => ( default => 'Bootstrap' );
591
592       There is also a sample "theme":
593       HTML::FormHandler::Widget::Theme::Bootstrap. It sets the widget_wrapper
594       for you and provides a 'render_form_messages' method to render a
595       success/error messages section.
596
597       There are a couple of examples in the t/bootstrap directory of
598       Bootstrap inline and search forms, which don't use exactly the same
599       kind of control HTML.
600
601       You can always copy the existing wrapper and add your own features,
602       with settings provided by the 'tags' hashref.
603
604   Rendering themes
605       Many of the flags and settings necessary for rendering can now be moved
606       out into a role.  Whether you want to do that or not is a matter of
607       style and preference. The advantage is that it leaves the form class
608       itself cleaner and easier to read. The disadvantage is that your
609       settings come from more different places.
610
611       Here's an example of a form rendering 'theme', taken from the
612       t/bootstrap/basic.t test:
613
614           package MyApp::Form::Basic::Theme;
615           use Moose::Role;
616
617           # make a wrapper around the form
618           sub build_do_form_wrapper {1}
619           # set the class for the form wrapper
620           sub build_form_wrapper_class { ['span9'] }
621           # set the class for the form element
622           sub build_form_element_class { ['well'] }
623           # set various rendering tags
624           sub build_form_tags {
625               {   wrapper_tag => 'div',
626                   before => qq{<div class="row"><div class="span3"><p>With v2.0, we have
627                      lighter and smarter defaults for form styles. No extra markup, just
628                      form controls.</p></div>\n},
629                   after => '</div>',
630               }
631           }
632
633           # the settings in 'build_update_subfields' are merged with the field
634           # definitions before they are constructed
635           sub build_update_subfields {{
636              # all fields have a label but no wrapper
637              all => { do_wrapper => 0, do_label => 1 },
638              # set the element class, a placeholder in element_attr
639              foo => { element_class => ['span3'],
640                  element_attr => { placeholder => 'Type something…' },
641                  tags => { after_element =>
642                     qq{\n<span class="help-inline">Associated help text!</span>} } },
643              bar => { option_label => 'Check me out',
644                 label_class => ['checkbox'], do_label => 0 },
645              submit_btn => { element_class => ['btn'] },
646           }}
647
648       Note that the value 'all' key in the update_subfields hashref will be
649       merged into the attributes used when building all of the fields.
650
651   Rendering fields
652       The default for most fields is a 'div' wrapper and a label. If you
653       don't want the wrapper, set "do_wrapper => 0". If you don't want the
654       label, set "do_label => 0".
655
656       Checkboxes are most complicated, in that the default is to have two
657       labels. The outer label, the one that's in the same place as the label
658       for other input elements, is set with "label => '...'". The inner
659       label, which is the equivalent of the "label => '...'" in the options
660       array used for selects and checkbox groups, is set with "option_label
661       => '...'".  There are a number of other 'tags' to control the
662       presentation. See HTML::FormHandler::Widget::Field::Checkbox for more
663       information, and t/render/checkbox.t for examples.
664
665       Some fields by default do not render a label: Button, Submit, Reset,
666       ButtonTag.  If you do want a label with these fields, you must set the
667       'do_label' flag to 1:
668
669          has_field 'foo' ( type => 'Button', do_label => 1 );
670
671       Select fields are also fairly complicated. They can be rendered with
672       the 'Select', 'RadioGroup', and 'CheckboxGroup' widgets. Option groups
673       are also supported. See HTML::FormHandler::Field::Select;
674
675   Rendering labels
676       A 'standard' label is built in the field if you don't supply one. The
677       label can be provided in the field definition:
678
679           has_field 'foo' => ( label => 'My Foo' );
680
681       You can also provide a method to 'build' the label:
682
683           has_field 'foo' => ( build_label_method => \&build_label );
684           sub build_label {
685               my $self = shift; # field method
686               return '...';
687           }
688
689       And a method to 'wrap' the label (used by the Simple and Bootstrap
690       wrappers):
691
692           has_field 'foo' => ( label => 'My Foo', wrap_label_method => \&wrap_label );
693           sub wrap_label {
694               my ( $self, $label ) = @_;
695               # or: my $label = $self->label;
696               return qq{<a href="...">$label</a>};
697           }
698
699       This is particularly useful for creating labels that have links or
700       other HTML.  The 'wrap_label_method' does no filtering or localization,
701       so you must do that yourself in the method if you need it.
702
703   Rendering filter
704       The base field class has a 'render_filter' attribute which is a coderef
705       used to clean the values used to fill in the form for Render::Simple
706       and the Widgets, and for some of the labels..  The default filter
707       changes quote, ampersand, <, and > to the equivalent html entities. If
708       you wish to use some other sort of filtering, you can use the
709       'render_filter' method in your form, or set a coderef on individual
710       field objects. A 'render_filter' function in your form will be used by
711       all fields.  Setting it for a field will just be for that field.
712
713           sub render_filter {
714               my $string = shift;
715               $string =~ s/my/MY/g; # perform some kind of transformation
716               return $string;
717           }
718           -- or --
719           has_field 'foo' => ( render_filter => sub { ... } );
720
721       The filter is called in Render::Simple and in the widgets with
722       "$self->html_filter( $fif )" or "$field->html_filter( $fif )".
723
724       If you want to turn off the filter for a particular field, you can set
725       it to a sub that just returns the value:
726
727           has_field 'bar' => ( render_filter => sub { shift } );
728
729       If you want a label that is unfiltered, see 'wrap_label_method'.
730

Special rendering pseudo-fields

732       Also see HTML::FormHandler::Widget::Block. Blocks may be a better
733       solution than pseudo-fields (i.e. fields that aren't actual form
734       elements).
735
736       Various 'tags' used for rendering can also be used for similar
737       purposes.
738
739   NonEditable
740       Like a Bootstrap 'non_editable' field. Displays the field's value as a
741       span.
742
743           has_field 'non_edit' => ( type => 'NonEditable', value => 'This is a Test' );
744
745   Display
746       HTML::FormHandler::Field::Display
747
748       You can supply an HTML string to this field, to be displayed directly.
749       There is no 'value' associated with this field; it's a field for
750       rendering only. The HTML string can be built with a form or field
751       method.
752
753       Blocks or tags will often be a better solution.
754

AUTHOR

756       FormHandler Contributors - see HTML::FormHandler
757
759       This software is copyright (c) 2017 by Gerda Shank.
760
761       This is free software; you can redistribute it and/or modify it under
762       the same terms as the Perl 5 programming language system itself.
763
764
765
766perl v5.38.0                      2023-0H7T-M2L0::FormHandler::Manual::Rendering(3)
Impressum