/ 
Catalyst-Plugin-FormBuilder-1.04
River stage zero No dependents
/ Catalyst::Plugin::FormBuilder

NAME

Catalyst::Plugin::FormBuilder - Catalyst FormBuilder Plugin

SYNOPSIS

package MyApp;
use Catalyst qw/FormBuilder/;

package MyApp::Controller::Example;
use base 'Catalyst::Controller';

#
# The simplest example looks for edit.fb to create
# a form, based on the presence of the ":Form" attribute.
# Use Local/Global/Private/etc to scope methods like normal.
#
sub edit : Local Form {
    my ($self, $c, @args) = @_;
    $c->form->field(name => 'email', validate => 'EMAIL');
    $c->form->messages('/locale/messages.fr');
}

#
# This example references edit still, since we are 
# just switching to a readonly view. The layout will be
# the same, but fields are rendered as static HTML.
# Note that the Catalyst action URL remains /books/view
#
sub view : Local Form('/books/edit') {
    my ($self, $c) = @_;
    $c->form->static(1);      # set form to readonly
}

DESCRIPTION

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:

http://www.formbuilder.org

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.

Here is an example edit.fb file:

# 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
    country:
        label: Country of Origin
        type:  select
        required: 1

submit: Save New Book

This will automatically create a complete form for you, using the specified fields. Note that the root/forms path is configurable; this path is 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 on the $c->form object. To manipulate the field named desc, simply call the field() method:

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

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

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

if ($c->form->submitted && $c->form->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 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.

TEMPLATES

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:

<!-- root/src/books/edit.tt -->
<head>
  <title>[% form.title %]</title>
  [% form.jshead %]<!-- javascript -->
</head>
<body>
  [% form.start %]
  <div id="form">
    [% FOREACH field IN form.fields %]
    <div id="[%- field.name -%]">
      <div class="label">
        [% field.required
              ? qq(<span class="required">$field.label</span>)
              : field.label
        %]
      </div>
      <div class="field">
        [% field.tag %]
        [% IF field.invalid %]
            <span class="error">
                Missing or invalid entry, please try again.
            </error>
        [% END %]
      </div>
    </div>
    [% END %]
    <div id="submit">[% form.submit %]</div>
    <div id="reset">[% form.reset %]</div>
    <div id="state">
      [% # The following two tags include state information %]
      [% form.statetags  %]
      [% form.keepextras %]
      [% form.end        %]
    </div>
  </div><!-- form -->
</body>

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

Note that the above form could become a generic form.tt 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).

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

CONFIGURATION

You can set defaults for your forms using Catalyst's config method:

MyApp->config(form => {
    method     => 'post',
    stylesheet => 1,
    messages   => '/locale/fr_FR/form_messages.txt',
});

This accepts the exact same options as FormBuilder's new() method (which is alot). See CGI::FormBuilder for a full list of options.

Two special configuration parameters control how this plugin resolves form config files:

form_path

The path to configuration files. This should be set to an absolute path to prevent problems. Within this plugin, it is set to:

form_path => 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").

form_suffix

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

In addition, the following FormBuilder options are automatically set for you:

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

$c->form->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.

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

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

SEE ALSO

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

AUTHOR

Copyright (c) 2006 Nate Wiger <nate@wiger.org>. All Rights Reserved.

Thanks to Laurent Dami for many good suggestions regarding this plugin.

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