.\" 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::Utils::ModelHelper 3"
.TH Gantry::Utils::ModelHelper 3 "2008-01-18" "perl v5.8.8" "User Contributed Perl Documentation"
.SH "NAME"
Gantry::Utils::ModelHelper \- mixin for model base classes
.SH "SYNOPSIS"
.IX Header "SYNOPSIS"
.Vb 5
\&    use Gantry::Utils::ModelHelper qw(
\&        db_Main
\&        get_listing
\&        get_form_selections
\&    );
.Ve
.PP
.Vb 4
\&    sub get_db_options {
\&        return {};  # put your default options here
\&        # consider calling __PACKAGE->_default_attributes
\&    }
.Ve
.SH "DESCRIPTION"
.IX Header "DESCRIPTION"
This module provides mixin methods commonly needed by model base classes.
Note that you must request the methods you want for the mixin scheme to
work.  Also note that you can request either db_Main or auth_db_Main, but
not both.  Whichever one you choose will be exported as db_Main in your
package.
.SH "METHODS"
.IX Header "METHODS"
.IP "db_Main" 4
.IX Item "db_Main"
This method returns a valid dbh using the scheme described in
Gantry::Docs::DBConn.  It is compatible with Class::DBI and
Gantry::Plugins::DBIxClassConn (the later is a mixin which allows
easy access to a DBIx::Schema object for controllers).
.IP "auth_db_Main" 4
.IX Item "auth_db_Main"
This method is exported as db_Main and works with the scheme described
in Gantry::Docs::DBConn.  It too is compatible with Class::DBI and
Gantry::Plugins::DBIxClassConn.
.Sp
I will repeat, if you ask for this method in your use statement:
.Sp
.Vb 1
\&    use lib/Gantry/Utils/ModelHelper qw( auth_db_Main ... );
.Ve
.Sp
it will come into your namespace as db_Main.
.IP "get_form_selections" 4
.IX Item "get_form_selections"
This method gives you a selection list for each foriegn key in your
table.  The lists come to you as a single hash keyed by the table names
of the foreign keys.  The values in the hash are ready for use
by form.tt as options on the field (whose type should be select).
Example:
.Sp
.Vb 8
\&    {
\&        status => [
\&            { value => 2, label => 'Billed' },
\&            { value => 1, label => 'In Progress' },
\&            { value => 3, label => 'Paid' },
\&        ],
\&        other_table => [ ... ],
\&    }
.Ve
.Sp
To use this method, your models must implement these class methods:
.RS 4
.IP "get_foreign_tables" 4
.IX Item "get_foreign_tables"
(Must be implemented by the model on which get_form_selections is called.)
Returns a list of the fully qualified package names of the models
of this table's foreign keys.  Example:
.Sp
.Vb 6
\&    sub get_foreign_tables {
\&        return qw(
\&            Apps::AppName::Model::users
\&            Apps::AppName::Model::other_table
\&        );
\&    }
.Ve
.IP "get_foreign_display_fields" 4
.IX Item "get_foreign_display_fields"
(Must be implemented by all the models of this table's foreign keys.)
Returns an array reference whose elements are the names of the columns
which will appear on the screen in the selection list.  Example:
.Sp
.Vb 3
\&    sub get_foreign_display_fields {
\&        return [ qw( last_name first_name ) ];
\&    }
.Ve
.RE
.RS 4
.RE
.IP "get_listing" 4
.IX Item "get_listing"
Replacement for retrieve_all_for_main_listing.
.Sp
Returns a list of row objects (one for each row in the table).  The
\&\s-1ORDER\s0 \s-1BY\s0 clause is either the same as the foreign_display columns
or chosen by you.  If you want to supply the order do it like this:
.Sp
.Vb 1
\&    my @rows = $MODEL->get_listing ( { order_by => 'last, first' } );
.Ve
.Sp
Note that your order_by will be used \s-1AS\s0 \s-1IS\s0, so it must be a valid \s-1SQL\s0
\&\s-1ORDER\s0 \s-1BY\s0 clause, but feel free to include \s-1DESC\s0 or anything else you and \s-1SQL\s0
like.
.IP "retrieve_all_for_main_listing" 4
.IX Item "retrieve_all_for_main_listing"
\&\s-1DEPRECATED\s0 use get_listing instead
.Sp
Returns a list of row objects (one for each row in the table) in order
by their foreign_display columns.
.SH "AUTHOR"
.IX Header "AUTHOR"
Phil Crow <philcrow2000@yahoo.com>
.SH "COPYRIGHT and LICENSE"
.IX Header "COPYRIGHT and LICENSE"
Copyright (c) 2006, 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.