.\" Automatically generated by Pod::Man 4.07 (Pod::Simple 3.32)
.\"
.\" 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
..
.if !\nF .nr F 0
.if \nF>0 \{\
.    de IX
.    tm Index:\\$1\t\\n%\t"\\$2"
..
.    if !\nF==2 \{\
.        nr % 0
.        nr F 2
.    \}
.\}
.\" ========================================================================
.\"
.IX Title "DBIx::Class::Helper::Row::OnColumnChange 3pm"
.TH DBIx::Class::Helper::Row::OnColumnChange 3pm "2016-11-02" "perl v5.24.1" "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"
DBIx::Class::Helper::Row::OnColumnChange \- Do things when the values of a column change
.SH "SYNOPSIS"
.IX Header "SYNOPSIS"
.Vb 1
\& package MyApp::Schema::Result::Account;
\&
\& use parent \*(AqDBIx::Class::Core\*(Aq;
\&
\& _\|_PACKAGE_\|_\->load_components(qw(Helper::Row::OnColumnChange));
\&
\& _\|_PACKAGE_\|_\->table(\*(AqAccount\*(Aq);
\&
\& _\|_PACKAGE_\|_\->add_columns(
\&    id => {
\&       data_type         => \*(Aqinteger\*(Aq,
\&       is_auto_increment => 1,
\&    },
\&    amount => {
\&       data_type          => \*(Aqfloat\*(Aq,
\&       keep_storage_value => 1,
\&    },
\& );
\& sub on_column_change_allow_override_args { 1 }
\&
\& _\|_PACKAGE_\|_\->before_column_change(
\&   amount => {
\&      method   => \*(Aqbank_transfer\*(Aq,
\&      txn_wrap => 1,
\&   }
\& );
\&
\& sub bank_transfer {
\&   my ($self, $old_value, $new_value) = @_;
\&
\&   my $delta = abs($old_value \- $new_value);
\&   if ($old_value < $new_value) {
\&      Bank\->subtract($delta)
\&   } else {
\&      Bank\->add($delta)
\&   }
\& }
\&
\& 1;
.Ve
.PP
or with DBIx::Class::Candy:
.PP
.Vb 1
\& package MyApp::Schema::Result::Account;
\&
\& use DBIx::Class::Candy \-components => [\*(AqHelper::Row::OnColumnChange\*(Aq];
\&
\& table \*(AqAccount\*(Aq;
\&
\& column id => {
\&    data_type         => \*(Aqinteger\*(Aq,
\&    is_auto_increment => 1,
\& };
\&
\& column amount => {
\&    data_type          => \*(Aqfloat\*(Aq,
\&    keep_storage_value => 1,
\& };
\& sub on_column_change_allow_override_args { 1 }
\&
\& before_column_change amount => {
\&    method   => \*(Aqbank_transfer\*(Aq,
\&    txn_wrap => 1,
\& };
\&
\& sub bank_transfer {
\&   my ($self, $old_value, $new_value) = @_;
\&
\&   my $delta = abs($old_value \- $new_value);
\&   if ($old_value < $new_value) {
\&      Bank\->subtract($delta)
\&   } else {
\&      Bank\->add($delta)
\&   }
\& }
\&
\& 1;
.Ve
.SH "DESCRIPTION"
.IX Header "DESCRIPTION"
This module codifies a pattern that I've used in a number of projects, namely
that of doing \fBsomething\fR when a column changes it's value in the database.
It leverages DBIx::Class::Helper::Row::StorageValues for passing in the
\&\f(CW$old_value\fR, which do not have to use.  If you leave the
\&\f(CW\*(C`keep_storage_value\*(C'\fR out of the column definition it will just pass \f(CW\*(C`undef\*(C'\fR
in as the \f(CW$old_value\fR.  Also note the \f(CW\*(C`txn_wrap\*(C'\fR option.  This allows you to
specify that you want the call to \f(CW\*(C`update\*(C'\fR and the call to the method you
requested to be wrapped in a transaction.  If you end up calling more than
one method due to multiple column change methods and more than one specify
\&\f(CW\*(C`txn_wrap\*(C'\fR it will still only wrap once.
.PP
I've gone to great lengths to ensure that order is preserved, so \f(CW\*(C`before\*(C'\fR
and \f(CW\*(C`around\*(C'\fR changes are called in order of definition and \f(CW\*(C`after\*(C'\fR changes
are called in reverse order.
.PP
To be clear, the change methods only get called if the value will be changed
after \f(CW\*(C`update\*(C'\fR runs.  It correctly looks at the current value of the column
as well as the arguments passed to \f(CW\*(C`update\*(C'\fR.
.SH "CANDY EXPORTS"
.IX Header "CANDY EXPORTS"
If used in conjunction with DBIx::Class::Candy this component will export:
.IP "before_column_change" 4
.IX Item "before_column_change"
.PD 0
.IP "around_column_change" 4
.IX Item "around_column_change"
.IP "after_column_change" 4
.IX Item "after_column_change"
.PD
.SH "NO SURPRISE RACE CONDITIONS"
.IX Header "NO SURPRISE RACE CONDITIONS"
One thing that should be made totally clear is that the column change callbacks
are in effect \fBonly once\fR in a given update.  If you expect to be able to
do something weird like calling one of the callbacks which changes a value with
an accessor which calls a callback etc etc, you probably just need to write some
code to do that yourself.  This helper is specifically made with the aim of
reacting to changes immediately before they hit the database.
.SH "METHODS"
.IX Header "METHODS"
.SS "before_column_change"
.IX Subsection "before_column_change"
.Vb 6
\& _\|_PACKAGE_\|_\->before_column_change(
\&   col_name => {
\&      method   => \*(Aqmethod\*(Aq, # <\-\- anything that can be called as a method
\&      txn_wrap => 1,        # <\-\- true if you want it to be wrapped in a txn
\&   }
\& );
.Ve
.PP
Note: the arguments passed to \f(CW\*(C`method\*(C'\fR will be
\&\f(CW\*(C`$self, $old_value, $new_value\*(C'\fR.
.SS "after_column_change"
.IX Subsection "after_column_change"
.Vb 6
\& _\|_PACKAGE_\|_\->after_column_change(
\&   col_name => {
\&      method   => \*(Aqmethod\*(Aq, # <\-\- anything that can be called as a method
\&      txn_wrap => 1,        # <\-\- true if you want it to be wrapped in a txn
\&   }
\& );
.Ve
.PP
Note: the arguments passed to \f(CW\*(C`method\*(C'\fR will be
\&\f(CW\*(C`$self, $new_value, $new_value\*(C'\fR. (Because the old value has been changed.)
.SS "around_column_change"
.IX Subsection "around_column_change"
.Vb 6
\& _\|_PACKAGE_\|_\->around_column_change(
\&   col_name => {
\&      method   => \*(Aqmethod\*(Aq, # <\-\- anything that can be called as a method
\&      txn_wrap => 1,        # <\-\- true if you want it to be wrapped in a txn
\&   }
\& );
.Ve
.PP
Note: the arguments passed to \f(CW\*(C`method\*(C'\fR will be
\&\f(CW\*(C`$self, $next, $old_value, $new_value\*(C'\fR.
.PP
Around is subtly different than the other two callbacks.  You \fBmust\fR call
\&\f(CW$next\fR in your method or it will not work at all.  A silly example of how
this is done could be:
.PP
.Vb 2
\& sub around_change_name {
\&   my ($self, $next, $old, $new) = @_;
\&
\&   my $govt_records = $self\->govt_records;
\&
\&   $next\->();
\&
\&   $govt_records\->update({ name => $new });
\& }
.Ve
.PP
Note: the above code implies a weird database schema.  I haven't actually seen
a time when I've needed around yet, but it seems like there is a use-case.
.PP
Also Note: you don't get to change the args to \f(CW$next\fR.  If you think you
should be able to, you probably don't understand what this component is for.
That or you know something I don't (equally likely.)
.SS "on_column_change_allow_override_args"
.IX Subsection "on_column_change_allow_override_args"
This is a method that allows a user to circumvent a strange bug in the initial
implementation.  Basically, if the user wanted, she could use
\&\*(L"before_column_change\*(R" to override the value of a given column before
\&\f(CW\*(C`update\*(C'\fR gets called, thus replacing the value.  Unfortunately this worked in
the case of accessors setting the value, but not if the user had used an
argument to \f(CW\*(C`update\*(C'\fR.  To be clear, if you want the following to actually
replace the value:
.PP
.Vb 4
\& _\|_PACKAGE_\|_\->before_column_change(
\&    name => {
\&       method   => sub {
\&          my ($self, $old, $new) = @_;
\&
\&          $self\->name(uc $new);
\&       },
\&    },
\& );
.Ve
.PP
you will need to define this in your result class:
.PP
.Vb 1
\& sub on_column_change_allow_override_args { 1 }
.Ve
.PP
If for some reason you need the old style, a default of false is already set.
If you are painted in the corner and need both, you can create an accessor and
set it yourself to change the behavior:
.PP
.Vb 3
\& _\|_PACKAGE_\|_\->mk_group_accessors(inherited => \*(Aqon_column_change_allow_override_args\*(Aq);
\& ...
\& $obj\->on_column_change_allow_override_args(1); # works the new way
.Ve
.SH "AUTHOR"
.IX Header "AUTHOR"
Arthur Axel \*(L"fREW\*(R" Schmidt <frioux+cpan@gmail.com>
.SH "COPYRIGHT AND LICENSE"
.IX Header "COPYRIGHT AND LICENSE"
This software is copyright (c) 2016 by Arthur Axel \*(L"fREW\*(R" Schmidt.
.PP
This is free software; you can redistribute it and/or modify it under
the same terms as the Perl 5 programming language system itself.