Necessary
installation skills
To install this script you will
need a basic understanding of HTML, Perl CGI scripts, and how they work. If this
is beyond your scope, Merchant Accounts
Express
offers installation services for this product for $99. For details, see the
install_order.txt file.
back to top
Installation
There are actually five Perl
scripts included with XpressCart, but only one needs significant modification.
The scripts are in UNIX text
format. If you open them with a text editor such as Windows Notepad, you may see
strange characters. These are UNIX newline characters. If you are using a
Windows machine, you will need to use an editor that translates UNIX characters
in order to modify the scripts properly. A good HTML editor or even Windows
WordPad is usually up to the task. The UNIX formatting is required for most UNIX
servers, and Windows servers interpret the UNIX characters just fine. That is
why the scripts are in this format.
back to top
Changes to *.cgi
If you are hosting the shopping
cart on a UNIX server, you will need to check the top of each of four files
ending in ".cgi" to make sure the path to Perl is set correctly. By
default, the top of each script begins:
#!/usr/bin/perl
This means that Perl is expected
to be found as /usr/bin/perl. If you do not know where Perl is installed, ask
your web server system administrator. If Perl is installed in /usr/local/bin/perl,
for instance, change the top of each file to:
#!/usr/local/bin/perl
back to top
Site-specific
configuration
Open up config.pl in a text editor
and modify the variable definitions at the top of the script to match your
installation needs. Detailed explanations for each are embedded in the script.
back to top
Changes to template.html
The template file is a normal HTML
file that can be modified as much as needed, with only one exception. Wherever
you want the output from the shopping cart to appear on your pages, you must
insert the following tag:
<!MAIN>
Note that this tag is case
sensitive.
In addition, XpressCart supports
several other special tags, <!BRAND>, <!PRODUCT>, and <!TITLE>. These tags
are also case sensitive. Where applicable, these tags will be replaced by the
brand name of the product being displayed, product name of the product being
displayed, or customized page title (see $title and $title product in config.pl),
respectively.
It should be noted that the HTML
in template.html will be used on the
receipt page after your customers' credit cards have been verified by
Authorize.Net. Therefore, it is recommended that any <img> tags,
<a>
tags, or other tags that reference a URL should specify the absolute URL
(i.e., the full http://www.mysite.com/dir/link.html syntax), since the
receipt page will have a base URL from the Authorize.Net site.
back to top
Uploading
the files
On Windows servers, you may need to
rename the scripts so that they have an
extension of .pl or .plx, depending upon how Perl is configured on your
server. Make sure to reflect the change in the variables in the config.pl
script.
On UNIX servers, you will need to
set file permissions on the scripts that
need to execute. Required permission settings can vary from server to
server, but normally you will set the files as follows:
| store.cgi |
755 or -rwxr-xr-x |
|
office.cgi |
755 or -rwxr-xr-x |
|
show_order.cgi |
755 or -rwxr-xr-x |
|
upload.cgi |
755 or -rwxr-xr-x |
|
config.pl |
600 or -rw------- |
|
common.pl |
600 or -rw------- |
|
SimHMAC.pm |
600 or -rw------- |
|
SimLib.pm |
600 or -rw------- |
Important: You will need to create
a customer folder, an authorization
folder, an order folder, a photo folder, and a working folder and define
them in the config.pl file as per the embedded documentation. Look for
the section labeled "PATHS" in the config.pl file. These
folders will
need both read and write permissions (which is normally the default). The
script will use these folders to write files to keep track of data. As
long as permissions are set correctly, the script will automatically
create the data files as needed.
back to top
Moving
store.cgi
The majority of a customer's
access to your site will be done through the
store.cgi script. As one of a number of optimizations to make your site
rank better with web search engines, XpressCart allows you to relocate
your store.cgi script. Typically, this is done to place store.cgi in the
"root" directory of your web site. That is, it is placed so that the
customer interface to the XpressCart system on mysite.com is:
http://www.mysite.com/store.cgi
In order to achieve this
optimization, the following steps must be taken:
1. Move store.cgi from
the directory where the rest of XpressCart is installed into the "root" directory of your
web site.
2. Modify store.cgi to
point to the rest of the XpressCart installation. At the top of store.cgi, you will see the following
line:
$subdir =
".";
You must
change this to the location of the rest of XpressCart. If, for example, you have installed the rest of XpressCart
in the cgi-bin/xpresscart directory of your web site, change
this line to read:
$subdir =
"cgi-bin/xpresscart";
3. Ensure that the
variables $script_url and $script_url_full are set correctly in config.pl.
Before you take any of the
preceding steps, you may want to first verify
that your web site hosting provider allows CGI scripts to be run outside
of your "cgi-bin" directory.
back to top
Configuring
Authorize.Net
At this point you should configure
your merchant account on Authorize.Net.
Below is a set of required steps. Additional customization may be
possible if you explore the options that Authorize.Net makes available to
you, although care should be taken not to break XpressCart functionality.
The following changes, found under "Settings" when logged into your
Authorize.Net account online, are required to work with XpressCart:
1. Under "Payment
Form," select "Form Fields" and customize the fields as follows:
a) Uncheck all boxes in the
"Edit" columns
b) Only check the following boxes in the "View" column:
- Billing: First Name, Last Name, Address, City, State,
Zip Code, Country, Phone, Email
- Shipping: First Name, Last Name, Address, City, State, Zip Code, Country
c) Only check the following boxes in the "Required" column:
- Billing: First Name, Last Name, Address, City, State, Zip Code, Customer ID
- Shipping: First Name, Last Name, Address, City, State, Zip Code
2. Under "Relay Response," set the URL to the value of the
variable $script_url_full in your config.pl file.
3. Under "Obtain Transaction Key," answer the prompts
appropriately to obtain a transaction key. You should then set $txnkey
in your config.pl file to your new transaction key.
4. (Optional) Use "Time Zone" to set your preferred
time zone,
if you haven't already.
5. (Optional) Use "Email Receipts" if you would like to
customize the emails from Authorize.Net that your customers will
receive, or to disable those emails entirely.
6. (Optional) Under "Payment Form," select "Color
Settings" and configure to better match your site's scheme.
back to top
Using
the scripts
Once you have successfully
installed the scripts, you will need to add some products to your store. Start by accessing the office.cgi script at the
URL where you have placed it. Once you log in, you will be able to add
products, configure shipping and tax information, etc.
After you have a few products in, you
may access the store.cgi script, which
will display a form with various search options. Browsing the store will
give you a better idea of how it all works.
back to top
Linking
to XpressCart
A nice feature of this program is
the ability to link to any product or
product category, externally or internally. A sample link would look like
this:
<a href="store.cgi?s=25&p=Pink_Sneakers">Click
here for pink sneakers!</a>
"s=25" tells the program
which product to display. It is intended to be
used as a Stock Keeping Unit (SKU). A SKU number is a unique identifier
for each product in the store. XpressCart lets you choose the SKU number
for each product, in case you already have a SKU system.
"p=Pink_Sneakers" is
strictly optional. This link will work equally well
without it. However, it is included as an optimization for web search
engines. You may enter whatever you like, as long as the result is still
a valid URL and does not include any special characters such as a "&"
or "?".
Web pages generated by XpressCart will include this optional field to
increase your standing in web search engines.
Below is a sample of how to link
to a product category:
<a href="store.cgi?category=Shoes">Shoes</a>
"category=Shoes" tells
the program that its search should only display
products in the "Shoes" category.
The product description fields
will accept HTML code, so you can embed
these types of links into the description of your products. For example,
on the page displaying pink sneakers, you might want a link to yellow
sneakers or to all shoes. This also enables a web developer to create
main categories with static HTML pages and then link to sub-categories
created within XpressCart.
As a special enhancement for your
customers and also for web search
engines, XpressCart will also automatically provide links to other
products in the same category at the bottom of each product's page. The
number of other products to display is controlled by the $same_category
variable in config.pl.
Below is a sample of how to
provide a link that adds an item directly
to the customer's shopping cart:
<a href="store.cgi?action=add_to_cart&s=102">Buy
pink sneakers!</a>
A comma-separated list of SKUs
such as "s=25,32" is also allowed, which
results in all products in the SKU list being added to the cart.
Below is a sample of how to
provide a link that lets the customer view
his or her shopping cart:
<a href="store.cgi?action=view_cart">View
Cart</a>
back to top
Going
live
The very last thing you should do
is to modify the value of $test_mode in config.pl. The original configuration of XpressCart is to run in
Authorize.Net "test mode." This allows to you test out your site
fully
without actually making any credit card charges. Remove the line with $test_mode from config.pl or set it equal to 0 to start processing and
charging credit cards.
Congratulations on setting up your new online
shopping cart system using XpressCart!
