=head1 NAME
iccattut - Catalog-Building Tutorial
=head1 DESCRIPTION
=head1 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.
=head1 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.
=head2 Install Interchange and the demo catalog
The easiest way to get Interchange and the demo set up is through an
I 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
I. 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:
=over 4
=item *
RPM (RPM Package Manager) install
=item *
Manual install as root
=item *
Manual install as regular user
=back
BAfter installation, F should be run to build your
catalog. For information on installing Interchange and building your
catalog using F, see the I. Do not to continue with this tutorial without a working demo
catalog.
Installing the demo catalog set up the Interchange global
configuration file F, 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.
=head2 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.
=head2 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:
=over 4
=item *
Interchange software directory
=over 8
=item *
B /usr/lib/interchange
=item *
B /usr/local/interchange
=item *
B /home/username/interchange
=back
=item *
Catalogs directory
=over 8
=item *
B /var/lib/interchange
=item *
B /usr/local/interchange/catalogs
=item *
B /home/username/catalogs
=back
=item *
cgi-bin directory
=over 8
=item *
B /var/www/cgi-bin
=item *
B
/usr/local/htdocs, /opt/www, ...
=item *
B /home/username/public_html (with
.cgi extension)
=back
=back
BThe 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.
=head2 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:
=over 4
=item *
B http://localhost/cgi-bin/tutorial/pagename
=item *
B
http://localhost/~username/tutorial.cgi/pagename
=back
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.
BIt 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.
=head2 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:
=over 4
=item *
B /usr/sbin/interchange -r
=item *
B
/usr/local/interchange/bin/interchange -r
=item *
B su interch -c
'/usr/local/interchange/bin/interchange -r'
=item *
B ~/interchange/bin/interchange -r
=back
Find the right command for your system and remember it, since you will
need to restart Interchange a few times during the tutorial.
=head2 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:
=over 4
=item *
B /usr/lib/interchange
=item *
B /var/lib/interchange
=item *
B /var/www/cgi-bin
=item *
B interch
=item *
B foundation
=item *
B http://localhost/cgi-bin/foundation
=item *
B tutorial
=item *
B http://localhost/cgi-bin/tutorial
=item *
B /var/lib/interchange/tutorial
=back
If you did not install with these settings, substitute the correct
values for your system when these settings are mentioned in the
tutorial.
=head1 Building Your Catalog
This section describes the pages and directories that need to be
established to create a properly functioning catalog.
=head2 Create the link program
You need to make a copy of the demo link program in your cgi-bin
directory and name it F.
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
=head2 Create the tutorial catalog directory
As root, create a subdirectory named F under your catalogs
directory (probably F). 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
=head2 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
B probably doesn't have a password. You'll have to set it
with a command such as passwd interch while root.
=head2 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, F
would actually be
F or the
equivalent on your system. The only exception is F,
which is in the Interchange software directory.
BTo improve clarity, we will append a trailing slash to
directory names to clearly distinguish them from file names. (Similar
to the output of the F command with the -F option.)
=head2 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
F and goes under your catalog directory. Type mkdir
session to create this directory.
=head1 Configuration files
Interchange configuration is controlled by a number of directives,
which are specified in two files. Global configuration directives go
in F in the Interchange software directory.
Catalog-specific configuration directives go in F 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.
=head2 interchange.cfg
The first directive we need to use is a global directive that tells
Interchange where the new catalog is, called I. The
B directive has the following format:
Catalog name catalog_base_directory link_url_path
Open F 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.
=head2 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 F 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 B 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 I is in a subdirectory called
F under the catalog directory. Interchange recognizes a
number of file formats. We will use a tab-delimited text file. Enter
the following into F:
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 F. 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
B directive. There is no default for this, so you will
have to specify your products table's name by adding the following
line to F:
ProductFiles products
There are a few other directives that Interchange expects to see in
order to complete the minimum configuration. They are B,
B, and B. 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 F to
establish these directives:
VendURL http://localhost/cgi-bin/tutorial
SecureURL http://localhost/cgi-bin/tutorial
MailOrderTo your@email.address
The F 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
=head1 The products database table
=head2 products/products.txt
Create the F directory in your tutorial catalog directory.
The F 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 F 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 F 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
BWhen 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.
=head1 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.
=head2 top
The Interchange Test Catalog
The Interchange Test Catalog |
=head2 left
(left) |
=head2 bottom
|
(bottom) |
=head2 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 I.
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.
=head1 Creating a welcome page
=head2 pages/index.html
Create a directory called F in your tutorial catalog
directory.
Type the following text and save it as F. 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.
BInterchange pages in the F or other directories
B 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.
=head1 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:
=over 4
=item 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.)
=item 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 F command.
=item 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.
=item 4.
Did you type all punctuation, ITL tags, and HTML tags correctly?
=item 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).
=item 6.
Did you restart Interchange if you changed anything in
F or F, or if you're in a high-traffic
mode?
=item 7.
Check your catalog error log, F in your tutorial catalog
directory, to see if Interchange reported any errors.
=item 8.
Check the Interchange server error log, F in the
Interchange software directory, to see if it had problems loading the
catalog at all.
=item 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.
=back
=head1 Displaying products
=head2 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 F 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 I ('ra') on the
file ('fi') I respectively. The following should take the
place of the ellipsis in the code you placed in F:
[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 F:
[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.
=head2 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
F. When a page is requested that does not exist in
the F 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 F (described in the
next section) will be displayed.
For example, if the page F<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 F. 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 F.
[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 F slightly, so that:
[loop-field description] |
becomes:
[loop-field description] |
=head2 special_pages/missing.html
Create the F directory in your tutorial catalog
directory (not in the F 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
F.
[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.
=head1 The shopping basket
=head2 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 F:
[loop-code] |
[loop-field description] |
[loop-field price] |
+ [order [loop-code]]Order Now |
[/loop]
BThe 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.
=head2 pages/ord/basket.html
Create the directory F in the tutorial catalog directory.
In other words, F should be inside the F directory.
For the [order] tag, Interchange expects a default page called
F. 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
F. 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.
=over 4
=item *
[item-quantity] shows the quantity of the item ordered. If the same
item is ordered multiple times, the quantity increases.
=item *
[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.
=item *
[item-price] shows the per-item price that is defined in the product
database table.
=item *
[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.
=item *
[subtotal] shows the calculated shopping basket subtotal.
=item *
[page index] creates the starting HTML for a link to
the catalog welcome page.
=back
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
F by adding the following lines.
+
+ [page order]View shopping cart
[include bottom]
Refresh the page and test the shopping basket in your browser.
=head1 Order checkout
=head2 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
F. 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
F page, which is described later.
You are submitting some hidden form values that will tell Interchange
how to process this form. The first value, B was set as
I. This causes the form to be submitted for validation. The
second value, B was set as I. This
determines the validation process for the form. It is explained
further in the next section.
The last value, B, was set to be I. The
B value determines what method will be used to charge a
credit card. The value of I 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.
=head2 etc/profiles.order
Create the F 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
F. 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
B<&fatal> setting indicates that validation will fail if any of the
requirements are not met. B<&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
B directive to the end of F:
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.
=head2 special_pages/needfield.html
If the submitted form lacks a required field, Interchange will display
an error page. The default location is
F. To create this page, type the
following text and save it as F.
[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 B
parameter tells the tag to iterate through all of the errors reported
from the failed verification, and the B parameter indicates
that the failed variable name should be displayed. For example, if the
first name was left empty, I would be shown. The B
parameter displays the actual error for the variable. The B
parameter inserts an HTML I<> 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.
=head2 Credit card processing
This tutorial uses a very simple order process. To accomplish this,
one more directive needs to be added to the file
F:
&fatal=yes
&final=yes
+ &credit_card=standard keep
__END__
This issues two instructions to the credit card system.
The first option, B, 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, B, 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).
=head2 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 F. The default location for the
template for this email report is F. 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 F.
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 I field is
that Interchange specifically precludes the credit card number from
being saved. This makes it unavailable to you in the [value] tag. The
B<[cgi]> tag is used to circumvent this important security measure in
order to get the value submitted from the last form.
B 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.
=head2 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
F. To create a receipt page, type the
following code and save it as F.
[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.
=head1 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.
=head2 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 I.
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 F 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
F.
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 F:
[loop search="ra=yes/fi=products"]
[loop-code] |
[loop-field description] |
- [loop-field price] |
+ [currency][loop-field price][/currency] |
[/loop]
BThe 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
F 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 F 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.
BConsult the Interchange documentation and your operating
system manual for more information on locale settings.
=head2 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 F file and use it
anywhere in your catalog pages. The B 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.
=head2 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 F:
Variable CONTACT_EMAIL someone@your.domain
Now make the following change to your template file F:
- (bottom) |
+ Contact us
+ if you have any questions. |