Cataly...Builder(3pm)

💖 Catalyst::Controller::FormBuilder(3pm) 💖

okay bestie, gather round 🫶 this is a User Contributed Perl Documentation page, and it's about the Catalyst FormBuilder Base Controller. it's a long one so we're doing this in parts — this is part 1, don't go anywhere 💅

---

✨ NAME ✨

Catalyst::Controller::FormBuilder — Catalyst FormBuilder Base Controller. that's it, that's the name, iconic 👑

---

🌸 SYNOPSIS 🌸

here's the vibe, copy it exactly bestie:

package MyApp::Controller::Books;
use base 'Catalyst::Controller::FormBuilder';

# optional config setup
__PACKAGE__->config(
    'Controller::FormBuilder' = {
        template_type => 'HTML::Template',    # default is 'TT' (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 => 'email', validate => 'EMAIL' );

    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('/books/edit') {
    my ( $self, $c ) = @_;
    $c->stash->{template} = "books/edit.tt" # TT2 template;
}

(yes, explicitedly is spelled like that in the original, and yes, we're keeping it, no notes 🫶)

---

🦋 DESCRIPTION 🦋

so. this base controller is literally the merger of CGI::FormBuilder with Catalyst PLUS these templating systems: Template Toolkit, Mason and HTML::Template. it's giving the whole package 😌 which means you get all of FormBuilder's niceties — controllable field stickiness, multilingual support, and Javascript generation. for more deets, peep CGI::FormBuilder or the website at:

http://www.formbuilder.org

FormBuilder inside Catalyst? super straightforward, no cap. since Catalyst handles page rendering, you do not call FormBuilder's render() method like you normally would. instead, you just add a :Form attribute to each method you wanna associate with a form. that's it. that's the whole trick ✨ and boom, you get access to a FormBuilder $self->formbuilder object inside that controller method:

# An editing screen for books
sub edit : Local Form {
    my ( $self, $c ) = @_;
    $self->formbuilder->method('post');   # set form method
}

the out-of-the-box setup looks for a form configuration file following the CGI::FormBuilder::Source::File format (essentially YAML), named for the current action url. so if you were serving /books/edit, this plugin would be looking for:

root/forms/books/edit.fb

(the path is configurable, obviously 💅) and if no source file is found? then it's assumed you'll be setting up your fields manually. in your controller you'll have to use that $self->formbuilder object to create your fields, validation, and so on. you got this bestie.

here's an example edit.fb file, look at her:

# 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's Name
        type:  text
        size:  80
        validate: NAME
        required: 1
    isbn:
        label: ISBN#
        type:  text
        size:  20
        validate: /^(\d{10}|\d{13})$/
        required: 1
    desc:
        label: Description
        type:  textarea
        cols:  80
        rows:  5

submit: Save New Book

this will automatically create a complete form for you, using the specified fields. and heads up: that root/forms path is configurable — it's used by default to integrate with the TTSite helper 🎀

within your controller, you can call any method that you would on a normal CGI::FormBuilder object, right on the $self->formbuilder object. wanna manipulate the field named desc? just call the field() method:

# Change our desc field dynamically
$self->formbuilder->field(
    name     => 'desc',
    label    => 'Book Description',
    required => 1
);

and to populate field options for country, you might do something like this to iterate through the database:

$self->formbuilder->field(
    name    => 'country',
    options =>
      [ map { [ $_->id, $_->name ] } $c->model('MyApp::Country')->all ],
    other => 1,    # create "Other:" box
);

this would create a select list with the last element as Other: so people can add more countries 🗺️ see CGI::FormBuilder for the methods available to the form object.

okay so the FormBuilder methodology is to handle both rendering and validation of the form. as such, the form will "loop back" onto the same controller method. within your controller, you'd then use the standard FormBuilder submit/validate check:

if ( $self->formbuilder->submitted && $self->formbuilder->validate ) {
    $c->forward('/books/save');
}

this would forward to /books/save 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 🙈

to render the form in your tt2 template, for example, you can use render to get a default table-based form:

<!-- root/src/books/edit.tt -->
[% FormBuilder.render %]

and you can also get fine-tuned control over your form layout from within your template. main character energy fr 💅

---

🎀 TEMPLATES 🎀

the simplest way to get your form into HTML is to reference the FormBuilder.render method, as shown above. however, frequently you want more control. relatable.

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 template_type config option. and of course, make sure you have a View to support the template, since this module does not render templates 🫶

from within your template, you can reference any of FormBuilder's methods to manipulate form HTML, JavaScript, and so forth. for example, you might want exact control over fields, rendering them in a <div> instead of a table. you could do something like this:

<!-- 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>

in this case, you would not call FormBuilder.render, since that would only result in a duplicate form (once using the above expansion, and a second time using FormBuilder's default rendering). not the move 😭

note that the above form could become a generic form.tt template which you simply include in all your files, since there is nothing specific to a given form hardcoded in (that's the idea, after all ✨).

you can also get some ideas based on FormBuilder's native Template Toolkit support at CGI::FormBuilder::Template::TT2.

---

that's part 1 bestie, and there's more coming — don't close the tab 💜

💖 CONFIGURATION 💖

okay so bestie, you can set defaults for your forms using Catalyst's config method inside your controller. it's giving main character energy for real. 🎀

__PACKAGE__->config(
    'Controller::FormBuilder' => {
        new => {
            method     => 'post',
            # stylesheet => 1,
            messages   => '/locale/fr_FR/form_messages.txt',
        },
        form_path =>
          File::Spec->catfile( $c->config->{home}, 'root', 'forms' ),
        method_name   => 'form',
        template_type => 'HTML::Template',
        stash_name    => 'form',
        obj_name      => 'FormBuilder',
        form_suffix   => 'fb',
        attr_name     => 'Form',
        source_type   => 'CGI::FormBuilder::Source::File',
    }
);

✨ new ✨

This accepts the exact same options as FormBuilder's new() method (which is a lot). See CGI::FormBuilder for a full list of options. like, it's a whole buffet, no cap. 💅

✨ form_path ✨

The path to configuration files. This should be set to an absolute path to prevent problems. By default, it is set to:

File::Spec->catfile( $c->config->{home}, 'root', 'forms' )

This can be a colon-separated list of directories if you want to specify multiple paths (ie, "/templates1:/template2"), or an array ref (ie, [qw/template1 templates2/]). highkey flexible. 🦋

✨ form_suffix ✨

The suffix that configuration files have. By default, it is "fb". periodt.

✨ method_name ✨

Accessor method name available in your controller. By default, it is "formbuilder".

✨ template_type ✨

Defines the Catalyst View that the stash will be prepared for. Possible values are: HTML::Template, Mason, TT. By default, it is "TT". obsessed with options. 🌸

✨ stash_name ✨

Not applicable for HTML::Template view. By default, it is "formbuilder". e.g. $c->stash->{formbuilder} = $formbuilder->prepare.

✨ obj_name ✨

Not applicable for HTML::Template view. By default, it is "FormBuilder". e.g. $c->stash->{FormBuilder} = $formbuilder.

✨ attr_name ✨

The attribute name. By default, it is "Form". e.g. sub edit : Form { ... }

✨ source_type ✨

The source adapter class name. By default, it is "CGI::FormBuilder::Source::File". See CGI::FormBuilder::Source

---

In addition, the following FormBuilder options are automatically set for you. not me listing them all, but yes, all of them. 😭

🫶 action 🫶

This is set to the URL for the current action. FormBuilder is designed to handle a full request cycle, meaning both rendering and submission. If you want to override this, simply use the $self->formbuilder object:

$self->formbuilder->action('/action/url');

The default setting is "$c->req->path".

🫶 cookies 🫶

Handling these are disabled (use Catalyst).

🫶 debug 🫶

This is set to correspond with Catalyst's debug setting.

🫶 header 🫶

This is disabled. Instead, use Catalyst's header routines.

🫶 params 🫶

This is set to get parameters from Catalyst, using "$c->req". To override this, use the $self->formbuilder object:

$self->formbuilder->params(\%param_hashref);

Overriding this is not recommended.

🫶 source 🫶

This determines which source file is loaded, to setup your form. By default, this is set to the name of the action URL, with ".fb" appended. For example, "edit_form()" would be associated with an "edit_form.fb" source file.

To override this, include the path as the argument to the method attribute:

sub edit : Local Form('/books/myEditForm') { }

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 $self->formbuilder object to create your fields, validation, and so on. it's giving DIY energy, fr fr. 💖

---

🌈 SEE ALSO 🌈

• CGI::FormBuilder
• CGI::FormBuilder::Source::File
• CGI::FormBuilder::Template::TT2
• Catalyst::Manual
• Catalyst::Request
• Catalyst::Response

---

👑 AUTHOR 👑

Copyright (c) 2006 Juan Camacho <formbuilder@suspenda.com>. All Rights Reserved.

Thanks to Laurent Dami and Roy-Magne Mo for suggestions.

This library is free software, you can redistribute it and/or modify it under the same terms as Perl itself.

---

and that's the whole page, bestie! this manual page is from perl v5.34.0, dated 2022-06-09, and it's Cataly...Builder(3pm). mwah 💋✨