For more information... RTFM!

You are not logged in

Powered by Interchange version 5.7.0


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


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


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. 


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+

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

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.

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
order_missing This event is triggered on an attempt to order a non-existent sku or variant code.  This subroutine is called with the invalid item code and quantity of the order attempt.  A false return value from the subroutine will instruct Interchange to log the failed attempt as per normal to the error log.  A true return value will suppress the error log message. 5.7.2+
(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

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.

user_merge This event is triggered from the [user-merge] UI tag on each user that is merged into the target user.  You can use this event to perform additional tasks during the merge such as copy some of the userdb data over from one user to the other or update additional tables in the database. 

The arguments passed to this subroutine are:  ($from_user, $from_urec, $to_user, $to_urec, $udb, $tdb).  $from_user and $to_user are the source and target usernames respectively.  $from_urec and $to_urec are the source and target user records fetched from the userdb table with the $db->row_hash() method.  $udb and $tdb are the userdb and transactions $db objects respectively. 

The subroutine should return true if no further processing of the merge is to take place.  If the subroutine returns false then the rest of the merge is performed as per usual.  Any changes made to $to_urec will also be saved back to the userdb if the subroutine returns false so it is not necessary to save those changes yourself.



"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.


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';

Handling the "debug_qualify" event

SpecialSub  debug_qualify  debug_cgi_check

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

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;

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;

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;

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};

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';

    return (1,'results');

Handling the "request_init" event

SpecialSub  request_init  on_request_init

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

Category:  Local config directives
Last modified by: Peter Ajamian
Modification date: Sunday 24 May 2009 at 9:00 AM (EDT)
Home  |  Legal nonsense  |  Privacy policy  |  Donations  |  Contact us