, except the prompt occurs after the catalog files
are copied and macro substitution is performed on all files.
There may also be SubCatalog directives:
SubCatalog easy simple /home/catalogs/simple /cgi-bin/easy
easy
The name of the subcatalog, which also controls the name of the
subcatalog configuration file. In this case, it is easy.cfg.
simple
The name of the base configuration that will be the basis for the
catalog. Parameters in the easy.cfg file that are different will
override those in the catalog.cfg file for the base
configuration.
The remaining parameters are similar to the Catalog directive.
Additional interchange.cfg parameters set up administrative parameters
that are catalog wide. See the server configuration file for details
on each of these.
Each catalog can be completely independent with different databases,
or catalogs can share pages, databases, and session files. This means
that several catalogs can share the same information, allowing
"virtual malls."
27.2. Manual Installation of Catalogs
-------------------------------------
An Interchange installation is complex, and requires quite a few
distinct steps. Normally you will want to use the interactive catalog
builder, makecat, described above. It makes the process much easier.
Please see the iccattut document for a full tutorial on building a
catalog by hand.
28. Link Programs
=================
Interchange requires a web server that is already installed on a
system. It does have an internal server which can be used for
administration, testing, and maintenance, but this will not be useful
or desirable in a production environment.
As detailed previously, Interchange is always running in the
background as a daemon, or resident program. It monitors either a
UNIX-domain file-based socket or a series of INET-domain sockets. The
small CGI link program, called in the demo simple, is run to connect
to one of those sockets and provide the link to a browser.
Note: Since Apache is the most popular web server, these instructions
will focus on it. If using another type of web server, some
translation of terms may be necessary.
A ScriptAlias or other CGI execution capability is needed to use the
link program. (The default ScriptAlias for many web servers is
/cgi-bin.) If ExecCGI is set for all directories, then any program
ending in a particular file suffix (usually .cgi) will be seen as a
CGI program.
Interchange, by convention, names the link program the same name as
the catalog ID, though this is not required. In the distribution demo,
this would yield a program name or SCRIPT_PATH of /cgi-bin/simple or
/simple.cgi. This SCRIPT_PATH can be used to determine which
Interchange catalog will be used when the link program is accessed.
28.1. UNIX-Domain Sockets
-------------------------
This is a socket which is not reachable from the Internet directly,
but which must come from a request on the server. The link program
vlink is the provided facility for such communication with
Interchange. This is the most secure way to run a catalog, for there
is no way for systems on the Internet to interact with Interchange
except through its link program.
The most important issue with UNIX-domain sockets on Interchange is
the permissions with which the CGI program and the Interchange server
run. To improve security, Interchange normally runs with the socket
file having 0600 permissions (rw-------), which mandates that the CGI
program and the server run as the same user ID. This means that the
vlink program must be SUID to the same user ID as the server executes
under. (Or that CGIWRAP is used on a single catalog system).
With Interchange's multiple catalog capability, the permissions
situation gets a bit tricky. Interchange comes with a program,
makecat, which configures catalogs for a multiple catalog system. It
should properly set up ownership and permissions for multiple users if
run as the superuser.
28.2. INET-Domain Sockets
-------------------------
These are sockets which 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 the request comes from one
of a limited number of systems, defined in the global TcpHost
directive. (This check is not made for the internal HTTP server.)
28.3. Internal HTTP Server
--------------------------
If the socket is contacted directly (only for INET-domain sockets),
Interchange will perform the HTTP server function itself, talking
directly to the browser. It can monitor any number of ports and map
them to a particular catalog. By default, it only maps the special
catalog mv_admin, which performs administrative functions. The default
port is 7786, which is the default compiled into the distribution
tlink program. This port can be changed via the TcpMap directive.
To prevent catalogs that do not wish access to be made in this way
from being served from the internal server, Interchange has a fixed
SCRIPT_PATH of /catalogname (/simple for the distribution demo) which
needs to be placed as an alias in the Catalog directive to enable
access. See TcpMap for more details.
28.4. Setting Up VLINK and TLINK
--------------------------------
The vlink and tlink programs, compiled from vlink.c and tlink.c, are
small C programs which contact and interface to a running Interchange
daemon. The VLINK executable is normally made setuid to the user
account which runs Interchange, so that the UNIX-domain socket file
can be set to secure permissions (user read-write only). It is
normally not necessary for the user to do anything. They 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. The following defines in the
produced config.h should be set:
LINK_FILE
Set this to the name of the socket file that will be used for
configuration, usually "/usr/local/lib/interchange/etc/socket" or
the "etc/socket" under the directory chosen for the VendRoot.
LINK_HOST
Set this to the IP number of the host which should be contacted.
The default of 127.0.0.1 (the local machine) is probably best for
many installations.
LINK_PORT
Set this to the TCP port number that the Interchange server will
monitor. The default is 7786 (the decimal ASCII codes for 'M' and
'V') and does not normally need to be changed.
LINK_TIMEOUT
Set this to the number of seconds vlink or tlink should wait
before announcing that the Interchange server is not running. The
default of 45 is probably a reasonable value.
28.5. Compiling VLINK and TLINK
-------------------------------
There is a compile_link program which will assist with this. Do:
perldoc VENDROOT/bin/compile_link
for its documentation.
28.6. Manually Compiling VLINK and TLINK
----------------------------------------
Change directories to the src directory, then run the GNU configure
script:
cd src
./configure
There will be some output displayed as the configure script checks the
system. Then, compile the programs:
perl compile.pl
To compile manually:
cc vlink.c -o vlink
cc tlink.c -o tlink
On manual compiles, ensure that the C compiler will be invoked
properly with this little ditty:
perl -e 'do "syscfg"; system("$CC $LIBS $CFLAGS $DEFS -o tlink tlink.c");'
perl -e 'do "syscfg"; system("$CC $LIBS $CFLAGS $DEFS -o vlink vlink.c");'
On some systems, the executable can be made smaller with the strip
program, if available. It is not required.
strip vlink
strip tlink
If Interchange is to run under a different user account than the
individual configuring the program, make that user the owner of vlink.
Do not make vlink 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)).
chown interchange vlink
Move the vlink executable to the cgi-bin directory:
mv vlink /the/cgi-bin/directory
Make vlink SETUID:
chmod u+s /the/cgi-bin/directory/vlink
Most systems unset the SUID bit when moving the file, so change it
after moving.
The SCRIPT_NAME, as produced by the HTTP server, must match the name
of the program. (As usual, let the makecat program do the work.)
28.7. VLINK or TLINK Compile Problems
-------------------------------------
The latest version of vlink.c and tlink.c have been compiled on the
following systems:
AIX 4.1
BSD2.0 (Pentium/x86)
Debian GNU/Linux
Digital Unix (OSF/Alpha)
FreeBSD 2.x, 3.x, 4.x
IRIX 5.3, IRIX 6.1
OpenBSD 2.7
Red Hat Linux 6.2, 7.0, 7.1, 7.2, 7.3, 8.0
SCO OpenServer 5.x
Solaris 2.x (Sun compiler and GCC)
Solaris 7 (Sun compiler and GCC)
SunOS 4.1.4
Some problems may occur. In general, ignore warnings about pointers.
Make sure that you have run the configure program in the src
directory. If you use Interchange's makecat program, it will try to
compile an appropriate link at that time, and will substitute tlink.pl
if that doesn't work.
You can compile manually with the proper settings with this series of
commands:
cd src
./configure
perl -e 'do "syscfg"; system ("$CC $CFLAGS $DEFS $LIBS -o tlink tlink.c")'
perl -e 'do "syscfg"; system ("$CC $CFLAGS $DEFS $LIBS -o vlink vlink.c")'
There is also a compile_link program which has documentation embedded
and which will compile an appropriate link. If you cannot compile, try
using the tlink.pl script, written in Perl instead of C, which should
work on most any system. Since vlink needs to have values set before
compilation, a pre-compiled version will not work unless it has the
exact values you need on your system. If you can use the defaults of
'localhost' and port 7786, you may be in luck.
29. Installing Perl Modules without Root Access
===============================================
Installing Interchange without root access is no problem. However,
installing Perl modules without root access is a little trickier.
You must build your makefile to work in your home dir. Something like:
PREFIX=~/usr/local \
INSTALLPRIVLIB=~/usr/local/lib/perl5 \
INSTALLSCRIPT=~/usr/local/bin \
INSTALLSITELIB=~/usr/local/lib/perl5/site_perl \
INSTALLBIN=~/usr/local/bin \
INSTALLMAN1DIR=~/usr/local/lib/perl5/man \
INSTALLMAN3DIR=~/usr/local/lib/perl5/man/man3
Put this in a file, say 'installopts', and use it for the Makefile.PL.
perl Makefile.PL `cat installopts`
Then, forget ./config. Just do:
make
make test
make install
Some of the tests may fail, but that's probably ok.
Also make sure to install Bundle::Interchange, which will need the
same config data as you put into 'installopts'.
30. Installation Troubleshooting
================================
Interchange uses the services of other complex programs, such as Perl,
Web servers, and relational databases, to work. Therefore, when there
is a problem, check these programs before checking Interchange. Many
more basic installation problems have to do with those than with
Interchange itself.
If an error message is received about not being able to find
libraries, or a core dump has occurred, or a segment fault message, it
is always an improperly built or configured Perl. Contact the system
administrator or install a new Perl.
The makecat program is intended to be used to create the starting
point for the catalog. If the demo does not work the first time, keep
trying. If it still does not work, try running in INET mode.
Check the two error log files: error.log in the Interchange home
directory (where interchange.cfg resides) and error.log in the catalog
directory (where catalog.cfg resides; there can be many of these).
Many problems can be diagnosed quickly if these error logs are
consulted.
Check the README file, the FAQ, and mail list archive at the official
Interchange web site for information:
http://www.icdevgroup.org/
Double check the following items:
1. Using UNIX sockets?
o Check that the vlink program is SUID, or the appropriate
changes have been made in the SocketPerms directive. Unless
the files are world-writable, the vlink program and the
Interchange server must run as the same user ID! If running
CGI-WRAP or SUEXEC, the vlink program must not be SUID.
o If having trouble with the vlink program (named construct in
the demo configuration), try re-running makecat and using
INET mode instead. (Or copy the tlink INET mode link program
over vlink). This should work unchanged for many systems.
o If using an ISP or have a non-standard network
configuration, some changes to interchange.cfg are
necessary. For tlink to work, the proper host name(s) must
be configured into the TcpHost directive in interchange.cfg.
The program selects port 7786 by default (the ASCII codes
for "M" and "V", for MiniVend). If another port is used, it
must be set to the same number in both the tlink program (by
running compile_link) and the interchange.cfg file. The
tlink program does not need to be SUID.
2. Proper file permissions?
o The Interchange server should not run as the user nobody!
The program files can be owned by anyone, but any databases,
ASCII database source files, error logs, and the directory
that holds them must be writable by the proper user ID, that
is the one that is executing the Interchange program.
o The best way to operate in multi-user, multiple catalog
setups is to create a special interch user, then put that
user in the group that contains each catalog user. If a
group is defined for each individual user, this provides the
best security. All associated files can be in 660 or 770
mode. There should be no problems with permissions and no
problems with security.
3. Is the vlink program being executed on a machine that has the
socket file etc/socket on a directly attached disk?
o UNIX-domain sockets will not work on NFS-mounted file
systems! This means that the Interchange server and the CGI
program vlink must be executing on the same machine.
o The tlink program does not have this problem, but it must
have the proper host name(s) and TCP ports set in the
TcpHost and TcpMap directives in interchange.cfg. Also, be
careful of security if sensitive information, like customer
credit card numbers, is being placed on a network wire.
31. Usertracking
================
Several actions from the user are recorded by Interchange's
usertracking facility. The usertracking data is logged at two
locations, depending on your setup.
The first location is the one specified by the TrackFile configuration
directive, e.g. logs/usertrack in the foundation demo.
The second location are the HTTP headers. You can configure Apache to
write this header into the access logs.
LogFormat "%h %l %u %t \"%r\" %>s %b \"%{Referer}i\" \"%{User-Agent}i\" \
%T %v \"%{X-Track}o\"" track
CustomLog /var/log/apache/access.log track
______________________________________________________________________
Copyright 2002-2004 Interchange Development Group. Copyright 2001-2002
Red Hat, Inc. Freely redistributable under terms of the GNU General
Public License. line:
Catalog-Building Tutorial
=========================
32. Purpose
===========
The purpose of this document is to guide you through constructing a
simple Interchange catalog from scratch. The demo catalog that ships
with Interchange is quite complex since it highlights some of the many
capabilities that Interchange offers. As a template for your own
catalog, the demo can be an intimidating place to start if your
purpose is to learn.
The simple catalog you create using this tutorial should give you a
feel for the basic Interchange system. It should also be considered a
stepping stone to a more complete and functional e-commerce system
built with Interchange. The tutorial relies as much as possible on
default settings to accentuate how Interchange works. It will use as
few of Interchange's capabilities as possible, while still building a
usable store. The resulting site will be simple but usable. The value
of this tutorial is in the instruction that occurs along the way.
It is recommended that you create the files used in this tutorial
yourself. You will learn more by creating the directory structure and
using your favorite text editor to create files in the proper places
on your own system as they are discussed.
33. Before you begin
====================
This section explains the initial set up tasks that must be completed
before you can begin building your simple e-commerce site.
33.1. Install Interchange and the demo catalog
----------------------------------------------
The easiest way to get Interchange and the demo set up is through an
RPM install on the Red Hat Linux or Linux Mandrake operating systems.
You can also get Interchange by unpacking an Interchange tarball or
checking out a copy of the CVS repository and doing a manual
installation. These installations can be done either as a regular user
or as root, installing for a special Interchange user.
You must also know what type of installation you ran so you know where
to place the various files created. Before proceeding, verify that
Interchange is properly installed. Also, keep in mind which type of
installation you did:
o RPM (RPM Package Manager) install
o Manual install as root
o Manual install as regular user
Note: After installation, makecat should be run to build your catalog.
For information on installing Interchange and building your catalog
using makecat, see the Interchange Getting Started Guide. Do not to
continue with this tutorial without a working demo catalog.
Installing the demo catalog set up the Interchange global
configuration file interchange.cfg, which resides in the Interchange
software directory. Also, it compiled the link program for your
specific server and placed the executable program in your cgi-bin
directory. This is necessary for your catalog to run properly.
33.2. The Interchange operating system user
-------------------------------------------
If Interchange was installed as a regular user, that will be the user
Interchange runs as. If Interchange was installed as root or from an
RPM, you need to know the name of the separate Interchange user. The
Interchange daemon will not run as root, and should not run as the web
server user (usually 'apache', 'www', 'httpd', or 'nobody'). If
Interchange was installed from the RPM, or with the default source
installation settings, the username is interch. If you selected a
different user name, you will need to know what it is.
33.3. Important directories
---------------------------
In order to complete this tutorial you will need to know the location
of each of the following directories and have write permissions on
them:
o Interchange software directory
o RPM install: /usr/lib/interchange
o Manual install as root: /usr/local/interchange
o Manual install as regular user: /home/username/interchange
o Catalogs directory
o RPM install: /var/lib/interchange
o Manual install as root: /usr/local/interchange/catalogs
o Manual install as regular user: /home/username/catalogs
o cgi-bin directory
o RPM install or source install as root: /var/www/cgi-bin
o Manual install as root (locally installed web server):
/usr/local/htdocs, /opt/www, ...
o Manual install as regular user: /home/username/public_html
(with .cgi extension)
Note: The installation of Interchange is very flexible and the file
locations on your system may vary, depending on how your system was
set up. It is recommended that you not proceed until you are sure you
have this information and the necessary permissions to write to these
directories.
33.4. Your catalog URL
----------------------
Finally, you need to know the URL to access your store from a web
browser. Again, this can vary depending on how your web server has
been set up. But, assuming a common setup of the Apache web server,
your URL should be one of the following:
o Root or RPM install: http://localhost/cgi-bin/tutorial/pagename
o Manual install as user:
http://localhost/~username/tutorial.cgi/pagename
If you aren't running your web browser on the server where Interchange
is running, you need to substitute your server's host name (for
example: machine.domain.com for localhost) where mentioned.
Note: It is recommended that you use the real machine name instead of
localhost. The standard for cookies specifies that they can only be
set when a domain name has at least two dots in it. If you use
localhost, you will lose session information if you leave catalog,
since the session ID is passed only as part of the URL.
33.5. Starting or restarting Interchange
----------------------------------------
When you make changes to the configuration files you need to restart
the Interchange server. How this is done depends on how you installed
Interchange:
o RPM install as root: /usr/sbin/interchange -r
o Manual install as Interchange user:
/usr/local/interchange/bin/interchange -r
o Manual install as root: su interch -c
'/usr/local/interchange/bin/interchange -r'
o Manual install as regular user: ~/interchange/bin/interchange -r
Find the right command for your system and remember it, since you will
need to restart Interchange a few times during the tutorial.
33.6. Tutorial assumptions
--------------------------
Because it is impossible to cover all scenarios, this tutorial assumes
that you installed Interchange on Red Hat Linux from the RPM packages.
This creates the following settings:
o Interchange software directory: /usr/lib/interchange
o Catalogs directory: /var/lib/interchange
o cgi-bin directory: /var/www/cgi-bin
o Interchange user: interch
o Demo catalog name: foundation
o Demo catalog URL base: http://localhost/cgi-bin/foundation
o Tutorial catalog name: tutorial
o Tutorial catalog URL base: http://localhost/cgi-bin/tutorial
o Tutorial catalog directory: /var/lib/interchange/tutorial
If you did not install with these settings, substitute the correct
values for your system when these settings are mentioned in the
tutorial.
34. Building Your Catalog
=========================
This section describes the pages and directories that need to be
established to create a properly functioning catalog.
34.1. Create the link program
-----------------------------
You need to make a copy of the demo link program in your cgi-bin
directory and name it tutorial.
The demo link program has the same name as your demo catalog, usually
foundation. The link program links the Interchange daemon with your
web server. Make sure that it has the same owner and file permissions
as the one you copied from. The set-UID bit is especially (unless you
installed as a regular user). Normally you will need to be root to
have write permissions in the cgi-bin directory.
Type this command as root while in your cgi-bin directory:
cp -p foundation tutorial
If everything is working correctly, typing ls -l should describe your
files roughly like this:
-rwsr-xr-x 1 interch interch 7708 Dec 16 22:47 foundation
-rwsr-xr-x 1 interch interch 7708 Dec 16 22:47 tutorial
34.2. Create the tutorial catalog directory
-------------------------------------------
As root, create a subdirectory named tutorial under your catalogs
directory (probably /var/lib/interchange/). This is where all of the
catalog-specific files will go. It needs to be readable, writable, and
executable by the Interchange user. This will be referred to as your
catalog directory. Type the following while in the catalogs directory
to create the tutorial subdirectory:
mkdir tutorial
chown interch.interch tutorial
chmod 770 tutorial
34.3. Become the Interchange user
---------------------------------
You should be able to do everything you need to do as the 'interch'
user for the rest of this tutorial. So you can switch to that user now
(su - interch). If you installed Interchange from the RPM, the user
interch probably doesn't have a password. You'll have to set it with a
command such as passwd interch while root.
34.4. Go to the tutorial catalog directory
------------------------------------------
Change to the catalog directory with the 'cd' command. For the rest of
this tutorial, all file locations will be given relative to the
tutorial catalog directory. For example, pages/ord/basket.html would
actually be /var/lib/interchange/tutorial/pages/ord/basket.html or the
equivalent on your system. The only exception is interchange.cfg,
which is in the Interchange software directory.
Note: To improve clarity, we will append a trailing slash to directory
names to clearly distinguish them from file names. (Similar to the
output of the ls command with the -F option.)
34.5. Create the session directory
----------------------------------
You need to create the session directory where Interchange saves
information on each visitor's browsing session. If you do not have
this directory, your catalog will not work. This directory is called
session/ and goes under your catalog directory. Type mkdir session to
create this directory.
35. Configuration files
=======================
Interchange configuration is controlled by a number of directives,
which are specified in two files. Global configuration directives go
in interchange.cfg in the Interchange software directory.
Catalog-specific configuration directives go in catalog.cfg in the
catalog directory.
A complete directive consists of the directive name followed by
whitespace-separated parameters. Any number of spaces or tabs can be
between the directive and its options, but the directive and its
options must be on the same line. The directive is case-insensitive,
but it is recommended that you use it consistently for readability.
You can insert blank lines or comment lines (lines where the first
non-blank character is '#') throughout the configuration files to
improve readability. The order the lines appear in is significant, but
unimportant for the simple catalog you are creating.
For the next part, access your text editor (for example, vi, emacs,
pico, joe, gedit, or nedit) to start editing some files.
35.1. interchange.cfg
---------------------
The first directive we need to use is a global directive that tells
Interchange where the new catalog is, called Catalog. The Catalog
directive has the following format:
Catalog name catalog_base_directory link_url_path
Open interchange.cfg in the Interchange software directory. Go near
the top of the file, right below the other Catalog directives, and add
this line:
Catalog tutorial /var/lib/interchange/tutorial /cgi-bin/tutorial
Save the file.
35.2. catalog.cfg
-----------------
For the rest of the tutorial, most of the files mentioned do not exist
yet. You will create them yourself with initial text we give.
You need to create a catalog.cfg file for your tutorial store (in the
tutorial catalog directory). We'll start with a very simple products
database table with a few fields and a few products.
The Database directive describes a database table to the Interchange
system in this format:
Database name filename format
Interchange has several database options available. We will use the
simplest, which is the built-in default (specifically, some variant of
DBM). The default location for filename is in a subdirectory called
products under the catalog directory. Interchange recognizes a number
of file formats. We will use a tab-delimited text file. Enter the
following into catalog.cfg:
Database products products.txt TAB
This tells Interchange that you have a database table named 'products'
that is described in a tab-delimited file named products.txt. You can
describe an unlimited number of arbitrary database tables for the
system to use this way. Interchange keeps a list of default tables
called "Product Files," reflecting its e-commerce roots. You can
specify all of the database tables that contain products by using the
ProductFiles directive. There is no default for this, so you will have
to specify your products table's name by adding the following line to
catalog.cfg:
ProductFiles products
There are a few other directives that Interchange expects to see in
order to complete the minimum configuration. They are VendURL,
SecureURL, and MailOrderTo. They are, respectively, your catalog's
base URL, its secure URL, and the e-mail address to mail order notices
to. Add the following lines to catalog.cfg to establish these
directives:
VendURL http://localhost/cgi-bin/tutorial
SecureURL http://localhost/cgi-bin/tutorial
MailOrderTo your@email.address
The catalog.cfg file should look like this when you save it:
Database products products.txt TAB
ProductFiles products
VendURL http://localhost/cgi-bin/tutorial
SecureURL http://localhost/cgi-bin/tutorial
MailOrderTo your@email.address
36. The products database table
===============================
36.1. products/products.txt
---------------------------
Create the products/ directory in your tutorial catalog directory.
The products/products.txt file will serve two purposes. It will
provide Interchange with the layout of the products database table and
it will also provide the data. When Interchange parses the
products.txt file, it will expect the first line to contain the names
of the fields for the database table (for example, sku, description,
price). The first field in the list is expected to be a primary key
(unique identifier) for that row. In most cases you are going to use
the SKU (stock keeping unit) as the unique identifier for each
product.
The product database is handled as a special case since Interchange
expects at least the description, price, and product ID (sku) fields.
In other words, the products.txt file must at least contain fields
named sku, price, and description. You can have other fields too, if
you wish.
The simple store that we are going to build will sell tests. You can
choose another sample product line, but it is recommended that you
keep it simple. Create the file products/products.txt to look like
this, with a single tab separating each field:
sku description price
4595 Nice Bio Test 275.45
2623 Stack of Econ Quizzes 1.24
0198 Really Hard Physics Test 1589.34
1299 Ubiquitous diff eq final 37.00
Note: When using tab-delimited files as we are, make sure you have
exactly one tab between each field. Some text editors will use spaces
to simulate tabs. Interchange expects actual ASCII tab characters;
extra spaces or other characters will corrupt your data.
You may notice that the columns don't line up in your text editor.
This is the nature of tab-delimited files. Do not try to fix these.
37. Page templates
==================
Since most sites have certain aspects of the site that remain the same
as the content of the pages changes, we are going to create a template
that we can use for all pages. We'll divide the page into four
sections:
_____________________
| |
| top |
| |
|---------------------|
| | |
| | |
| left | main |
| | |
| | |
|---------------------|
| |
| bottom |
|_____________________|
The "main" section holds the content that is different for each page.
The "top" section is for headers, banners, menus, and so on. The
"left" section can be used as a sidebar or navigation bar, and the
"bottom" section can contain the copyright and contact info. The top,
left, and bottom sections will remain constant throughout the site.
Making a change to information in one of these sections will make that
change to all pages in your site.
Now type the HTML for each template section in an individual plain
text file in the catalog directory, named 'top', 'left', and 'bottom',
respectively using the code displayed below. No '.html' suffixes are
used on these because they are not meant to be parsed directly by
Interchange as full pages.
37.1. top
---------
The Interchange Test Catalog
The Interchange Test Catalog |
37.2. left
----------
(left) |
37.3. bottom
------------
|
(bottom) |
37.4. The Interchange Tag Language
----------------------------------
Now we need a way to pull the template pieces we just created into the
proper places to make a complete page. This is done using ITL, the
Interchange Tag Language.
ITL is at the heart of almost all Interchange catalog pages. It's how
you use Interchange's functionality. The ITL tags appear between
square brackets like [this]. Options appear after the tag, separated
by whitespace, like this: [tag option1 option2] and this: [tag
option1=value1 option2=value2]. They can span multiple lines. (That
can help readability when the tag has many options.) There are many
ITL tags, and for this tutorial very few will be addressed. For a
complete listing of the ITL tags, see the Interchange Tag Reference
Guide.
Your first tag will be [include], which reads the file mentioned
(relative to the catalog directory), parses any Interchange tags, and
puts the result in place of the tag. This is demonstrated on the next
page you need to create.
38. Creating a welcome page
===========================
38.1. pages/index.html
----------------------
Create a directory called pages/ in your tutorial catalog directory.
Type the following text and save it as pages/index.html. This will
create a page to test that everything works so far.
[include top]
[include left]
This is where your content goes.
[include bottom]
Restart Interchange so your changes take effect. Go to your web
browser and load the page. The URL should be similar to the following:
http://localhost/cgi-bin/tutorial/index.html.
Note: Interchange pages in the pages/ or other directories must have
the .html suffix on them. You can drop the suffix in your URL and in
other places, such as the [page] tag you'll learn about later, but the
file name on disk must have the suffix.
39. Troubleshooting
===================
Your first Interchange page should have displayed as described in your
browser. If it didn't, you need to figure out what went wrong. Most of
the time, overlooked details are the problem. Double-checking your
typing is a good habit to get into.
The following is a troubleshooting checklist to use when you run into
problems:
1. Have you created directories with the proper names in the proper
locations? (See Appendix A for a full directory and file
structure of the tutorial catalog.)
2. Have you misspelled any file names or put them in the wrong
directories? Are the files and parent directories readable by the
interch user? Double-check with the ls command.
3. Did you type letters in the proper case? Remember that both Unix
and Interchange are case-sensitive, and for the most part you may
not switch upper- and lower-case letters.
4. Did you type all punctuation, ITL tags, and HTML tags correctly?
5. Did you use whitespace correctly in the cases where it mattered?
Remember to use tabs when tabs are called for (in lists and
database text files).
6. Did you restart Interchange if you changed anything in
interchange.cfg or catalog.cfg, or if you're in a high-traffic
mode?
7. Check your catalog error log, error.log in your tutorial catalog
directory, to see if Interchange reported any errors.
8. Check the Interchange server error log, error.log in the
Interchange software directory, to see if it had problems loading
the catalog at all.
9. View the HTML source of any catalog pages that are loading
incorrectly to check for a coding error. The problem may reveal
itself when you see what HTML the browser is getting.
40. Displaying products
=======================
40.1. Listing all products
--------------------------
Now that your store is running, you need to display your products on
the welcome page. We will loop over all of the products in our
database and produce an entry for each one in a table. Replace the
line "This is where your content goes" in pages/index.html with the
following:
Test # |
Description |
Price |
. . .
Now we will use Interchange tags to fill in the rest of the table from
the products database you created. The [loop] [/loop] ITL tag pair
tells Interchange to iterate over each item in the parameter list. In
this case, the loop is over the result of an Interchange search. The
search parameter does a database search on the provided parameters. In
this case, we're doing a very simple search that returns all of the
fields for all of the entries in the products database. The parameters
passed to the search tell Interchange to return all ('ra') on the file
('fi') products respectively. The following should take the place of
the ellipsis in the code you placed in index.html:
[loop search="ra=yes/fi=products"]
. . .
[/loop]
In the loop we just established, the individual elements of the entry
using the [loop-field] tag. The following code should replace the
above ellipsis in the code we placed in pages/index.html:
[loop-code] |
[loop-field description] |
[loop-field price] |
The [loop-code] tag refers to the primary key (unique identifier) for
the current row of the database table in question. In this case, it
will produce the same output as the [loop-field sku] tag, because the
'sku' field is the primary key for products table. In each case the
tag is replaced by the appropriate element. When put together,
Interchange generates a page with your products table on it.
Your finished page should look like this:
[include top]
[include left]
Test # |
Description |
Price |
[loop search="ra=yes/fi=products"]
[loop-code] |
[loop-field description] |
[loop-field price] |
[/loop]
[include bottom]
Test this page by refreshing the index.html page in your browser.
40.2. pages/flypage.html
------------------------
The next step is to create an individual page for each item. To do
this, you need to create a special generic page called
pages/flypage.html. When a page is requested that does not exist in
the pages/ directory, Interchange will check and see if the requested
page has the same name as a product ID from the product database table
(in this case a SKU). If it does, it will show the flypage for that
product. If there's no product with that ID, the special error page
special_pages/missing.html (described in the next section) will be
displayed.
For example, if the page 0198.html was requested, Interchange first
checks for a page with that name. If one is not found, it searches the
products database table for a product with that ID. Interchange then
creates a product page "on the fly" using pages/flypage.html. When
constructing the flypage, the entire product record for the requested
product is available through the [item-field] tag (similar to the
[loop-field] tag). To create a fly page, type the following code and
save it as pages/flypage.html.
[include top]
[include left]
Test #[item-code]
[item-field description] . . . [item-field price]
[include bottom]
Then, to provide links to the product flypages from your home page,
modify pages/index.html slightly, so that:
[loop-field description] |
becomes:
[loop-field description] |
40.3. special_pages/missing.html
--------------------------------
Create the special_pages/ directory in your tutorial catalog directory
(not in the pages/ directory).
As mentioned, it is a good idea to display an error page when
Interchange is asked for an unknown page. To create a missing page for
display, type the following and save it as special_pages/missing.html.
[include top]
[include left]
We're sorry, the page you requested has not been found.
Try finding what you need on the [page index]welcome page.
[include bottom]
The addition of this page ensures that users see your error message
instead of a mysterious server error if they mistype a URL.
41. The shopping basket
=======================
41.1. A link for ordering
-------------------------
Now that you have your products available, let's add a shopping cart
so customers can purchase them. This is created using the [order] tag.
These tags create an HTML link that causes the specified item to be
ordered and transfers the shopper to the basket page. This is a
built-in shortcut to the complete order process which uses an HTML
form submission process. The parameter for the [order] tag is the
product ID. To add these tags to the catalog, make the following
change to pages/index.html:
[loop-code] |
[loop-field description] |
[loop-field price] |
+ [order [loop-code]]Order Now |
[/loop]
Note: The line you need to add is marked by a '+'. However, do not
include the '+' when adding this line. The surrounding lines are shown
to give you context. This style is called a "context diff" and is used
often in this tutorial.
41.2. pages/ord/basket.html
---------------------------
Create the directory pages/ord/ in the tutorial catalog directory. In
other words, ord/ should be inside the pages/ directory.
For the [order] tag, Interchange expects a default page called
pages/ord/basket.html. This page displays the contents of the shopping
basket and contains other shopping basket functionality.
The Foundation store has a full-featured shopping basket available for
use, but this tutorial teaches you to build your own simple one. The
shopping basket items can be accessed using a set of tags that have an
[item] prefix. Put the following code in the new file
pages/ord/basket.html. The section that follows explains the tags
used.
[include top]
[include left]
This is your shopping cart!
Qty. |
Description |
Cost |
Subtotal |
[item-list]
[item-quantity] |
[item-field description] |
[item-price] |
[item-subtotal] |
[/item-list]
|
Total: |
[subtotal] |
[page checkout]Purchase now
[page index]Return to shopping
[include bottom]
The basket items can be accessed one at a time by using the
[item-list] tag. So we will create a table by iterating through the
basket items. The text within the [item-list] [/item-list] tags is
created for each item in the list.
o [item-quantity] shows the quantity of the item ordered. If the
same item is ordered multiple times, the quantity increases.
o [item-field description] shows the description from the product
database table. Any field that is not special to Interchange can
be accessed from the shopping cart this way.
o [item-price] shows the per-item price that is defined in the
product database table.
o [item-subtotal] shows the total cost of this order line. This is
normally the price multiplied by the quantity, but it can also
take into account other considerations, such as various kinds of
price discounts.
o [subtotal] shows the calculated shopping basket subtotal.
o [page index] creates the starting HTML for a link
to the catalog welcome page.
You also need to put a link in the index page so that shoppers can go
to their shopping cart without ordering something. Modify the end of
pages/index.html by adding the following lines.
+
+ [page order]View shopping cart
[include bottom]
Refresh the page and test the shopping basket in your browser.
42. Order checkout
==================
42.1. pages/checkout.html
-------------------------
The site can now be completed by adding the ability to check out with
the shopping cart and finalize the order. To do this the customer
needs to provide a shipping address (which, for the sake of this
tutorial, we will assume is the same as the billing address), and
payment information. We will process the order by verifying the
customer's payment information and sending an email to the merchant
(ourselves) detailing the order.
First you need to create a checkout page. The checkout page consists
of a form that receives order information from the customer and
performs a simple credit card number check. In this tutorial we will
use a built-in test that only checks to see if a given credit card
number could be valid. If the information is acceptable the customer
will move to the next phase of the order process. If it is not, an
error page will be displayed.
To create a checkout page, type the following code and save it as
pages/checkout.html. The section that follows explains the code.
[include top]
[include left]
Checkout Page
[page index]Return to shopping instead
[include bottom]
The HTML form begins with a method of 'post' (which sends the form
data as its own stream, as opposed to the 'get' method which encodes
the data as part of the URL). The [process] tag creates a special URL
for form processing. Interchange has a built-in form processor that is
configured by submitting certain fields in the form. The Finalize
button will invoke this form processor and link the user to the
special_pages/receipt.html page, which is described later.
You are submitting some hidden form values that will tell Interchange
how to process this form. The first value, mv_todo was set as submit.
This causes the form to be submitted for validation. The second value,
mv_order_profile was set as order_profile. This determines the
validation process for the form. It is explained further in the next
section.
The last value, mv_cyber_mode, was set to be minivend_test. The
mv_cyber_mode value determines what method will be used to charge a
credit card. The value of minivend_test uses the internal test method,
which calculates a simple checksum against the card to determine if it
is a valid number.
When preparing an order for processing, Interchange looks for certain
named fields in the form values for name, address, and credit card
information. We are using all expected field names in this form so
that no translation needs to take place.
View the checkout page in your browser. The "Finalize!" link has not
been enabled, but the page should display properly.
42.2. etc/profiles.order
------------------------
Create the etc/ directory in the tutorial catalog directory now.
You need to set up verification for the order form by defining an
order profile for the form. An order profile determines what fields
are necessary for the form to be accepted. Create an order profile
verification page by typing the following and saving it as
etc/profiles.order. The section that follows explains the code used.
__NAME__ order_profile
fname=required
lname=required
address1=required
city=required
state=required
zip=required
&fatal=yes
&final=yes
__END__
A single file can contain multiple profile definitions. First the
profile is named using the __NAME__ pragma. (This is unrelated to the
__VARIABLE__ syntax seen elsewhere in Interchange.) Then in the
profile there is a list of the form fields that are required. The
&fatal setting indicates that validation will fail if any of the
requirements are not met. &final indicates that this form will
complete the ordering process. This setting is helpful if you have a
multi-page ordering process and you want to validate each page
individually. The __END__ pragma signals the end of this profile,
after which you can begin another one.
In order to activate your order profile, add the following
OrderProfile directive to the end of catalog.cfg:
OrderProfile etc/profiles.order
Watch for white space in front of the __NAME__ pragma, it can cause
your profile to be ignored. Rember to restart Interchange for any
changes to take effect.
42.3. special_pages/needfield.html
----------------------------------
If the submitted form lacks a required field, Interchange will display
an error page. The default location is special_pages/needfield.html.
To create this page, type the following text and save it as
special_pages/needfield.html.
[include top]
[include left]
The following information was not given:
[error all=1 show_var=1 show_error=1 joiner='
']
Please go back to the [page checkout]checkout page
and fill out the form properly.
[include bottom]
The [error] tag is the most important tag on this page. The all
parameter tells the tag to iterate through all of the errors reported
from the failed verification, and the show_var parameter indicates
that the failed variable name should be displayed. For example, if the
first name was left empty, fname would be shown. The show_error
parameter displays the actual error for the variable. The joiner
parameter inserts an HTML
tag between each error message, so each
error is displayed on its own line. In more complex configurations,
the [error] tag can be even more expressive.
42.4. Credit card processing
----------------------------
This tutorial uses a very simple order process. To accomplish this,
one more directive needs to be added to the file etc/profiles.order:
&fatal=yes
&final=yes
+ &credit_card=standard keep
__END__
This issues two instructions to the credit card system.
The first option, standard, uses the standard built-in encryption
algorithm to encrypt the credit card number and erases the unencrypted
copy from memory. We are using the standard option not to encrypt the
number but to run the checksum verification on the number to verify
that it is a potentially correct number. We will not be checking with
a real payment processor to see if it actually is a valid card number.
For testing purposes, you can use the card number 4111 1111 1111 1111,
which will pass the checksum test.
The second option, keep, keeps the credit card number from getting
removed from memory. We want to keep the number in memory so that it
is available when it is mailed as part of the order.
If the credit card number passes and all of the required fields are
present, the customer will be sent to the final page. Interchange then
sends an e-mail to the store owner (you).
42.5. etc/report
----------------
When the customer's involvement in the order is complete, Interchange
composes an email and sends it to the recipient defined in the
MailOrderTo directive in catalog.cfg. The default location for the
template for this email report is etc/report. Interchange tags can be
used to fill in the body of the message.
The report should include at least the customer's name, address, and
the items they ordered. The following is a simple report template;
save it as etc/report.
Name: [value fname] [value lname]
Address: [value address1][if value address2]
[value address2][/if]
City, State, etc.: [value city], [value state] [value zip] [value country]
Credit Card #: [cgi mv_credit_card_number]
Expiration Date: [cgi mv_credit_card_exp_month]/[cgi mv_credit_card_exp_year]
************ ORDER ************
[item-list]
[item-quantity] x [item-description] ([item-code]), [item-price] ea.
[/item-list]
Subtotal: [subtotal]
Total: [total-cost]
This file is in plain text format where, unlike HTML, white space is
relevant. It is fairly straightforward, except that the [if] tag was
added to only include the optional second address line if the customer
filled it in.
One of the special properties of the mv_credit_card_number field is
that Interchange specifically precludes the credit card number from
being saved. This makes it unavailable to you in the [value] tag. The
[cgi] tag is used to circumvent this important security measure in
order to get the value submitted from the last form.
WARNING! Obviously it is a bad idea to send a real credit card number
over an insecure channel like email. In a real configuration, you
would encrypt the number securely before emailing or storing it.
42.6. special_pages/receipt.html
--------------------------------
Once the report has been run, Interchange will finish the order
process on the customer side by displaying a success screen containing
a receipt. The default location for this page is
special_pages/receipt.html. To create a receipt page, type the
following code and save it as special_pages/receipt.html.
[include top]
[include left]
Thank you for ordering stuff from us.
Have a nice day!
[page index]Return to our welcome page
[include bottom]
Once the order is processed, the customer's shopping cart is emptied.
At this point you have a more-or-less functional store.
Congratulations.
43. Enhancing the catalog
=========================
Now that you have a working catalog, you can go back and add
improvements and test them incrementally. This section walks you
through several and then suggests more enhancements you can attempt on
your own.
43.1. Price pictures
--------------------
You may have noticed that the product prices aren't formatted as
prices usually are. The way to correct this is with an Interchange
feature called price pictures.
There are several properties to price pictures: the currency symbol,
the thousands separator, the decimal point, the number of digits to
show behind the decimal, and so on. Most Unix systems have U.S.
currency and the English language as the default locale, which is
called en_US. The only thing you need to do on such a system is
specify the currency symbol, which, in this case, is the dollar sign.
To do this, add the following line to your catalog.cfg file:
Locale en_US currency_symbol $
Restart Interchange and view your catalog. You will notice little has
changed on the welcome page or the flypages, but in the shopping cart
all your prices should be formatted as U.S. dollars ("1347.3" has
become "$1,347.30"). This is because Interchange automatically formats
shopping cart prices as currency. To turn off this feature, you would
have to change the [item-price] tag to [item-price noformat] in
pages/ord/basket.html.
But that's probably not what you want to do. You're probably more
interested in formatting your other prices as currency. To do that,
simply use the [currency] [/currency] tag pair for all price values.
Make the following change to pages/index.html:
[loop search="ra=yes/fi=products"]
[loop-code] |
[loop-field description] |
- [loop-field price] |
+ [currency][loop-field price][/currency] |
[/loop]
Note: The line that begins with '-' should be deleted. Do not type the
'-'. The next line, that starts with '+', replaces it.
A similar change to the [item-field price] tag in the
pages/flypage.html page will fix that currency display. View the page
in your browser. All your prices should be formatted for U.S.
currency.
If your prices are not being formatted correctly, your default system
locale may be set up differently or your en_US locale settings may be
wrong. There are a few other catalog.cfg directives you can use to
correct the situation:
Locale en_US p_cs_precedes 1
Makes the currency symbol precede the currency value. A '0' setting
makes the symbol come after the currency value.
Locale en_US mon_thousands_sep ,
Sets your thousands separator to a comma. It can be set to any value.
Locale en_US mon_decimal_point .
Sets your decimal separator to a comma. Many countries use a comma
instead of a period to separate the integer from the decimal part.
Note: Consult the Interchange documentation and your operating system
manual for more information on locale settings.
43.2. Catalog variables
-----------------------
Interchange provides a very useful feature that has not been discussed
yet called catalog variables. It provides a way for you to set a
variable to a certain value in the catalog.cfg file and use it
anywhere in your catalog pages. The Variable directive allows an
Interchange catalog variable to be created with the name coming from
the first parameter and the value from the rest of the line, like
this:
Variable SOMENAME whatever value you want
To access that variable in your pages, type the token __SOMENAME__.
Notice that there are two underscore characters before the variable
name and two after it, and that in place of the word SOMENAME you
would put the actual name of the variable. The first thing Interchange
does on a page is to replace the token with the variable's value. The
value can also include Interchange tags to be parsed.
43.3. A more interesting page footer
------------------------------------
You can put a contact email address at the bottom of each page in case
your customers want to contact you. You could just add it to the
footer, but by putting it into a variable you can use it in contact
pages as well. This allows you to easily change the variable
information and have that change reflected in all instances of that
variable. The following is an example of how to set a catalog variable
in catalog.cfg:
Variable CONTACT_EMAIL someone@your.domain
Now make the following change to your template file bottom:
- (bottom) |
+ Contact us
+ if you have any questions. |