CartTrigger

Specify one or more subroutines to invoke every time the contents of a shopping cart is changed.

Synopsis

CartTrigger subroutine_name [subroutine_names...]

Scope

This directive is only available for use in the local (catalog.cfg) configuration file. It will not affect any other website in any way. This directive will not work in the global (interchange.cfg) configuration file.

Description

This directive allows you to specify any number of Perl subroutines (Sub or GlobalSub) that will be invoked whenever a user's shopping cart contents change via one of the standard methods (i.e. with mv_order_item or mv_order_quantity parameters in a <form> submission).

Note

Quantity changes will not cause triggers to fire unless the CartTriggerQuantity configuration directive is set true.

The subroutine(s) will be executed on a per-change basis; If a <form> submission results in multiple alterations to the shopping cart, then the trigger subroutines will be called multiple times, once for each change.

The following parameters will be passed to the trigger subroutine(s):

A reference to the user's shopping cart in which the change is triggered.
The name of the action that fired the trigger (one of either "add", "update" or "delete")
A hashref pointing to the new item content for the shopping cart line (except for the "delete" action, in which case this parameter will be undefined).
A hashref that contains a copy of the line item data prior to the change (except for the "add" action).
The name of the shopping cart in which the change was made. See $Carts in the Interchange Perl objects documentation.

The return value from each subroutine call is pushed onto an array. When all subroutines specified in CartTrigger have been called, the full array of results will be returned. Note that the initial version of this functionality does not use these return values in any meaningful way.

Warning

Direct [perl] manipulation of the $Carts hashref, or the $Items arrayref, will not cause either CartTrigger or CartTriggerQuantity triggers to fire. Cart triggers only fire when the cart content is modified by Interchange's CGI argument processing code.

Example

The following example sets up a trigger that forces the quantity of all sub items to match their corresponding master item's quantity. Whenever the master item's quantity is modified, the quantity of all dependent sub items will be changed to match the new value.

Sub <<EOS
sub cascade_quantities {
my ($cartref, $action, $newref, $oldref, $cartname) = @_;

#
# only act upon the "main" cart
#
return unless $cartname eq 'main';

if ($action eq 'update' && $newref->{mv_si} == 0 && $newref->{quantity} != $oldref->{quantity}) {
#
# update quantities of sub-items
#
foreach my $subref (grep {$_->{mv_mi} eq $newref->{mv_mi}} @$cartref) {
$subref->{quantity} = $newref->{quantity};
}
}
}
EOS

CartTrigger cascade_quantities
CartTriggerQuantity Yes