dump The content of all carts ....

Most of the time, you will want the successful check-out operation (order completion) to generate some kind of notification. In most common setups, this will include e-mailing order reports.

Simple order report file, CATROOT/etc/report, defines the layout (template) of the order report. All form variables are accessible from the report file by using the familiar Perl $ syntax.

         Order Date: $date
  
               Name: $name
      Email address: $email
  
   Shipping address: $addr
   Town, State, Zip: $town, $state $zip
            Country: $country

You can specify fully-configurable order reports by setting the hidden form variable mv_order_report to an existing Interchange catalog page. This page will be processed (interpolated and all) as standard Interchange page before being sent by email. That said, you see you could include HTML in the file. Although many mail clients will parse HTML, it seems that the initial excitement among the ordinary people vanished and they again prefer plain-text e-mails. If you wanted to provide a HTML version, you could always provide a link to a copy on your web server.

An order counter can be enabled simply — just set the OrderCounter directive to the appropriate file name. An incrementing count of all orders will be kept and assigned as orders are placed. By default, the number starts at 0, but you can edit the file and change the starting or current number at any time. This feature is made possible by the File::CounterFile Perl module.

The default basket and order pages contain a number of form fields, allowing customers to enter the necessary information. This, however, can't satisfy all individual needs. To remove some of the fields, simply delete them from the HTML pages (or, better yet, disable by using the comment tag). Do not forget to also deactivate any entries in the profile files.

To add new fields, simply add them to the pages. The information will automatically be included in the report files. Here's a template you could re-use for your own fields, replacing town with your values:

<input type="text" name="town" value="[value town]" size="30" maxlen="40" />

	Note
	Using maxlen HTML <input> attribute to limit the length of incoming input is insecure, since that check is performed client-side only. It is surely an element of good programming on all levels, but don't forget to perform real length check in the appropriate form profile.

Configuration directives are normally specified with the directive name as the first word on the line, with its value or values following. Capitalization of the directive name is not significant, but it helps readability and consistency. Additionally, any leading and trailing whitespace is removed ("stripped") before processing. Here's a simple example:

DirectiveName value

Besides specifying directive values inline, one can conveniently use the following syntax to obtain value from external files:

DirectiveName <include_filename

	Note
	Note that this syntax can be used anywhere on a line, such as in Variable MYSTUFF <file. You can use this to achieve the best performance with Variables.

Files included from interchange.cfg are relative to ICROOT. Files included from catalog.cfg are relative to specific catalog's CATROOT.

So-called "here document" syntax is supported as well. You can use it to spread directive values over several lines, with the usual Perl <<MARKER syntax (but unlike Perl, Interchange syntax uses no semicolon to terminate the marker). The closing marker must be the only thing on the line. No leading or trailing characters are allowed, not even whitespace. Here is a hypothetical directive using a here document:

DirectiveName <<EOD
    setting1 setting2
    setting3
EOD

The above is equivalent to:

DirectiveName setting1 setting2 setting3

Other configuration files can also be included from the current one. For example, common settings can be defined in a single file:

include common.cfg

Or all files loaded from a directory:

