/ 
Form-Tiny-Plugin-Diva-1.03
River stage zero No dependents
/ Form::Tiny::Plugin::Diva

NAME

Form::Tiny::Plugin::Diva - Form::Diva integration for Form::Tiny

SYNOPSIS

### Form configuration

use Form::Tiny plugins => ['Diva'];

# Form::Diva configuration can be passed using diva_config
diva_config label_class => 'my-label-class';

# data of fields is used as an input to Form::Diva
# note: name is added automatically from field name
form_field 'normal_edit' => (
	data => {type => 'text'},
);

# passing type => 'hidden' will make the field hidden in diva
form_field 'hidden' => (
	data => {type => 'hidden'},
);

# if there is no data section at all, the field is also treated as hidden
# default value in form is used
form_field 'also_hidden' => (
	default => sub { 55 },
);


### Using Form::Diva

my $form = MyFormPackage->new;
$form->set_input({normal_edit => 'edited!'});

# Form::Diva adapter - see Form::Diva docs
my $diva = $form->diva;

# no need to pass the data in first argument to functions that need it
print Dumper($form->generated);

DESCRIPTION

This plugin adds some HTML outputting capabilities to Form::Tiny forms using Form::Diva.

CONFIGURATION

This plugin can be added to Form::Tiny with the following line:

use Form::Tiny plugins => ['Diva'];

Form::Diva form scope configuration

By default, these values will be passed to Form::Diva constructor:

id_base => 'form-field-',
label_class => 'form-label',
input_class => 'form-control',
error_class => 'invalid-feedback',

These can be changed by a call to a new diva_config DSL keyword:

# one or more at a time
diva_config
	label_class => 'form-label',
	input_class => 'form-control';

Form::Diva field scope configuration

All fields defined in the form will be passed into Form::Diva constructor:

  • fields with no data attribute will be used as hidden fields

  • fields with data attribute must have it as a hash reference and will be used as regular fields, unless type => 'hidden' is specified

Contents of data are documented in "form" in Form::Diva. A couple of notes:

  • name will be automatically copied over from Form::Tiny field name, so there's no need to write it out loud

  • default will be copied over from Form::Tiny default, but only if not explicitly passed

  • comment is reserved for internal use

Printing out the form

You can get a preconfigured diva object by calling diva method on your form instance:

my $diva = $form_instance->diva;

This is a subclass of Form::Diva, and it behaves slightly differently. The main difference is that you no longer need to pass the data explicitly into methods like generate or prefill, as the form input will be used by default:

# no arguments, yet will use $form_instance->input
my $generated = $diva->generated;

Additionally, all generated fields will have an extra hash key, errors which will contain the string with errors ready to be put into HTML:

my $errors = $generated->[0]{errors};

When there are no errors, this value will be empty (but never undefined). You can reliably use it with your template engine to print errors. Note that no form scope errors are included - for those you will have to call another method form_errors on diva adapter:

my $global_errors = $diva->form_errors;

You can configure the HTML class of error containers with error_class configuration field (see above).

LIMITATIONS

  • No support for nesting - neither nested arrays nor hashes

    Form should print without problems, but will not accept the data back from HTML without modification.

  • Occupies 'comment' field from Form::Diva

    Comment field is needed to pass metadata through the generation mechanism. Contents of this field explicitly configured in forms will be discarded.

SEE ALSO

Form::Tiny

Form::Diva

AUTHOR

Bartosz Jarzyna, <bbrtj.pro@gmail.com>

COPYRIGHT AND LICENSE

Copyright (C) 2022 by Bartosz Jarzyna

This library is free software; you can redistribute it and/or modify it under the same terms as Perl itself, either Perl version 5.34.0 or, at your option, any later version of Perl 5 you may have available.