.\" 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::AutoCRUD 3"
.TH Gantry::Plugins::AutoCRUD 3 "2008-01-18" "perl v5.8.8" "User Contributed Perl Documentation"
.SH "NAME"
Gantry::Plugins::AutoCRUD \- provides CRUD support
.SH "SYNOPSIS"
.IX Header "SYNOPSIS"
In a base class:
.PP
.Vb 1
\&  use Gantry qw/-Engine=MP13 -TemplateEngine=Default AutoCRUD/;
.Ve
.PP
Or
.PP
.Vb 1
\&  use Gantry qw/-Engine=MP13 -TemplateEngine=TT AutoCRUD/;
.Ve
.PP
In your subclass:
.PP
.Vb 2
\&  use base 'BaseClass';
\&  use Gantry::Plugins::AutoCRUD;
.Ve
.SH "DESCRIPTION"
.IX Header "DESCRIPTION"
This plugin exports do_add, do_edit, and do_delete for modules which
perform straight Create, Update, and Delete (commonly called \s-1CRUD\s0,
except that R is retrieve which you still have to implement yourself in
do_main, do_view, etc.).
.SH "METHODS"
.IX Header "METHODS"
This module exports the following methods into the site object's class:
.IP "do_add" 4
.IX Item "do_add"
.PD 0
.IP "do_edit" 4
.IX Item "do_edit"
.IP "do_delete" 4
.IX Item "do_delete"
.IP "form_name (see below)" 4
.IX Item "form_name (see below)"
.PD
.PP
The handler calls these when the user clicks on the proper links
or types in the proper address by hand.
.PP
In order for these to work, you must implement the required
methods from this list yourself:
.IP "text_descr" 4
.IX Item "text_descr"
Return the string which will fill in the blank in the following phrases
.Sp
.Vb 3
\&    Add _____
\&    Edit _____
\&    Delete ____
.Ve
.IP "form_name" 4
.IX Item "form_name"
Optional.
The name of the template which generates the form's html.  There
is a default method provided here, but you can override it.  The
default always returns 'form.tt'.
.Sp
The method is called through the site object and passed either
\&'add' or 'edit', in case you need different forms for these two
activities.
.Sp
If you implement your own, don't import the one provided here (or
Perl will warn about subroutine redefinition).
.IP "get_orm_helper" 4
.IX Item "get_orm_helper"
Optional, defaults to
.Sp
.Vb 3
\&    sub get_orm_helper {
\&        return 'Gantry::Plugins::AutoCRUDHelper::CDBI';
\&    }
.Ve
.Sp
Implement this if you are not using Class::DBI as your \s-1ORM\s0.  Return the
name of your \s-1ORM\s0 helper.  For instance, if you use DBIx::Class implement
this in your controller (or in something your controller inherits from):
.Sp
.Vb 3
\&    sub get_orm_helper {
\&        return 'Gantry::Plugins::AutoCRUDHelper::DBIxClass';
\&    }
.Ve
.Sp
If you need to implement your own helper, see AutoCRUDHelpers below
and/or look at any module in Gantry::Plugins::AutoCRUDHelper::* for advice.
.IP "get_relocation" 4
.IX Item "get_relocation"
Optional.
Called with the name of the current action and whether the user clicked
submit or cancel like this:
.Sp
.Vb 1
\&    $self->get_relocation( 'add', 'cancel' );
.Ve
.Sp
Possible actions are add, edit, or delete.  Clicks are either cancel
or submit.
.Sp
Returns the url where users should go if they submit or cancel a form.
If defined, this method is used for both submit and cancel actions.
This means that get_submit_loc and get_cancel_loc are ignored.
.IP "get_cancel_loc" 4
.IX Item "get_cancel_loc"
Optional.
Called with the action the user is cancelling (add, edit, or delete).
Returns the url where users should go if they cancel form submission.
Ignored if get_relocation is defined, otherwise defaults to
\&\f(CW$self\fR\->location.
.IP "get_submit_loc" 4
.IX Item "get_submit_loc"
Optional.
Called with the action the user is submitting (add, edit, or delete).
Returns the url where users should go after they successfully submit a form.
Ignored if get_relocation is defined, otherwise defaults to
\&\f(CW$self\fR\->location.
.Sp
Instead of implementing get_relocation or get_submit_loc, 
you could implement one or more *_post_action method which alter the location
attribute of the self object.  Then the default behavior of get_submit_loc
would guide you to that location.  In this case, you could still implement
get_cancel_loc to control where bailing out takes the user.
.IP "get_model_name" 4
.IX Item "get_model_name"
Return the name of your data model package.  If your base class knows
this name you might want to do something like this:
.Sp
.Vb 1
\&    sub get_model_name { return $_[0]->companies_model }
.Ve
.Sp
This way, the model name is only in one place.
.IP "form" 4
.IX Item "form"
[ For historical reasons, you can name this _form, but that is deprecated
and subject to change. ]
.Sp
Called as a method on your self object with:
.Sp
.Vb 1
\&    the row object from the data model (if one is available)
.Ve
.Sp
This describes the entry form for do_add and do_edit.  Return a hash
with at least a fields key.
You can add to this any keys that your template is expecting.
.Sp
The fields key stores an array reference.  The array elements are
hashes with at least these keys (your template may be expecting others):
.RS 4
.IP "name" 4
.IX Item "name"
The name of the column in the database table and the field in the web form.
.IP "label" 4
.IX Item "label"
What the user will see as the name of the field on the web form.
.IP "optional" 4
.IX Item "optional"
Optional.  If included and true, the field will be optional.
Otherwise, the field will be required.
.IP "constraint" 4
.IX Item "constraint"
Optional.  Any valid Data::FormValidator constraint.
.RE
.RS 4
.Sp
Remember that your template may be expecting other keys like type,
display_size, default_value, date_select and others that vary by type.
.Sp
The default template in the sample apps uses options for select types
and both rows and cols for textarea types.
.RE
.IP "add_pre_action" 4
.IX Item "add_pre_action"
.Vb 4
\&  sub add_pre_action {
\&    my ( $self, $params ) = @_;
\&    ...  
\&  }
.Ve
.Sp
Optional.
Called immediately before a new row is inserted into the database with
the hash that will be passed directly to the \s-1ORM\s0 helper's insert method.
Adjust any parameters in the hash you like (fill in dates,
remove things that can't have '' as a value, etc.).
.IP "add_post_action" 4
.IX Item "add_post_action"
.Vb 4
\&  sub add_post_action {
\&    my ( $self, $new_row ) = @_;
\&    ...  
\&  }
.Ve
.Sp
Optional.
Called immediately after a new row has been inserted (and committed) into
the database with the newly minted row object.  This is a useful place
to make change log entries, send email, etc.
.IP "edit_pre_action" 4
.IX Item "edit_pre_action"
.Vb 4
\&  sub edit_pre_action {
\&    my ( $self, $row, $params ) = @_;
\&    ...  
\&  }
.Ve
.Sp
Optional.
Like add_pre_action, but receives the row to be updated and the params hash
that is about to be set on it.
.IP "edit_post_action" 4
.IX Item "edit_post_action"
.Vb 4
\&  sub edit_post_action {
\&    my ( $self, $row, $params ) = @_;
\&    ...  
\&  }
.Ve
.Sp
Optional.
Just like add_post_action, but for edit.
.IP "delete_pre_action" 4
.IX Item "delete_pre_action"
.Vb 4
\&  sub delete_pre_action {
\&    my ( $self, $row, $params ) = @_;
\&    ...  
\&  }
.Ve
.Sp
Optional.
Called just before a row is removed from the database with the row
object.
.IP "delete_post_action" 4
.IX Item "delete_post_action"
.Vb 4
\&  sub delete_post_action {
\&    my ( $self, $row, $params ) = @_;
\&    ...  
\&  }
.Ve
.Sp
Optional.
Called just after a row has been removed from the database with the former
row's id.
.SH "INTERNAL METHODS"
.IX Header "INTERNAL METHODS"
These are methods used internally to figure out where to go on button presses
and who should help the \s-1ORM\s0 manage the database.
.IP "find_orm_helper" 4
.IX Item "find_orm_helper"
.PD 0
.IP "find_cancel_loc" 4
.IX Item "find_cancel_loc"
.IP "find_submit_loc" 4
.IX Item "find_submit_loc"
.PD
.SH "AutoCRUDHelpers"
.IX Header "AutoCRUDHelpers"
If there is not a Gantry::Plugins::AutoCRUD::* module for your \s-1ORM\s0, you
can easily implement your own.  Here's how.
.PP
Create a module (the name is completely up to you, but something in the
Gantry::Plugins::AutoCRUD:: namespace may be easier for others to find).
In it implement four methods:
.IP "insert" 4
.IX Item "insert"
Parameters:
    \f(CW$class\fR              \- invoking class name
    \f(CW$gantry_site_object\fR \- the current Gantry site object
    \f(CW$params\fR             \- a hash to be inserted into a new row
Return:
    the newly created row
.Sp
Puts a new row into a table of the database.  You must determine
the table name by querying \f(CW$gantry_site_object\fR.  For instance, if the app
uses \s-1CDBI\s0 models, your table name is:
.Sp
.Vb 1
\&    $gantry_site_object->get_model_name
.Ve
.Sp
For DBIx::Class models, your table name is:
.Sp
.Vb 1
\&    $gantry_site->get_model_name->table_name();
.Ve
.IP "retrieve" 4
.IX Item "retrieve"
Parameters:
    \f(CW$class\fR              \- invoking class name
    \f(CW$gantry_site_object\fR \- the current Gantry site object
    \f(CW$id\fR                 \- the primary key of a row (single column only)
Return:
    the row whose id is \f(CW$id\fR
.Sp
Given a unique one column primary key, called \f(CW$id\fR, return the corresponding
row.  See the discussion under insert for how to find your table name.
.IP "update" 4
.IX Item "update"
Parameters:
    \f(CW$class\fR              \- invoking class name
    \f(CW$gantry_site_object\fR \- the current Gantry site object
    \f(CW$row\fR                \- the row object to update
    \f(CW$params\fR             \- a hash to be inserted into a new row
Return:
    whatever you like (ignored)
.Sp
Given an \s-1ORM\s0 object, update the underlying data.
.IP "delete" 4
.IX Item "delete"
Parameters:
    \f(CW$class\fR              \- invoking class name
    \f(CW$gantry_site_object\fR \- the current Gantry site object
    \f(CW$row\fR                \- the row object to update
Return:
    whatever you like (ignored)
.Sp
Given an \s-1ORM\s0 object, delete the underlying row.
.SH "SEE ALSO"
.IX Header "SEE ALSO"
.Vb 1
\& Gantry::Plugins::AutoCRUD::CDBI
.Ve
.PP
.Vb 1
\& Gantry::Plugins::AutoCRUD::DBIxClass
.Ve
.PP
.Vb 1
\& Gantry::Plugins::CRUD
.Ve
.PP
.Vb 1
\& The Billing sample app
.Ve
.PP
.Vb 1
\& Gantry and the other Gantry::Plugins
.Ve
.SH "LIMITATIONS"
.IX Header "LIMITATIONS"
These methods only work one way.  If you need more flexibility, you
will have to code your own method and nothing here will help you
(but Gantry::Plugins::CRUD might).
.PP
The idea is to do the work for the 60\-80% of your modules which manage
data in one table one row at a time, leaving you to work on the ones
that are more interesting.
.SH "AUTHOR"
.IX Header "AUTHOR"
Phil Crow <philcrow2000@yahoo.com>
.SH "COPYRIGHT and LICENSE"
.IX Header "COPYRIGHT and LICENSE"
Copyright (c) 2005, Phil Crow
.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.