Why not adopt me?
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 theas_form
call.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.
You can add a
mode_args
argument to the hashref of arguments that reachsetup_form_mode
. For instance, theaddto
template uses this to passModes supported here are:
list addnew search do_search ${action}_button where $action is any public action on the class editlist edit edit_all_has_a do_edit editrelated addto addhowmany addmany
Column and field lists
Standard Maypole defines a few methods to return different lists of columns and column-like accessors (display_columns
, list_columns
, and related
). Several more methods are added here, and are used in the templates, but in general they will default to return the same list as one of the standard methods.
The rationale is that in general, each template may need to display a different view of the object(s) (edit
, view
, list
, search
etc.). Your own templates can use these methods, and you will probably want to define additional column/field listing methods in your custom models and templates.
Each *_columns
method has a matching <*_fields> method, which can be used to add non-column fields (i.e. has_many
accessors) to the relevant form. (For display_columns
, the relevant fields method is related
).
- 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. - display_fields
-
Defaults to
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_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 thelist
template. - list_fields
-
Defaults to
related
.The
list
template useslist_columns
pluslist_fields
as the default list of fields to display, andsetup_form_mode
setslist_columns
pluslist_fields
in thefields
argument ineditlist
mode, so that editable and navigable list views both present the same fields. - search_columns
-
Used to build the search form. Defaults to
display_columns
. - search_fields
-
Used to build the search form. Defaults to an empty list.
- edit_columns
-
Defaults to
display_columns
. - edit_fields
-
Defaults to
related
. Used in theedit
template to display values ofhas_many
fields and build separate forms for adding more items to ahas_many
. - addnew_columns
-
Defaults to
display_columns
. - addnew_fields
-
Defaults to empty list, at least until I add
addmany
support toaddnew
. - addmany_columns
- addmany_fields
- view_columns
- view_fields
- hasa_columns
- field_names
-
Counterpart to
MP::Model::Base::column_names
. Returns a hash of field names to field labels.
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.
- 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.Note this method returns to the
edit
template, which is useful in some situations, but for many apps, you probably want to return the user to theview
template instead. Simply overrideaddnew
in your model, perhaps calling$self->SUPER::addnew
to perform the update, then return vis$self->view( $r )
. - addto
-
Adds a new item in a
has_many
relationship. - addhowmany
-
Receives the number of requested items and forwards to the
addmany
template. - addmany
-
Add several items to the target, where <target_class has_many items>.
- edit
-
Sets the
edit
template.Also sets the
action
toedit
. This is necessary to support forwarding to theedit
template from theedit
button on theeditlist
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
andlist
. -
Basic support for the
editrelated
template. This is currently under development inClass::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.
Gotchas
- form mode
-
Sometimes you need to set the form mode in these methods, sometimes not. 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 fordo_edit
, except here theedit
mode needs to be set. Elsewhere the mode is automatically set to the Maypole action. -
If you insert a line in
CGI::FormBuilder::submitted()
towarn
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).
Maypole::Model::CDBI methods
These methods are copied verbatim from Maypole::Model::CDBI. See that module for documentation.
- 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
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.