1HTML::FormHandler::ManuUasle:r:RCeonndterriibnugt(e3d)PHeTrMlL:D:oFcourmmeHnatnadtlieorn::Manual::Rendering(3)
2
6 HTML::FormHandler::Manual::Rendering - how to render with FormHandler
7
9 version 0.40068
10
12 Manual Index
13 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
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 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 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 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 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 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 Form used in examples:
51 package MyApp::Form::Example;
53 use HTML::FormHandler::Moose;
54 extends 'HTML::FormHandler';
55 has_field 'foo';
57 has_field 'bar';
58 has_field 'save' => ( type => 'Submit' );
59 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 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 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 *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 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 Going a little bit farther in using FormHandler rendering, you can
92 render each of the fields individually, using 'render' or 'renderx':
93 <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 If you don't want the wrappers, use a widget_wrapper of 'None'.
103 has '+widget_wrapper' => ( default => 'None' );
105 Then you can provide the HTML in which the form elements are embedded:
107 <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 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 <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 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 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 See also HTML::FormHandler::Manual::Templates.
138 Automatic rendering
140 If you take all the defaults, you can simply render a form with
141 "$form->render".
142 [% form.render %]
144 or
145 [% form.renderx( form_element_class => ['xxx'] ) %]
146 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 with 'HTML::FormHandler::Widget::Form::Table';
152 has '+widget_wrapper' => ( default => 'Table' );
153 For the 'Table' form widget, you will also need to set the matching
155 Table widget_wrapper.
156 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 has_field 'foxy' => ( widget => 'MyWidget', widget_wrapper => 'MyWrapper' );
163 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 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 has '+widget_name_space' => ( default => sub { ['MyApp::Form::Widget' ] } );
177 For the above widget ('MyWidget') and widget_name_space, you need to
179 have a package named 'MyApp::Form::Widget::Field::MyWidget'.
180 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 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 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 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 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 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 has_field 'foo' => ( wrapper_class => ['form', 'special' ] );
221 See the documentation on "Attributes_for_creating_HTML" in
223 HTML::FormHandler::Field.
224 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 do_form_wrapper
232 Flag set with 'sub build_do_form_wrapper{ 1 }'. Default is no form
233 wrapper.
234 form_tags
236 Hashref of various tags used in rendering code. See the
237 documentation for HTML::FormHandler::Widget::Form::Simple.
238 form_element_attr
240 Hashref of arbitrary HTML attributes to be included in the form
241 element.
242 sub build_form_element_attr { [ ... ] }
244 form_element_class
246 Arrayref of classes to be included in the form element.
247 form_element_class => ['hfh', 'admin']
249 -- or in your class --
250 sub build_form_element_class { ['hfh', 'admin'] }
251 The above class would produce a form element:
253 <form id="myform" method="post" class="hfh admin">
255 form_wrapper_attr
257 Hashref of arbitrary HTML attributes to be included in the form
258 wrapper
259 sub build_form_wrapper_attr { { name => 'formname' } }
261 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 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 has '+success_message' => ( default => 'Form successfully submitted' );
274 has '+error_message' => ( default => 'There were errors in your form.' );
275 And then are displayed after the form is validated.
277 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 $form->process( params => {}, info_message => 'Fill in the form' );
282 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 widget
290 Short name of the rendering widget for this field.
291 widget_wrapper
293 Short name of the wrapping widget for this field.
294 do_wrapper
296 Flag that indicates whether or not the 'wrapper' should be
297 rendered.
298 do_label
300 Flag that indicates whether or not a label should be rendered.
301 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 element_class
309 Arrayref of classes to include in the element.
310 wrapper_attr
312 Hashref of arbitrary HTML attributes to include in the wrapper.
313 wrapper_class
315 Arrayref of classes to include in the wrapper.
316 label_attr
318 Hashref of arbitrary HTML attributes to include in the label.
319 label_class
321 Arrayref of classes to include in the label.
322 build_id_method
324 Coderef to construct the 'id'. Useful if your javascript needs a
325 different format for the 'id'.
326 build_label_method
328 Coderef to construct the label.
329 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 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 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 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 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 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 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 has_field 'my_field' => (
371 tags => {wrapper_tag => 'p', label_after => ': ' } );
372 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 Tag types
379 The 'get_tag' method will check for these three types of tags and
381 perform the appropriate action.
382 String
384 Standard, most common type of value for a tag.
385 has_field 'bar' => ( tags => { before_element => '<span>...</span>' } );
387 Some tags are true/false also:
389 has_field 'foo' => ( type => 'CheckBox',
391 tags => { no_wrapped_label => 1 } );
392 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 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 Block
405 You can supply a block by giving a string that consists of a '%'
406 followed by the block name:
407 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 Tags and other settings for all fields
413 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 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 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 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 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 In a role you would have to do the equivalent with an 'around' method
448 modifier.
449 Repeatable field instances
451 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 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 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 widget and widget_wrapper set to 'None'
468 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 Error messages
475 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 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 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 '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 Here is the definition of a fieldset block that contains two fields:
501 has_field 'foo';
503 has_field 'bar';
504 has_block 'first_fset' => ( tag => 'fieldset, label => 'Two Fields',
505 render_list => ['foo', 'bar'] );
506 The 'first_fset' block will render like this:
508 <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 You can also provide a method to 'build' the block's render list
521 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 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 sub build_render_list { ['first_fset', 'submit_btn'] }
530 You could also render it with "$form->block('first_fset')->render".
532 Blocks should be located in a widget name space, in a 'Block'
534 directory, or else the name should be prefixed with a '+'.
535 has '+widget_name_space' => ( default => sub { ['MyApp::Form::Widget'] };
537 has_block 'first' => ( type => 'MyBlock', ... );
538 The 'MyBlock' above will be found in
540 'MyApp::Form::Widget::Block::MyBlock'.
541 has_block 'intro' => ( type => '+MyApp::Form::Component::Intro' );
543 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 The following package provides a functional block:
550 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 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 Note that you must be rendering with widgets to use block rendering.
573 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 <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 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 has '+widget_wrapper' => ( default => 'Bootstrap' );
591 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 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 You can always copy the existing wrapper and add your own features,
602 with settings provided by the 'tags' hashref.
603 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 Here's an example of a form rendering 'theme', taken from the
612 t/bootstrap/basic.t test:
613 package MyApp::Form::Basic::Theme;
615 use Moose::Role;
616 # 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 # 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 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 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 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 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 has_field 'foo' ( type => 'Button', do_label => 1 );
670 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 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 has_field 'foo' => ( label => 'My Foo' );
680 You can also provide a method to 'build' the label:
682 has_field 'foo' => ( build_label_method => \&build_label );
684 sub build_label {
685 my $self = shift; # field method
686 return '...';
687 }
688 And a method to 'wrap' the label (used by the Simple and Bootstrap
690 wrappers):
691 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 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 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 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 The filter is called in Render::Simple and in the widgets with
722 "$self->html_filter( $fif )" or "$field->html_filter( $fif )".
723 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 has_field 'bar' => ( render_filter => sub { shift } );
728 If you want a label that is unfiltered, see 'wrap_label_method'.
730
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 Various 'tags' used for rendering can also be used for similar
737 purposes.
738 NonEditable
740 Like a Bootstrap 'non_editable' field. Displays the field's value as a
741 span.
742 has_field 'non_edit' => ( type => 'NonEditable', value => 'This is a Test' );
744 Display
746 HTML::FormHandler::Field::Display
747 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 Blocks or tags will often be a better solution.
754
756 FormHandler Contributors - see HTML::FormHandler
757
759 This software is copyright (c) 2017 by Gerda Shank.
760 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.
763perl v5.38.0 2023-0H7T-M2L0::FormHandler::Manual::Rendering(3)