NAME

Maypole::FormBuilder::Model

SYNOPSIS

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

Major surgery

This class does not inherit from Maypole::Model::CDBI, for several reasons. We don't need to load Class::DBI::Untaint, Class::DBI::AsForm or Class::DBI::FromCGI. I wanted to implement a config option to choose which pager to use (see do_pager). And I wanted to rename methods that share a name with methods in Class::DBI (delete and search are now do_delete and do_search).

Maypole is pretty stable these days and it should be easy enough to keep up with any bug fixes.

METHODS

setup_form_mode

This method is responsible for ensuring that the 'server' form and the 'client' form are equivalent - see Coordinating client and server forms.

Returns a form spec for the selected form mode. The mode defaults to $r->action. You can set a different mode in the args hash to the as_form call. Mostly, this method is responsible for setting the action parameter of the form.

Override this in model classes to configure custom modes, and call

$proto->SUPER::setup_form_mode( $r, $args )

in the custom method if it doesn't know the mode.

Modes supported here are:

list
addnew
search
do_search
${action}_button    where $action is any public action on the class
editlist
edit
do_edit
editrelated
addto

Column and field lists

display_columns

Returns a list of columns, minus primary key columns, which probably don't need to be displayed. The templates use this as the default list of columns to display.

Note that Class::DBI::FormBuilder will add back in hidden fields for the primary key(s), to support lookups done in several of its *_from_form methods.

list_columns

This method is not defined here, but in Maypole::Model::Base, and defaults to display_columns. This is used to define the columns displayed in the list template.

related

Returns a list of accessors for has_many related classes. These can appear as fields in a form, but are not columns in the database.

list_fields

This method is new in Maypole::FormBuilder. Defaults to related.

The list template uses list_columns plus list_fields as the default list of fields to display, and setup_form_mode sets list_columns plus list_fields in the fields argument in editlist mode, so that editable and navigable list views both present the same fields.

Exported methods

Exported methods have the Exported attribute set. These are the methods that URLs can trigger. See the main Maypole documentation for more information.

As a convenience and a useful convention, all these methods now set the appropriate template, so it shouldn't be necessary to set the template and then call the method. This is particularly useful in despatching methods, such as editlist.

Some exported methods are defined in Maypole::FormBuilder::Model::Base, if they have no dependency on CDBI. But the likelihood of a FormBuilder distribution that doesn't depend on Class::DBI::FormBuilder is pretty low.

Gotchas

Sometimes you need to set the form mode in these methods, sometimes not. I think that if the mode matches the action, you don't need to set it. So to get searching working, the do_search mode needs to be set. Similarly for do_edit, except here the edit mode needs to be set. Elsewhere the mode is automatically set to the Maypole action. If you insert a line in CGI::FormBuilder::submitted() to warn the value of $smtag, that needs to match the name of the submit button in $request->params (i.e. $request->params->{$smtag} needs to be true).

addnew

The way CGI::FormBuilder handles different button clicks (i.e. it handles them), means we need a separate method for creating new objects (in standard Maypole, addnew posts to do_edit). But Class::DBI::FormBuilder keeps things simple.

addto

edit

Sets the edit template.

Also sets the action to edit. This is necessary to support forwarding to the edit template from the edit button on the editlist template.

do_edit

Implements update operations on submitted forms.

do_search

Runs a search_where search.

Does not implement search ordering yet, and there are various other modifications that could make this better, such as allowing LIKE comparisons (% and _ wildcards) etc.

editlist

Detects which submit button was clicked, and despatches to the appropriate method.

list

Does not implement ordering yet.

do_delete

Deletes a single object.

view

Just sets the view template.

switchlistmode

If sessions are enabled, this switches the default list mode between editlist and list.

editrelated

Basic support for the editrelated template. This is currently under development in Class::DBI::FormBuilder::as_form_with_related().

Coordinating client and server forms

Every form is used in two circumstances, and the forms must be built with equivalent properties in each. In the first, a form object is constructed and used to generate an HTML form to be sent to the client. In the second, a form object is constructed and is used to receive data sent in a form submission from the client. These may be loosely termed the 'server' and 'client' forms (although they are both built on the server).

The forms built in these two situations must have equivalent properties, such as the same field lists, the same option lists for multi-valued fields, etc.

The point of co-ordination is the setup_form_mode method. This supplies the set of characteristics that must be synchronised by both versions of the form. setup_form_mode selects a set of form parameters based on the current action of the Maypole request.

Maypole::Model::CDBI methods

These methods are copied verbatim from Maypole::Model::CDBI. See that module for documentation.

related

related_class

stringify_column

adopt

do_pager

The default pager is Class::DBI::Pager. Use a different pager by setting the pager_class config item:

BeerFB->config->pager_class( 'Class::DBI::Plugin::Pager' );

order

This method is not used in the Maypole::Plugin::FormBuilder templates at the moment. Probably, ordering will be implemented directly in Class::DBI::FormBuilder and this method can disappear.

setup_database

class_of

fetch_objects

AUTHOR

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

TODO

Refactor setup_form_mode() into a dispatch table.

I think splitting modes into search and do_search, and edit and do_edit, is probably unnecessary.

Pairs of methods like search and do_search, edit and do_edit are probably unnecessary, as FB makes it easy to distinguish between rendering a form and processing a form - see editrelated().

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.