NAME

Maypole::Plugin::FormBuilder - CGI::FormBuilder for Maypole

SYNOPSIS

package BeerFB;
use warnings;
use strict;

use Class::DBI::Loader::Relationship;

use Maypole::Application qw( FormBuilder QuickTable );

BeerFB->config->model( 'Maypole::FormBuilder::Model' );

# note: the latest development version is broken
#BeerFB->config->pager_class( 'Class::DBI::Plugin::Pager' );

# global FormBuilder defaults
BeerFB->config->form_builder_defaults( method => 'post' );

# standard config
BeerFB->config->{template_root}  = '/home/beerfb/www/www/htdocs';
BeerFB->config->{uri_base}       = '/';
BeerFB->config->{rows_per_page}  = 10;
BeerFB->config->{display_tables} = [ qw( beer brewery pub style ) ];
BeerFB->config->{application_name} = 'The BeerFB Database';

BeerFB->setup( 'dbi:mysql:BeerDB', 'username', 'password' );

BeerFB->config->loader->relationship( $_ ) for (
    'a brewery produces beers',
    'a style defines beers',
    'a pub has beers on handpumps',
    );

# ----- set up validation and other form defaults -----

BeerFB::Beer->columns( Required => qw( brewery name ) );
BeerFB::Beer->form_builder_defaults( { validate => { abv     => 'NUM',
                                                    style   => 'INT',
                                                    brewery => 'INT',
                                                    price   => 'NUM',
                                                    url     => 'VALUE',
                                                    notes   => 'VALUE',
                                                    name    => 'VALUE',
                                                    score   => [ qw( 1 2 3 4 5 ) ],
                                                    },
                                    options => { score => [ qw( 1 2 3 4 5 ) ],
                                                    },
                                    } );
    
BeerFB::Brewery->columns( Required => qw( name ) );
BeerFB::Brewery->form_builder_defaults( { validate => { name  => 'VALUE',
                                                        notes => 'VALUE',
                                                        url   => 'VALUE',
                                                        },
                                        } );
                                        
# or put the required columns in the CGI::FormBuilder default spec:
BeerFB::Pub->form_builder_defaults( { validate => { name  => 'VALUE',
                                                    notes => 'VALUE',
                                                    url   => 'VALUE',
                                                    },
                                    required => [ qw( name ) ],
                                    } );
                                        
BeerFB::Style->form_builder_defaults( { validate => { name  => 'VALUE',
                                                    notes => 'VALUE',
                                                    },
                                        required => [ qw( name ) ],
                                        } );    

1;


# -------------------------------------------------------------------------
# --- in a Mason template (adapt syntax for your preferred template system)

<% $request->as_form->render %>

DESCRIPTION

Generate CGI::FormBuilder forms from Maypole objects, using Class::DBI::FormBuilder.

Includes an alternative Maypole model, which should be set up in your config:

BeerFB->config->model( 'Maypole::FormBuilder::Model' );

Note that a new vars method is installed, which removes the classmetadata functionality. It just seemed like an extra level of API to learn, and we don't need the Class::DBI::AsForm stuff.

METHODS

setup

init

as_form

This returns a CGI::FormBuilder object. Accepts any parameters that CGI::FormBuilder->new() accepts.

Defaults are as in CGI::FormBuilder, you can alter them using the form_builder_default Maypole config slot.

There are a few additional Maypole-specific options:

mode

The form generated depends on the mode. Defaults to the current action.

Pass this argument to generate a different form from that specified by the current value of $r->action. For instance, to generate a search form to include on a list template, say

print $r->as_form( mode => 'do_search' )->render;

You can add more modes by defining setup_form_mode methods in your model classes. See Maypole::FormBuilder::Model and Maypole::FormBuilder::Model::Base.

entity

Normally, as_form builds a form based on the first object in $r->objects, or based on the current model ($r->model_class) if there are no objects. To use a different object or model, pass it in the entity argument:

my $form = $r->as_form( entity => $class_or_object );

search_form

Returns a search form, via Class::DBI::FormBuilder::search_form(). The mode defaults to do_search.

as_forms( %args )

%args = ( objects       => $object|$arrayref_of_objects,    defaults to $r->objects
          with_colnames => true|false value,                default false
          render        => true|false value,                default false
          no_textareas  => true|false value,                default false
          %other_form_args,
          );

Generates multiple forms. If render is true, calls render on each form and returns the generated HTML as a single string. If with_colnames is also true, the HTML table includes a row of column names.

If render is false, returns a list containing the form objects.

You will probably want to set no_textareas to true (converts them to text inputs), and perhaps reduce selectnum ( see the editlist template in this distribution).

This method may change in the future. I don't like having two output modes from one method, and it would be nicer to use Maypole::Plugin::QuickTable to build the rendered output.

Maypole::Config::form_builder_defaults()

Defaults that apply to all forms.

# make all forms POST their data
BeerFB->config->form_builder_defaults->{method} = 'post';

Configuring custom actions

Custom actions may require custom configuration of the form object (in addition to providing an Exported method in your model class to support the new action). Write a setup_form_mode method in your model class. See Maypole::Plugin::FormBuilder::Model::Base.

SEE ALSO

Maypole::FormBuilder::Model and Maypole::FormBuilder::Model::Base.

AUTHOR

David Baird, <cpan@riverside-cms.co.uk>

BUGS

Please report any bugs or feature requests to bug-maypole-formbuilder@rt.cpan.org, or through the web interface at http://rt.cpan.org/NoAuth/ReportBug.html?Queue=Maypole-FormBuilder. I will be notified, and then you'll automatically be notified of progress on your bug as I make changes.

COPYRIGHT & LICENSE

Copyright 2005 David Baird, All Rights Reserved.

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