SpecialSub

Specify specify subroutines that should be called to handle certain events.

Synopsis

SpecialSub event subroutine_name

You can specify subroutines for multiple events at once by using the Perl-style "here document" syntax, as follows:

SpecialSub <<EOS
event1 subroutine_name1
event2 subroutine_name2
EOS

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 is used to specify Sub or GlobalSub subroutines that will be called to handle certain events. Individual subroutines can be defined to handle the following events:

Event

Description

Versions

admin_init

If the user has administrator privileges then this subroutine will be called after "catalog_init" (if defined), after session assignment and after all of the Interchange Perl objects have been set up and initialised. This could, for instance, allow you to gain access to admin facilities, based upon user names or groups etc.

5.5.0+

debug_qualify

This subroutine (if defined) will be called to decide whether a debug message should be either logged to the DebugFile or simply ignored. The "debug_qualify" subroutine will only be called if the visitor's IP address is found in the DebugHost list, or no such list of IP addresses has been declared. If the "debug_qualify" subroutine returns a true value then the debug message will be logged.

5.5.0+

flypage

This event is triggered just before each flypage is displayed. The page name is provided to the given subroutine to be qualified or modified. The subroutine is expected to return a single SKU value for use on the subsequent flypage. See the example, below. The subroutine could also be used to set scratchpad and/or CGI values etc., of course.

API change

From its introduction in version 5.3.2, right up to version 5.5.2, the return value from this event's subroutine was expected to look like the following:

{ mv_results => [[ $sku ]] }

The API was changed in version 5.5.2 to allow the subroutine the choice of returning the above hashref or just a scalar containing the SKU value. The example, below, uses the simpler scalar return value.

5.3.2+

guess_cc_type

This event is triggered when the "mv_credit_card_type" is derived. Interchange recognises major card types but you might find that you need more. The subroutine is called with the credit card number. The return value should either be a type name, or a false value. A false return value will be taken to mean that Interchange should proceed with its built-in card type detection algorithm.

All

init_session

This event is triggered every time a new session is created. The subroutine is called with a reference to the newly created session hash. You may add, remove or modify session values as you see fit, but you must fully understand what you are doing before you start monkeying about in there. The subroutine's return value will be ignored.

All

lockout

This event allows you to run custom code during the bad robot lockout procedure (see the RobotLimit local configuration directive). The subroutine is called without parameters. If the subroutine returns true then the standard (LockoutCommand) lockout procedure will be skipped, otherwise the standard lockout procedure will run as usual.

All

missing

This Event is triggered when a requested Interchange page is missing. The subroutine is called with the name of the missing page. A false return value from the subroutine will instruct Interchange to continue executing the default, built-in, action. A true return value will indicate that all actions (including the response to the client) have been performed by the custom subroutine, and so the default action should not be executed. Optionally, the subroutine can return an array consisting of a true value and the name of a page that should to be displayed to the user.

All

request_init
(was catalog_init)

This subroutine is called upon the receipt of every page request, and before any session assignment or creation is performed. The subroutine's return value is ignored.

Name change

This subroutine was named "catalog_init" when it was introduced in version 5.5.0. It was renamed as "request_init" in version 5.5.2 to make way for a new "catalog_init" event which, when it is introduced in the future, will have an entirely different purpose.

5.5.0+

Availability

"All versions" refers to Interchange 5.0.0 and above, as 5.0.0 is the baseline for the documentation on this website. Most of the events marked "All" were available long before version 5.0.0 was released.

Examples

Handling the "admin_init" event

SpecialSub admin_init on_admin_init

Sub on_admin_init <<EOS
sub {
if ($Session->{username} eq 'foundation') {
$Variable->{MV_MENU_DIRECTORY} = 'include/foundation/menus';
}
}
EOS

Handling the "catalog_init" event

SpecialSub catalog_init on_catalog_init

Sub on_catalog_init <<EOS
sub {
$CGI::user = $CGI::server_host;
return 0;
}
EOS

Handling the "debug_qualify" event

SpecialSub debug_qualify debug_cgi_check

Sub debug_cgi_check <<EOS
sub {
return $CGI->{debug};
}
EOS

The above will only allow debug messages to be written into the DebugFile if [cgi debug] is set to a true value.

Handling the "flypage" event

SpecialSub flypage bounce_variants

Sub bounce_variants <<EOS
sub {
my $sku = shift;

my $override = $Tag->data({
table => 'variants',
column => 'sku',
key => $sku,
});
return length($override) ? $override : $sku;
}
EOS

The above code will show users the base SKU when they ask to see a variant. The code will check whether the requested SKU is listed in the "variants" table. If so then the base SKU will be returned, otherwise the requested SKU will be returned. The returned SKU will be displayed on the subsequent flypage.

Handling the "guess_cc_type" event

SpecialSub guess_cc_type check_card_type

Sub check_card_type <<EOS
sub {
my $num = shift;
return 'LOCAL_TYPE' if $num =~ /^41/;
return 0;
}
EOS

Handling the "init_session" event

SpecialSub init_session on_init_session

Sub on_init_session <<EOS
sub {
my $session = shift;

if (grep { $CGI::remote_addr } @blacklisted_IPs) {
$session->{blacklist} = 1;
}
}
EOS

In the event of a client coming from a "blacklisted" IP address, the blacklist entry in the user's session would be created. At a later stage, "blacklisted" sessions could be prevented from ordering items, as the order is markedly more likely to be fraudulent.

Handling the "lockout" event

SpecialSub lockout on_lockout

Sub on_lockout <<EOS
sub {
return $::Scratch->{override_lockout};
}
EOS

The above code will return the value of the "override_lockout" scratchpad variable. If the value is true (non-zero and not blank or undefined) then the user will not be locked out for exceeding the RobotLimit.

Handling the "missing" event

SpecialSub missing on_missing

Sub on_missing <<EOS
sub {
my $name = shift;
return unless $name =~ /^[A-Z]/;
$name =~ s,_, ,g;
my ($prod_group, $category) = split('/',$name);

$CGI->{st} = 'db';
$CGI->{fi} = 'products';
$CGI->{sp} = 'results';
$CGI->{co} = 1;
$CGI->{sf} = join("\0",'prod_group','category');
$CGI->{op} = join("\0",'eq','eq');
$CGI->{se} = join("\0",$prod_group,$category);
$CGI->{mv_todo} = 'search';
$Tag->update('process');

return (1,'results');
}
EOS