This module has been deprecated in favor of Catalyst::Controller::FormBuilder. Please do not use it in new code. It has known compatibility issues and is absolutely not supported by anyone. It remains only in case you have existing code that relies on it.

This plugin merges the functionality of CGI::FormBuilder with Catalyst and Template Toolkit. This gives you access to all of FormBuilder's niceties, such as controllable field stickiness, multilingual support, and Javascript generation. For more details, see CGI::FormBuilder or the website at:

FormBuilder usage within Catalyst is straightforward. Since Catalyst handles page rendering, you don't call FormBuilder's render() method, as you would normally. Instead, you simply add a :Form attribute to each method that you want to associate with a form. This will give you access to a FormBuilder $c->form object within that controller method:

# An editing screen for books
sub edit : Local Form {
# The file books/edit.fb is loaded automatically
$c->form->method('post'); # set form method
}

The out-of-the-box setup is to look for a form configuration file that follows the CGI::FormBuilder::Source::File format (essentially YAML), named for the current action url. So, if you were serving /books/edit, this plugin would look for:

root/forms/books/edit.fb

(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 $c->form object to create your fields, validation, and so on.

This would create a select list with the last element as "Other:" to allow the addition of more countries. See CGI::FormBuilder for methods available to the form object.

The FormBuilder methodolody 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 would then use the standard FormBuilder submit/validate check:

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 template, you can use render to get a default table-based form:

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

You can also get fine-tuned control over your form layout from within your template.

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

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:

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 $c->form object:

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 $c->form object to create your fields, validation, and so on.