.\" Automatically generated by Pod::Man v1.37, Pod::Parser v1.32
.\"
.\" Standard preamble:
.\" ========================================================================
.de Sh \" Subsection heading
.br
.if t .Sp
.ne 5
.PP
\fB\\$1\fR
.PP
..
.de Sp \" Vertical space (when we can't use .PP)
.if t .sp .5v
.if n .sp
..
.de Vb \" Begin verbatim text
.ft CW
.nf
.ne \\$1
..
.de Ve \" End verbatim text
.ft R
.fi
..
.\" Set up some character translations and predefined strings.  \*(-- will
.\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left
.\" double quote, and \*(R" will give a right double quote.  | will give a
.\" real vertical bar.  \*(C+ will give a nicer C++.  Capital omega is used to
.\" do unbreakable dashes and therefore won't be available.  \*(C` and \*(C'
.\" expand to `' in nroff, nothing in troff, for use with C<>.
.tr \(*W-|\(bv\*(Tr
.ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p'
.ie n \{\
.    ds -- \(*W-
.    ds PI pi
.    if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch
.    if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\"  diablo 12 pitch
.    ds L" ""
.    ds R" ""
.    ds C` ""
.    ds C' ""
'br\}
.el\{\
.    ds -- \|\(em\|
.    ds PI \(*p
.    ds L" ``
.    ds R" ''
'br\}
.\"
.\" If the F register is turned on, we'll generate index entries on stderr for
.\" titles (.TH), headers (.SH), subsections (.Sh), items (.Ip), and index
.\" entries marked with X<> in POD.  Of course, you'll have to process the
.\" output yourself in some meaningful fashion.
.if \nF \{\
.    de IX
.    tm Index:\\$1\t\\n%\t"\\$2"
..
.    nr % 0
.    rr F
.\}
.\"
.\" For nroff, turn off justification.  Always turn off hyphenation; it makes
.\" way too many mistakes in technical documents.
.hy 0
.if n .na
.\"
.\" Accent mark definitions (@(#)ms.acc 1.5 88/02/08 SMI; from UCB 4.2).
.\" Fear.  Run.  Save yourself.  No user-serviceable parts.
.    \" fudge factors for nroff and troff
.if n \{\
.    ds #H 0
.    ds #V .8m
.    ds #F .3m
.    ds #[ \f1
.    ds #] \fP
.\}
.if t \{\
.    ds #H ((1u-(\\\\n(.fu%2u))*.13m)
.    ds #V .6m
.    ds #F 0
.    ds #[ \&
.    ds #] \&
.\}
.    \" simple accents for nroff and troff
.if n \{\
.    ds ' \&
.    ds ` \&
.    ds ^ \&
.    ds , \&
.    ds ~ ~
.    ds /
.\}
.if t \{\
.    ds ' \\k:\h'-(\\n(.wu*8/10-\*(#H)'\'\h"|\\n:u"
.    ds ` \\k:\h'-(\\n(.wu*8/10-\*(#H)'\`\h'|\\n:u'
.    ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'^\h'|\\n:u'
.    ds , \\k:\h'-(\\n(.wu*8/10)',\h'|\\n:u'
.    ds ~ \\k:\h'-(\\n(.wu-\*(#H-.1m)'~\h'|\\n:u'
.    ds / \\k:\h'-(\\n(.wu*8/10-\*(#H)'\z\(sl\h'|\\n:u'
.\}
.    \" troff and (daisy-wheel) nroff accents
.ds : \\k:\h'-(\\n(.wu*8/10-\*(#H+.1m+\*(#F)'\v'-\*(#V'\z.\h'.2m+\*(#F'.\h'|\\n:u'\v'\*(#V'
.ds 8 \h'\*(#H'\(*b\h'-\*(#H'
.ds o \\k:\h'-(\\n(.wu+\w'\(de'u-\*(#H)/2u'\v'-.3n'\*(#[\z\(de\v'.3n'\h'|\\n:u'\*(#]
.ds d- \h'\*(#H'\(pd\h'-\w'~'u'\v'-.25m'\f2\(hy\fP\v'.25m'\h'-\*(#H'
.ds D- D\\k:\h'-\w'D'u'\v'-.11m'\z\(hy\v'.11m'\h'|\\n:u'
.ds th \*(#[\v'.3m'\s+1I\s-1\v'-.3m'\h'-(\w'I'u*2/3)'\s-1o\s+1\*(#]
.ds Th \*(#[\s+2I\s-2\h'-\w'I'u*3/5'\v'-.3m'o\v'.3m'\*(#]
.ds ae a\h'-(\w'a'u*4/10)'e
.ds Ae A\h'-(\w'A'u*4/10)'E
.    \" corrections for vroff
.if v .ds ~ \\k:\h'-(\\n(.wu*9/10-\*(#H)'\s-2\u~\d\s+2\h'|\\n:u'
.if v .ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'\v'-.4m'^\v'.4m'\h'|\\n:u'
.    \" for low resolution devices (crt and lpr)
.if \n(.H>23 .if \n(.V>19 \
\{\
.    ds : e
.    ds 8 ss
.    ds o a
.    ds d- d\h'-1'\(ga
.    ds D- D\h'-1'\(hy
.    ds th \o'bp'
.    ds Th \o'LP'
.    ds ae ae
.    ds Ae AE
.\}
.rm #[ #] #H #V #F C
.\" ========================================================================
.\"
.IX Title "Gantry::Plugins::AjaxFORM 3"
.TH Gantry::Plugins::AjaxFORM 3 "2008-01-18" "perl v5.8.8" "User Contributed Perl Documentation"
.SH "NAME"
Gantry::Plugins::AjaxFORM \- helper for AJAX based Form processing
.SH "SYNOPSIS"
.IX Header "SYNOPSIS"
.Vb 1
\&    use Gantry::Plugins::AjaxFORM;
.Ve
.PP
.Vb 2
\&    sub do_main {
\&        my ( $self ) = @_;
.Ve
.PP
.Vb 2
\&        my $data = "something';
\&        $self->stash->view->template('form.tt');
.Ve
.PP
.Vb 10
\&        my $form = Gantry::Plugins::AjaxFORM->new(
\&            process_action  => \e&user_process,
\&            cancel_action   => \e&user_cancel,
\&            success_action  => \e&user_success,
\&            form            => \e&user_form,
\&            user_data       => $data,
\&            text_descr      => 'database row description',
\&            use_clean_dates => 1,
\&            turn_off_clean_params => 1,
\&        );
.Ve
.PP
.Vb 1
\&        $form->process($self);
.Ve
.PP
.Vb 1
\&    }
.Ve
.PP
.Vb 2
\&    sub user_process {
\&        my ( $self , $params, $data ) = @_;
.Ve
.PP
.Vb 1
\&        # do somthing interesting with the data
.Ve
.PP
.Vb 1
\&    }
.Ve
.PP
.Vb 2
\&    sub user_success {
\&        my ( $self, $params, $action ) = @_;
.Ve
.PP
.Vb 1
\&        $self->do_main( );
.Ve
.PP
.Vb 1
\&    }
.Ve
.PP
.Vb 2
\&    sub user_cancel {
\&        my ( $self, $params, $action ) = @_;
.Ve
.PP
.Vb 1
\&        $self->do_main( );
.Ve
.PP
.Vb 1
\&    }
.Ve
.PP
.Vb 2
\&    sub form {
\&        my ( $self, $data ) = @_;
.Ve
.PP
.Vb 7
\&        return {name   => 'form',
\&                row    => $data->{row},
\&                fields => [{name => 'name',
\&                            label => 'Name',
\&                            type => 'text',
\&                            is => 'varchar'}]
\&               };
.Ve
.PP
.Vb 1
\&    }
.Ve
.SH "DESCRIPTION"
.IX Header "DESCRIPTION"
This module is used for basic form processing. Instead of writing the
same form processing code over and over again. You can use this module 
instead. This module is sensitive to server side relocations so it will
work with \s-1AJAX\s0 based systems.  
.PP
Notice: most plugins export methods into your package, this one does \s-1NOT\s0.
.PP
This module does the following basic form handling:
.PP
.Vb 7
\&    redispatch to listing page if user presses cancel
\&    if form parameters are valid:
\&        callback to action method
\&    else:
\&        if method is POST:
\&            add form validation errors
\&        (re)display form
.Ve
.SH "METHODS"
.IX Header "METHODS"
This is an object oriented only module (it doesn't export like the other
plugins).  
.IP "process" 4
.IX Item "process"
Dispatches to the form handler. Called from the do_* function.
.IP "new" 4
.IX Item "new"
Constructs a new AjaxFORM helper.  Pass in a list of the following callbacks
and config parameters (similar, but not the same as in \s-1CRUD\s0):
.RS 4
.IP "process_action (a code ref)" 4
.IX Item "process_action (a code ref)"
Called with:
.Sp
.Vb 3
\&    your self object
\&    hash of form parameters
\&    user specific data
.Ve
.Sp
Called only when the form parameters are valid. Do anything you want with
the data. You should try not to die.
.IP "form (a code ref)" 4
.IX Item "form (a code ref)"
Called with:
.Sp
.Vb 2
\&    your self object
\&    user specific data
.Ve
.Sp
This needs to return just like the _form method required by
\&\f(CW\*(C`Gantry::Plugins::AutoCRUD\*(C'\fR.  See its docs for details.
The only difference between these is that the AutoCRUD calls
_form with your self object and the row being edited (during editing)
whereas this method \s-1ALWAYS\s0 receives both your self object and the
data you supplied.
.IP "cancel_action (a code ref)" 4
.IX Item "cancel_action (a code ref)"
Called with:
.Sp
.Vb 3
\&    your self object
\&    the form parameters
\&    the action
.Ve
.Sp
Triggered by the user successfully submitting the form.
This and \f(CW\*(C`success_action\*(C'\fR replaces the redirect callback used by
\&\f(CW\*(C`Gantry::Plugins::CRUD\*(C'\fR.  They should redispatch directly to a do_* method
like this:
.Sp
.Vb 2
\&    sub _my_cancel_action {
\&        my $self = shift;
.Ve
.Sp
.Vb 2
\&        $self->do_something( @_ );
\&    }
.Ve
.IP "success_action (a code ref)" 4
.IX Item "success_action (a code ref)"
Called with:
.Sp
.Vb 3
\&    your self object
\&    the form parameter
\&    the action
.Ve
.Sp
Just like the \f(CW\*(C`cancel_action\*(C'\fR, but triggered when the user presses the Cancel 
button.
.IP "user_data" 4
.IX Item "user_data"
Data to be passed to the form and process actions.
.IP "text_descr" 4
.IX Item "text_descr"
Same as in CRUD/AjaxCRUD/AutoCRUD.
.Sp
The text string used in the page titles and in the delete confirmation
message.
.IP "use_clean_dates (optional, defaults to false)" 4
.IX Item "use_clean_dates (optional, defaults to false)"
Same as in CRUD/AjaxCRUD/AutoCRUD.
.Sp
This is ignored unless you turn_off_clean_params, since it is redundant
when clean_params is in use.
.Sp
Make this true if you want your dates cleaned immediately before your
add and edit callbacks are invoked.
.Sp
Cleaning sets any false fields marked as dates in the form fields list
to undef.  This allows your \s-1ORM\s0 to correctly insert them as
nulls instead of trying to insert them as blank strings (which is fatal,
at least in PostgreSQL).
.Sp
For this to work your form fields must have this key: \f(CW\*(C`<is =\*(C'\fR 'date'>>.
.IP "turn_off_clean_params (optional, defaults to false)" 4
.IX Item "turn_off_clean_params (optional, defaults to false)"
Same as in CRUD/AjaxCRUD/AutoCRUD.
.Sp
By default, right before an \s-1SQL\s0 insert or update, the params hash from the
form is passed through the clean_params routine which sets all non-boolean
fields which are false to undef.  This prevents \s-1SQL\s0 errors with ORMs that
can correctly translate blank strings into nulls for non-string types.
.Sp
If you really don't want this routine, set turn_off_clean_params.  If you
turn it off, you can use_clean_dates, which only sets false dates to undef.
.RE
.RS 4
.RE
.SH "HELPER FUNCTIONS"
.IX Header "HELPER FUNCTIONS"
.IP "select_multiple_closure" 4
.IX Item "select_multiple_closure"
If you have a form field of type select_multiple, one of the form.tt keys
is selected.  It wants a sub ref so it can reselect items when the form
fails to validate.  This function will generate the proper sub ref (aka
closure).
.Sp
Parameters:
    form field name
    hash reference of default selections (usually the ones in the database)
.Sp
Returns: a closure suitable for immediate use as the selected hash key value
for a form field of type select_multiple.
.SH "SEE ALSO"
.IX Header "SEE ALSO"
.Vb 1
\& Gantry::Plugins::CRUD
.Ve
.PP
.Vb 1
\& Gantry::Plugins::AjaxCRUD
.Ve
.PP
.Vb 1
\& Gantry::Plugins::AutoCRUD
.Ve
.PP
.Vb 1
\& Gantry and the other Gantry::Plugins
.Ve
.SH "AUTHOR"
.IX Header "AUTHOR"
Kevin L. Esteb
.SH "COPYRIGHT and LICENSE"
.IX Header "COPYRIGHT and LICENSE"
Copyright (c) 2006, Kevin L. Esteb
.PP
This library is free software; you can redistribute it and/or modify
it under the same terms as Perl itself, either Perl version 5.8.6 or,
at your option, any later version of Perl 5 you may have available.