/ 
Data-MuForm-0.02
River stage one • 3 direct dependents • 3 total dependents
/ Data::MuForm::Renderer::Base

NAME

Data::MuForm::Renderer::Base - Renderer

VERSION

version 0.02

DESCRIPTION

Base functionality for renderers, including rendering standard form controls.

You should normally create your own custom renderer class which inherits from this one. In it you should set the various standard defaults for your rendering, and override some of the methods, like 'render_errors'. You should also create custom layouts using the layout sub naming convention so they can be found.

There is a 'render_hook' which can be used to customize things like classes and attributes. It is called on every 'render_field', 'render_element', 'render_errors', and 'render_label' call. The hook can be used in the renderer or in the form class, whichever is most appropriate.

This is Perl code, and can be customized however you want. This base renderer is supplied as a library of useful routines. You could replace it entirely if you want, as long you implement the methods that are used in the form and field classes.

As part of an attempt to separate the core code more from the rendering code, and limit the explosion of various rendering attributes, the rendering is always done using a 'render_args' hashref of the pieces of the form and field that are needed for rendering. Most of the rendering settings are set as keys in the render_args hashref, with some exceptions. This means that you can just start using a new render_args hashref key in your custom rendering code without having to do anything special to get it there. You have to set it somewhere of course, either in the field definition or passed in on the rendering calls.

For a particular field, the field class will supply a 'base_render_args', which is merged with the 'render_args' from the field definition, which is merged with the 'render_args' from the actual rendering call.

One of the main goals of this particular rendering iteration has been to make it easy and seamless to limit rendering to only the field elements, so that all of the complicated divs and classes that are necessary for recent 'responsive' CSS frameworks can be done in the templates under the control of the frontend programmers.

[% form.field('foo').render_element({ class => 'mb10 tye', placeholder => 'Type...'}) %]

Or render the element, the errors and the labels, and do all of the other formatting in the template:

[% field = form.field('foo') %]
<div class="sm tx10">
   [% field.render_label({ class="cxx" }) %]
   <div class="xxx">
     [% field.render_element({ class => 'mb10 tye', placeholder => 'Type...'}) %]
   </div>
   <div class="field-errors">[% field.render_errors %]</div>
</div>

And yet another goal has been to make it possible to render a form automatically and have it just work.

[% form.render %]

Renderer defaults

standard_layout

For normal inputs and select fields.

Provided:

lbl_ele_err    - label, element, error
lbl_wrele_err  - label, wrapped element, error

Create new layouts starting with 'layout_<name>'.

cb_layout

Default checkbox layout. Create new checkbox layouts with methods starting with 'cb_layout_<name>'.

Provided:

cbwrll - checkbox, wrapped, label left
cbwrlr - checkbox, wrapped, label right
cbnowrll - checkbox, not wrapped, label left
cb2l   - checkbox, 2 labels
rdgo_layout

Default radiogroup option layout

Provided:

labels_left
labels_right

Supply more with 'rdgo_layout_<name>'.

cbgo_layout

Default checkbox group option layout

Provided:

labels_left
labels_right

Supply more with 'cbgo_layout_<name>'.

display_layout

Default 'display' field layout.

Provided:

span

Provide more options with 'layout_<name>'.

field_wrapper

Default field wrapper. Supply more with 'wrapper_<name>'.

Provided:

simple
fieldset
wrapper_tag

Default wrapper tag. Default: 'div'.

error_tag

Default error tag.

NAME

Data::MuForm::Renderer::Base

Layouts

The 'standard' layouts are for all fields that don't have another layout type. This includes text fields, selects, and textareas. Create a new layout with 'layout_<layout-name'. Included layouts are 'lbl_ele_err' and 'no_label'. The default is 'lbl_ele_err', which renders a label, the form control, and then error messages.

The 'radiogroup' layouts are for radiogroups, which is a 'Select' field layout type. Create a new layout with 'rd_layout_<layout name>'. Radiogroup option layouts are named 'rdgo_layout_<layout name>'. The provided layouts are 'right_label' and 'left_label'.

Checkbox layout methods are named 'cb_layout_<layout name>'. The provided layouts are 'cbwrll' - checkbox wrapped, label left, 'cbwrlr' - checkbox wrapped, label right, 'cb2l' - checkbox with two labels, 'cbnowrll' - checkbox unwrapped, label left.

The checkbox group layouts are another 'Select' field layout type. Checkbox group options layouts are named 'cbgo_layout_<layout name>'.

Form and Field methods

In the field:

render (render_field, render_compound or render_repeatable in the renderer)
render_element (for standard single elements)
render_label
render_errors

In the Select field:

render_option (for select, radio group and checkbox group)

In the form:

render (render_form in the renderer)
render_start
render_end
render_errors (render_form_errors in the renderer)

add_to_class

Utility class used to add to the 'class' key of an attribute hashref, handling arrayref/not-arrayref, etc. Used to add 'error' and 'required' classes.

process_attrs

Takes a hashref of key-value pairs to be rendered into HTML attributes. Second param ($skip) is keys to skip in the hashref.

All 'values' are html filtered.

render_input

render_select

render_textarea

render_element

render_label

render_errors

render_checkbox

cbwrll

Checkbox, wrapped, label left

<label class="checkbox" for="option1"><input id="option1" name="option1" type="checkbox" value="1" /> Option1 </label>

cbwrlr

Checkbox wrapped, label right

cbnowrll

Checkbox not wrapped, label left

AUTHOR

Gerda Shank

COPYRIGHT AND LICENSE

This software is copyright (c) 2017 by Gerda Shank.

This is free software; you can redistribute it and/or modify it under the same terms as the Perl 5 programming language system itself.