include usertag/*

It may come to you as a surprise, to learn that any configuration directive can be "tied" to a Perl subroutine (if the Tie::Watch Perl module is installed). This allows for a kind of triggers, watch points, or numerous other interesting applications.

Similar to "here documents" ("<<"), subroutine watches are defined using the "<&" notation. Consider the following example:

MailOrderTo orders@myhost.mydomain.local
MailOrderTo <&EOF
sub {
	my($self, $default) = @_;
	if($Values->{special_handling}) {
		return 'vip@myhost.mydomain.local';
	}
	else {
		return $default;
	}
}
EOF

When Interchange tries to retrieve the value of the MailOrderTo configuration directive (usually to e-mail out an order), our subroutine watch is called. In turn, it returns a special value (a separate e-mail address) for customers having value "special_handling" defined in their session. For the rest, it simply returns the default value.

Now that you've grasped the basics, there's more to the story. From the above example, you see our watch subroutine was called in style of &{$subref}(SELF, PREVIOUS_VALUE). "SELF", meaning what it usually means in Perl code, is a reference to the appropriate Tie::Watch object. "PREVIOUS_VALUE" is simply the previously set value for a directive (usually its default). Those are the standard two arguments we receive in a subroutine watch if the configuration directive was of type SCALAR (defined to accept one string or text value).

	Note
	Subroutine watches must be defined after the configuration directives have been set to their values. Setting values after subroutine watches will simply destroy them (the watches) and have unpredictable effects.

If the configuration directive being watched was a list (type ARRAY), the subroutine would be called in pattern &{$subref}(SELF, INDEX, PREVIOUS_VALUE). ("INDEX" would be an array index of the item accessed). Setting watch points on arrays that you don't control completely is not recommended. (Namely, most Interchange subroutines call arrays in their list context, and no access method is provided for that).

Finally, if the configuration directive watched was a hash (type HASH), the subroutine would be called in pattern &{$subref}(SELF, KEY, PREVIOUS_VALUE). ("KEY" would be a name of the hash value accessed). In the following example, we tie the Variable configuration directive. This is not recommended for performance reasons — Variable directive is called very often and should not bear any extra overhead). But it illustrates the power of this operation:

Variable TESTIT Unwatch worked.

Variable <&EOV
sub {
  my ($self, $key, $orig) = @_;

  if($key eq 'TESTIT') {
    # only the first time
    if($Scratch->{$key}++) {
      $self->Unwatch();
      return $orig->{TESTIT};
    }
    else {
      return "Tie::Watch works! -- name=$Values->{fname}";
    }
  }
  else {
    return $orig->{$key};
  }
}
EOV

The first time __TESTIT__ is called for an individual user, it would return the string "Tie::Watch works! -- name=NAME" along with their first name (if they provided one at some point). On a second access (again, for an individual user), the watch would be dynamically dropped and the default value of the variable TESTIT returned. All other variables would operate as usual.

Text source files are not databases themselves, of course (for performance and other reasons); they are only used to provide initial data for the corresponding database tables.

By default, all database source files are kept in the products/ subdirectory of your CATROOT. The ProductDir directive controls the exact location.

The ASCII files can contain carriage return (^M) characters even in data fields, but must have a newline character (^N) at the end of line to properly separate records. Mac users uploading files must use ascii mode, not binary mode.

Interchange's default ASCII delimiter is TAB. Keep in mind that the items must be separated by a single delimiter (that is, by a single TAB only). Due to the nature of TABs, TAB-delimited files look messy and unaligned when viewed in a text editor. Do not try to fix these; better use the te utility that comes as part of the Interchange distribution to edit such files more conveniently.

	Note
	Field names are usually case-sensitive (in fact, that depends on the underlying database type). Always be consistent when naming or referencing fields and you'll avoid the trouble. All lower or all upper case names are recommended.

If a database is specified to be one of the first six types, then the database will automatically be converted to a more efficient internal structure. Those include DB_FILE, GDBM, or MEMORY. The order of preference and the selection is:

As hinted above, you do not need to use an external SQL database. If you only have a small data set, you could use Interchange's internal databases. This is a tremendous gain for small and quick setups, or ad-hoc Interchange evaluation. However, some functions (order management, for example) will be slower and not as robust without an SQL database. SQL is strongly recommended for at least the state, country, orderline, transactions and userdb tables. Any other tables that will have programmed updates, such as inventory, are also best placed in SQL.

	Database performance
	Do not, however, try to optimize too soon and for no measurable difference. Do not fall in the jaws of premature optimization, your worst enemy.

Generally, you should make an additional effort of configuring and using SQL databases to achieve Interchange's full potential. Using SQL also makes your data sets easily available for integration with other applications.

In any case, database import and conversion routines are already available in Interchange and you can use them at any point.

Speaking of the source files' behavior, if a file named table.sql is present in the same directory as table.txt, then database table will never be imported from the ASCII text source file. If there is no table.sql, the DBI/SQL import will happen once, at Interchange startup or catalog reconfiguration time (and the table.sql file will be created); Interchange will connect to the SQL database using the specified DSN (DSN is a standard DBI parameter meaning "Database Source Name"). The table will be dropped (if it already exists in the database) using a line similar to DROP TABLE table. This will occur without warning, but NoImport can be used to prevent it or otherwise change the default behavior. The table will then be created again and populated with text source file data.

If there are any COLUMN_DEF specifications present in interchange.cfg, catalog.cfg or products/table.sql, they will be used to create SQL table specification (which is recommended for clean and correct database layout). If there aren't any, however, then the key (first field in the text file, by default) will be created with the type char(16), and all other fields will be created as char(128). This is very unfortunate, but the best Interchange can do without your help. Table creation statements will be written to the error.log along with, of course, any errors. From our experience, the most common mistake at this point is choosing column names that sound perfectly reasonable, but also happen to be reserved keywords in MySQL. (The error messages appear to be misleading here, so you better take a look at the list of reserved MySQL keywords before losing patience with the problem).

Once the database (database table actually, remember?) is created, the text source file will be imported into it. For this step to succeed, data typing must be user-configured. In other words, if say, word "none" is placed in a field while the field in question is defined to be of numeric type, database import will not succeed; consequently, the problematic catalog won't configure successfully (it will be skipped) and it won't be available when Interchange starts up.

For a complete discussion, please see the Database configuration directive.

By file-based databases we primarily assume GNU DBM and DB_File. We also call those database types "internal", since in the absence of say, an SQL definition, all inferior formats (such as text source files) are automatically converted to some kind of a file-based database.

Those database types usually work in a way that, on every client access, the appropriate database text source file is checked for being newer than the actual DB file itself. When it happens that it is, the database table is re-imported from the text source file on the fly, and the routine then proceeds as usual.

Database updates

It is important to note that, when using Interchange internal database methods, all changes in the text source files cause the databases to be re-created. This can have unwanted effects if the database was modified from within Interchange and the contents have not been written back to the text source files. Another common problem are larger data sets that take noticeable time to get imported to (or exported from) the internal database. The exact behavior can be controlled via the NoImport config directive, but by default, changes in text files will trigger a complete rewrite of DBM or DB_File databases.

To check if you have GNU DBM and GDBM Perl support available, run perl -le'require GDBM_File and print "I have GDBM."'. To check if you have Berkeley DB and DBM Perl support available, run perl -le'require DB_File and print "I have Berkeley DB."'. Sometimes you want to use Berkeley DB even if GNU DBM is installed and would naturally take precedence; in such cases, set the MINIVEND_DBFILE environment variable to a true value (setenv MINIVEND_DBFILE 1 in csh, MINIVEND_DBFILE=1 ; export MINIVEND_DBFILE in sh, b(a)sh or ksh). It is also possible to use Berkeley DB for just specific databases.

For a complete discussion, please see the Database configuration directive.

Memory Interchange databases use Perl hashes to store the data directly in memory. Every time the Interchange server is restarted, it will re-import all in-memory databases for every catalog.

Memory databases are used by default only if no database type is explicitly specified, and there is no DB_File or GNU DBM found on the system. Otherwise they can be used for small but high-traffic tables. Keep in mind, however, that since their contents are not saved back to the text files, you'll want to either take care of the data export yourself, or keep the tables stuffed with read-only data.

if you want to force memory databases despite of GDBM_File or DB_File being present, set the MINIVEND_NODBM environment variable to a true value (look previous chapter for hints on setting it). It is also possible to use memory type for just specific databases.

Memory databases import will be performed once at every Interchange startup or catalog reconfiguration time.

For a complete discussion, please see the Database configuration directive.

We are trying not to impose any database structure that would require our own tools to maintain the data. We always want to keep it such that Interchange data can be maintained via a spreadsheet processor or foreign database tools.

This section describes naming and file usage conventions used with Interchange. This is very important for both understanding Interchange and developing your own custom solutions which build upon officially recommended practices.

Term definitions:

Interchange uses one mandatory database, which is referred to as the products database. In the supplied demo catalog (and in the most of real-world solutions as well), the primary database is directly called products and the ASCII source is kept in the products/products.txt file. This is also the default file for searching contents with the search engine, such as Glimpse, HTDig or Swish.

Note

Interchange also has two optional databases that are specified in special, fixed formats: shipping.asc database contains shipping options that are accessed if the CustomShipping directive is in use. This is a fixed-format database, and must be created as specified. For more information, see shipping glossary entry and the shipping tag. salestax.asc database contains sales tax information if the salestax tag is to be used. A default is supplied. Caution, these things change and need periodic updating! See tax glossary entry for more information. The two above tables cannot be stored in any user-specified format.

The first step is to fulfil the prerequisites of the payment module (listed in the individual module documentation below) and enable the module in the global configuration file with the Require directive:

require Vend::Payment::NetBilling

If we are using only one gateway in a catalog, setting up MV_PAYMENT variables is sufficient.

An example configuration looks like:

Variable MV_PAYMENT_MODE signio
Variable MV_PAYMENT_PARTNER verisign
Variable MV_PAYMENT_ID nevairbe
Variable MV_PAYMENT_SECRET foobar

With the Route directive it is possible to specify payment gateways for special purposes. The payment route should set all relevant payment parameters for the gateway, otherwise the settings from the MV_PAYMENT_* may leak into the route.

Route signio partner verisign
Route signio id nevairbe
Route signio secret foobar

The following payment gateway transactions are known by Interchange:

Modules for the following payment gateways are included in the Interchange source code:

The AuthorizeNet module implements the ADC Direct Response method for AuthorizeNet version 3.

The Getitcard payment module is used for purchases with prepaid cards issued by Getitcard® (http://www.getitcard.com/).

The Netbilling module implements the Netbilling Direct Mode 2.1.

This module can be used for test purposes.

ITL tags are similar to HTML, in that they accept attributes and that there are both standalone (non-container) and container tags.

A standalone tag has no ending element, such as value:

[value name]

The above example will insert user's name.

A container tag has both beginning and ending elements, such as tag if:

[if value name]
  You have provided us with your name. It is [value name].
[/if]

In the above example, you see that container tags are in general useful only when content is provided in their body (the place between the opening and corresponding ending tag).

There must be no whitespace between the left bracket ([) and the tag name; [forum] is valid, [ forum] is not!

We've covered the most basic syntax above. If you need to pass attributes to the tag, you do that in the opening section. If the tag is a container, then body text can additionally be specified between the opening and closing marker:

[tagname parameters_or_attributes]
  Body Text
[/tagname]

Note that some Interchange macros (drop-in text replacements) may look like tags or end tags. For example, [/page] used to be a macro that expanded to </a>, but page itself was not a container tag and [/page] wasn't its closing element. Likewise, some tags perform special subtags processing on their own, and the subtags are not considered real tags — they only exist in the context of the surrounding tag and usually support only limited options. One such example is tag row with its subtag .

It is important to mention that if a tag or argument name includes an underscore or dash (such as in item-list), then you can always choose between the dash and underscore! The two forms are interchangeable, except that you must be consistent with tag markers; an ending tag must match the opening tag. Both [item-list]...[/item-list] or [item_list]...[/item_list] are fine, but [item-list]...[/item_list] is not.

This is a very convenient feature. It is a common standard to use dashes (-) in ITL, and underscores (_) in Perl code (because in Perl, dashes would be interpreted as minus operators, which is not what you'd expect).

There are two styles of supplying attributes to a tag: named and positional.

In the named style, you supply attributes using key=value pairs, just as with HTML:

[value name=variable_name]

The positional-style tag that accomplishes the same thing, but is more compact:

[value variable_name]

Positional syntax, however, requires support by each tag individually. That is, set of arguments that can be specified in positional notation (as well as their position in the set) are fixed and determined in advance. You can see a list of accepted positional arguments (and their implicit order) in each tag's SYNOPSIS reference section; try value for example.

You cannot mix named and positional attributes in the same tag; use either all named, or all positional.

Positional syntax is appropriate for simpler tags and Interchange interprets positional arguments slightly faster, but don't let premature optimization kick in — as Edsger W. Dykstra once said, "Premature optimization is the root of all programming evil".

In most cases, positional attributes (called parameters) work the same as named attributes. However, there are a few situations where you must use named attributes:

ITL also supports a special notation where you use HTML comment markers with ITL inside, and where the comments are removed by Interchange so that the tag results show up in the generated HTML page.

That means [tagname ...] and <!--[tagname ...]--> are equivalent.

This allows you to make your raw ITL tags appear as comments in HTML browsers, and especially in HTML editors which might not like non-HTML markup at random positions. You might want to use this if your editor has trouble with ITL tags when editing Interchange page templates, or alternatively, if you want to use one .html file both as an Interchange page and as a static page delivered directly by your web server where no Interchange processing is performed.

When you really wish to treat HTML comments as plain comments and not remove them, then you must include a whitespace between the HTML comment delimiters and the ITL square brackets:

<!--[value name]-->       becomes  Bill
<!-- [value name] -->     becomes  <!-- Bill -->

ITL is interpolated in both cases however. To prevent ITL interpolation within HTML comments, you either need to see the <pragma>no_html_comment_embed</pragma> pragma, or enclose the block in a special ITL comment tag instead of in HTML comment:

[comment] [value name] [/comment]

Besides not being interpolated at all, comment blocks do not appear in the final HTML sent to the client either, so you can be completely safe regarding any unintentional code or information leakage.

While <!--[ and [ are completely interchangeable, the Interchange parser does not replace ]--> with ] unless it sees <!--[ at least once somewhere on the page. This is a small parsing speed optimization and shouldn't cause you any trouble as you're supposed to be consistent in your syntax anyway.

When ITL tags are expanded, for example when [value name] yields the actual user's name, we say the tags are interpolated.

If you want to use one tag's output as another tag's input, you must use named syntax and you must double-quote the argument. For example, this WILL NOT work:

[page scan se=[scratch variable_name]]

The above code is in really bad shape. To make it work, we need to do two things: switch to named syntax, and properly quote arguments containing whitespace:

[page href=scan arg="se=[scratch variable_name]"]

Note that the href argument did not need to be quoted; arg did, because it contained a whitespace and it contained a tag intended for interpolation ([scratch variable_name]).

Note

As you can implicitly see from the above example, attribute values are normally interpolated (in other words, se=[scratch variable_name] was expanded to se=VARIABLE_VALUE before being passed as value to arg=. However, when the attributes contain a dot (such as name.first= or name.last=), their values are not interpolated by default. Their interpolation is controlled by the <pragma>interpolate_itl_references</pragma> pragma, and more about this whole concept can be learned below in the section called “Attribute Arrays and Hashes”.

Interchange parse content like pages, components and profiles in a few consecutive passes instead of once from the top to the bottom:

The question is — exactly when can you omit the quotes around argument values? First answer is trivial; never omit the quotes and you'll never run into trouble.

The other answer says, "omitting quotes earns you a bonus for style and achieves small parser speed improvement". However, if the value contains a whitespace, you must quote it. To quote values, you can use double quotes ("), single quotes (') and pipes (|) interchangeably. Pipes have the additional functionality of removing leading and trailing whitespace, but generally you can use all types in combination to do three levels of quoting with ITL; for more deeply nested constructs, use direct Perl code.

Additionally, container tags can be closed using "XML-style" syntax. The following two lines are identical in effect:

  [forum top="[item-code]" display_page=forum_display  ][/forum]
  [forum top="[item-code]" display_page=forum_display /]

Note, however, that you can use "/]" only with tags for which you provide no attributes, or the attributes are named and quoted. Positional attributes (parameters) "absorb" everything (including the "/") up to the closing bracket, and therefore using "/]" is not possible.

When using "/]" notation, it is still possible to provide body for the tag by specifying body= attribute.

The above covers a good deal of quoting, but it's still not all there is to it. Loop subtags, which we explain some lines below, are an exception to the rule and do not need quotes (even though they sometimes contain whitespace), because they are parsed earlier in a separate pass, before the general parser takes on.

Here's an example with loop subtags that would work properly even with quotes omitted. (Pay attention to [item-field url] which, at first sight, looks like it is invalid because it contains a space and is not quoted nor named.)

[item-list]
[page [item-field url]]detailed info[/page] on [item-description]
[/item-list]

You might wonder why unquoted tags are allowed. The answer is performance. If you have large lists of tags you can achieve significant speed-ups by using positional attributes. Parsing and disassembling named attributes takes some more CPU cycles.

Universal attributes apply to all tags, although tags might specify their own defaults for the attribute. The code implementing universal attributes is independent of the routines that implement specific tags.

We will explain interpolate and reparse attributes here. It is important to remember that the behavior of the interpolate attribute (unfortunately) differs, based on whether a tag is stand-alone or a container. In addition, the reparse attribute is only used with container tags.

With standalone tags, the interpolate attribute specifies whether the output of the tag will be interpolated.
Output of most of the stand-alone tags is not interpolated by default. Exceptions to this rule would include, for example, the include tag.

With container tags, the interpolate attribute specifies whether the tag body will be interpolated before being passed to the tag.
The reparse attribute specifies whether output will be interpolated.

For an interpolation example with container tags, let's assume the user's name is Kilroy:

[log interpolate=1][value name] was here[/log]

[log interpolate=0][value name] was here[/log]

The first line would log "Kilroy was here" to CATROOT/etc/log, while the second line would log pretty useless "[value name] was here".

For an interpolation example with stand-alone tags, consider the following:

[set name=now interpolate=0][time]%A, %B %d, %Y[/time][/set]

We've set the scratch variable new to not contain the actual date, but the ITL code to calculate and display the date each time it's called. Let's assume today is Monday, January 1, 2001, and we have the following code:

[scratch name=now interpolate=1]

[scratch name=now interpolate=0]

The first line would then produce the expected Monday, January 1, 2001, while the second would leave us with unusable [time]%A, %B %d, %Y[/time].

The example above serves to show interpolate used with a stand-alone tag. This behavior can only be achieved by using reparse attribute if you're having a container instead of the stand-alone tag.

The reparse attribute is only used with container tags, and specifies whether the tag output will be interpolated. This is basically the same as the interpolate attribute for stand-alone tags, but a new name had to be invented because interpolate already performed a different function with container tags, when this functionality was to be added.

Most container tags will have their output re-parsed for more Interchange tags by default. If you wish to prevent this behavior, you must explicitly set the reparse attribute to a false value. Note, however, that you will almost always want the default action. Probably the only ITL tag that doesn't reparse by default is mvasp.

Here's an example. Again, assuming the user's name is Kilroy,

[perl reparse=1]
   my $tagname = 'value';
   return "[$tagname name] was here\n"
[/perl]

[perl reparse=0]
   my $tagname = 'value';
   return "[$tagname name] was here\n"
[/perl]

expands to

Kilroy was here

[value name] was here

In Interchange 5.3.1, the <pragma>no_default_reparse</pragma> pragma was added, which disables the default reparsing of container tags' output. It is therefore advisable to always specify the reparse=1 attribute at places where you want reparsing to really occur.

The third attribute, send , was deprecated long ago and will only be described for historical reference.

Each tag may accept additional arguments which vary from tag to tag. For each tag individually, you need to consult the appropriate reference page to learn tag-specific parameters and attributes. Note, however, that the tag arguments do not necessarily have to be announced in the tag definition header; sometimes they're used pretty much ad-hoc, but we are making sure to keep the documentation up to date. We kindly ask you to inform us of any errors or omissions in the documentation.

Instead of just plain values, for some tags it would be particularly convenient if they accepted arrays or hashes of argument values, much like you could do if you used Perl directly. Fortunately, ITL supports that too! For an ordinary tag, the syntax is as follows:

attribute.ARRAY_INDEX=value

attribute.HASH_KEY=value

ARRAY_INDEX is an integer array index starting from 0 (this is due to standard programming practice and Perl behavior). Note that you cannot have both an array and a hash attribute of the same name (even though that would be possible in pure Perl).

Here is an example of an array-based attribute:

search.0="se=hammer
          fi=products
          sf=description"

search.1="se=plutonium
          fi=products
          sf=comment"

It is up to each individual tag to handle an array or hash value properly. See the documentation for the specific tag before passing it an attribute array or hash value. The page tag, for example, would treat a search specification array (the structure we've shown above) as a joined search (one of different search types we support).

On the Perl level, before passing attributes to a tag, Interchange parser would convert attributes to an anonymous array reference.

If you were passing the above example directly to a tag named ROUTINE within a perl block or your custom tag, you would actually pass an anonymous array as the value of the attribute:

my $arrayref = [ "se=hammer/fi=products/sf=description",
                 "se=plutonium/fi=products/sf=description", ];

$Tag->ROUTINE( { search => $arrayref } );

Similarly, to use a hash reference in some other occasion:

my $hashref = { name   => "required",
                date   => 'default="%B %d, %Y"', };

$Tag->ROUTINE( { entry => $hashref } );

Pay attention to the fact that with array- or hash-based attributes, their values are not interpolated. It means that, at places where scalar options are interpolated (such as [tag option='[time]'], resulting in time expanding to the current time), reference-based attributes are not (such as [tag my.option='[time]'], which would result in literal "[time]" being passed to the attribute "my.option". Interpolation of reference-based attributes can be enabled by setting the <pragma>interpolate_itl_references</pragma> pragma.

Certain tags can only appear in a special context, usually nested within other, parent tags. Those include, for example, the ones interpreted as part of a surrounding loop tags, such as loop, item-list, query or search-region.

Some of those subtags are PREFIX-accessories, PREFIX-alternate, PREFIX-calc, PREFIX-change, PREFIX-code, PREFIX-data, PREFIX-description, PREFIX-discount, PREFIX-discount-subtotal, PREFIX-field, PREFIX-increment, PREFIX-last, PREFIX-line, PREFIX-modifier, PREFIX-next, PREFIX-param, PREFIX-pos, PREFIX-price, PREFIX-quantity, PREFIX-subtotal, if-PREFIX-data, if-PREFIX-field, if-PREFIX-param, if-PREFIX-pos, PREFIX-modifier-name and PREFIX-quantity-name.

In each of the above, PREFIX represents an arbitrary prefix that is used in that looping tag; this is needed to be able to support nesting in arbitrary order and to arbitrary level. All of the subtags are only interpreted within their container tags (they can only appear inside their parent tags' bodies) and they only accept positional parameters. The default prefixes follow:

Sub-tag behavior is consistent among the looping tags.

	Important
	As we've said already, subtags are parsed before the standard parsing routine takes on; that means before any regular tags within the loop. This has a subtle effect; it can, for example, prevent the usual tags from accepting looping tags' values as attributes. In such cases, look for "subtag" (prefixed) variants of the usual tags.

Speaking of loops and Perl, there are two types of records that Interchange can return with looping lists: ARRAY and HASH.

An array list is the normal output of the query and loop tags, or of a search operation. In those cases, fields specified in mv_return_fields (or those specified in SQL) are returned for each selected row. The two queries below are essentially identical:

[query sql="select foo, bar from products" /]

[loop search="
                ra=yes
                fi=products
                rf=foo,bar
"]

Both will return an array of arrays consisting of the foo and bar columns. The corresponding Perl data structure would look like this (familiarity with the output from Data::Dumper Perl module helps here):

[
    ['foo0', 'bar0'],
    ['foo1', 'bar1'],
    ['foo2', 'bar2'],
    ['fooN', 'barN'],
]

A hash list is the normal output of the item-list tag. It returns the value of all return fields in an array of hashes. A normal return might look like this:

[
    {
        code     => '99-102',
        quantity => 1,
        size     => 'XL',
        color    => 'blue',
        mv_ib    => 'products',
    },
    {
        code     => '00-341',
        quantity => 2,
        size     => undef,
        color    => undef,
        mv_ib    => 'products',
    },

]

However, you can explicitly request hash lists to be returned from queries:

[query sql="select foo, bar from products" type=hashref /]

The data structure returned would then be:

[
    { foo => 'foo0', bar => 'bar0' },
    { foo => 'foo1', bar => 'bar1' },
    { foo => 'foo2', bar => 'bar2' },
    { foo => 'fooN', bar => 'barN' },
]

Standard PreFork uses the typical double-fork method in UNIX for generating daemons so as to avoid zombies (or more specifically needing to deal with them). However, forking Interchange daemons is relatively expensive.

For most (if not all) sane, modern Unixen, you can avoid the relative expense of double forking by setting SIGCHLD to IGNORE in the master, which accomplishes roughly the same goal. It states, essentially, that the parent is not interested in the result of the child's process, so don't zombify my kids waiting for me to check on them.

Every job is tied to a directory containing job files. The selection of the files is controlled by the HTMLsuffix and the suffix Jobs attribute. By default all files not matching HTMLsuffix are included.

The following configuration example directs Interchange to execute all files matching jobs/NAME/*.job for the job named NAME.

Jobs base_directory jobs
Jobs suffix .job

Interchange gathers the output of all job files and passes through the filter(s) specified with filter key of the Jobs directive.

The remaining output is optionally written to the job logfile and/or emailed as specified by the log and email keys of the Jobs directive.

Jobs email racke@linuxia.de
Jobs log logs/job

Tracking jobs into a database table can be enabled with the trackdb key of the Jobs directive.

Jobs trackdb jobs

Required fields for this table are code, name, pid, begin_run, end_run.

UNIX domain sockets are not reachable from the Internet directly; they can only be accessed from the local host. This improves security and is the right thing to do when the web and Interchange server are running on the same host.

The link program vlink is the provided facility for such communication with Interchange. As said, this is the most secure way to run a catalog, as there is no way for systems on the Internet to interact with Interchange except through the offered link program.

The most important issue with UNIX-domain sockets and Interchange are file permissions (Unix sockets appear as files on the local disk). Interchange normally runs with the socket file having permissions 0600 (which translates to rw-------), which mandates that the CGI program and the Interchange server run as the same user ID. This means that the vlink program must be SUID to the same user ID as the Interchange server executes under. (Or that CGIWRAP is used on a single catalog system, but CGIWRAP is largely obsolete these days).

Even though this is against good security practice, let's say you can put SocketPerms 0666 in your interchange.cfg (and restart Interchange) to allow wide-open access to the socket file. In fact, you should do this when you have connection problems to quickly rule out whether it's just permissions or something else.

INET sockets are reachable from the Internet directly. The link program tlink is the provided facility for such communication with Interchange. Other browsers can talk to the socket directly if mapped to a catalog with the global TcpMap directive. To improve security, Interchange usually checks that requests come from one of a limited number of "trusted" systems defined with the global TcpHost directive.

vlink and tlink, compiled from vlink.c and tlink.c source files, are very small, fast and low-overhead C programs that contact the running Interchange daemon. The vlink executable is normally made setuid (SUID) to the user account which runs Interchange, so that the UNIX-domain socket file can be set to secure permissions (user read-write only, as mentioned above). It is normally not necessary for the user to do anything — the link programs will be compiled by the configuration program. If the Interchange daemon is not running, either of the programs will display a message indicating that the server is not available.

Link program source files, found in dist/src/ directory with Interchange source tree, share the common C include file config.h which sets required variables:

There is a compile_link program found within Interchange source tree that will assist you with link program compilation. Run perldoc PATH/TO/compile_link to read its documentation. (To find where the compile_link or compile_link.PL commands are, use locate compile_link or find / -name 'compile_link*').

Anyhow, you can also compile the link programs more "manually" if you position yourself to the Interchange source tree:

$ cd dist/src
$ ./configure
$ # (open and inspect config.h)
$ mkdir ../bin
$ perl compile.pl

After which the compiled vlink and tlink programs will be in your dist/bin/ directory.

For yet another iteration, if you want the control over the whole process, instead of perl compile.pl invoke simply:

$ gcc vlink.c -o ../bin/vlink
$ gcc tlink.c -o ../bin/tlink

The problem with the above approach, however, is that you might be missing critical compiler options, or that the compiler isn't gcc at all. To ensure that the C compiler will be invoked properly, use the following little ditty instead of the two gcc lines:

perl -e 'do "syscfg"; system("$CC $LIBS $CFLAGS $DEFS vlink.c -o ../bin/vlink");'
perl -e 'do "syscfg"; system("$CC $LIBS $CFLAGS $DEFS tlink.c -o ../bin/tlink");'

And finally, you can make the binaries smaller by going to ../bin/ and typing strip *, if available. (strip removes all debugging symbols from the binaries).

Have in mind that link programs are the same for all catalogs running on the same server — it's only their name that makes them refer to different catalogs. In other words, once you get one link program compiled, you can simply keep copying it to new names as you create new catalogs.

First of all, if Interchange is to run under a different user account than the individual configuring the program, change vlink ownership to the Interchange user. Do not make it owned by root, because making vlink SETUID root is an huge and unnecessary security risk. It should also not normally run as the default Web user (often nobody or http>).

Here's a prospective session transcript (starting in dist/bin/):

# Set up ownership and suid bit
chown INTERCHANGE_USER vlink

# Move the vlink executable to the cgi-bin directory:
mv vlink /usr/lib/cgi-bin/CATALOG_NAME

# Most systems unset the SUID bit when moving the file,
# that's why we add suid here and not above:
chmod u+s /usr/lib/cg-bin/CATALOG_NAME

The latest versions of the link programs have been compiled on the following systems:

If nothing works and you have a problem, you can try using the tlink.pl program found in the same location as link and tlink. tlink.pl is a tlink implementation written in Perl and should work on a really broad range of systems. In any case, unless you are using tlink.pl for a specific reason, and you do have a working compiler, tuning the C source files to overcome compilation problems is preferred over using Perl implementation of the link program.

The important thing to have in mind is that Interchange allows customers to access the same catalog in an unlimited number of languages, currencies and regional settings. What's more, you can switch locales at will, at any time!

The simplest and recommended way to set the default catalog locale is to define a starting value for mv_locale in catalog.cfg:

ScratchDefault mv_locale de_DE

The per-user locale change can be made permanent (for the duration of the user session, of course), or temporary (if you're, say, displaying pricing information in multiple currencies). See setlocale for more discussion and examples.

Besides using actual "programmatic" methods to set locales, you can achieve the same effect by using one terrific feature of the process ActionMap; to display page named "pricelist" in locale fr_FR and currency en_US, simply call ITL tag [page process/locale/fr_FR/currency/en_US/page/pricelist].

The localized messages you want to display must previously be defined, of course. The simplest way to define localized messages is to use the Locale directive in any of the ways shown:

Locale de_DE "Value setting" Werteinstellung
Locale de_DE "Search"        Suchen

Locale fr_FR <<EOF
{
  "Value setting",
  "Configuration de valeur",
  
  "Search",
  "Recherche"
}
EOF

This method, however, is not practical when you have a lot of messages; for robust setups use LocaleDatabase.

With the above, to display an appropriate translation of "Value setting", you would call "[L]Value setting[/L]", which would display as "Configuration de valeur" in locale fr_FR, "Werteinstellung" in locale de_DE, and as a fallback, it would be displayed unmodified as "Value setting" — if the locale is neither fr_FR not de_DE, or no localized string for the message was found at all. Keep in mind that the "[L]" tags must be capitalized — this is done for both processing speed and easy visual distinction within pages.

A word on localization tag [L]

Interchange tries to substitute text for its localized variant very early in the page serving process — even before variables are expanded or tags interpolated. On one hand, this means you can use variables and tags in localized strings as they will be handled properly. On the other hand, it means code constructs like [L][item-data table field][/L] will fail, as Interchange would try to translate "[item-data table field]" literally. There's a loc tag available which is functionally identical to L, but is parsed in normal order and therefore solves the problem.

Another way to display localized messages is to supply localization text directly within Interchange pages, inside LC tag; have a look at this intuitive example:

[LC]
  This is the default text.
  [fr_FR] Text for the fr_FR locale. [/fr_FR]
  [de_DE] Text for the de_DE locale. [/de_DE]
[/LC]

It's also possible to display completely different pages, based on the locale in effect. You probably know the default HTMLsuffix in Interchange is ".html", but you probably do not know it is locale-sensitive. With a request for page named "index" ([page index]), fr_FR locale in effect, and a catalog.cfg directive of

Locale fr_FR HTMLsuffix .fr_FR

Interchange would first look for pages/index.fr_FR, and only if it's not found go to the usual pages/index.html.

	A general note on locale-sensitivity of config directives
	We've said HTMLsuffix is locale-sensitive, but the story gets much better. In reality, any Locale key that matches the name of a config directive, causes the directive to be re-set on locale change — in other words, all config directives are locale-sensitive!

Interchange sorting features (such as — but not only — the sort tag) will honor a setting of LC_COLLATE, provided that the operating system and C compiler support locales for POSIX, have the locale definitions set, and the locale chosen matches one of locales available.

Suppose we have a letters database, containing some of the letters of the alphabet. A code of:

[loop 19-202 00-0011 99-102]
  [sort letters:letter]
  [loop-data letters letter]   [loop-code] <br/>
[/loop]

would provide different order for locale C than fr_FR.

Interchange supports a number of ways to add an item to the basket. You can order an item by using both form-based (button-clicking) and link-based (link-visiting) methods.

[order code=SKU quantity=NUMBER href=URL cart=NAME ]Link text</a>

Order a [order TK112]Toaster</a> today!
Order a [page order TK112]Toaster</a> today!

Order a <a href="[area order TK112]">Toaster</a> today!
Order a <a href="[area href=order arg=TK112]">Toaster</a> today!

Order a <a href="[area href=order form='mv_order_item=TK112']">Toaster</a> today!

Order a [order [item-code]][item-field name]</a> today!

<form action="[process href=order]" method="post">
  [form-session-id]
  <input name="mv_order_item"     type="hidden" value="TK112"      />
  <input name="mv_order_quantity" type="text"   value="1" size="3" /> toasters 
  <input value="Order!"           type="submit"                    />
</form>

<form action="[process href=order]" method="post">
  [form-session-id]
  <input name="mv_order_item"     type="hidden" value="TK112"            />
  <input name="mv_order_quantity" type="text"   value="1"       size="3" /> Standard Toaster <br/>
  <input name="mv_order_item"     type="hidden" value="TK200"            />
  <input name="mv_order_quantity" type="text"   value="1"       size="3" /> Super Toaster
  <input value="Order!"           type="submit"                          />
</form>

Note that "on the fly" items are those that do not exist in any of the products databases, and are literally "put together" on the fly. This is unrelated to Interchange flypage functionality.

If you setup the OnFly config directive, Interchange will be able to add items to user's basket even if they're not listed in any of the products databases.

A basic on-fly item can then be generated like this:

<a href="[area form="
  mv_order_item=000101
  mv_order_quantity=1
  mv_order_fly=description=An on-the-fly item|price=100.01
"]">Order item 000101</a>

Or, through a proper Submit button:

<form action="[process href=order]" method="post">
  [form-session-id]
  <input type="hidden" name="mv_order_item" value="000101">
  Qty: <input size="2" name="mv_order_quantity" value="1">
  <input type="hidden" name="mv_order_fly" value="description=An on-the-fly item|price=100.01">
  <input type="submit" value="Order button">
</form>

A lot of things might look weird in the above example, but it is all valid ITL code.

The form parameter mv_order_fly can contain any number of fields which define attributes for our on-fly item. Fields are separated by the pipe (|) character and contain value-parameter pairs separated by an equal (=) sign.

	Note
	To show description for the on-fly item, you must use the item-description tag; [item-field description] or [item-data products description] will not work since both try referencing existing fields in products databases. Similarly, an attempt to generate a flypage for an on-fly item will fail, resulting in display of the SpecialPage missing URL.

Multiple items can be ordered at once by stacking the variables, as we've shown already. However, if there is only one mv_order_item instance defined, then you can stack mv_order_fly variables which will result in their concatenation just as if you separated them with pipes. Here's an example, equal in effect to the previous one:

<a href="[area form="
  mv_todo=refresh
  mv_order_item=000101
  mv_order_fly=description=An on-the-fly item
  mv_order_fly=price=100.00
"]">Order item 000101</a>

We've seen variable stacking at work above, but there's more to it. Imagine you had a master item and accompanying accessories which only make sense together with the main item. You could order them at once using ordinary stacking - no problem there, but what if you also wanted accessories or options removed at the same time the master item is removed from the cart? In the simplest form, this is achieved by ordering items as usual, while defining mv_order_group. The first item in the list is then treated as the master item, and all other are sub-items.

<form action="[process href=order]"  method="post">
  [form-session-id]
  <input name="mv_order_group" type="hidden" value="1"         />
  <input name="mv_order_item"  type="hidden" value="00-0011"   />
  <input name="mv_order_item"  type="hidden" value="00-0011a"  />
  <input value="Order Mona Lisa with frame" type="submit"      />
</form>

Incredible, but you can also define multiple master items! All you need to do is define a mv_order_group for each individual item. Master item "owns" all subsequent sub-items until the next master is defined.

<form action="[process href=order]"  method="post">
  [form-session-id]
  <input name="mv_order_group" type="hidden" value="1"         />
  <input name="mv_order_item"  type="hidden" value="00-0011"   />
  <input name="mv_order_group" type="hidden" value="0"         />
  <input name="mv_order_item"  type="hidden" value="00-0011a"  />
  <input name="mv_order_group" type="hidden" value="1"         />
  <input name="mv_order_item"  type="hidden" value="19-202"    />
  <input name="mv_order_group" type="hidden" value="0"         />
  <input name="mv_order_item"  type="hidden" value="99-102"    />
  <input value="Order Mona Lisa and more!"   type="submit"     />
</form>

The example shows a 4-item order form. Items 1 and 3 are master items, items 2 and 4 are sub-items. If a master item of SKU 00-0011 is deleted from the basket, 00-0011a will be deleted too. If 19-202 is deleted, then 99-102 will be deleted along.

Note

Use of HTML checkboxes for this type of thing could be inappropriate because they do not pass a value when unchecked. The value then remains defaulting to last used value. It is preferable to use radio groups or select/drop-down widgets instead. If you use checkboxes, make sure to explicitly clear mv_order_group and mv_order_item somewhere on the form page. You can re-use the following code snippet: [value name=mv_order_group set=''] [value name=mv_order_item set='']

mv_mi and mv_si attributes are set to the group and sub-item status of each item. The group, contained in the attribute mv_mi, is a meaningless yet unique integer. All items in a group will have the same mv_mi value. The attribute mv_si is 0 if the item is a master item, and 1 if it is a sub-item.

Basket pages list electronic cart contents and usually allow order contents to be adjusted; items can be removed, ordered in different quantities etc.

It is possible to have an multiple (different) basket pages, because they're in no way special. It is also possible to have multiple shopping carts, for example in cases where the same user maintains a buy and sell list. Multiple basket pages could also be used where items have many accessories and, depending on the item ordered, you send customers to different, item-specific pages to choose accessories. The possibilities are endless, it's just about evaluating your actual needs.

The name of the basket page to be displayed upon item order can be defined in a few ways:

Interchange allows you to define and maintain multiple shopping carts for each user. The default shopping cart named main is created when the user session starts. If the user orders an item of SKU M1212 through the following link:

[order code=M1212 cart=layaway]Order this item!</a>

then the item will be placed in the cart named layaway, and not main. Consequently, the use won't see the just-ordered item on the basket page because the default shopping basket displays contents of the main cart only. The easiest way to support multiple carts is to copy the default basket page (CATROOT/pages/ord/basket.html) to a new file, insert [cart layaway] code snippet at the top, and specify it as the target page for the order tag:

[order code=M1212 cart=layaway page=ord/layaway_basket]Order this item!</a>

Now the contents of the layaway cart would be displayed on the appropriate page. Most of the fundamental cart management ITL tags support the nickname option, allowing cart name to be chosen. Using nickname is handy, and has no permanent effect, the default cart remains set at value of main. A sticky attribute could be set to change the default cart name until further notice. This is convenient, but you must remember to use [cart main] to get back to the primary cart!

And for the sake of completeness, here's the above example using form-based ordering:

<form action="[process href=order]" method="post">
  [form-session-id]
  <input name="mv_order_item"     type="checkbox" value="M1212"   /> Item M1212
  <input name="mv_order_quantity" type="text"     value="1"       /> Quantity
  <input name="mv_cartname"       type="hidden"   value="layaway" />
  <input value="order this item!" type="submit">
</form>

The simplest method, as we've just hinted above, is flat pricing based on a fixed value in the products database. All you have to do is put item price in the price field and you're all set. If you want to change pricing based on quantity, size, color or arbitrary other factors, then read on.

Although the CommonAdjust directive provides a lot of options to describe pricing schemes, it might not match yours or you are just feeling more comfortable in writing code instead of delving through the following section. In this case you can simply write your own usertag calculating the price with the following settings for CommonAdjust and PriceField:

PriceField 0
CommonAdjust [calc-price]

The following example can be used to base your own usertag on. Product code and quantity for the price calculation can be found in the $item variable from the Vend::Interpolate namespace.

UserTag calc_price Routine <<EOR
sub {
	my ($code, $quantity, $set);

	$code = $item->{code};
	$quantity = $item->{quantity};

	$Tag->perl({tables => 'vendors_pricing'});

	$set = $Db{vendors_pricing}->query(q{select price from vendors_pricing where sku = '%s' order by price asc limit 1}, $code);

	if (@$set) {
		return $set->[0]->[0];
	} else {
		return 0;
	}
}
EOR

A flexible, chained pricing scheme is available when CommonAdjust directive is set up.

CommonAdjust string, a term we'll use in this section, will be explained below.

Here are CommonAdjust usage rules, all assuming PriceField having the default value of price.

Using valid CommonAdjust strings, prices may be adjusted in several ways, but we first need to define "CommonAdjust string" as we've promised in the introduction. CommonAdjust strings are price definition strings which consist of individual actions called atoms. Atoms in turn consist of settors. Roughly, we could say atoms convey "control information" — they define when are contained settors applied, and settors define what is applied.

Price atoms can be of type final, chained and fallback.

Atom types are recognizable from the syntax used to define them.

Atoms themselves are separated by whitespace and must be quoted if they themselves contain whitespace.

A settor is a mean by which the price is set. In other words, it is an expression contained in an atom which, when evaluated, affects the item price. Just as there are different types of atoms, there are different types of settors as well. Be aware that all settor types can yield new CommonAdjust strings, and it's quite possible to create endless loops this way. Therefore, the maximum number of initial CommonAdjust strings is 16, and there may be a maximum of 32 repeated CommonAdjust string iterations or loops before the price will return zero on an error. Those limits are only defaults and can be adjusted using general-purpose Limit config directive.

	Note
	Common needs are easily shown but not so easily explained. Follow our pointers to examples if your vision starts to blur as you dive into the following section.

Let's take a look at available settor types. Settor types do not have distinguishable symbolic names, but their type is recognizable from the syntax used. Note that bold elements are required, while the rest are optional.

For actual examples, please see the CommonAdjust reference page.

For product discount settings, see the discount glossary entry.

Interchange form profiles are used to validate form inputs and eventually trigger additional actions. The validation usually consists in requiring that some of the fields are non-empty or match a specific regular expression pattern.

Profiles are not specific to order checkout or any specific step; they are an integral part of all form processing in Interchange. You will also see actions such as Interchange account creation, login, logout or password change being at least partly handled using profiles.

Profiles can be defined in external files (and activated using OrderProfile) or in scratch variables. External files are, by convention, kept in CATROOT/etc/ and begin with profiles.. Multiple profiles can be defined in each file.

A very simple hello world-like profile example follows:

__NAME__  test_profile

fname=required
lname=required

__END__

The above profile requires customers' first and last names to be entered.

	Note
	The __NAME__ and __END__ markers must start at the beginning of line, not even whitespace is allowed. This is very important because the profile would otherwise be silently ignored.

If users leave some of the required fields empty (or there's some other reason why you'd want them to correct their input), you'll probably want to show them the form page again and display some kind of an error message. To override the default messages, simply specify your own strings after the format check specification. Here's an example:

__NAME__  test_profile

fname=required First name is required!
lname=required Last name is required!

__END__

username=regex ^[a-z][-a-z0-9]*$ "Invalid characters in username."
&and
username=length 6-32 Size limits exceeded (6-32 characters)

To enable the Interchange SOAP server, set SOAP to yes in the global configuration file. It is also important to allow SOAP actions with SOAP_Control both in the global configuration and in the catalog configuration file in order to provide web services.

SOAP_Control Action always

After restart, the Interchange SOAP server will listen on port 7780 for requests.

For all catalogs providing SOAP services, do the following steps:

Finally, restart your Interchange server.

The port can be changed with the SOAP_Socket configuration directive.

If Interchange cannot determine the catalog for the SOAP request, it will trigger the soap:Client.NotFound fault.

If the catalog hasn't enabled SOAP, Interchange will trigger the soap:Client.NotAvailable fault.

If the called SOAP action dies, Interchange triggers a soap:Server fault with the message Application error.

SOAP resource at W3C.

SOAP::Lite homepage.

Sales tax calculation in this simple scheme is performed on a straight percentage basis, with certain items allowed to be tax-exempt. Simply initialize the SalesTax directive to the name of lookup fields. Those lookup fields are the ones that are available on the final order form and indicate geographical locality.

SalesTax configuration directive is set to form fields whose values will be used as keys to look up the tax rate in products/salestax.asc, based on localities. salestax is a fixed-format database, and consists of identifiers that match localities defined using SalesTax.

Locality names are always forced to UPPER CASE, and are usually identified by zip or state codes:

SalesTax    zip,state

Each line of the mentioned products/salestax.asc file should contain a code (again, usually 5-digit zip or 2-letter state ID), followed by a TAB character and a desired percentage.

default	0.0
45056	.0525
61821	.0725
61801	.075
IL	.0625
OH	.0525
VAT	.15
WA	.08

Based on user information given on the order form (and given our sample SalesTax setting), Interchange will attempt a tax lookup by zip and state (in that order), and apply the percentage found to the subtotal of the order. The subtotal will include item prices, taxes and shipping costs (if TaxShipping was set up). It will add the percentage, then make that available with the salestax tag for display on the order form. If no match is found in CATROOT/products/salestax.asc, the entry DEFAULT (case-insensitive) will be applied — which is usually zero.

If some items are not taxable, then you must set up a field in your database which indicates that. Announce this field name by using the NonTaxableField directive. If the specified field for that item evaluates to a true value, sales tax will not be applied to the item.

If you want to set a fixed tax for all orders, as might occur for VAT in some countries, then SalesTax set to the zip or state codes is not optimal for the purpose of sales tax calculation. The solution is to introduce an arbitrary variable that, unlike zip or state, does not change from user to user. Then, you would set that variable in user session to point to a fixed entry in the CATROOT/products/salestax.asc file. Exactly how you're going to set a session variable is not important; you could use the ValuesDefault directive ( ValuesDefault tax_code VAT), a hidden form variable (<input type="hidden" name="tax_code" value="VAT" />), or a simple Perl code block ([perl] $Values->{tax_code} = 'VAT'; return [/perl]).

This is one of the simpler taxing methods as well. A series of Interchange Variable settings are read to develop a salestax rate for one or more geographical localities.

With this method, you implement the simple SalesTax method explained above, but only put one entry in CATROOT/products/salestax.asc. Then , TAXRATE and TAXSHIPPING catalog variables would be used to build the tax rates.

The single entry in CATROOT/products/salestax.asc should be default with a value of fly-tax:

DEFAULT	[fly-tax]

With this method, country and state databases are used to develop complex VAT or salestax rate calculations, based on country and state, possibly with different rates based on product type.

The SalesTax directive must be set to multi, and then the type of tax to apply will be read from the country database. Since this is a standard database, to display taxing for say, Croatia (code HR), you'd simply call:

[data table=country col=tax key=HR]

We've mentioned some hard-coded values above (the country table, column names etc.), but this is all configurable using MV_COUNTRY_TABLE, MV_COUNTRY_FIELD, MV_COUNTRY_TAX_FIELD, MV_STATE_TABLE, , MV_STATE_TAX_FIELD, MV_TAX_TYPE_FIELD and MV_TAX_CATEGORY_FIELD variables.

So, with this multi approach, Interchange first performs a lookup in the country database. The default key for the lookup is, of course, [value country] (value of the country form variable), and the column retrieved is tax. At that point, the following rules are applied:

Using Levies and Levy structure, any or all of the above methods are used in combination to implement the a taxing scheme of truly arbitrary complexity.

To prevent tax calculation routines from ever applying a negative tax amount, see pragma <pragma>no_negative_tax</pragma>.

To create the database, you could follow a very simple structure. The only two required fields are username and password. Your sample test database could look like this:

code	password

(Note that the name of the first column — the primary key — is arbitrary because Interchange's default functions are not accessing it by name. But it is a good standard to name the first field code in all your database tables).

It is, however, recommended to use an SQL database for any more complex functions. Let's take a look at a more elaborate user database that, among other things, has support for visitors' first and last name, inactivity flag and billing and shipping addresses:

Database  userdb  LENGTH_EXCEPTION_DEFAULT  truncate_log
Database  userdb  DEFAULT_TYPE  varchar(255)

Database  userdb  COLUMN_DEF   "username=varchar(64) NOT NULL PRIMARY KEY"
Database  userdb  COLUMN_DEF   "password=varchar(64) NOT NULL"
Database  userdb  COLUMN_DEF   "accounts=text"
Database  userdb  COLUMN_DEF   "acl=text"
Database  userdb  COLUMN_DEF   "address1=varchar(64)"
Database  userdb  COLUMN_DEF   "address2=varchar(64)"
Database  userdb  COLUMN_DEF   "address3=varchar(64)"
Database  userdb  COLUMN_DEF   "address_book=text"
Database  userdb  COLUMN_DEF   "b_address1=varchar(64)"
Database  userdb  COLUMN_DEF   "b_address2=varchar(64)"
Database  userdb  COLUMN_DEF   "b_address3=varchar(64)"
Database  userdb  COLUMN_DEF   "b_city=varchar(30)"
Database  userdb  COLUMN_DEF   "b_company=varchar(64)"
Database  userdb  COLUMN_DEF   "b_country=varchar(10)"
Database  userdb  COLUMN_DEF   "b_fname=varchar(30)"
Database  userdb  COLUMN_DEF   "b_lname=varchar(30)"
Database  userdb  COLUMN_DEF   "b_nickname=text"
Database  userdb  COLUMN_DEF   "b_phone=varchar(30)"
Database  userdb  COLUMN_DEF   "b_state=varchar(10)"
Database  userdb  COLUMN_DEF   "b_zip=varchar(10)"
Database  userdb  COLUMN_DEF   "carts=text"
Database  userdb  COLUMN_DEF   "city=varchar(30)"
Database  userdb  COLUMN_DEF   "company=varchar(64)"
Database  userdb  COLUMN_DEF   "country=varchar(10)"
Database  userdb  COLUMN_DEF   "credit_limit=varchar(16)"
Database  userdb  COLUMN_DEF   "db_acl=text"
Database  userdb  COLUMN_DEF   "dealer=varchar(32)"
Database  userdb  COLUMN_DEF   "email=varchar(42)"
Database  userdb  COLUMN_DEF   "fax=varchar(30)"
Database  userdb  COLUMN_DEF   "file_acl=text"
Database  userdb  COLUMN_DEF   "fname=varchar(30)"
Database  userdb  COLUMN_DEF   "inactive=varchar(8)"
Database  userdb  COLUMN_DEF   "lname=varchar(30)"
Database  userdb  COLUMN_DEF   "mail_list=text"
Database  userdb  COLUMN_DEF   "mod_time=varchar(20)"
Database  userdb  COLUMN_DEF   "mv_shipmode=varchar(255)"
Database  userdb  COLUMN_DEF   "owner=varchar(20)"
Database  userdb  COLUMN_DEF   "p_nickname=text"
Database  userdb  COLUMN_DEF   "phone_day=varchar(30)"
Database  userdb  COLUMN_DEF   "phone_night=varchar(30)"
Database  userdb  COLUMN_DEF   "price_level=varchar(30)"
Database  userdb  COLUMN_DEF   "preferences=text"
Database  userdb  COLUMN_DEF   "s_nickname=text"
Database  userdb  COLUMN_DEF   "state=varchar(20)"
Database  userdb  COLUMN_DEF   "zip=varchar(10)"
Database  userdb  DEFAULT      "inactive=''"

The above is Interchange's database representation format that allows Interchange to be aware of the database structure and automagically create it if it's missing. See database glossary entry for complete information.

The above is PostgreSQL-compatible definition. We have the equivalent MySQL version available (in short, you only need to replace type =text with MySQL's =BLOB).

To make the new database table accessible to Interchange, and to define a couple more UserDB-specific options, you could add the following to your catalog.cfg:

# For SQL databases:
Database  userdb  userdb.txt   __SQLDSN__

# Or for file-based database (DBM):
Database  userdb  userdb.txt   TAB

# Encrypt passwords?
UserDB    default    crypt         0

# Ignore uppercase/lowercase in usernames?
UserDB    default    ignore_case   1

# Enable this in combination with the above, so that
# username is always 'normalized':
Filter    mv_username lc

# To disable field containing date of last change:
UserDB    default    time_field    none

# To enable field containing date of last change
#UserDB    default    time_field    mod_time

UserDB    default    logfile       var/log/userdb.log

# To allow people login using their email, and not their username
# (in that case, username does not have to be meaningful and
# can be automatically assigned, like "U00001"):
#UserDB    default    indirect_login  email

The login page could again be very simple, like this:

[set Login]
[userdb login]
[/set]

<form action="[process secure=1]" method="POST">
  <input type="hidden" name="mv_todo"  value="return">
  <input type="hidden" name="mv_nextpage" value="index">
  <input type="hidden" name="mv_click" value="Login">
  [form-session-id]

  <input name="mv_username" type="text">
  <input name="mv_password" type="password">
  <input value="Submit"   type="submit">
</form>

More complex login page with support for cookies and "remembering" users, and that displays a logout option if the user is already logged in could look like this:

[set Login]
  [userdb login]
[/set]

[set Logout_choice]
  [if type=explicit compare="[userdb function=logout clear='[cgi clear_values]']"]
    [set mv_no_count]1[/set]
    [set mv_no_session_id]1[/set]
    [if cgi clear_cart]
      [calc] @$Items = (); return; [/calc]
    [/if]
  [/if]
[/set]

[tmp cookie_username][read-cookie MV_USERNAME][/tmp]

<form action="[process secure=1]" method="POST">
  <input type="hidden" name="mv_todo"  value="return">
  <input type="hidden" name="mv_nextpage" value="index">
  [form-session-id]

  [if !session logged_in]
    <input type="hidden" name="mv_click" value="Login">

    <input name="mv_username" type="text">
    <input name="mv_password" type="password">

    [if config CookieLogin]
    <input type="hidden" name="mv_cookie_password" value="0">
    <input type="checkbox" name="mv_cookie_password" value="1" [if scratch cookie_username]CHECKED[/if]>
    [/if]

  [else]
    <input type="hidden" name="mv_click" value="Logout_choice">

    Logged in as [data session username].

    <input class="input" type="hidden" name="clear_values" value="1">
    <input class="input" type="checkbox" name="clear_values" checked value="1"> Erase values.

  [/else]
  [/if]

  <input type="submit" value="Submit">
</form>

When the user logs in, user database values are automatically copied to their values space and can be retrieved at any time using the value tag. (Values which are not present in the database might take on a default value defined with ValuesDefault).

Often times, you would like to save users' data back to the user database, be it during or at the end of user session. You can automatically do this with a combination of form processing directives, but if you want to do it manually, use the following simple yet powerful code:

[update values]
[userdb save]

The above code saves all users' values back to the database. Values which do not have a corresponding database field are ignored (as there's no place to save them). This is a fault-tolerant behavior and something you almost always want to happen anyway.

For all advanced examples and more technical discussion, see userdb tag documentation.