.\" Automatically generated by Pod::Man 4.14 (Pod::Simple 3.42)
.\"
.\" Standard preamble:
.\" ========================================================================
.de Sp \" Vertical space (when we can't use .PP)
.if t .sp .5v
.if n .sp
..
.de Vb \" Begin verbatim text
.ft CW
.nf
.ne \\$1
..
.de Ve \" End verbatim text
.ft R
.fi
..
.\" Set up some character translations and predefined strings.  \*(-- will
.\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left
.\" double quote, and \*(R" will give a right double quote.  \*(C+ will
.\" give a nicer C++.  Capital omega is used to do unbreakable dashes and
.\" therefore won't be available.  \*(C` and \*(C' expand to `' in nroff,
.\" nothing in troff, for use with C<>.
.tr \(*W-
.ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p'
.ie n \{\
.    ds -- \(*W-
.    ds PI pi
.    if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch
.    if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\"  diablo 12 pitch
.    ds L" ""
.    ds R" ""
.    ds C` ""
.    ds C' ""
'br\}
.el\{\
.    ds -- \|\(em\|
.    ds PI \(*p
.    ds L" ``
.    ds R" ''
.    ds C`
.    ds C'
'br\}
.\"
.\" Escape single quotes in literal strings from groff's Unicode transform.
.ie \n(.g .ds Aq \(aq
.el       .ds Aq '
.\"
.\" If the F register is >0, we'll generate index entries on stderr for
.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index
.\" entries marked with X<> in POD.  Of course, you'll have to process the
.\" output yourself in some meaningful fashion.
.\"
.\" Avoid warning from groff about undefined register 'F'.
.de IX
..
.nr rF 0
.if \n(.g .if rF .nr rF 1
.if (\n(rF:(\n(.g==0)) \{\
.    if \nF \{\
.        de IX
.        tm Index:\\$1\t\\n%\t"\\$2"
..
.        if !\nF==2 \{\
.            nr % 0
.            nr F 2
.        \}
.    \}
.\}
.rr rF
.\" ========================================================================
.\"
.IX Title "Catalyst::Controller::FormBuilder 3pm"
.TH Catalyst::Controller::FormBuilder 3pm "2022-06-09" "perl v5.34.0" "User Contributed Perl Documentation"
.\" For nroff, turn off justification.  Always turn off hyphenation; it makes
.\" way too many mistakes in technical documents.
.if n .ad l
.nh
.SH "NAME"
Catalyst::Controller::FormBuilder \- Catalyst FormBuilder Base Controller
.SH "SYNOPSIS"
.IX Header "SYNOPSIS"
.Vb 2
\&    package MyApp::Controller::Books;
\&    use base \*(AqCatalyst::Controller::FormBuilder\*(Aq;
\&
\&    # optional config setup
\&    _\|_PACKAGE_\|_\->config(
\&        \*(AqController::FormBuilder\*(Aq = {
\&            template_type => \*(AqHTML::Template\*(Aq,    # default is \*(AqTT\*(Aq (e.g. TT2)
\&        }
\&    );
\&
\&    # looks for books/edit.fb form configuration file, based on the presence of
\&    # the ":Form" attribute.
\&    sub edit : Local Form {
\&        my ( $self, $c, @args ) = @_;
\&
\&        my $form = $self\->formbuilder;
\&
\&        # add email form field to fields already defined edit.fb
\&        $form\->field( name => \*(Aqemail\*(Aq, validate => \*(AqEMAIL\*(Aq );
\&
\&        if ( $form\->submitted ) {
\&            if ( $form\->validate ) {
\&                return $c\->response\->body("VALID FORM");
\&            }
\&            else {
\&                $c\->stash\->{ERROR}          = "INVALID FORM";
\&                $c\->stash\->{invalid_fields} =
\&                  [ grep { !$_\->validate } $form\->fields ];
\&            }
\&        }
\&    }
\&
\&    # explicitedly use books/edit.fb, otherwise books/view.fb is used
\&    sub view : Local Form(\*(Aq/books/edit\*(Aq) {
\&        my ( $self, $c ) = @_;
\&        $c\->stash\->{template} = "books/edit.tt" # TT2 template;
\&    }
.Ve
.SH "DESCRIPTION"
.IX Header "DESCRIPTION"
This base controller merges the functionality of \fBCGI::FormBuilder\fR with
Catalyst and the following templating systems: Template Toolkit, Mason and
HTML::Template. This gives you access to all of FormBuilder's niceties,
such as controllablefield stickiness, multilingual support, and Javascript
generation. For more details, see CGI::FormBuilder or the website at:
.PP
.Vb 1
\&    http://www.formbuilder.org
.Ve
.PP
FormBuilder usage within Catalyst is straightforward. Since Catalyst handles
page rendering, you don't call FormBuilder's \f(CW\*(C`render()\*(C'\fR method, as you
would normally. Instead, you simply add a \f(CW\*(C`:Form\*(C'\fR attribute to each method
that you want to associate with a form. This will give you access to a
FormBuilder \f(CW\*(C`$self\->formbuilder\*(C'\fR object within that controller method:
.PP
.Vb 5
\&    # An editing screen for books
\&    sub edit : Local Form {
\&        my ( $self, $c ) = @_;
\&        $self\->formbuilder\->method(\*(Aqpost\*(Aq);   # set form method
\&    }
.Ve
.PP
The out-of-the-box setup is to look for a form configuration file that follows
the CGI::FormBuilder::Source::File format (essentially \s-1YAML\s0), named for the
current action url. So, if you were serving \f(CW\*(C`/books/edit\*(C'\fR, this plugin
would look for:
.PP
.Vb 1
\&    root/forms/books/edit.fb
.Ve
.PP
(The path is configurable.) If no source file is found, then it is assumed
you'll be setting up your fields manually. In your controller, you will
have to use the \f(CW\*(C`$self\->formbuilder\*(C'\fR object to create your fields,
validation, and so on.
.PP
Here is an example \f(CW\*(C`edit.fb\*(C'\fR file:
.PP
.Vb 10
\&    # Form config file root/forms/books/edit.fb
\&    name: books_edit
\&    method: post
\&    fields:
\&        title:
\&            label: Book Title
\&            type:  text
\&            size:  40
\&            required: 1
\&        author:
\&            label: Author\*(Aqs Name
\&            type:  text
\&            size:  80
\&            validate: NAME
\&            required: 1
\&        isbn:
\&            label: ISBN#
\&            type:  text
\&            size:  20
\&            validate: /^(\ed{10}|\ed{13})$/
\&            required: 1
\&        desc:
\&            label: Description
\&            type:  textarea
\&            cols:  80
\&            rows:  5
\&
\&    submit: Save New Book
.Ve
.PP
This will automatically create a complete form for you, using the
specified fields. Note that the \f(CW\*(C`root/forms\*(C'\fR path is configurable;
this path is used by default to integrate with the \f(CW\*(C`TTSite\*(C'\fR helper.
.PP
Within your controller, you can call any method that you would on a
normal \f(CW\*(C`CGI::FormBuilder\*(C'\fR object on the \f(CW\*(C`$self\->formbuilder\*(C'\fR object.
To manipulate the field named \f(CW\*(C`desc\*(C'\fR, simply call the \f(CW\*(C`field()\*(C'\fR
method:
.PP
.Vb 6
\&    # Change our desc field dynamically
\&    $self\->formbuilder\->field(
\&        name     => \*(Aqdesc\*(Aq,
\&        label    => \*(AqBook Description\*(Aq,
\&        required => 1
\&    );
.Ve
.PP
To populate field options for \f(CW\*(C`country\*(C'\fR, you might use something like
this to iterate through the database:
.PP
.Vb 6
\&    $self\->formbuilder\->field(
\&        name    => \*(Aqcountry\*(Aq,
\&        options =>
\&          [ map { [ $_\->id, $_\->name ] } $c\->model(\*(AqMyApp::Country\*(Aq)\->all ],
\&        other => 1,    # create "Other:" box
\&    );
.Ve
.PP
This would create a select list with the last element as \*(L"Other:\*(R" to allow
the addition of more countries. See CGI::FormBuilder for methods
available to the form object.
.PP
The FormBuilder methodolody is to handle both rendering and validation
of the form. As such, the form will \*(L"loop back\*(R" onto the same controller
method. Within your controller, you would then use the standard FormBuilder
submit/validate check:
.PP
.Vb 3
\&    if ( $self\->formbuilder\->submitted && $self\->formbuilder\->validate ) {
\&        $c\->forward(\*(Aq/books/save\*(Aq);
\&    }
.Ve
.PP
This would forward to \f(CW\*(C`/books/save\*(C'\fR if the form was submitted and
passed field validation. Otherwise, it would automatically re-render the
form with invalid fields highlighted, leaving the database unchanged.
.PP
To render the form in your tt2 template for example, you can use \f(CW\*(C`render\*(C'\fR
to get a default table-based form:
.PP
.Vb 2
\&    <!\-\- root/src/books/edit.tt \-\->
\&    [% FormBuilder.render %]
.Ve
.PP
You can also get fine-tuned control over your form layout from within
your template.
.SH "TEMPLATES"
.IX Header "TEMPLATES"
The simplest way to get your form into \s-1HTML\s0 is to reference the
\&\f(CW\*(C`FormBuilder.render\*(C'\fR method, as shown above. However, frequently you
want more control.
.PP
Only Template Toolkit, Mason and HTML::Template are currently supported, but
if your templating system's stash requirements are identical to one of these,
simply choose and define it via the \f(CW\*(C`template_type\*(C'\fR config option.  Of course,
make sure you have a View to support the template, since this module does not
render templates.
.PP
From within your template, you can reference any of FormBuilder's
methods to manipulate form \s-1HTML,\s0 JavaScript, and so forth. For example,
you might want exact control over fields, rendering them in a \f(CW\*(C`<div>\*(C'\fR
instead of a table. You could do something like this:
.PP
.Vb 10
\&    <!\-\- root/src/books/edit.tt \-\->
\&    <head>
\&      <title>[% formbuilder.title %]</title>
\&      [% formbuilder.jshead %]<!\-\- javascript \-\->
\&    </head>
\&     <body>
\&      [% formbuilder.start \-%]
\&      <div id="form">
\&        [% FOREACH field IN formbuilder.fields \-%]
\&        <p>
\&            <label>
\&               <span [% IF field.required %]class="required"[%END%]>[%field.label%]</span>
\&            </label>
\&          [% field.field %]
\&          [% IF field.invalid \-%]
\&              <span class="error">
\&                  Missing or invalid entry, please try again.
\&              </span>
\&          [% END %]
\&          </p>
\&        [% END %]
\&        <div id="submit">[% formbuilder.submit %]</div>
\&        <div id="reset">[% formbuilder.reset %]</div>
\&        </div>
\&      </div>
\&      [% formbuilder.end \-%]
\&    </body>
.Ve
.PP
In this case, you would \fBnot\fR call \f(CW\*(C`FormBuilder.render\*(C'\fR, since that would
only result in a duplicate form (once using the above expansion, and
a second time using FormBuilder's default rendering).
.PP
Note that the above form could become a generic \f(CW\*(C`form.tt\*(C'\fR template
which you simply included in all your files, since there is nothing
specific to a given form hardcoded in (that's the idea, after all).
.PP
You can also get some ideas based on FormBuilder's native Template Toolkit
support at CGI::FormBuilder::Template::TT2.
.SH "CONFIGURATION"
.IX Header "CONFIGURATION"
You can set defaults for your forms using Catalyst's config method inside
your controller.
.PP
.Vb 10
\&    _\|_PACKAGE_\|_\->config(
\&        \*(AqController::FormBuilder\*(Aq => {
\&            new => {
\&                method     => \*(Aqpost\*(Aq,
\&                # stylesheet => 1,
\&                messages   => \*(Aq/locale/fr_FR/form_messages.txt\*(Aq,
\&            },
\&            form_path =>
\&              File::Spec\->catfile( $c\->config\->{home}, \*(Aqroot\*(Aq, \*(Aqforms\*(Aq ),
\&            method_name   => \*(Aqform\*(Aq,
\&            template_type => \*(AqHTML::Template\*(Aq,
\&            stash_name    => \*(Aqform\*(Aq,
\&            obj_name      => \*(AqFormBuilder\*(Aq,
\&            form_suffix   => \*(Aqfb\*(Aq,
\&            attr_name     => \*(AqForm\*(Aq,
\&            source_type   => \*(AqCGI::FormBuilder::Source::File\*(Aq,
\&        }
\&    );
.Ve
.ie n .IP """new""" 4
.el .IP "\f(CWnew\fR" 4
.IX Item "new"
This accepts the exact same options as FormBuilder's \f(CW\*(C`new()\*(C'\fR method
(which is a lot). See CGI::FormBuilder for a full list of options.
.ie n .IP """form_path""" 4
.el .IP "\f(CWform_path\fR" 4
.IX Item "form_path"
The path to configuration files. This should be set to an absolute
path to prevent problems. By default, it is set to:
.Sp
.Vb 1
\&    File::Spec\->catfile( $c\->config\->{home}, \*(Aqroot\*(Aq, \*(Aqforms\*(Aq )
.Ve
.Sp
This can be a colon-separated list of directories if you want to
specify multiple paths (ie, \*(L"/templates1:/template2\*(R"), or an array
ref (ie, [qw/template1 templates2/]).
.ie n .IP """form_suffix""" 4
.el .IP "\f(CWform_suffix\fR" 4
.IX Item "form_suffix"
The suffix that configuration files have. By default, it is \f(CW\*(C`fb\*(C'\fR.
.ie n .IP """method_name""" 4
.el .IP "\f(CWmethod_name\fR" 4
.IX Item "method_name"
Accessor method name available in your controller. By default, it is
\&\f(CW\*(C`formbuilder\*(C'\fR.
.ie n .IP """template_type""" 4
.el .IP "\f(CWtemplate_type\fR" 4
.IX Item "template_type"
Defines the Catalyst View that the stash will be prepared for. Possible
values are: HTML::Template, Mason, \s-1TT.\s0 By default, it is \f(CW\*(C`TT\*(C'\fR.
.ie n .IP """stash_name""" 4
.el .IP "\f(CWstash_name\fR" 4
.IX Item "stash_name"
Not applicable for HTML::Template view.  By default, it is \f(CW\*(C`formbuilder\*(C'\fR.
e.g. \f(CW$c\fR\->stash\->{formbuilder} = \f(CW$formbuilder\fR\->prepare.
.ie n .IP """obj_name""" 4
.el .IP "\f(CWobj_name\fR" 4
.IX Item "obj_name"
Not applicable for HTML::Template view. By default, it is \f(CW\*(C`FormBuilder\*(C'\fR.
e.g. \f(CW$c\fR\->stash\->{FormBuilder} = \f(CW$formbuilder\fR.
.ie n .IP """attr_name""" 4
.el .IP "\f(CWattr_name\fR" 4
.IX Item "attr_name"
The attribute name. By default, it is \f(CW\*(C`Form\*(C'\fR.
e.g. sub edit : Form { ... }
.ie n .IP """source_type""" 4
.el .IP "\f(CWsource_type\fR" 4
.IX Item "source_type"
The source adapter class name. By default, it is
\&\f(CW\*(C`CGI::FormBuilder::Source::File\*(C'\fR. See CGI::FormBuilder::Source
.PP
In addition, the following FormBuilder options are automatically set for you:
.ie n .IP """action""" 4
.el .IP "\f(CWaction\fR" 4
.IX Item "action"
This is set to the \s-1URL\s0 for the current action. \fBFormBuilder\fR is designed
to handle a full request cycle, meaning both rendering and submission. If
you want to override this, simply use the \f(CW\*(C`$self\->formbuilder\*(C'\fR object:
.Sp
.Vb 1
\&    $self\->formbuilder\->action(\*(Aq/action/url\*(Aq);
.Ve
.Sp
The default setting is \f(CW\*(C`$c\->req\->path\*(C'\fR.
.ie n .IP """cookies""" 4
.el .IP "\f(CWcookies\fR" 4
.IX Item "cookies"
Handling these are disabled (use Catalyst).
.ie n .IP """debug""" 4
.el .IP "\f(CWdebug\fR" 4
.IX Item "debug"
This is set to correspond with Catalyst's debug setting.
.ie n .IP """header""" 4
.el .IP "\f(CWheader\fR" 4
.IX Item "header"
This is disabled. Instead, use Catalyst's header routines.
.ie n .IP """params""" 4
.el .IP "\f(CWparams\fR" 4
.IX Item "params"
This is set to get parameters from Catalyst, using \f(CW\*(C`$c\->req\*(C'\fR.
To override this, use the \f(CW\*(C`$self\->formbuilder\*(C'\fR object:
.Sp
.Vb 1
\&    $self\->formbuilder\->params(\e%param_hashref);
.Ve
.Sp
Overriding this is not recommended.
.ie n .IP """source""" 4
.el .IP "\f(CWsource\fR" 4
.IX Item "source"
This determines which source file is loaded, to setup your form. By
default, this is set to the name of the action \s-1URL,\s0 with \f(CW\*(C`.fb\*(C'\fR appended.
For example, \f(CW\*(C`edit_form()\*(C'\fR would be associated with an \f(CW\*(C`edit_form.fb\*(C'\fR
source file.
.Sp
To override this, include the path as the argument to the method attribute:
.Sp
.Vb 1
\&    sub edit : Local Form(\*(Aq/books/myEditForm\*(Aq) { }
.Ve
.Sp
If no source file is found, then it is assumed you'll be setting up your
fields manually. In your controller, you will have to use the
\&\f(CW\*(C`$self\->formbuilder\*(C'\fR object to create your fields, validation, and so on.
.SH "SEE ALSO"
.IX Header "SEE ALSO"
CGI::FormBuilder, CGI::FormBuilder::Source::File,
CGI::FormBuilder::Template::TT2, Catalyst::Manual,
Catalyst::Request, Catalyst::Response
.SH "AUTHOR"
.IX Header "AUTHOR"
Copyright (c) 2006 Juan Camacho <formbuilder@suspenda.com>. All Rights Reserved.
.PP
Thanks to Laurent Dami and Roy-Magne Mo for suggestions.
.PP
This library is free software, you can redistribute it and/or modify
it under the same terms as Perl itself.