.\" Automatically generated by Pod::Man 4.14 (Pod::Simple 3.40)
.\"
.\" Standard preamble:
.\" ========================================================================
.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.  \*(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-
.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" ''
.    ds C`
.    ds C'
'br\}
.\"
.\" Escape single quotes in literal strings from groff's Unicode transform.
.ie \n(.g .ds Aq \(aq
.el       .ds Aq '
.\"
.\" If the F register is >0, we'll generate index entries on stderr for
.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index
.\" entries marked with X<> in POD.  Of course, you'll have to process the
.\" output yourself in some meaningful fashion.
.\"
.\" Avoid warning from groff about undefined register 'F'.
.de IX
..
.nr rF 0
.if \n(.g .if rF .nr rF 1
.if (\n(rF:(\n(.g==0)) \{\
.    if \nF \{\
.        de IX
.        tm Index:\\$1\t\\n%\t"\\$2"
..
.        if !\nF==2 \{\
.            nr % 0
.            nr F 2
.        \}
.    \}
.\}
.rr rF
.\" ========================================================================
.\"
.IX Title "Class::DBI::FromCGI 3pm"
.TH Class::DBI::FromCGI 3pm "2021-01-05" "perl v5.32.0" "User Contributed Perl Documentation"
.\" For nroff, turn off justification.  Always turn off hyphenation; it makes
.\" way too many mistakes in technical documents.
.if n .ad l
.nh
.SH "NAME"
Class::DBI::FromCGI \- Update Class::DBI data using CGI::Untaint
.SH "SYNOPSIS"
.IX Header "SYNOPSIS"
.Vb 4
\&  package Film;
\&  use Class::DBI::FromCGI;
\&  use base \*(AqClass::DBI\*(Aq;
\&  # set up as any other Class::DBI class.
\&
\&  _\|_PACKAGE_\|_\->untaint_columns(
\&    printable => [qw/Title Director/],
\&    integer   => [qw/DomesticGross NumExplodingSheep/],
\&    date      => [qw/OpeningDate/],
\&  );
\&
\&  # Later on, over in another package ...
\&
\&  my $h = CGI::Untaint\->new( ... );
\&  my $film = Film\->retrieve(\*(AqGodfather II\*(Aq);
\&     $film\->update_from_cgi($h);
\&
\&  my $new_film = Film\->create_from_cgi($h);
\&
\&  if (my %errors = $film\->cgi_update_errors) {
\&    while (my ($field, $problem) = each %errors) {
\&      warn "Problem with $field: $problem\en";
\&    }
\&  }
\&
\&  # or
\&  $film\->update_from_cgi($h => @columns_to_update);
\&
\&  # or
\&  $film\->update_from_cgi($h => { ignore => \e@cols_to_ignore,
\&                                 required => \e@cols_needed,
\&                                 all => \e@columns_which_may_be_empty });
\&
\&
\&  my $how = $film\->untaint_type(\*(AqTitle\*(Aq); # printable
.Ve
.SH "DESCRIPTION"
.IX Header "DESCRIPTION"
Lots of times, Class::DBI is used in web-based applications. (In fact,
coupled with a templating system that allows you to pass objects, such
as Template::Toolkit, Class::DBI is very much your friend for these.)
.PP
And, as we all know, one of the most irritating things about writing
web-based applications is the monotony of writing much of the same stuff
over and over again. And, where there's monotony there's a tendency to
skip over stuff that we all know is really important, but is a pain to
write \- like Taint Checking and sensible input validation. (Especially
as we can still show a 'working' application without it!). So, we now
have CGI::Untaint to take care of a lot of that for us.
.PP
It so happens that CGI::Untaint also plays well with Class::DBI.
Class::DBI::FromCGI is a little wrapper that ties these two together.
.SH "METHODS"
.IX Header "METHODS"
.SS "untaint_columns"
.IX Subsection "untaint_columns"
All you need to do is to 'use Class::DBI::FromCGI' in your class (or
in your local Class::DBI subclass that all your other classes inherit
from. You do do that, don't you?).
.PP
Then, in each class in which you want to use this, you declare how you
want to untaint each column:
.PP
.Vb 5
\&  _\|_PACKAGE_\|_\->untaint_columns(
\&    printable => [qw/Title Director/],
\&    integer   => [qw/DomesticGross NumExplodingSheep/],
\&    date      => [qw/OpeningDate/],
\&  );
.Ve
.PP
(where the keys are the CGI::Untaint package to be used, and the values
a listref of the relevant columns).
.SS "update_from_cgi"
.IX Subsection "update_from_cgi"
When you want to update based on the values coming in from a
web-based form, you just call:
.PP
.Vb 1
\&  $obj\->update_from_cgi($h => @columns_to_update);
.Ve
.PP
If every value passed in gets through the CGI::Untaint process, the object
will be updated (but not committed, in case you want to do anything else
with it). Otherwise the update will fail (there are no partial updates),
and \f(CW$obj\fR\->cgi_update_errors will tell you what went wrong (as a hash of
problem field => error from CGI::Untaint).
.SS "create_from_cgi"
.IX Subsection "create_from_cgi"
Similarly, if you wish to create a new object, then you can call:
.PP
.Vb 1
\&  my $obj = Class\->create_from_cgi($h => @columns_to_update);
.Ve
.PP
If this fails, \f(CW$obj\fR will be a defined object, containing the errors,
as with an update, but will not contain the values submitted, nor have
been written to the database.
.SS "untaint_type"
.IX Subsection "untaint_type"
.Vb 1
\&  my $how = $film\->untaint_type(\*(AqTitle\*(Aq); # printable
.Ve
.PP
This tells you how we're going to untaint a given column.
.SS "cgi_update_errors"
.IX Subsection "cgi_update_errors"
.Vb 5
\&  if (my %errors = $film\->cgi_update_errors) {
\&    while (my ($field, $problem) = each %errors) {
\&      warn "Problem with $field: $problem\en";
\&    }
\&  }
.Ve
.PP
This returns a hash of any errors when updating. Despite its name it
also applies when inserting.
.SH "Column Auto-Detection"
.IX Header "Column Auto-Detection"
As Class::DBI knows all its columns, you don't even have to say
what columns you're interested in, unless it's a subset, as we can
auto-fill these:
.PP
.Vb 1
\&  $obj\->update_from_cgi($h);
.Ve
.PP
You can also specify columns which must be present, or columns to be
ignored even if they are present:
.PP
.Vb 5
\&  $film\->update_from_cgi($h => {
\&    all      => \e@all_columns, # auto\-filled if left blank
\&    ignore   => \e@cols_to_ignore,
\&    required => \e@cols_needed,
\&  });
.Ve
.PP
Doesn't this all make your life so much easier?
.SH "NOTE"
.IX Header "NOTE"
Don't try to update the value of your primary key. Class::DBI doesn't
like that. If you try to do this it will be silently skipped.
.SH "ANOTHER NOTE"
.IX Header "ANOTHER NOTE"
If you haven't set up any 'untaint_column' information for a column which
you later attempt to untaint, then we try to call \f(CW$self\fR\->column_type to
ascertain the default handler to use. Currently this will only use if
you're using Class::DBI::mysql, and only for certain column types.
.SH "SEE ALSO"
.IX Header "SEE ALSO"
Class::DBI. CGI::Untaint. Template.
.SH "AUTHOR"
.IX Header "AUTHOR"
Tony Bowden
.SH "BUGS and QUERIES"
.IX Header "BUGS and QUERIES"
Please direct all correspondence regarding this module to:
  bug\-Class\-DBI\-FromCGI@rt.cpan.org
.SH "COPYRIGHT"
.IX Header "COPYRIGHT"
Copyright (C) 2001\-2005 Kasei. All rights reserved.
.PP
This module is free software; you can redistribute it and/or modify
it under the same terms as Perl itself.