NAME

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

VERSION

version 0.05

DESCRIPTION

Base functionality for renderers, including rendering standard form controls.

You can use this base renderer if it does everything that you need. The various attributes can be set in a form class:

  sub build_renderer_args { { error_tag => 'label' } }

In many cases you might want to create your own custom renderer class which inherits from this one. In it you can set the various standard defaults for your rendering, and override some of the methods, like 'render_errors'. You can 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 a custom renderer or in the form class, whichever is most appropriate.

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.

The rendering is always done using a 'render_args' hashref of the pieces of the form and field that are needed for rendering. Instead of having lots of rendering attributes in the fields, with additional rendering pieces and settings in other attributes (like the 'tags' hashref in FormHandler, most of the rendering settings are passed along as keys in the render_args hashref.

The 'render_args' can be defined in a field definition:

  has_field 'foo' => ( type => 'Text', render_args => { element => { class => ['abc', 'def'] }} );
  or
  has_field 'foo' => ( type => 'Text', 'ra.ea.class' => ['abc', 'def'] );

Or passed in on a render call:

  $field->render({ 'ea.class' => 'abc' });

If you have custom rendering code that depends on some new flag, you can just start using a new render_args hashref key in your custom 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>

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

  [% form.render %]

Renderer attributes

In a form class:

  sub build_renderer_args { { error_tag => 'label', cb_layout => 'cbwrll' } }

In a Renderer subclass:

  has '+error_tag' => ( default => 'label' );
  has '+cb_layout' => ( default => 'cbwrll' );

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.

error_class

The default class added to the rendered errors.

render_element_errors

This is for when you are just doing 'render_element', but want to also render the errors, without having to do a separate call. It's off by default.

is_html5

Render using the html5_input_type for the field (if one exists). Currently the following fields have an html5_input_type: Currency (number), Date (date), Email (email), Integer (number), URL (url). You can set the html5_input_type in the field definition.

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) 2018 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.

cpanm Data::MuForm

perl -MCPAN -e shell
install Data::MuForm