.\" 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::TablePerms 3"
.TH Gantry::Utils::TablePerms 3 "2008-01-18" "perl v5.8.8" "User Contributed Perl Documentation"
.SH "NAME"
Gantry::Utils::TablePerms \- enforces retrieve permssions on main listings
.SH "SYNOPSIS"
.IX Header "SYNOPSIS"
.Vb 1
\&    use Gantry::Utils::TablePerms;
.Ve
.PP
.Vb 11
\&    # ...
\&    sub do_main {
\&        #...
\&        my $perm_obj = Gantry::Utils::TablePerms->new(
\&            {
\&                site           => $self,
\&                real_location  => $real_location,
\&                header_options => \e@header_options,
\&                row_options    => \e@row_options,
\&            }
\&        );
.Ve
.PP
.Vb 3
\&        # useful accessors available after a call to the contstructor:
\&        my $limit_to_user_id = $perm_obj->limit_to_user_id;
\&        my $hide_all_data    = $perm_obj->hide_all_data;
.Ve
.PP
.Vb 3
\&        # other accessors available after a call to the contstructor:
\&        my $logged_in_user   = $perm_obj->logged_in_user;
\&        my $admin_user       = $perm_obj->admin_user;
.Ve
.PP
.Vb 5
\&        ROW:
\&        foreach my $row ( @rows ) {
\&            next ROW if $perm_obj->hide_all_data;
\&            my $real_options = $perm_obj->real_row_options( $row );
\&        }
.Ve
.PP
.Vb 1
\&    }
.Ve
.SH "DESCRIPTION"
.IX Header "DESCRIPTION"
This module factors out the common task of row level permission handling
for do_main methods.
.SH "METHODS"
.IX Header "METHODS"
There is only one method, which is not exported.
.IP "new" 4
.IX Item "new"
This constructor method does a lot of grunt work surrounding the display
of main listing table rows when you use row level permissions.
.Sp
If your \f(CW\*(C`controller_config\*(C'\fR method's hash has a 'permissions' key, this
method enforces those permissions.  Otherwise, it opens the table to full
access.  To keep people out in that case, auth the whole controlller.
.Sp
Parameters a single hash ref with these keys:
.RS 4
.IP "gantry_site_object" 4
.IX Item "gantry_site_object"
This is the invocant of your do_ method.
.IP "real_location" 4
.IX Item "real_location"
This is usually generated for you by bigtop.  If not, use code like this:
.Sp
.Vb 5
\&    my $real_location = $self->location() || '';
\&    if ( $real_location ) {
\&        $real_location =~ s{/+$}{};
\&        $real_location .= '/';
\&    }
.Ve
.Sp
The real location becomes the base \s-1URL\s0 for edit and delete links.
.IP "header_options" 4
.IX Item "header_options"
An array ref of options for the whole table.  Each array element is a
hash.  The hashes have the same form as the ones in the \f(CW\*(C`row_options\*(C'\fR,
which are fully described below.  The default type for header options
is 'create'.  Of course, ids are never added to header option links,
since these do not apply to individual rows.
.IP "row_options" 4
.IX Item "row_options"
An array ref of options for each row.  Each array element is a hash.  Here's
a full sample:
.Sp
.Vb 6
\&    [
\&        { text => 'Edit',    type => 'update',                       },
\&        { text => 'Special', type => 'retrieve', link => '/your/url' },
\&        { text => 'Make one like this', type => 'create',            },
\&        { text => 'Delete',  type => 'delete',                       },
\&    ]
.Ve
.Sp
The keys:
.RS 4
.IP "text" 4
.IX Item "text"
What the user sees in the link text (if they are allowed to click it).
.IP "type" 4
.IX Item "type"
[optional defaults to 'retrieve']
.Sp
Pick from \f(CW\*(C`create\*(C'\fR, \f(CW\*(C`retrieve\*(C'\fR, \f(CW\*(C`update\*(C'\fR, or \f(CW\*(C`delete\*(C'\fR. 'create'
links are subject to the 'c' flag in the crudcrudcrud permissions.
\&'retrieve' links are subject to the 'r' flag.  'update' links are
subject to the 'u'.  'delete' links are subject to the 'd' flag.
If no type is given the 'r' flag governs.
.IP "link" 4
.IX Item "link"
[optional]
.Sp
Defaults to \f(CW"real_location/lctext/$id"\fR, where \f(CW\*(C`real_location\*(C'\fR
is the first parameter and \f(CW\*(C`lctext\*(C'\fR is the text parameter with two
changes.  First, all spaces are replaced with underscores.  Second,
it is forced to lower case.  So 'Make \s-1PDF\s0' becomes 'make_pdf'.
.Sp
Note that all links will have \f(CW"/$id"\fR as their last \s-1URL\s0 path element.
.RE
.RS 4
.RE
.RE
.RS 4
.RE
.IP "real_header_options" 4
.IX Item "real_header_options"
Parameters: none
.Sp
Returns: an array ref of header options for immediate use by main listing
tempaltes.
.IP "real_row_options" 4
.IX Item "real_row_options"
Parameter: a database row
.Sp
Returns: an array ref of row options suitable for immediate use by
main listing templates.
.SH "GET ONLY ACCESSORS"
.IX Header "GET ONLY ACCESSORS"
The only accessors you really need are \f(CW\*(C`limit_to_user_id\*(C'\fR,
\&\f(CW\*(C`hide_all_data\*(C'\fR, and \f(CW\*(C`real_row_options\*(C'\fR above.
.IP "limit_to_user_id" 4
.IX Item "limit_to_user_id"
This is the id number of the logged in user, but only if the main listing
should be limited to rows owned by that user.
.IP "hide_all_data" 4
.IX Item "hide_all_data"
Inidcates that the table permissions prohibit the current user from seeing
any rows in the table.  Use this to make sure no data is actually fed
to the template.
.IP "logged_in_user" 4
.IX Item "logged_in_user"
The id number of the currently logged in user (if anyone is logged in).
.IP "admin_user" 4
.IX Item "admin_user"
True if the user is an admin or if the page does not have table permissions.
.IP "gantry_site" 4
.IX Item "gantry_site"
For internal use.  Returns the site object you passed to the constructor.
.SH "AUTHOR"
.IX Header "AUTHOR"
Phil Crow, <crow.phil@gmail.com>
.SH "COPYRIGHT AND LICENSE"
.IX Header "COPYRIGHT AND LICENSE"
Copyright (C) 2005\-7, 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.