ActionMap

Allows Interchange pseudo-page actions to be defined or overridden, usually with a Perl subroutine.

Synopsis

ActionMap action sub { Perl code here }

ActionMap action <<EOA
Interchange tags or Perl sub here
EOA

Scope

This directive is available for use globally (in the "interchange.cfg" configuration file), and locally (in the "catalog.cfg" configuration file).

The global configuration affects all websites running under the Interchange instance. Each individual website's local configuration will not affect or influence other websites in any way.

Description

Allows Interchange pseudo-page actions to be defined or overridden, usually with a Perl subroutine. Actions are page names like the following standard actions, supplied with Interchange:

Name	Description
process	Process user-submitted form data.
order	Add products to the basket.
scan	Search based upon criteria encoded into the URI path.
search	Search based upon submitted form variables.

The above can be overwritten with user-defined versions if desired. For example, to ignore the order action, set:

ActionMap order sub { return 1; }

When the leading part of the incoming path is equal to "order", it will trigger the action. Actions can be written in Perl, or with Interchange tags. Tag-coded actions are not anywhere near as efficient as Perl-coded actions.

The example, above, is essentially a no-op. In this case, the first part of the path (order) would be stripped. Take the following link as an example:

Users clicking on that link would find that the "order/foo/bar" is transformed into "foo/bar". The "foo/bar.html" page would then be displayed (if present).

As Interchange only checks the first part of the path against the ActionMap list, virtual directories can be created. See the examples, below.

If the action does not return a true (non-zero, non-blank) status, no page will be displayed by Interchange, not even the special missing page. A Perl response may also be generated.

The standard "process" action has a number of associated FormAction settings that you may override if necessary.

Examples

API differences between local and global ActionMaps

Availability and upgrade note

The difference between the global and local ActionMap API, described in this section, only applies to Interchange version prior to 5.5.2. Interchange 5.5.2 and above uses the local API for all ActionMaps, regardless of whether they are defined locally or globally.

Note that this will require you to make a change to your global ActionMaps if you are upgrading from a version earlier than 5.5.2. See the one line difference between the local API and global API examples, below, and adapt that one extra line for use in your global ActionMaps; Simply change the ActionMap name in the regex from "foo" to whatever your ActionMap is called and insert that one line into your global ActionMap code.

ActionMap subroutines have a slightly different API, depending upon whether they are set up globally (interchange.cfg) or locally (catalog.cfg). The difference is that local ActionMap subroutines get passed the ActionMap name, whereas global ActionMap subroutines do not.

The best way to show the difference is with examples: The following examples both set up an ActionMap that do the same thing; They both accept a path, call a page and pass the page a single CGI argument.

If "http://www.example.com/foo/bar/baz/bork.html" is called, then the "foo" ActionMap subroutine will be run. The subroutine then sets up a call to the "bar" page, passing "baz/bork" as an argument. The "bar" page can then pick up its argument using [cgi mv_arg] or $CGI->{mv_arg} etc.

Local API

ActionMap foo <<EOA
sub {
my $page = shift;
$page =~ s:^foo/+::i;

if ($page =~ s:/+(.*)$::) {
$CGI->{mv_arg} = $1;
}
$CGI->{mv_nextpage} = $page;
return 1;
}
EOA

Global API

ActionMap foo <<EOA
sub {
my $page = shift;

if ($page =~ s:/+(.*)$::) {
$CGI->{mv_arg} = $1;
}
$CGI->{mv_nextpage} = $page;
return 1;
}
EOA

Pratical example

A common question on the interchange-users mail list is how one can convert a URI such as "http://www.example.com/category/somecat.html" into a search for all products in the "somecat" category. The idea being that this keeps the URI nice and neat, and also helps with search engine optimisation. This can be easily implemented using the following local ActionMap:

ActionMap category <<EOA
sub {
my $category = shift;
$category =~ s:^category/+::i;

$CGI->{mv_todo} = 'search';
$CGI->{mv_nextpage} = $Config->{SpecialPage}->{results};

$CGI->{mv_searchtype} = 'db';
$CGI->{mv_search_file} = 'products';
$CGI->{mv_matchlimit} = '10';
$CGI->{mv_sort_field} = 'title';
$CGI->{mv_return_fields} = 'sku';
$CGI->{mv_coordinate} = 'yes';
$CGI->{mv_search_field} = "inactive\0category";
$CGI->{mv_searchspec} = "1\0$category";
$CGI->{mv_column_op} = "ne\0eq";

$Tag->update('process');
return 1;
}
EOA

You can also define your code as a Sub or GlobalSub, and then pass the subroutine name to the ActionMap directive. For example, you can use the following technique to create multiple ActionMaps that all execute the same code:

Sub foo <<EOS
sub {
my $page = shift;

if ($page =~ s:/+(.*)$::) {
$CGI->{mv_arg} = $1;
}
$CGI->{mv_nextpage} = $page;
return 1;
}
EOS

ActionMap foo foo
ActionMap bar foo

Using the above code, in your local website configuration, calls pages under both "/foo" and "/bar" will be passed to the "foo" subroutine. In other words, "/foo" and "/bar" will become aliases of one another.