For a complete introduction to Interchange config files and the supported syntax, please see the configuration glossary entry.
Table of Contents
- AcceptRedirect — accept Web server redirects
- Accounting
- AccumulateCode — fetch Interchange code on-demand from CodeRepository instead of starting up with everything
- AcrossLocks — open real databases instead of fast dummy pointers
- ActionMap — modify existing or define custom Interchange actions
- AddDirective — add a new configuration directive
- AdminHost — (obsolete)
- AdminSub — specify global subroutines that can be used only by catalogs listed under AllowGlobal directive
- AdminUser — specify usernames that are given full access to all catalogs, regardless of any permissions
- AliasTable — specify database that contains page aliases ("redirect" instructions)
- AllowGlobal — specify catalogs that may define subroutines and tags which operate with full Interchange server permissions
- AlwaysSecure — specify pages that are always to be served over a HTTPS connection
- AsciiTrack — specify filename to which formatted order reports should be appended
- AutoEnd — specify macro to be executed automatically at the end of every page access
- AutoModifier — specify products database columns containing values for product attributes
- AutoVariable — specify config directives that are to be made available through the Variable space
- Autoload — specify actions to be executed automatically at the beginning of every page access
- BounceReferrals — remove visible affiliate code from URLs after first access
- Capability — test existence of a capability
- CartTrigger — specify subroutines to invoke when cart contents change
- CartTriggerQuantity — specify whether quantity changes to cart items will cause CartTrigger subroutines to execute
- Catalog — register catalog with the Interchange server
- CatalogUser — specify catalog-specific usernames to use when accessing files with absolute pathnames
- CategoryField — specify name of the "category" field in the Interchange database
- CheckHTML — check the generated HTML code with an external program
- ChildLife — define maximum child process lifetime
- ClearCache — (obsolete)
- CodeDef — generic subroutine mapper
- CodeRepository — specify directory containing code that can be included in the running installation when needed
- CommonAdjust — define default settings for a flexible, chained item pricing scheme
- ConfDir — specify catalog "config" directory
- ConfigAllAfter — specify config files to read as part of every catalog's configuration, after all its files are read in first
- ConfigAllBefore — specify config files to read as part of every catalog's configuration, before any of its files are read in
- ConfigDatabase — specify database holding definitions usually found in catalog.cfg
- ConfigDir — specify default "include" directory for "<file" notation
- ConfigParseComments — (obsolete) treat config meta-directives as plain comments
- CookieDomain — set domain common to all servers providing Interchange content
- CookieLogin — allow autologin based on username and password stored in a client cookie
- CookieName — specify Interchange session cookie name
- CookiePattern — specify regular expression to extract session ID out of a client cookie
- Cookies — specify whether Interchange will try to send session cookies to client browsers
- CountrySubdomains — honor ccTLD domains in IP qualification
- CreditCardAuto — encrypt credit card information automatically
- CustomShipping — specify SQL query to use in obtaining shipping costs data
- CyberCash — (obsolete)
- DNSBL — specify real-time DNS blocklist servers
- DataTrace — trace DBI calls with variable granularity
- Database — register existing database table for use with Interchange
- DatabaseAuto — register database tables for use with Interchange automatically
- DatabaseAutoIgnore — prevent DatabaseAuto from configuring tables whose names match regex pattern
- DatabaseDefault — specify default settings for Database directives
- DbDatabase — (obsolete)
- DebugFile — specify Interchange debug output filename
- DebugHost — restrict debug mode to requests originating from specific hosts
- DebugMode — (obsolete)
- DebugTemplate — specify format of debug messages
- DefaultLocale — specify default locale
- DefaultShipping — specify default shipping method
- DeleteDirective — disable use of specified configuration directive in catalog.cfg
- DeliverImage — allow delivery of images through Interchange
- DescriptionField — specify name of the "description" field in the Interchange database
- DifferentSecure — (obsolete)
- DirConfig — batch-set a bunch of variables (or values in general) from files
- DirectiveDatabase — specify database to read configuration directives from
- DirectoryIndex — specify the default page in a directory
- DiscountSpaceVar — specify names of CGI variables to check for discount space definition
- DiscountSpacesOn — enable "discount spaces" feature
- DisplayErrors — display eventual errors directly in the client session
- DomainTail — honor only the toplevel domain in IP qualification
- DumpAllCfg — dump global Interchange server configuration
- DumpStructure — dump Interchange server and catalog structure for each catalog
- DynamicData — (obsolete) specify databases which are dynamic, so pages using them must not be cached
- EncryptKey — specify default key to use for encryption
- EncryptProgram — specify default encryption program
- Environment — specify environment variables to inherit from the calling CGI link program
- ErrorDestination — route error messages to different files, based on message content or arbitrary tag
- ErrorFile — specify error log filename
- ExecutionLocale — specify lowest-level locale
- External — enable dump of selected global and catalog values for use by external programs
- ExternalExport — specify Perl variables to dump to external file
- ExternalFile — specify external dump filename
- ExtraSecure — disallow unencrypted access to pages which are listed under AlwaysSecure
- FallbackIP —
- Feature — specify Interchange "feature" for activation in the catalog
- FeatureDir — specify "feature" directory
- FileControl — specify page names and Perl subroutines that implement access control
- FileDatabase — specify table and column to look up in search for file contents
- Filter — specify variables and filters through which they should be run through automatically
- FormAction — define or override form action
- FormIgnore — specify variables that should not be propagated from CGI to Values space
- FractionalItems — allow fractional quantities in the shopping cart
- FullUrl — use full URLs (those including hostnames) in catalog definition lines
- Glimpse — specify program path and options for the Glimpse search engine
- GlobalSub — define global Perl functions for use within Interchange
- HTMLmirror — (obsolete)
- HTMLsuffix — specify filename extension for files in the PageDir and TemplateDir directories
- HammerLock — number of seconds after which a locked session is considered lost due to malfunction
- History — how many most-recent user clicks should be saved in session history
- HitCount — increment a counter on every catalog access
- HostnameLookups — perform hostname lookups (DNS resolving)
- HotDBI — specify catalogs that should use persistent database connections
- HouseKeeping — specify number of seconds between periodic "house keeping" jobs
- HouseKeepingCron — define Interchange-aware crontab entries
- IPC — (obsolete)
- IPCdir — (obsolete)
- IPCmode — (obsolete)
- IPCsocket — specify IPC socket filename
- ImageAlias — specify alias location for all image files
- ImageDir — specify base location for all image files
- ImageDirInternal — (obsolete)
- ImageDirSecure — specify base location for all IMG and INPUT src= files served over HTTPS
- Inet_Mode — specify whether Interchange server should open an INET socket and listen on a port
- IpHead — use only part of the IP to qualify user sessions
- IpQuad — specify number of dot-quads to honor when IpHead is enabled
- ItemAction — specify subroutine to invoke when users' electronic cart contents change
- Jobs — define parameters for batch jobs
- Levies — specify Levy sections to apply
- Levy — define levy section (levy key)
- Limit — set or modify various limits
- Locale — specify locale definitions
- LocaleDatabase — specify database that contains locale settings
- LockType — specify file locking method to use
- LockoutCommand — specify command to run in order to lock a client out of the site
- LogFile — specify Interchange log output filename
- Logging — specify log granularity treshold
- MailOrderTo — specify e-mail address that completed orders should be sent to
- Mall — issue cookies only for the current catalog, and not the base domain
- MasterHost — specify regular expression that client IP must match to access protected directories
- MaxQuantityField — specify tables and columns containing maximum allowed quantity for an item
- MaxRequestsPerChild — define maximum number of per-server page deliveries before respawn
- MaxServers — define maximum number of spawned servers
- Member — override catalog variables for logged-in users
- Message — write custom message to console and Interchange log
- MimeType — specify MIME types
- MinQuantityField — specify table and/or column containing minimum allowed quantity for an item
- MixMatch — (obsolete)
- MoreDB — enable saving of search paging files into users' DBI sessions
- NoAbsolute — deny catalogs to read absolute filenames on the system
- NoCache — (obsolete) explicitly specify pages or directories that are not to be cached when static page building is enabled
- NoExport — specify databases not to re-export
- NoExportExternal — enable use of the NoExport directive
- NoImport — specify databases not to re-import, unless the database completely disappears
- NoImportExternal — do not re-import external databases
- NoSearch — specify databases on which Interchange-style searches cannot be performed
- NonTaxableField — specify name of the non-taxable field in the products database
- NotRobotUA — specify user-agents that will NOT be classified as crawler bots (search engines)
- OfflineDir — specify directory to use for "offline" files
- OnFly — enable on-fly additions to client shopping cart
- Options — define options types and behavior
- OptionsAttribute
- OptionsEnable — specify table and/or column for option type
- OrderCleanup —
- OrderCounter — specify file that keeps and increments order count
- OrderLineLimit — specify maximum number of items the user is allowed to place in the shopping cart
- OrderProfile — specify files containing order profile definitions
- OrderReport — specify location of the order report form
- PGP — encrypt complete order reports automatically
- PIDcheck — check running Interchange processes during the HouseKeeping routine
- PIDfile — PID filename
- PageDir — specify directory containing catalog pages
- PageSelectField — specify products database column used to select the flypage
- PageTableMap — map field names for page lookup tables
- PageTables
- ParseVariables — parse (interpolate) config file variables
- Password — specify password for RemoteUser
- PermanentDir — specify directory containing temporary files for permanent searches
- PostURL — specify URL for POST requests
- Pragma — specify pragma's default value
- PreFork — specify whether Interchange server should pre-fork processes that wait for client connections
- PreForkSingleFork
- Preload — specify macro to be executed at the very beginning of every request
- PriceAdjustment — (obsolete)
- PriceBreaks — (obsolete)
- PriceCommas — show thousands separator in price pictures
- PriceDefault
- PriceDivide — specify number to divide the price by, to obtain price in units
- PriceField — specify name of the "price" field in the Interchange database
- ProcessPage — specify "virtual" location of the form processor page
- ProductDir — specify directory containing database files
- ProductFiles — specify all databases containing products that form one big "products" database
- Profile
- Profiles — specify files containing OrderProfile and SearchProfile definitions
- Promiscuous — allow output of HTML code in value variables
- ReadPermission — affect file mode (read permissions, specifically) on Interchange-generated files
- RedirectCache
- RemoteUser — specify required value of the REMOTE_USER environment variable
- Replace — reset directive to a new value, or to its default
- Require — require existence of a capability
- RequiredFields — (obsolete)
- RobotHost — specify hostnames that will be classified as crawler bots (search engines) visiting the site
- RobotIP — specify IP numbers or ranges that will be classified as crawler bots (search engines)
- RobotLimit — specify maximum number of pages a user can visit without a short pause
- RobotUA — specify user-agents that will be classified as crawler bots (search engines)
- Route — specify order and payment routes
- RouteDatabase
- RunDir — specify directory containing runtime files
- SOAP — enable handling of SOAP RPC requests
- SOAP_Action
- SOAP_Control — control access to SOAP features
- SOAP_Enable
- SOAP_Host — (obsolete) specify list of hosts that are allowed to connect and issue SOAP RPC requests
- SOAP_MaxRequests — define maximum number of per-server SOAP RPC response deliveries before respawn
- SOAP_Perms — specify SOAP RPC Unix socket permissions
- SOAP_Socket — specify name of SOAP RPC socket file
- SOAP_StartServers — specify number of servers which should be started to handle SOAP RPC requests
- SafeSignals — (obsolete)
- SafeTrap — specify operation codes to trap in Safe.pm compartments
- SafeUntrap — specify operation codes to untrap in Safe.pm compartments
- SalesTax — specifies sales tax calculation mode
- SalesTaxFunction — specify custom tax calculation function
- SaveExpire — specify the amount of time for which Interchange cookies should be valid (their expiry time)
- ScratchDefault — define default scratch variable values
- ScratchDir — specify directory containing temporary files
- SearchProfile — specify files containing search profile definitions
- SecurePostURL — specify URL for secure POST requests
- SecureURL — specify base URL of the Interchange catalog link program, when pages are served over HTTPS
- SendMailProgram — sendmail (or compatible) binary location
- SeparateItems — treat items with quantity greater than 1 as separate items
- SessionDB — specify name of a database to use with DBI-based sessions
- SessionDatabase — specify location of the file-based user sessions database
- SessionExpire — specify a duration after which idle user sessions expire
- SessionLockFile — specify the name of a lock file if DBM-based sessions are used
- SessionType — specify type of the user sessions database
- SetGroup — specify primary Unix group to switch to, after catalog to invoke is determined
- Shipping
- ShowTimes — insert timing information in debug output
- SocketFile — specify Unix socket filename
- SocketPerms — specify Unix socket permissions
- SocketReadTimeout — specify timeout on client sockets
- SpecialPage — specify location of special pages
- SpecialPageDir — specify directory containing special catalog pages
- SpecialSub — specify Perl subroutines to handle certain events or conditions
- StartServers — specify the number of Interchange servers to prefork when running in PreFork mode
- Static — (obsolete)
- StaticAll — (obsolete) try building all pages statically
- StaticDBM — (obsolete)
- StaticDepth — (obsolete) specify number of levels of static 'search' building
- StaticDir — (obsolete) specify path of the directory which should be used as root for static pages
- StaticFly — (obsolete) specify whether to build flypages statically
- StaticLogged — (obsolete)
- StaticPage — (obsolete) specify individual pages to build statically
- StaticPath — (obsolete) specify path to the statically built pages
- StaticPattern — (obsolete) specify regular expression used to qualify pages that are to be built statically
- StaticSuffix — (obsolete) specify file extension for statically-built HTML pages
- Sub — define Perl functions for use within a catalog
- SubCatalog — register subcatalog with the Interchange server
- Suggest — check existence of a capability
- SysLog — instruct Interchange to log to Unix system's log (syslog)
- TableRestrict — restrict database searches to rows satisfying given criteria
- TagDir — specify directories containing code declaration blocks
- TagGroup — group Interchange code declarations in groups, for later convenient inclusion or exclusion from the setup
- TagInclude — include (a group of) tags in Interchange
- TaxInclusive — display prices with tax amount included
- TaxShipping — specify states or jurisdictions that tax shipping costs
- TcpHost — specify which hosts can connect to Interchange server running in Inet mode
- TcpMap — specify which ports should Interchange server running in Inet mode listen on
- TcpPort — (obsolete)
- TemplateDir — specify common template/fallback "pages" directories
- TolerateGet — specify whether information from both GET and POST method should be parsed when form is submitted using POST method
- TrackDateFormat — specify time format used in TrackFile logs
- TrackFile — specify user tracking log filename
- TrackPageParam — insert specified variables' values in the user track file
- TrustProxy — designate certain IP addresses or hostnames as trusted HTTP proxies
- Unix_Mode — specify whether Interchange server should open an UNIX socket
- UpsZoneFile — specify file containing region-specific UPS zone information
- UrlSepChar — specify default URL separator character
- UseCode — (obsolete)
- UseModifier — specify default attributes that can be attached to items
- UserControl — enable enhanced user database functions
- UserDB — adjust default behavior of Interchange user database functions
- UserDatabase — specify name of table to use as user database
- UserTag — define an Interchange tag
- UserTrack — enable sending of X-Track HTTP header
- ValuesDefault — define default user values
- VarName — remap Interchange variables to arbitrary names in generated URLs
- Variable — define an Interchange variable
- VariableDatabase — specify database containing variables
- VendURL — specify base URL of the Interchange catalog link program
- WideOpen — disable IP-based qualification of user sessions (the directive degrades catalog security!)
- Windows — (obsolete) indicate that Interchange is running under Microsoft Windows
- WritePermission — affect file mode (write permissions, specifically) on Interchange-generated files
- XHTML — enable XHTML-conformant HTML output
Name
AcceptRedirect — accept Web server redirects
DESCRIPTION
The directive
enables processing of HTTP server redirects, i.e. when handling ErrorDocument
for a Web server such as Apache. For instance, if your Apache
httpd.conf contains
ErrorDocument 404 /cgi-bin/ic/standard
then a request for /somedir/index.html that is not found
on the Web server would be resent to
/cgi-bin/ic/standard/somedir/index.html, and
would be indistinguishable from the static Web server-served page.
NOTES
Combined with the RedirectCache directive, you can automatically
create missing HTML pages in your web server's static HTML space,
so that they are found on next access.
Just beware; that turns them into static pages!
Although the idea seems attractive at first sight, caution should be taken not to allow Web server's ErrorDocument redirection to Interchange globally — it would render you subject to a denial-of-service attack at random URLs (i.e. a flood of MS Windows "Code Red" attacks). It is recommended that you enable it only for specific directories, as Apache or another HTTP server would stand much better up to such a "limited-scale" flood.
SOURCE
Interchange 5.7.0:
Source: lib/Vend/Config.pm
Line 5260 (context shows lines 5260-5272)
sub parse_yesno {
my($var, $value) = @_;
$_ = $value;
if (m/^y/i || m/^t/i || m/^1/ || m/^on/i) {
return 1;
}
elsif (m/^n/i || m/^f/i || m/^0/ || m/^of/i) {
return 0;
}
else {
config_error("Use 'yes' or 'no' for the $var directive\n");
}
}
Name
Accounting
EXAMPLES
No examples are available at this time. We do consider this a problem and will try to supply some.SOURCE
Interchange 5.7.0:
Source: lib/Vend/Config.pm
Line 3015 (context shows lines 3015-3079)
sub parse_locale {
my($item,$settings) = @_;
return ($settings || '') unless $settings =~ /[^\d.]/;
$settings = '' if "\L$settings" eq 'default';
my $name;
my ($c, $store);
if(defined $C) {
$c = $C->{$item} || { };
$C->{$item . "_repository"} = {}
unless $C->{$item . "_repository"};
$store = $C->{$item . "_repository"};
}
else {
no strict 'refs';
$c = ${"Global::$item"} || {};
${"Global::$item" . "_repository"} = {}
unless ${"Global::$item" . "_repository"};
$store = ${"Global::$item" . "_repository"};
}
my ($eval, $safe);
if ($settings =~ s/^\s*([-\w.@]+)(?:\s+)?//) {
$name = $1;
undef $eval;
$settings =~ /^\s*{/
and $settings =~ /}\s*$/
and $eval = 1;
$eval and ! $safe and $safe = new Safe;
if(! defined $store->{$name} and $item eq 'Locale') {
my $past = POSIX::setlocale(POSIX::LC_ALL);
if(POSIX::setlocale(POSIX::LC_ALL, $name) ) {
$store->{$name} = POSIX::localeconv();
}
POSIX::setlocale(POSIX::LC_ALL, $past);
}
my($sethash);
if ($eval) {
$sethash = $safe->reval($settings)
or config_warn("bad Locale setting in %s: %s", $name, $@),
$sethash = {};
}
else {
$settings =~ s/^\s+//;
$settings =~ s/\s+$//;
$sethash = {};
%{$sethash} = Text::ParseWords::shellwords($settings);
}
$c = $store->{$name} || {};
my $nodefaults = delete $sethash->{MV_LOCALE_NO_DEFAULTS};
for (keys %{$sethash}) {
$c->{$_} = $sethash->{$_};
}
}
else {
config_error("Bad locale setting $settings.\n");
}
$C->{LastLocale} = $name if $C and $item eq 'Locale';
$store->{$name} = $c unless $store->{$name};
return $c;
}
Name
AccumulateCode — fetch Interchange code on-demand from CodeRepository instead of starting up with everything
DESCRIPTION
The directive instructs Interchange to fetch code blocks "on-demand" from the
CodeRepository instead of starting up with everything.
It helps speed up Interchange startup time and reduce memory footprint.
So, at runtime, when particular functionality is needed but is not
yet present in the running Interchange installation, it is copied from
CodeRepository to
$Global::TagDir/Accumulated/
and automatically activated.
Later, when you restart Interchange the next time, these code blocks will be
found in the accumulated directory and loaded normally
(there will be no need to fetch them from CodeRepository
again).
Over time, as you access pages and routines, a full set of tags
used by a catalog
will be copied to the accumulated directory, and you will then be
able to turn AccumulateCode off.
(In fact, AccumulateCode is recommended for development and should
really be turned off in production systems).
SOURCE
Interchange 5.7.0:
Source: lib/Vend/Config.pm
Line 5260 (context shows lines 5260-5272)
sub parse_yesno {
my($var, $value) = @_;
$_ = $value;
if (m/^y/i || m/^t/i || m/^1/ || m/^on/i) {
return 1;
}
elsif (m/^n/i || m/^f/i || m/^0/ || m/^of/i) {
return 0;
}
else {
config_error("Use 'yes' or 'no' for the $var directive\n");
}
}
Name
AcrossLocks — open real databases instead of fast dummy pointers
DESCRIPTION
All configured databases are opened every time an Interchange page is visited and enters processing. Opening a new database connection takes time, so Interchange provides fast dummy pointer to each database until that database is actually used within the page.
Enabling this directive has the effect of disabling fast pointers and always opening real databases.
SOURCE
Interchange 5.7.0:
Source: lib/Vend/Config.pm
Line 5260 (context shows lines 5260-5272)
sub parse_yesno {
my($var, $value) = @_;
$_ = $value;
if (m/^y/i || m/^t/i || m/^1/ || m/^on/i) {
return 1;
}
elsif (m/^n/i || m/^f/i || m/^0/ || m/^of/i) {
return 0;
}
else {
config_error("Use 'yes' or 'no' for the $var directive\n");
}
}
Name
ActionMap — modify existing or define custom Interchange actions
DESCRIPTION
The directive allows creation of new (and modification of existing) Interchange ActionMaps using Perl subroutines.
If the action does not return a true value, Interchange processing will stop right there, allowing you to fully handle the request from your action.
See ActionMap glossary entry for more explanation and the list of built-in Interchange actionmaps.
EXAMPLES
Example: Replacing the Order action with a no-op
Put the following in catalog.cfg:
ActionMap order sub { 1 }
Since we effectively turned Order into a no-operation action, the usual
order link such as
<A HREF="[area order/nextpage]">Order</a>
would be equivalent to [page nextpage]Order (does nothing)</a>.
Example: Splitting a request into action map, page name and arguments
Here's an example of an actionmap "test" that translates
HTTP requests in form of test/
into actual page requests to page/argumentspage.html with optional arguments.
ActionMap test <<EOA
sub {
my $url = shift;
# Remove actionmap name from the URL
$url =~ s:^test/+::i;
# Arguments are optional
if ($url =~ s:/+(.*)$::) {
$CGI->{mv_arg} = $1;
}
$CGI->{mv_nextpage} = $url;
return 1;
}
EOA
NOTES
For an introduction to Action Maps, see ActionMap glossary entry.
The standard process ActionMap has a number of
configuration settings which can be controlled through FormAction.
For catalog-level ActionMaps, Interchange does not strip the actionmap nam from the requested HTTP path; for global ActionMaps it does. See the section called “EXAMPLES”.
SOURCE
Interchange 5.7.0:
Source: lib/Vend/Config.pm
Line 2134 (context shows lines 2134-2213)
sub parse_action {
my ($var, $value, $mapped) = @_;
if (! $value) {
return $InitializeEmpty{$var} ? '' : {};
}
return if $Vend::ExternalProgram;
my $c;
if($mapped) {
$c = $mapped;
}
elsif(defined $C) {
$c = $C->{$var} ||= {};
}
else {
no strict 'refs';
$c = ${"Global::$var"} ||= {};
}
if (defined $C and ! $c->{_mvsafe}) {
my $calc = Vend::Interpolate::reset_calc();
$c->{_mvsafe} = $calc;
}
my ($name, $sub) = split /\s+/, $value, 2;
# Untaint and strip this pup
$sub =~ s/^\s*([\000-\377]*\S)\s*//;
$sub = $1;
if($sub !~ /\s/) {
no strict 'refs';
if($sub =~ /::/ and ! $C) {
$c->{$name} = \&{"$sub"};
}
else {
if($C and $C->{Sub}) {
$c->{$name} = $C->{Sub}{$sub};
}
if(! $c->{$name} and $Global::GlobalSub) {
$c->{$name} = $Global::GlobalSub->{$sub};
}
}
if(! $c->{$name} and $AllowScalarAction{$var}) {
$c->{$name} = $sub;
}
elsif(! $c->{$name}) {
$@ = errmsg("Mapped %s action routine '%s' is non-existent.", $var, $sub);
}
}
elsif ( ! $mapped and $sub !~ /^sub\b/) {
if($AllowScalarAction{$var}) {
$c->{$name} = $sub;
}
else {
my $code = <<EOF;
sub {
return Vend::Interpolate::interpolate_html(<<EndOfThisHaiRYTHING);
$sub
EndOfThisHaiRYTHING
}
EOF
$c->{$name} = eval $code;
}
}
elsif (! $C or $Global::AllowGlobal->{$C->{CatalogName}}) {
package Vend::Interpolate;
$c->{$name} = eval $sub;
}
else {
package Vend::Interpolate;
$c->{$name} = $c->{_mvsafe}->reval($sub);
}
if($@) {
config_warn("Action '%s' did not compile correctly (%s).", $name, $@);
}
return $c;
}
Name
AddDirective — add a new configuration directive
DESCRIPTION
This directive allows you to extend the set of regular
configuration
directives accepted in each catalog.cfg. The added
directives are then treated the same as the existing "built-ins".
Three standard arguments can be specified: the
directive_name,
parse_function_name and
default_value.
If the parser function is not defined (either by omitting it or
literally specifying undef), then no parser
will be called on the value at all,
and the value of the directive will be exactly what users specify in their
config files (which will usually be Perl scalar values). If the parser
argument is supplied, then the requested parser function
must already be defined because it can't be referenced
in advance. It can be defined either as a
Sub or GlobalSub block, or can refer to an existing parser
function from lib/Vend/Config.pm.
The file lib/Vend/Config.pm contains all the default
parser functions, which are recognized by the mandatory prefix
parse_. (You do not, however, include
parse_ in the parse_function_name.)
The default_value does not have to be specified.
Directly modifying Config.pm (or any other
files from the Interchange installation) is discouraged for portability and other
reasons. Therefore, to add your custom parsing function, you should
modify interchange.cfg as seen in the section called “EXAMPLES”
(note again that the parser definition
must logically come before AddDirective).
EXAMPLES
Example: Adding a new catalog configuration directive with a custom parse routine
Let's add the DocRoot directive. Put the following
in your interchange.cfg:
GlobalSub <<EOS
sub declare_extra_config {
package Vend::Config;
sub parse_docroot {
my ($var, $value) = @_;
unless ( -d $value ) { $@ = errmsg("Directory $value: $!") }
if ($@) { config_warn($@) }
return;
}
}
EOS
AddDirective DocRoot docroot "/var/www"
Example: Adding the "Swish" directive with an existing parse routine
Require module Vend::Swish Variable swish Vend::Swish AddDirective Swish hash
NOTES
Note that boolean, one of the default parse functions, is
actually
a boolean list, and not a true boolean value. The list achieves the effect
of being boolean by logically returning true or false,
depending on whether the searched item is present in the list or not.
True boolean values are called "yesno"s in Interchange parlance.
Please see the configuration glossary entry for a discussion on config directives.
SOURCE
Interchange 5.7.0:
Source: lib/Vend/Config.pm
Line 2868 (context shows lines 2868-2885)
sub parse_directive {
my($name, $val) = @_;
return '' unless $val;
my($dir, $parser, $default) = split /\s+/, $val, 3 ;
if(! defined &{"parse_$parser"} and ! defined &{"$parser"}) {
if (defined $Global::GlobalSub->{"parse_$parser"}) {
no strict 'refs';
*{"Vend::Config::parse_$parser"} = $Global::GlobalSub->{"parse_$parser"};
} else {
$parser = undef;
}
}
$default = '' if ! $default or $default eq 'undef';
$Global::AddDirective = [] unless $Global::AddDirective;
push @$Global::AddDirective, [ $dir, $parser, $default ];
return $Global::AddDirective;
}
Name
AdminSub — specify global subroutines that can be used only by catalogs listed under AllowGlobal directive
DESCRIPTION
Specify global subroutines that may only be used by catalogs
which are listed under the AllowGlobal directive.
Otherwise, in the default course of action, global subroutines can be used by all catalogs.
SOURCE
Interchange 5.7.0:
Source: lib/Vend/Config.pm
Line 2957 (context shows lines 2957-2974)
sub parse_boolean {
my($item,$settings) = @_;
my(@setting) = grep /\S/, split /[\s,]+/, $settings;
my $c;
if(defined $C) {
$c = $C->{$item} || {};
}
else {
no strict 'refs';
$c = ${"Global::$item"} || {};
}
for (@setting) {
$c->{$_} = 1;
}
return $c;
}
Name
AdminUser — specify usernames that are given full access to all catalogs, regardless of any permissions
DESCRIPTION
Username and password pairs for users which are given administrator privileges to all catalogs.
This functionality is standalone — you do not need to have the access database since usernames and passwords here are specified directly.
Name
AliasTable — specify database that contains page aliases ("redirect" instructions)
DESCRIPTION
The directive specifies Interchange database that contains page aliases (default database name is alias).
This way, flypages can be aliased and redirected to different locations without performing file lookup cycles.
Primary applications include content management and creation of pseudo-paths. See the section called “EXAMPLES”.
EXAMPLES
Example: Creating AliasTable database
base_page real_page 4595 index
In our example, page 4595.html redirects
back to the index page.
You might notice that the fields names and values above are not properly aligned. This is an unfortunate nature of tab delimited files.
To minimize the chance of confusion, you can download properly composed example file alias.txt.
Name
AllowGlobal — specify catalogs that may define subroutines and tags which operate with full Interchange server permissions
DESCRIPTION
Specify catalogs that can operate with the full permissions of the Interchange server.
Don't use this directive unless the catalog user is completely trusted.
SOURCE
Interchange 5.7.0:
Source: lib/Vend/Config.pm
Line 2957 (context shows lines 2957-2974)
sub parse_boolean {
my($item,$settings) = @_;
my(@setting) = grep /\S/, split /[\s,]+/, $settings;
my $c;
if(defined $C) {
$c = $C->{$item} || {};
}
else {
no strict 'refs';
$c = ${"Global::$item"} || {};
}
for (@setting) {
$c->{$_} = 1;
}
return $c;
}
Name
AlwaysSecure — specify pages that are always to be served over a HTTPS connection
DESCRIPTION
The directive specifies Interchange pages that are always to be served over a secure (HTTPS) connection.
EXAMPLES
Example: Specifying AlwaysSecure
AlwaysSecure ord/checkout AlwaysSecure <<EOD change_password login member/account ord/billing ord/checkout ord/finalize ord/multi ord/shipping query/order_detail EOD
SOURCE
Interchange 5.7.0:
Source: lib/Vend/Config.pm
Line 2957 (context shows lines 2957-2974)
sub parse_boolean {
my($item,$settings) = @_;
my(@setting) = grep /\S/, split /[\s,]+/, $settings;
my $c;
if(defined $C) {
$c = $C->{$item} || {};
}
else {
no strict 'refs';
$c = ${"Global::$item"} || {};
}
for (@setting) {
$c->{$_} = 1;
}
return $c;
}
Name
AutoEnd — specify macro to be executed automatically at the end of every page access
DESCRIPTION
Specify an Interchange to be invoked automatically, at the end of every page access. This step is performed after all page parsing occurs, just before the whole transaction ends.
In other respects, it behaves the same as its closely related
directive Autoload.
EXAMPLES
No examples are available at this time. We do consider this a problem and will try to supply some.SOURCE
Interchange 5.7.0:
Source: lib/Vend/Config.pm
Line 3700 (context shows lines 3700-3734)
sub parse_routine_array {
my($item,$settings) = @_;
return '' unless $settings;
my $c;
if(defined $C) {
$c = $C->{$item};
}
else {
no strict 'refs';
$c = ${"Global::$item"};
}
my @mac;
if($settings =~ /^[-\s\w,]+$/) {
@mac = grep /\S/, split /[\s,]+/, $settings;
}
else {
push @mac, $settings;
}
if(ref($c) eq 'ARRAY') {
push @$c, @mac;
}
elsif($c) {
$c = [$c, @mac];
}
else {
$c = scalar(@mac) > 1 ? [ @mac ] : $mac[0];
}
return $c;
}
Name
AutoModifier — specify products database columns containing values for product attributes
DESCRIPTION
The directive specifies names of the product attributes
which should be automatically loaded from database columns.
Table, column and key identifiers belonging to a single specification
are separated by a colon (:), while multiple specifications
are separated by whitespace.
In other words,
when an item is added to the shopping cart using Interchange's routines, the
attributes declared in AutoModifier will be set to the values of the
fields in the products database.
This facility will often be employed in determining product
price, discount, tax and shipping, and
other custom attributes; these attributes will probably
be used in custom Perl code that will scan the electronic
cart contents and perform some decisions. For example, by defining
database columns heavy and
downloadable, you will be
able to perform decisions
based on $item->{heavy} and
$item->{downloadable} (but there are more access methods,
see the attribute glossary entry.
EXAMPLES
Example: Specifying AutoModifier
To set whether an item is defined as "heavy" and requires truck shipment, or is "downloadable", set:
AutoModifier heavy downloadable
Also make sure to have the heavy and downloadable columns defined in your products database.
Example: set attribute 'weighty' from inventory table, column 'heavy'
AutoModifier weighty=inventory:heavy
Example: set attribute 'heavy' from inventory table, with a different SKU
AutoModifier inventory:heavy:mv_sku
NOTES
This can useful when doing shipping calculations or in embedded Perl code that works on item attributes.
See attribute for a complete introduction to item attributes.
SOURCE
Interchange 5.7.0:
Source: lib/Vend/Config.pm
Line 3678 (context shows lines 3678-3698)
sub parse_array {
my($item,$settings) = @_;
return '' unless $settings;
my(@setting) = grep /\S/, split /[\s,]+/, $settings;
my $c;
if(defined $C) {
$c = $C->{$item} || [];
}
else {
no strict 'refs';
$c = ${"Global::$item"} || [];
}
for (@setting) {
check_legal($item, $_);
push @{$c}, $_;
}
$c;
}
Name
AutoVariable — specify config directives that are to be made available through the Variable space
DESCRIPTION
Specify list of configuration directives whose values are to be made
available through the variable space.
This allows you to conveniently
write say, __, and
retrieve the corresponding configuration directive's value.
DirectiveName__
To support s, arrays and hashes of values (all three basic Perl types), the syntax had to be extended a little. With array or hash configuration directives, you need to append the index number or hash key respectively. See the section called “EXAMPLES” for clarification.
Note that the behavior of AutoVariable is not dynamic — if need
to re-invoke AutoVariable every time you want to "refresh" the
value visible through __.
DirectiveName__
EXAMPLES
Example: Enabling configuration directives through Variable space
Put the following in catalog.cfg:
VendURL http://myhost.mydomain.local/cgi-bin/ic/catalog SecureURL https://myhost.mydomain.local/cgi-bin/ic/catalog MailOrderTo root@mydomain.local SafeUntrap sort SysLog command /usr/bin/logger AutoVariable VendURL SecureURL MailOrderTo SafeUnutrap SysLog
Example: Displaying a scalar value
Put the following on a page:
Orders are e-mailed to: __MailOrderTo__
Example: Displaying an array value
Put the following on a page:
First SafeUntrap value is: __SafeUntrap_0__
NOTES
The directive does not support hash keys that contain non-word characters or whitespace. Also, only the first-level of array and hash indices/keys is translated properly.
SOURCE
Interchange 5.7.0:
Source: lib/Vend/Config.pm
Line 2505 (context shows lines 2505-2536)
sub parse_autovar {
my($var, $val) = @_;
return '' if ! $val;
my @dirs = grep /\w/, split /[\s,\0]+/, $val;
my $name;
foreach $name (@dirs) {
next unless $name =~ /^\w+$/;
my $val = get_directive($name);
if(! ref $val) {
parse_variable('Variable', "$name $val");
}
elsif ($val =~ /ARRAY/) {
for(my $i = 0; $i < @$val; $i++) {
my $an = "${name}_$i";
parse_variable('Variable', "$an $val->[$i]");
}
}
elsif ($val =~ /HASH/) {
my ($k, $v);
while ( ($k, $v) = each %$val) {
next unless $k =~ /^\w+$/;
parse_variable('Variable', "$k $v");
}
}
else {
config_warn('%s directive not parsable by AutoVariable', $name);
}
}
}
Name
Autoload — specify actions to be executed automatically at the beginning of every page access
DESCRIPTION
Specify actions (in form of Perl subroutines or ITL tags) that are to be invoked automatically, on every page access. This step is performed before any page parsing occurs, and before the action or page is even determined.
The directive can be set to the name of a subroutine (Sub or
GlobalSub), or to a string containing ITL tags.
The return value from the code run is discarded.
EXAMPLES
Example: Simple Autoload example
Put the following in interchange.cfg:
GlobalSub <<EOR
sub simple_gsub {
open OUT, "> /tmp/out";
print OUT scalar localtime, "\n";
close OUT;
}
EOR
Put the following in catalog.cfg:
Autoload simple_gsub
Now, at each page visit, the file /tmp/out will
contain the access time. This example is pretty useless and does not
convey good programming practice (the file opening part), but it does
show a practical, stand-alone example.
Example: Redirect page accesses
Let's say that a new page visit is "triggered" as a result of users
submitting a HTML form. At that point, mv_nextpage
contains the name of the page to display next, of course.
The following would redirect all accesses from
directory public/ to
directory private/:
Autoload [perl] $CGI->{mv_nextpage} =~ s:^public/:private/:; [/perl]
Example: Temporary change of configuration directives
As you might know, on each page access, all catalog configuration directives (global and catalog) are "re-instantiated", and valid for the current page. This particularly convenient feature allows us to change (modify, add or delete) configuration directives as we see fit on a per-page basis, without worrying about them being persistent, and consequently, even without the need to re-set them back to original values.
The following example (put in catalog.cfg) displays a different flypage for
Opera web browsers:
Autoload <<EOA
[perl]
if ($Session->{browser} =~ /opera/i) {
$Config->{Special}->{flypage} = 'opera_flypage';
}
[/perl]
EOA
Please note that SpecialPage is the corresponding directive in
the catalog configuration (and not Special as
we see above). This is an exceptional case — the hash keys otherwise
have the same name as the catalog configuration directives themselves.
SOURCE
Interchange 5.7.0:
Source: lib/Vend/Config.pm
Line 3700 (context shows lines 3700-3734)
sub parse_routine_array {
my($item,$settings) = @_;
return '' unless $settings;
my $c;
if(defined $C) {
$c = $C->{$item};
}
else {
no strict 'refs';
$c = ${"Global::$item"};
}
my @mac;
if($settings =~ /^[-\s\w,]+$/) {
@mac = grep /\S/, split /[\s,]+/, $settings;
}
else {
push @mac, $settings;
}
if(ref($c) eq 'ARRAY') {
push @$c, @mac;
}
elsif($c) {
$c = [$c, @mac];
}
else {
$c = scalar(@mac) > 1 ? [ @mac ] : $mac[0];
}
return $c;
}
Name
BounceReferrals — remove visible affiliate code from URLs after first access
DESCRIPTION
When BounceReferrals is enabled, GET requests to URLs with
mv_pc or mv_source set to an affiliate code are redirected
to the same URL minus the affiliate code.
This keeps search engines that respect redirects from storing the affiliate code-salted URLs in their indexes, and helps them focus on the real resource with a single URL instead of a multitude of salted links.
NOTES
When this directive is enabled and visitors do not already have a session
cookie (the most common case on first access), they are bounced to an URL
that does not have the affiliate code but has the session ID.
There's no easy way around this, and we consider it a separate issue from the
BounceReferrals concept.
If session IDs in URLs are a concern, they'll need a separate solution.
Historically, many application servers always bounce the first request to check for cookie support. Nowadays, many simply require cookies for anything that needs a session. Interchange is different on both counts.
SOURCE
Interchange 5.7.0:
Source: lib/Vend/Config.pm
Line 5260 (context shows lines 5260-5272)
sub parse_yesno {
my($var, $value) = @_;
$_ = $value;
if (m/^y/i || m/^t/i || m/^1/ || m/^on/i) {
return 1;
}
elsif (m/^n/i || m/^f/i || m/^0/ || m/^of/i) {
return 0;
}
else {
config_error("Use 'yes' or 'no' for the $var directive\n");
}
}