cactusoft
CactuShop
ASP Shopping Cart
Version 4.6
User &
Developer
Manual
Cactusoft Ltd.
5th Floor, Tolworth Tower
Surbiton, Surrey, KT6 7EL
United Kingdom.
www.cactusoft.com
Copyright 1999-2002
Cactusoft Ltd.
CactuShop ASP Shopping Cart – User & Developer Manual
Introduction
CactuShop is an ASP shopping cart system based around established and
widely adopted Microsoft technologies: Access or SQL Server for the database,
and the IIS web server. The software is script-based and this, combined with
a standard ODBC compliant database format, means it can be modified as
much as required with commonly available development tools.
There are two versions of CactuShop – a free ‘lite’ version and the full
licensed version. The differences are outlined further on, but this manual
serves as a reference for both.
CactuShop has progressed much since the original version and runs hundreds
of web sites around the world. Clients range from small sole traders to large
high street retailers.
Although requiring an amount of ASP knowledge to modify, CactuShop isn’t
used just by egghead developers. This documentation and the body of
material online about ASP have helped numerous customers achieve the ecommerce solution that instant-CD products cannot offer.
Don’t be intimidated by the size of this manual. It’s a reference work designed
to outline how to set up the product and how the features work. You don’t
need to memorize everything but a broad understanding of how the software
works will help as you work to create your online store with CactuShop.
Happy shop-building!
24/7 Online Help System
The quickest way to get answers to your CactuShop problems is by
searching the online knowledgebase. 80% of the problems we get
reported by email or phone are already dealt with in the knowledgebase.
www.cactushop.com/support/
V25102002 Copyright 1998-2002 Cactusoft Ltd.
1
CactuShop ASP Shopping Cart – User & Developer Manual
Contents
Introduction ........................................................................................ 1
Contents.............................................................................................. 2
1
Overview....................................................................................... 7
1.1
CactuShop Lite – Our Free Trial Version ......................................... 7
1.1.1
Similarities between the lite and full versions ........................... 7
1.1.2
License agreement for CactuShop Lite ..................................... 7
1.1.3
Security issues ....................................................................... 7
1.2
2
CactuShop - Full Version ............................................................... 7
Setting Up ..................................................................................... 9
2.1
Base Platform Requirements.......................................................... 9
2.1.1
Operating system ................................................................... 9
2.1.2
Database ............................................................................... 9
2.1.3
VBscript version ..................................................................... 9
2.1.4
Support for third party software .............................................. 9
2.2
Installing the Files......................................................................... 9
2.2.1
Unzipping the software........................................................... 9
2.2.2
Importing into the web server................................................. 9
2.2.3
Setting up CactuShop to use an ODBC datasource ................. 10
2.2.4
Changes for security reasons ................................................ 10
2.3
Setting Permissions..................................................................... 10
2.3.1
How to set ‘full control’ permissions for the database ............. 10
2.3.2
Setting image upload permissions ......................................... 11
2.3.3
Setting scripts permissions.................................................... 11
2.4
Run the Software!....................................................................... 11
2.4.1
Dealing with errors............................................................... 11
3
The CactuShop Front End ........................................................... 12
3.1
Introduction ............................................................................... 12
3.2
Skins.......................................................................................... 12
3.2.1
The style sheet reference ..................................................... 12
3.2.2
What elements make a skin? ................................................ 13
3.2.3
How is the template used to format my pages (tech stuff)...... 13
3.2.4
What essential features must a ‘skin’ have? ........................... 13
3.3
Product view .............................................................................. 13
3.3.1
Product information.............................................................. 13
3.3.2
Version list........................................................................... 14
3.3.3
Auto sizing of ‘large view’ pop ups......................................... 14
3.3.4
‘Related items’ functionality .................................................. 14
3.4
Save/Recover Basket................................................................... 14
3.4.1
Basic operation .................................................................... 14
3.4.2
Used to store regular repeat orders....................................... 14
3.4.3
Used to store orders for another user to read ........................ 14
V25102002 Copyright 1998-2002 Cactusoft Ltd.
2
CactuShop ASP Shopping Cart – User & Developer Manual
3.4.4
Issues affecting recovered baskets ........................................ 14
3.5
Wish List .................................................................................... 15
3.5.1
Creating and saving a wish list .............................................. 15
3.5.2
Editing a list......................................................................... 15
3.5.3
Viewing a wish list................................................................ 15
3.6
SpeedOrder ................................................................................ 15
3.7
Stock Tracking............................................................................ 15
3.7.1
Basic operation .................................................................... 15
3.7.2
Trapping stock-related errors and issues................................ 16
3.7.3
Setting up stock tracking for an item ..................................... 16
3.8
My Account ................................................................................ 16
3.8.1
Saved baskets...................................................................... 16
3.8.2
Order tracking and history .................................................... 16
3.8.3
Cookie-based security........................................................... 16
3.9
Affiliates Section ......................................................................... 16
3.9.1
Affiliate Application............................................................... 16
3.9.2
Click-through tracking .......................................................... 16
3.9.3
Assigning a customer to an affiliate ....................................... 16
3.9.4
Affiliate statistics .................................................................. 17
3.10 The
3.10.1
3.10.2
3.10.3
3.10.4
Ship-to Page ........................................................................ 17
Destination menu ................................................................. 17
Payment method selection.................................................... 17
Email address box ................................................................ 17
Request customer code ........................................................ 17
3.11 Online Payment – Checkout Area ................................................. 17
3.11.1 Payment through an online authorization gateway ................. 17
3.11.2 Payment through CactuShop under SSL................................. 18
3.11.3 Payment by PO .................................................................... 18
3.11.4 Email signup ........................................................................ 18
4
The Back-End.............................................................................. 19
4.1
Logging In / Back End Password.................................................. 19
4.2
Navigating the Back End ............................................................. 19
4.3
Listing Orders ............................................................................. 19
4.3.1
Recent orders ...................................................................... 19
4.3.2
Awaiting payment ................................................................ 19
4.4
Stock Tracking............................................................................ 19
4.4.1
Basic operation .................................................................... 19
4.4.2
Warnings page..................................................................... 19
4.4.3
Setting up stock tracking for an item ..................................... 19
4.4.4
Why disable stock tracking for some items? ........................... 20
4.5
Statistics .................................................................................... 20
4.5.1
Turning off statistical tracking ............................................... 20
4.6
Modifying a Category .................................................................. 20
4.6.1
Deleting a category .............................................................. 20
4.7
Modifying a Product .................................................................... 21
4.7.1
Featured items dropdown ..................................................... 21
4.7.2
Large image view ................................................................. 21
V25102002 Copyright 1998-2002 Cactusoft Ltd.
3
CactuShop ASP Shopping Cart – User & Developer Manual
4.7.3
4.7.4
Products can appear in more than one category..................... 21
Adding ‘related products’ ...................................................... 21
4.8
Modifying/Cloning a Version ........................................................ 21
4.8.1
Cloning versions................................................................... 21
4.9
Customer Database Admin .......................................................... 21
4.9.1
Basic operation .................................................................... 21
4.9.2
Creating customer records from the back end ........................ 21
4.9.3
Customer record listing......................................................... 22
4.10 Affiliate Admin Section ................................................................ 22
4.10.1 Basic operation .................................................................... 22
4.10.2 Technical implementation ..................................................... 22
4.10.3 Approving, setting up and modifying affiliates ........................ 22
4.10.4 Viewing statistics for affiliates ............................................... 22
4.11 Email List Management ............................................................... 23
4.11.1 Spamming ........................................................................... 23
4.11.2 Send mail ............................................................................ 23
4.11.3 Copy to clipboard ................................................................. 23
4.11.4 List/find ............................................................................... 23
4.11.5 New/edit address ................................................................. 23
4.11.6 Purge unauthorized addresses .............................................. 23
4.12
Searching for Products or Versions............................................... 24
4.13
Closing the Shop......................................................................... 24
4.14
Switching Products or Categories Off ........................................... 24
4.15 Customers .................................................................................. 24
4.15.1 Finding/creating/modifying records ....................................... 24
4.15.2 Cross linking of customer and order records .......................... 24
4.15.3 Purge incomplete ................................................................. 24
4.16 Orders........................................................................................ 25
4.16.1 Reviewing orders ................................................................. 25
4.16.2 Invoicing ............................................................................. 25
4.16.3 Order progress and status .................................................... 25
4.16.4 Turning off order progress system ........................................ 25
4.17
Tax Rates................................................................................... 25
4.18 Shipping Destinations.................................................................. 25
4.18.1 Charge tax by country .......................................................... 25
4.18.2 Shipping zone ...................................................................... 25
4.18.3 ISO country code ................................................................. 26
4.18.4 Country name ...................................................................... 26
4.18.5 The country ID .................................................................... 26
4.19
Shipping Rates............................................................................ 26
4.20
News Items ................................................................................ 26
4.21 Static HTML Product Gateway Pages ............................................ 26
4.21.1 The debate over search engine indexing of database sites...... 26
4.21.2 Creating the static pages ...................................................... 27
4.21.3 Products no longer on the site .............................................. 27
4.21.4 Folder permissions ............................................................... 27
5
Online Payment Methods – Setup .............................................. 28
V25102002 Copyright 1998-2002 Cactusoft Ltd.
4
CactuShop ASP Shopping Cart – User & Developer Manual
5.1
Setting Up WorldPay Select Junior ............................................... 28
5.2
Setting Up Authorize.Net ............................................................. 29
5.3
Setting Up Protx VSP Form .......................................................... 31
5.4
Setting Up PayPal ....................................................................... 31
5.5
Setting Up Verisign Payflow Link .................................................. 32
5.6
Email Notification - Unencrypted .................................................. 32
5.7
Cactushop Encrypted Mail Add-on (“CEM”) ................................... 32
5.7.1
Generating a key.................................................................. 33
5.7.2
Enabling CactuShop to send encrypted mail........................... 33
5.7.3
Setting up the decryption software........................................ 33
5.8
Secure Back End Review – Requires SSL ...................................... 34
5.9
Setting Up SSL............................................................................ 34
5.9.1
SSL issues ........................................................................... 34
5.9.2
SSL access to the database................................................... 35
5.10
6
Other Payment Systems .............................................................. 35
The Config System...................................................................... 36
6.1
Basic Operation .......................................................................... 36
6.2
The License Number ................................................................... 36
6.3
Database Connection .................................................................. 36
6.3.1
Other database types ........................................................... 37
6.4
The
6.4.1
6.4.2
6.4.3
7
8
Config Table ........................................................................ 37
Basic operation .................................................................... 37
Changing config settings....................................................... 37
Config settings table............................................................. 38
Language Strings System ........................................................... 44
7.1
Background ................................................................................ 44
7.2
Advantages of the New Database System..................................... 44
7.3
The Language String Editor ......................................................... 44
7.4
The
7.4.1
7.4.2
7.4.3
7.4.4
7.4.5
Language Strings Table ........................................................ 45
LS_ID .................................................................................. 45
LS_FrontBack....................................................................... 45
LS_Name ............................................................................. 45
LS_Value ............................................................................. 45
LS_Description ..................................................................... 45
7.5
The
7.5.1
7.5.2
7.5.3
Language Strings Functionality.............................................. 45
PageStrings ......................................................................... 45
LoadStrings ......................................................................... 45
WriteString and GetString functions....................................... 46
Support ....................................................................................... 47
8.1
Scope of Tech Support ................................................................ 47
8.2
FAQ ........................................................................................... 47
V25102002 Copyright 1998-2002 Cactusoft Ltd.
5
CactuShop ASP Shopping Cart – User & Developer Manual
8.2.1
8.2.2
8.2.3
8.2.4
8.2.5
8.2.6
8.2.7
8.2.8
8.2.9
8.2.10
8.2.11
8.2.12
What does the error ‘must use updateable query’ mean?........ 47
I get a 500 error. What does this mean? ............................... 47
What is the database password? ........................................... 47
What is the back end login and password? ............................ 47
Can I change the currency to dollars?.................................... 47
Can I have a full version for a trial period?............................. 48
Will you do some modifications? ........................................... 48
Will the software run on Linux? ............................................. 48
What is your upgrade policy? ................................................ 48
Can I use a visual editor? ..................................................... 48
How does the licensing work? ............................................... 48
How much is it in US Dollars? ............................................... 49
V25102002 Copyright 1998-2002 Cactusoft Ltd.
6
CactuShop ASP Shopping Cart – User & Developer Manual
1
Overview
1.1
CactuShop Lite – Our Free Trial Version
Cactusoft produces two versions of CactuShop v4. The lite version is a cut
down version with much of the security code removed, no license for live web
use, and some of the features disabled. CactuShop Lite is available as a
download from the CactuShop web site for the purposes of testing the basic
code on your server, populating a database with products, creating the ‘skin’
template design and satisfying yourself that you have the technical capability
to set up and create your web store.
1.1.1
Similarities between the lite and full versions
CactuShop Lite shares the following with the full version:
a.
b.
c.
d.
e.
f.
1.1.2
database structure
basic back end code for adding and updating products
navigation
basic basket functionality
coding style
platform and set up requirements
License agreement for CactuShop Lite
Please read the license agreement that comes with CactuShop Lite carefully.
In particular, you may NOT do the following with CactuShop Lite:
a. run any of the Cactusoft copyrighted code on a live web site other
than as temporary trial development version
b. remove copyright messages or credits from Cactusoft’s code
c. remove copyright messages or credits from the image upload and
sizing scripts; these are freeware written by other authors – we have
left their code and comments intact to give them full credit for their
work, please respect their right to be credited for their efforts
1.1.3
Security issues
CactuShop Lite is a trial version and as such is NOT secure. The back end has
no password protection and much of the code that secures various sections of
the front end is not present in the lite version.
1.2
CactuShop - Full Version
The full licensed version of CactuShop is available from the CactuShop web
site and includes the following features that are not part of the lite version:
a.
b.
c.
d.
e.
f.
g.
h.
i.
j.
license for single site live web use
save/recover basket functionality
wish list
payment systems scripts
more robust cookie-based basket
large views of products and versions
speed ordering
‘my account’ – order tracking and saved basket management
statistics system
email newsletter mailing list signup and management
V25102002 Copyright 1998-2002 Cactusoft Ltd.
7
CactuShop ASP Shopping Cart – User & Developer Manual
k.
l.
m.
n.
o.
p.
q.
r.
‘related product’ functionality
back end customer account management tools
back end order management section
back end stock level warnings
back end affiliate system
static HTML gateway page generation
affiliate tracking and commission calculations
invoicing
V25102002 Copyright 1998-2002 Cactusoft Ltd.
8
CactuShop ASP Shopping Cart – User & Developer Manual
2
Setting Up
2.1
Base Platform Requirements
2.1.1
Operating system
CactuShop is an Active Server Pages application and as such needs to run on
a web server that incorporates an ASP scripting engine. Although Linux/Unix
servers can be made to run ASP, we have no experience of doing this and do
not support the product on those platforms.
We advise running CactuShop on Microsoft NT/Win2000 server with the latest
service packs you can lay your hands on. IIS4.0 or 5.0 web server software
needs to be running and on older NT versions, the ASP support may need to
be installed separately. CactuShop will run fine on shared web space but
check the platform and permission requirements with your host first if in any
doubt. Use the free lite version as a test.
2.1.2
Database
CactuShop ships with an Access 2000 database file. The ASP code is written
to be switchable between MS Access, Microsoft SQL Server and MySQL syntax
(similar but with some small differences). Access 97, MS SQL Server and
MySQL versions of database are available as free downloads from our web
site.
2.1.3
VBscript version
The CactuShop code is VBscript – the ASP default language. In order to
update the VBscript engine, install the latest version of Internet Explorer on
the server. For the image upload capability, VBscript 5.0+ is required and you
will get an error trying to update products without it.
2.1.4
Support for third party software
The above software set up is a prerequisite for running an ASP site. We
cannot support set up and installation of Microsoft or other third party
software – please consult the relevant web sites and use their sample
applications to test that your server, scripting engine and RDMS (database)
are running properly.
2.2
Installing the Files
2.2.1
Unzipping the software
The product is shipped electronically as a self-extracting zip file, which is itself
zipped to pass through firewalls. To unzip the files, double click the file and
follow the onscreen instructions. You should end up with a CactuShop folder
containing several other folders and files. The folder structure of the unzipped
files should be as in figure 1 (below).
2.2.2
Importing into the web server
You can import the folder to create a new web in FrontPage or import into IIS
– however you normally set up webs. If FrontPage prompts you to set up
database connections for the Access file, click no because you do not need to.
A DSN-less database connection is already set up within the software.
V25102002 Copyright 1998-2002 Cactusoft Ltd.
9
CactuShop ASP Shopping Cart – User & Developer Manual
2.2.3
Setting up CactuShop to use an ODBC datasource
Some users prefer to connect to the database via ODBC. If so, set up the
datasource and change the datasourcename setting in the includes/config.asp
file to the name of your datasource, with quotes around it. For example:
datasourcename=”mydatasource”
2.2.4
Changes for security reasons
The database and its folder should both have their names changed at this
point. You will need to adjust the database connection in the config.asp to
reflect these name changes. If you do not change these default values,
malicious users will easily be able to download your database and any private
customer data it may hold. If your hosting provider has a ‘private’ or ‘data’
folder specifically for Access databases, we’d strongly advise using this.
Permissions on this folder should prevent anyone downloading the file via
HTTP (e.g. through a web-browser). In this case, please note that the back
end ‘back-up database’ link will cease to work and you will need to back-up
the database via FTP.
2.3
Setting Permissions
Figure 1. CactuShop folder layout and permissions
cactushop web
Permission
standard
execute scripts
IUSR full-control
asp
cactushopback
includes
database
cactushop .mdb
html
images_webshop
images_products
images_products_large
images_versions
images_versions_large
skin_default
templateimages
The folders and Access database file need certain security permissions set in
order to function properly. Figure 1 shows which items should have what
permissions. Note that these permissions cannot be changed via FTP. If your
web host doesn’t set these as standard, you will need either physical access
to the server, access via PC-anywhere, VNC or some similar system or an
obliging techie at the web hosting company. The database folder should be
renamed or made ‘private’ as mentioned in 2.2.4.
2.3.1
How to set ‘full control’ permissions for the database
On Win2000 and NT, you need to set security permissions to allow the
Internet Guest Account full rights to modify the database. As default, it will
V25102002 Copyright 1998-2002 Cactusoft Ltd.
10
CactuShop ASP Shopping Cart – User & Developer Manual
only have read permissions. Note that you cannot change these permissions
through FTP – you will need to ask your web host to make these changes if
you experience permissions problems on a hosted web site.
Using Windows Explorer, navigate to the CactuShop mdb file (in the
‘database’ folder), right click it and click ‘properties’, then the ‘security’ tab. If
the Internet Guest Account (also shown as IUSR_MachineName or something
similar) is not present, you will need to click ‘add’ and then select and add this
user. Next, select this user and tick the top box, ‘full control’. Click OK and
you’re done.
If you don’t give the database these permissions, you will get the following
error on pages that write to the database. This includes the front end product
page which writes statistical hit information:
“….must use updateable query…”
2.3.2
Setting image upload permissions
Assuming IE5+ is installed on the server, it should be possible to upload
images to the web site through the facilities provided in the back end of
CactuShop. However, the images folders must have the permissions properly
set on Win 2000 and NT. Right-click the folder, click properties and then
security. Select the IUSR account (Internet Guest Account) and ensure that
‘full control’ permissions are set for it. This action should be performed on the
html, images_products, images_products_large, images_versions and
images_versions_large folders.
2.3.3
Setting scripts permissions
Some folders within the web may not have ‘scripts’ permissions set – they
may only allow reading of files. This is fine for HTML, but ASP pages are
dynamic and contain active code that needs to run. To ensure that the scripts
have permission to run, navigate to CactuShop in the IIS manager or
FrontPage, right click the asp, includes and cactushopback folders and tick the
‘allow scripts to run’ box. You cannot do this from Windows Explorer, it must
be done within FrontPage or IIS. You don’t need to set this for the other
folders since they don’t contain ASP scripts.
2.4
Run the Software!
Type in the address of the web that you’ve just created into a browser and
you should get the home page of the shopping cart. If you get any errors,
please check the path you typed (careful!) and the points above. If you
installed IIS or PWS on your own machine, the address of the server will
normally be “http://localhost/”, plus whatever your web is called.
2.4.1
Dealing with errors
If you get any errors at any stage, please refer to the FAQ in section 8.2 and
search our knowledgebase on the CactuShop web site before contacting us.
Most common problems are dealt with there already.
V25102002 Copyright 1998-2002 Cactusoft Ltd.
11
CactuShop ASP Shopping Cart – User & Developer Manual
3
The CactuShop Front End
3.1
Introduction
The front end is the part that visitors to the site see. All the pages are
dynamically generated and allow the user to navigate around the site, view
products, select items to add to the shopping basket and then finally,
checkout and pay for the goods.
3.2
Skins
CactuShop has a template-based front end. This pulls the HTML base of the
page from a folder containing a template HTML file and associated images. By
adding a new skin folder (we have downloads of more from our site or you
can modify the existing one or create your own) you can totally transform the
appearance of the entire front end. Fonts, colours, alignment, arrangement of
page elements – all of these can be changed by modifying the skin.
3.2.1
The style sheet reference
The default skin template includes the following styles:
.netscape6problem
Fixes a bug we encountered where NS6 ignored the
first line in our stylesheet - weird but this fixed it…
.smallnormal
small size of text used throughout
.smallnormaltable
small size of text in tables such as basket and shipping
.smallnormaltablealt
.mednormal
small text used in tables - alternative colour for
contrast
medium sized plain text used throughout
.mednormaltable
medium sized plain text used in tables such as basket
.medbold
medium bold text used throughout
.medboldalt
medim bold text in alternative colour for contrast
.medboldtable
medium bold text used in tables
.largebold
large bold text used as page headings
.smallcompact
smaller than smallnormal
.smallbold
small bold used throughout
.smallboldtable
small bold on tables such as the basket
.smallboldtablealt
small bold on tables - alternative colour for contrast
.smallboldtabletop
column headings on tables such as the basket
.smallboldtemplate
small bold style for use in the default template
.smallboldfooter
small bold syle for use in the default template
.locationbar
small syle for use in the location hierarchy links
A:link
standard hyperlinks used throughout
A:visited
visited hyperlinks used throughout
A:hover
hover style for hyperlinks used throughout (IE 4.0+,
Netscape 6.0+, Opera 5.0+)
A.minibasket:link
hyperlinks in the basket summary
A.minibasket:visited
visited hyperlinks in the basket summary
A.minibasket:hover
hover style for hyperlinks in basket summary (IE4.0+,
NS6+)
A.table:link
hyperlinks in tables such as the basket
A.table:visited
visited hyperlinks in tables
A.table:hover
hover style for hyperlinks in tables (IE4.0+, NS6+)
A.templatemenu:link
hyperlinks style for the default template menu bar
V25102002 Copyright 1998-2002 Cactusoft Ltd.
12
CactuShop ASP Shopping Cart – User & Developer Manual
A.templatemenu:visited
visited hyperlinks for menu bar
A.templatemenu:hover
hover style for hyperlinks in menu bar
table.minibasket
background colour for basket summary table
tr.minibasketline
line shade colour for basket summary
hr
horizontal line throughout site
pre
fixed-width font style used in preformatted text for
specifications field
select
dropdown menu style
table.mainpage
table background colour for site tables other than
basket summary
tr.mainpagetableline
line shade colour for tables within the main content
section of the page
tr.mainpagetableline2
variation shade colour for tables – slight contrast with
above style to give faint striped appearance
tr.mainpagetablespecial
row alternative colour in tables
tr.mainpageversionhighlight
highlight colour for rows in site tables
buttonstyle
style used for push buttons
3.2.2
What elements make a skin?
A skin is a selection of files placed in a folder that sits on the root of the web.
The template HTML document itself is always called template.htm and the
images folder is called templateimages. The template also contains images for
the basket icons and any header images.
3.2.3
How is the template used to format my pages (tech stuff)
An include file called buildpage.asp features on each front end page. This
reads the skin template file’s HTML, builds the basket summary HTML, builds
the product category listing HTML and then replaces the
xxxBASKETSUMMARYxxx and xxxCATEGORYMENUxxx tags with the
appropriate HTML. Finally, the string of HTML is split around the
xxxPAGECONTENTxxx tag, with either half being stored in a box of a 2dimensional array called aryPageTemplate. Each page contains just the code
that is necessary to generate the content part of the page – the buildpage
include builds the rest of the HTML and the two halves stored in the
aryPageTemplate array are written to the page above and below the main
page content.
3.2.4
•
•
•
•
•
3.3
What essential features must a ‘skin’ have?
the style sheet incorporated into the head section of the page
xxxPAGECONTENTxxx tag in order for page content to appear
the main menu must be included to give users a way to navigate
a <head> tag (the basket message refresh system requires this – it
MUST be lower case)
javascript pop-up function (see default skin)
Product view
This is the key part of the front end – the page that displays products and
their versions.
3.3.1
Product information
The CactuShop code pulls out product information and checks to see whether
an image exists for the product. If one is present, this is displayed. Another
V25102002 Copyright 1998-2002 Cactusoft Ltd.
13
CactuShop ASP Shopping Cart – User & Developer Manual
check is made to see if a large image has been uploaded too. If yes, the ‘view’
link is displayed.
3.3.2
Version list
‘Versions’ is a critical design feature in CactuShop. Products can have any
number of versions, and each version of a product can have a different spec,
price and availability. Versions may typically be different sizes, colours, etc.
The version list can include an optional description for each version, an image,
a large image link and an ‘add to basket’ link. CactuShop does not use product
‘option’ selections.
3.3.3
Auto sizing of ‘large view’ pop ups
The large view pop ups are automatically sized to fit the size of the images
that occupy them.
3.3.4
‘Related items’ functionality
CactuShop includes facilities in the back end for setting up links between
products. In this way, a page containing electric torches could have links to
batteries or replacement bulbs, for example. These links are one way, so in
the above example, the battery page of bulbs page won’t have links to electric
torches unless you specifically set these up.
For information on setting up related items, see section 4.7.4.
3.4
Save/Recover Basket
3.4.1
Basic operation
This feature lets users save their basket contents to the database so they can
recover them on a future visit. To save a basket, a user needs only enter and
email address and name/password for the saved record. The same
information is entered in the appropriate place to recover the saved basket,
instantly reinstating the products to the current basket.
3.4.2
Used to store regular repeat orders
Users can save any number of baskets, so this system is also perfect for
storing several regular orders that a user may make from your web shop.
3.4.3
Used to store orders for another user to read
Since the basket can be recovered by any user with the email address and
name/password, a CactuShop saved basket is perfect if you wish to select
items and get someone else on a different machine to recover the basket and
pay for the items.
3.4.4
Issues affecting recovered baskets
If a basket has been stored for some time, it may be that the products in the
basket are no longer available, or the specification/price may have changed.
In the first instance, items no longer available or items out of stock will be
removed from the cart automatically. However, the user should always check
recovered items through to ensure the specification and price is acceptable.
CactuShop provides a link to the basket and a message explaining this so that
customers will be encouraged to check through recovered basket details.
V25102002 Copyright 1998-2002 Cactusoft Ltd.
14
CactuShop ASP Shopping Cart – User & Developer Manual
3.5
Wish List
The wish list lets individuals prepare a list of items on the site that they can
then make available to friends and relatives. This is perfect for wedding lists,
children’s Christmas presents and other such situations.
3.5.1
Creating and saving a wish list
In order to create a wish list, simply load up the basket with all the items
required and then click the ‘wish list’ link on the main menu. In the second
section on the page, there is a link to create a new wish list. The user
specifies their email address, first and last names, the private password they
wish to use for editing the list and the public password they will circulate to
their friends and relatives. In order to personalize the experience, they may
also specify a greeting that those viewing the list will see above it.
3.5.2
Editing a list
Editing a list is just as easy. Click the wish list link and enter the email address
and private password in the boxes on the second section of the page. You can
first recover the list (which will fill your basket with all the items in the wish
list) and then make any additions/changes before returning to save the list.
Remember that items that have been purchased will have been removed from
the list.
At the point the wish list is saved, a confirmation email with the details is sent
for future reference.
3.5.3
Viewing a wish list
All friends and relatives need to view a list is the email address and public
password. They simply enter these in the top section of the wish list page and
click the ‘recover’ button. This displays the items on the wish list so that they
can click through and view these. From here, they can add items to their
basket and buy them just as with normal items. At the point of purchase,
these purchased items will be removed from the wish list.
A user stays logged into the wish list so simply clicking on the ‘wish list’ link
on the main menu will bring up the list. Users can log out once they are
finished (this is necessary if you wish to view another wish list for example).
3.6
SpeedOrder
This lets users enter the code number of versions and a desired quantity to
add them to their basket. This is particularly useful when users may prepare
their order from printed versions of the catalogue and don’t want to search
the site looking for those items to add to their cart. CactuShop will trap and
display any errors with the data entered, such as an item not being found or
the quantity being an illegal value. SpeedOrdering is handy when you know
the product code of what you’re looking for and don’t want to have to search
and add items manually.
3.7
Stock Tracking
3.7.1
Basic operation
CactuShop supports stock quantity tracking for items. The total of each item is
adjusted each time any are purchased and items where the stock has reached
V25102002 Copyright 1998-2002 Cactusoft Ltd.
15
CactuShop ASP Shopping Cart – User & Developer Manual
zero will automatically display as ‘out of stock’, preventing further users from
adding these to their order.
3.7.2
Trapping stock-related errors and issues
If a user tries to add more of an item to their basket than are currently in
stock, or increase the quantity of an item in their basket beyond the total
available, CactuShop will only add the available quantity. A message
explaining why the quantity added was reduced is displayed and the relevant
line in the basket is highlighted.
3.7.3
Setting up stock tracking for an item
Stock tracking can be enabled or disabled for items on an individual basis. For
more details see 4.4.
3.8
My Account
3.8.1
Saved baskets
Logged in users can view a list of their saved baskets. They can load any of
these saved baskets or delete them.
3.8.2
Order tracking and history
CactuShop allows the user to see their order history, including the quantities
of items bought, pricing and discount (if any). A full history is retained so
users can go back and check orders they made at any point in the past. If
order tracking is enabled by the store owner (see ‘ordertracking’ config setting
in 6.4.3) then the user can see the current status of the order and any
comments the store owner has added regarding the order.
3.8.3
Cookie-based security
The user’s email address and password are stored on a per-session cookie
that expires with the end of the session.
3.9
Affiliates Section
3.9.1
Affiliate Application
Visitors to the site can apply to become affiliates. They enter their details and
submit. An email is sent to the store owner informing him/her that there is a
new application for them to check in the back end.
3.9.2
Click-through tracking
CactuShop has an affiliate system that lets you track click-throughs to the site
via affiliate links. This is dealt with in more detail in section 4.10.2. This page
logs and affiliate click-through in the tblCactuShopAffiliateLog table and also
plants a cookie on the visitor’s browser that is used later on if the visitor
makes an order through the site.
3.9.3
Assigning a customer to an affiliate
The shipto.asp page checks to see if there is a cookie planted with an affiliate
ID, indicating that the visitor came to the site via an affiliate link. If there is
such a cookie, the affiliate ID is transferred to the next page via form fields,
ensuring the value will be passed whichever payment system the site is using.
When the customer record is created on the mailorder.asp page (or payment
system alternative page), it is assigned this affiliate ID. All future orders by
V25102002 Copyright 1998-2002 Cactusoft Ltd.
16
CactuShop ASP Shopping Cart – User & Developer Manual
this customer will be credited to the affiliate responsible for them first signing
up.
3.9.4
Affiliate statistics
Affiliates can access statistics on the hits and sales their link has generated for
each month of the last 12 months.
3.10
The Ship-to Page
3.10.1
Destination menu
CactuShop’s payment form works a bit differently to other packages because
it asks where the goods are being shipped to before offering final pricing and
getting the cardholder’s details. This is because the destination will affect final
pricing. Shipping a long way will likely cost more, but tax may be charged to
local customers and not to overseas customers. Once the destination is
chosen, it is hardcoded into the next form so users can’t change it without the
pricing being recalculated.
3.10.2
Payment method selection
From CactuShop v4.6 onwards, customers can be given a choice as to how
they pay. The store owner can set these options from the back end config
settings (see section 6 for more information).
3.10.3
Email address box
Before making an enquiry or going to the check out, the user must enter an
email address. This way, the software can check if any previous purchases
have been made by the user. If so, the user will be directed back to the shipto page from where they can request their customer code and use that to pull
up their address details. The user will also get the benefit of any discount
their account has been given and the shop owner can more accurately link
orders to customers in the back end.
3.10.4
Request customer code
Customers are automatically given a random customer code when they first
place an order. This acts as a password for looking up their order and can be
used to recover account details when ordering subsequently. If the number
has been lost or misplaced, the user can request an automated reminder.
3.11
Online Payment – Checkout Area
This part may vary depending on whether the user is paying via an online
payment provider, through a secure area on the CactuShop system itself or by
purchase order.
3.11.1
Payment through an online authorization gateway
The user will fill in customer information that will be retained on the
CactuShop system. This is not done under SSL since no credit card or other
sensitive financial information is stored. The user then clicks a button which
transfers them to the secure payment form on the payment provider’s web
site. Once the payment is made, the gateway either calls back the CactuShop
system, or forwards the user back, confirming to CactuShop that the order
was paid for successfully. At this point, CactuShop mails the order to the store
owner, a confirmation to the customer and the order will become visible in the
back end of CactuShop. Note that if you’re using CactusPay, the process is the
V25102002 Copyright 1998-2002 Cactusoft Ltd.
17
CactuShop ASP Shopping Cart – User & Developer Manual
same as that employed by an online gateway, however, the store owner will
receive the card details encrypted.
3.11.2
Payment through CactuShop under SSL
If the payment area of CactuShop is setup under SSL and the Cactusoft
Encrypted Mail system is employed, the user will fill out their personal details
and credit card info into the CactuShop payment form.
3.11.3
Payment by PO
If you have customers who you wish to allow to pay on account, or by
purchase order (with payment to be invoiced for later), CactuShop supports
this too. The store owner can decide whether only trusted existing customers
can buy in this way, or whether all customers can. The payment method is
similar to payment through CactuShop, but instead of a section of the form
for credit card details, the user gets a text box to enter their PO (or reference)
number that they wish to use for the order.
See section 5 for further information.
3.11.4
Email signup
The newsletter mailing list signup is incorporated into the online payment part
of the site so users can opt-in to the newsletter when ordering. Our
newsletter database follows best practice by sending an email to those signing
up for the newsletter, a link in which must be clicked to complete the signup
process. This ensures that email addresses are verified before they can
receive the newsletter.
See section 4.11 for further information.
V25102002 Copyright 1998-2002 Cactusoft Ltd.
18
CactuShop ASP Shopping Cart – User & Developer Manual
4
The Back-End
The back-end is used by the shop owner or operator to add, modify or delete
products, categories and other items.
4.1
Logging In / Back End Password
Go to cactushopback/default.asp. This should bring up the login screen. The
default login and password is “cactushop” for both. We recommend for
obvious security reasons that you make changing this a priority before you
put the site online.
Changing the defaults is easy. In CactuShop v4.2 or earlier this was done by
modifying the values in includes/back_password.asp.
From v4.5 onwards it is done by changing the two config settings
backendlogin and backendpassword.
4.2
Navigating the Back End
This is similar to the front end in appearance. Note that the left hand side
category menu now shows “(MAS)” after master categories (categories that
contain sub categories rather than products). Clicking on a category brings up
a list of the products and versions of those products. Clicking on a master
category brings up a list of the sub categories.
4.3
Listing Orders
4.3.1
Recent orders
This link on the navigation menu lists the 25 most recent orders. From this
page, the site owner can click through to the full order text, view orders on
any specified day, scroll through the days one by one or click through to the
customer record.
4.3.2
Awaiting payment
This link lists the orders that are marked as awaiting payment.
4.4
Stock Tracking
4.4.1
Basic operation
Stock tracking stores levels of particular items in the database and flags them
as ‘out of stock’ on the front end if the supply is exhausted. For more
information about the front end aspects of stock tracking, see 3.7.
4.4.2
Warnings page
This is the easiest way to see at a glance which items are out of stock and
which are below their warning levels. Items in red are out of stock, those in
grey are below their preset warning levels.
4.4.3
Setting up stock tracking for an item
When creating or editing a version, there are two boxes that refer to stock
tracking. The first is the current level of that version in stock. This can be
adjusted by changing the value and submitting the form. It is also adjusted as
customers purchase stock through the site. The second box is the warning
V25102002 Copyright 1998-2002 Cactusoft Ltd.
19
CactuShop ASP Shopping Cart – User & Developer Manual
level. If this is set to zero, stock tracking is disabled for that item. But if an
integer value higher than zero is set, stock tracking is enabled and the whole
stock tracking system kicks into action for that product.
4.4.4
Why disable stock tracking for some items?
Stock tracking requires commitment on the store owner’s part. As stock is
depleted, the store owner must adjust the quantities of stock upwards when
new stock arrives to ensure that products do not show as out of stock on the
front end. For products that are never out of stock (core products, warranties,
service agreements, etc.) stock tracking may be an inconvenience. Therefore,
setting the stock tracking warning level to zero for such items is
recommended.
4.5
Statistics
CactuShop provides detailed graphical statistics of how many times each
product and category has been viewed. Each time a product or category is
displayed on the front end, a ‘hit’ record is added to the database. The back
end stats pages dynamically count these records and display data by month,
category and product, allowing you to view trends and compare what you are
selling with where people are looking. Statistics for the various products and
categories are now ordered in descending order of popularity.
4.5.1
Turning off statistical tracking
If you don’t require statistics, you can turn the system off from the config
settings. These stats can cause your database to grow in size and the more
traffic your site gets, the faster the database will grow. Disabling stats will
also speed up the product pages to a small extent.
4.6
Modifying a Category
Use the ‘modify the page’ link in the top right of the category page. You can
select whether a category is a normal category or a master category. You
cannot set a category to be a master category if it still has products
associated with it. Similarly, you cannot change a master category to a normal
category if it still has sub categories associated with it.
4.6.1
Deleting a category
Because of the database structure that enables products to feature in any
number of categories, deleting a category becomes a more complex operation
than before, both in terms of coding and the concept of what will actually be
deleted.
In order to preserve database integrity, it is clearly logical to delete ‘orphan’
records – the products and versions that belong to a category you are
removing. However, this can cause problems. What if you delete a category
and find that you’ve wiped out products that also belonged to another
category that you didn’t wish to remove?
This is why CactuShop has two delete options for categories. Option 1 is a
‘soft delete’ – it will remove products (and their versions) only where they
belong to the category you’re deleting. Where they belong to other categories
too, it will leave the products intact but just clean up the linkage with the
deleted category. Option 2 is a ‘hard delete’ - it will remove the products
whether they belong to other categories or not. In this case, it will also clean
V25102002 Copyright 1998-2002 Cactusoft Ltd.
20
CactuShop ASP Shopping Cart – User & Developer Manual
up the linkages between those other categories and the products that have
been removed.
4.7
Modifying a Product
4.7.1
Featured items dropdown
You can highlight certain products by featuring them on the home page. The
order of products depends on the priority set with this dropdown. Zero means
not featured at all.
4.7.2
Large image view
In order to add or modify a large image view, you must check the box
provided. This will lead through to an extra page after the product record is
updated from where a new image can be uploaded.
4.7.3
Products can appear in more than one category
One of the major structural changes in v4 is that products can feature in any
number of categories. So ‘anti-backdraft sunglasses’ can be seen in both the
‘equipment’ and ‘clothing’ sections of our demo, for example. Consequently,
products can also be accessed for editing through any of the categories they
belong to within the back end.
4.7.4
Adding ‘related products’
Click the RELATED PRODUCTS link located under each product in the category
page. This will spring a pop-up window. Select the category of the product
and then the product, then add it. Finally, confirm the products and they’re
saved to the database.
4.8
Modifying/Cloning a Version
Click on the ‘edit’ icon by a version in order to edit it. The same rules apply as
for editing products, including the method of uploading large view images.
4.8.1
Cloning versions
Because of the way CactuShop allows you to create versions of products, it is
often the case that you will have several different colour and size
combinations. In order to minimize data entry for what are essentially similar
items, cloning has been introduced. By cloning a version, you bring up that
existing version’s details, but can make changes to it and submit it to create a
new version.
4.9
Customer Database Admin
4.9.1
Basic operation
Each time a customer first orders through CactuShop, a customer record is
created. Because the email address is required to make an order, the shop
can find if that customer has an existing customer record and use that for
reordering. For more information, see 3.10.
4.9.2
Creating customer records from the back end
Customer records can also be created from the back end, so existing clients
can be set up and given the appropriate discount without needing to make a
prior order through your store.
V25102002 Copyright 1998-2002 Cactusoft Ltd.
21
CactuShop ASP Shopping Cart – User & Developer Manual
4.9.3
Customer record listing
Customer records can be looked up using the email address (or any part of it,
such as just the companyname.com part). The ‘list orders’ link will show a full
list of all orders that customer has made.
4.10
Affiliate Admin Section
4.10.1
Basic operation
Affiliates are other web sites who are paid commission for putting either web
traffic or orders through to your web site. CactuShop tracks both clickthroughs (visitors) from affiliate web sites and the value of orders
subsequently made by those visitors. Detailed stats for both are available and
the system also calculates the commission due for any month in the last year.
4.10.2
Technical implementation
Affiliate sites can post a coded hyperlink pointing to your aftrack.asp page.
They can also post a redirect page address to this as a querystring, in order
that customers can end up on a specific page of the site. The coded hyperlink
should look something like this:
http://www.cactushop.com/asp/aftrack.asp?ID=2&Req=product.asp?product=7
Where ‘ID’ is the affiliate ID number and ‘Req’ is the page to redirect to once
the affiliate data has been logged.
The aftrack.asp script records the following information to the database if the
affiliate number is a valid one:
a.
b.
c.
d.
HTTP referer: the address of the page where the user clicked from
Remote address: the IP of the user who clicked the link
Requested page: the ‘Req’ value above
Date and time: time stamp for the record.
Users also have a cookie planted on their machine containing the affiliate ID
of the link they came in from. If they order from the web site, this ID number
is read and the affiliate is credited with the sale. For more information see
3.9.3.
4.10.3
Approving, setting up and modifying affiliates
Affiliate records can be created and edited in a similar way to customer
records. When the listing of affiliates is displayed, it shows which have been
approved. Affiliates that have just signed up should appear at the top of the
listings on the default page and the ‘approved?’ field should be blank. To
review the affiliate application, click on the edit icon. The commission level
that the store owner wishes to grant them can be set, and a password MUST
be assigned to them. When the submit button is pushed, the details are
updated and an email is automatically sent to the affiliate with the details of
the hyperlink they must post on their site, their commission rate and their
password.
4.10.4
Viewing statistics for affiliates
This works in a very similar way to the main stats system (section 4.5). The
total amount of clicks, order value generated and commission can be looked
up by month.
V25102002 Copyright 1998-2002 Cactusoft Ltd.
22
CactuShop ASP Shopping Cart – User & Developer Manual
4.11
Email List Management
Having the facility to let visitors and customers signup to an email newsletter
is a valuable way of keeping in touch with those interested in your products.
Users can signup via the mailing list box on the site, the ‘make enquiry’ form
or when making an order.
4.11.1
Spamming
Spamming is a modern-day scourge. It is the act of sending bulk unsolicited
emails to users who have not consented or requested them. Spam increases
the overhead on networks and irritates the recipients. The cost of spam in
Europe alone has recently been estimated as billions of Euros per year.
Consequently, most networks will remove users who spam. This can cause
problems if your legitimate mailshot is interpreted by a recipient as spam
because their address was signed up maliciously by another user, or they
forget they signed up.
To counter this, CactuShop’s mailing list system uses best practice ‘doubleoptin’. When someone signs up, a link in a confirmation email is sent to them.
Only if they click this link (thereby confirming that they own the email
address) will they be added to the mailing list. The confirmation mail includes
the IP address of the person signing up and this is stored on the database
too.
We believe that the benefits of true, verified, double-optin mailing lists cannot
be overstated. Our own list has nearly 10,000 subscribers and we’ve never
had a single spam complaint. Double-optin is the only method to protect your
mailing list from false signups.
4.11.2
Send mail
You can mail all the confirmed subscribers to your newsletter from CactuShop.
Since users can opt for either plain text or HTML email, you can put two
different versions of the email body text into the fields provided.
4.11.3
Copy to clipboard
If you wish to export your mail list to an external program, you can easily
copy and paste it from here.
4.11.4
List/find
You can view the most recent signups or look for particular people with the
search feature.
4.11.5
New/edit address
You can create or edit email address records.
4.11.6
Purge unauthorized addresses
If users don’t authorize their signup within a reasonable period, the record is
effectively useless because CactuShop will not send mail to users who have
not verified their email address by clicking on the link in the confirmation mail.
CactuShop can clean the database of these records in order to reduce the
database size.
V25102002 Copyright 1998-2002 Cactusoft Ltd.
23
CactuShop ASP Shopping Cart – User & Developer Manual
4.12
Searching for Products or Versions
In a large store or any database system with numerous records, items
occasionally get filed in the wrong place. If you accidentally put a product or
version in the wrong category, finding it again can be a difficult task. The
back end search is designed to help you find items quickly, especially if you
are not sure which category they are attached to.
The search will find both products and versions where the name, description
or product code (or part of them) matches the search text you have entered.
This means you should be able to find items even when the product code has
been incorrectly entered or you can only remember basic details about the
name or description.
4.13
Closing the Shop
From time to time, you might be making a major update such as uploading a
modified database file or changing prices across the system. During these
periods, it is a good idea to close the shop. Clicking the ‘close the shop’ link
will end all current user sessions and prevent new users from starting to use
the shop. A ‘temporarily closed’ message will be displayed on the site.
4.14
Switching Products or Categories Off
If you have seasonal goods, products that are out of stock, or are carrying out
updates to the site one section at a time, you will likely want to keep the shop
open but just close that section off.
You can temporarily suspend products and categories by editing that item and
unticking the ‘show on site?’ box. You should switch off products that contain
no versions until such a time as you have added versions.
4.15
Customers
4.15.1
Finding/creating/modifying records
You can list or find customers (by name or part of email address). You can
then edit these customer records or add new ones, applying a discount for
future purchases if you choose. This is a useful way of giving valued
customers an incentive to use your site.
4.15.2
Cross linking of customer and order records
You can pull up a customer record from an order record or vice versa by
clicking on a link in the respective records.
4.15.3
Purge incomplete
On the front end of the site, customer records are added as a user fills out
their details while buying items. However, if the record is incomplete or
contains errors and the user then quits the site, it cannot be used
subsequently when that user comes back. In order to clean up the database,
these records can be purged from time to time. This will not affect valid
customer records – it just removes fragmented and incomplete data that is of
no further use.
V25102002 Copyright 1998-2002 Cactusoft Ltd.
24
CactuShop ASP Shopping Cart – User & Developer Manual
4.16 Orders
4.16.1
Reviewing orders
CactuShop stores orders in the database and these can be reviewed online.
For security reasons, card details are not stored, but everything else is. The
items and quantities, shipping charge, tax and discount (if any) are all
available, as is the text of the order email.
4.16.2
Invoicing
The stored information is used to produce invoices by simply clicking a link.
4.16.3
Order progress and status
There are four checkboxes that allow you to set the current progress of the
order from it being sent to the store to invoicing (if payment by PO number),
shipping and payment. There is also a text field where the store owner can
add comments that are available to the customer through the ‘my account’
feature on the front end.
4.16.4
Turning off order progress system
If the store owner does not intend keeping order progress and status up-todate (this obviously requires a time commitment), it can be switched off from
the ordertracking config setting. This does not change anything on the back
end, but removes the order status and progress sections from the ‘my
account’ view. Order history is still available as before.
4.17
Tax Rates
Some items might have no tax (0%), others might have a standard rate, and
some items may even have a special rate. As default, CactuShop supports up
to 4 different tax rates, but adding more is relatively simple. Setting up these
tax rates is not to be confused with whether or not tax applies to certain
individuals because of their location. For example, in the UK even an item that
requires tax will be tax free to someone from outside the EU. The
determination of who pays tax rather than what items require tax is handled
in the next section.
4.18
Shipping Destinations
A web site is accessible to users across the globe and you want to be able to
deal with those users as smoothly as you deal with customers in your own
country. You also want to be able to offer them the best price that you can.
4.18.1
Charge tax by country
A UK company needs to charge VAT (sales tax) to customers in the UK and
Europe but those outside of the EU are not required to pay this tax. Deciding
on whether residents of a particular country must pay tax is something you
might want to check with your tax authorities or accountant. In some
countries like the US, tax may also be different depending on the state or
province the customer is in. In this case, we would advise adding US states to
the dropdown menu from the US destinations table included in the database.
You can then treat these as different tax jurisdictions.
4.18.2
Shipping zone
Shipping to different locations costs different amounts of money. CactuShop
lets you place each country into a shipping zone – each zone will have a
V25102002 Copyright 1998-2002 Cactusoft Ltd.
25
CactuShop ASP Shopping Cart – User & Developer Manual
different scale of charges applied to it. As default, zone 1 is domestic (UK),
zone 2 is regional (Europe) and zone 3 is worldwide. Depending on the
location of your shop, you may need to adjust these settings, making your
own country zone 1 and working outwards from there. To add more shipping
zones, create a new set of band records in the tblCactuShopShippingRates
and a new zonearray name in the config settings.
Shipping is also dependent on either the total value of the order or the weight
of the order. Which of these factors is actually used is decided by the
calcshipcostbyweight setting in the config.asp file. Default of “n” will result
in shipping costs being calculated based on order value. Change the value to
“y” for shipping cost based on weight.
4.18.3
ISO country code
WorldPay and other payment systems need to know the country where goods
are being shipping to. Because country names can often be quoted in
different ways (UK, England, Great Britain, GB, etc.), standardized ISO codes
are often used. You probably won’t need to change these, but if you do, you
can do it here.
4.18.4
Country name
Some parts of the world like their coups and revolutions and seem to change
their names on a regular basis. Keep up with foreign affairs by listening or
watching to the BBC World Service and help keep your CactuShop country list
up-to-date. Hey, those ISO codes might even change too…
4.18.5
The country ID
This is just the database ID used for that country’s record. You don’t need to
do anything with this but it can sometimes be useful during development.
4.19
Shipping Rates
Shipping rates for the three zones specified in the tblCactuShopDestination
can be set here. The order value (or weight) that a particular shipping charge
applies to can be set independently. You could increase shipping with price
band but give the biggest orders free shipping to encourage customers to
spend big.
4.20
News Items
You can easily add up to three news items here for display on the front of the
site. The news items are added from the back end of the site and are stored
in the database - no FTPing required.
4.21
Static HTML Product Gateway Pages
4.21.1
The debate over search engine indexing of database sites
All serious e-commerce web sites use dynamically generated pages created
from information stored in an online database. However, those vendors selling
lightweight e-commerce products often argue that static HTML pages are
better because they can be indexed by search engines, whereas database
content cannot. In the past this was true. However, since most major news,
e-commerce and general interest sites are now databased, search engines
have made major advances in indexing dynamic content. Otherwise, they
would miss the best parts of the web! But just to be on the safe side,
V25102002 Copyright 1998-2002 Cactusoft Ltd.
26
CactuShop ASP Shopping Cart – User & Developer Manual
CactuShop now includes a facility to build static versions of the product pages
automatically – so you get the vast benefits of using a database, with all the
benefits of static HTML too.
4.21.2
Creating the static pages
On the gateway pages screen, just click the link. The system will build a series
of static pages, one for each product. It will also generate a static default.htm
document that links to all the static HTML pages. This document is linked to
by a hidden image on the front of the web site, ensuring that a search engine
can follow through the pages and index them.
4.21.3
Products no longer on the site
No facility is built in for removing pages of products that are no longer
present. You should keep all static HTML pages where possible because each
may have search engine links to it that will result in lost sessions if users click
to come through to your site only to get a 404 ‘page not found’ error.
If a user clicks through from a gateway page but the product is no longer
available, they will simply get a ‘product not available’ message once they
click on to the CactuShop product page. At least this way they still arrive
successfully at your site and can search for other products.
4.21.4
Folder permissions
The HTML folder must be set to allow the Internet Guest Account to write to it
(as for all image upload folders). If this permission is not set, the attempt to
create static pages will fail and an error message will display.
V25102002 Copyright 1998-2002 Cactusoft Ltd.
27
CactuShop ASP Shopping Cart – User & Developer Manual
5
Online Payment Methods – Setup
5.1
Setting Up WorldPay Select Junior
For further WorldPay information, see www.worldpay.com
WorldPay is a major provider for online credit card transactions. By using the
scripts provided, CactuShop can easily be configured to use WorldPay for
payment. You will need WorldPay to set up an account for you on their
system. The CactuShop software handles the entire ordering process and
formats the customer and order details in a form for submission to WorldPay.
The customer then inputs credit card details at WorldPay's secure site. Once
the transaction has been completed, WorldPay informs your CactuShop, which
updates its records to show the status of the transaction and sends order
notification to the store owner and customer (if required).
One big advantage of using an external card payment system like WorldPay is
that you do not need to implement SSL on your site since the card details are
entered on WorldPay’s system.
Some configuration to your account must be done at WorldPay's Web site
(WorldPay will have supplied you with access details). This is referred to as
WorldPay's Merchant Management System.
The WorldPay scripts are
- WORLDPAY_mailorder.asp
- WORLDPAY_callback.asp
and should all be in the ASP folder of CactuShop
To switch CactuShop to use WorldPay, you must edit the config settings under
‘Miscellaneous’.
paymentsystem (string)
This should be set to “WORLDPAY”.
The WorldPay payment scripts are configured from the
WorldPay part of the config settings. The details of each entry are as follows:
WP_CallbackPassword (string)
This is an added security measure. Set a password or phrase
here and then set up the corresponding phrase in the WorldPay
merchant management system. WorldPay passes this back to
CactuShop after the transaction has completed.
WP_CallbackURL (string)
This is where you want the user to return after the transaction
has completed (most likely your homepage). The purchaser will be
given a hyperlink to return to this location. Do not confuse this with the
callback setup at WorldPay’s site (which will be the full URL to
WORLDPAY_callback.asp.
WP_EmailCustomer (string)
Whether you want CactuShop to email the customer when an order
V25102002 Copyright 1998-2002 Cactusoft Ltd.
28
CactuShop ASP Shopping Cart – User & Developer Manual
goes through. Alternatively you can get WorldPay to send the emails
(see WorldPay's Merchant Management System).
WP_EmailMerchant (string)
Whether you want CactuShop to email the store owner when an order
goes through. Alternatively you can get WorldPay to send the emails
(see WorldPay's Merchant Management System).
WP_InstallID (numeric)
The Install ID given to you by WorldPay
WP_ISOCurrencyCode (string)
Currency code... GBP for Great British Pounds... USD for United
States Dollars... check WorldPay's documentation to find the code
for your currency.
WP_testmode (numeric)
If this is set to 100 whilst you are testing, then all transactions will succeed. If
set to 101 all transactions will fail. See WorldPay’s documentation for more
information.
WP_WorldPayURL (string)
The default value is https://select.worldpay.com/wcc/purchase,
the URL of
WorldPay. It is very unlikely this will change. Don't touch it unless WorldPay
tells you to.
Within WorldPay's Merchant Management system you must setup
the following (in addition to standard setup info)...
- callback password (should be same as CallbackPassword in the
WorldPay config settings)
- use callback enabled should be set ticked on
- use callback response should be set ticked on
- the callback URL - this should be where your
WORLDPAY_callback.asp page is located. This MUST be accessible
from the web as WorldPay will call the scripts.
Please review WorldPay's documentation. WorldPay gives you
the facility to customize the look and feel of their pages,
specify minimum transaction values and a whole lot more.
5.2
Setting Up Authorize.Net
For further Authorize.Net information, see http://www.authorize.net/
Authorize.Net is a major provider for online credit card transactions. By using
the scripts provided, CactuShop can easily be configured to use Authorize.Net
for payment. You will need Authorize.Net to set up an account for you on
their system. The CactuShop software handles the entire ordering process and
formats the customer and order details in a form for submission to
Authorize.Net. The customer then inputs credit card details at Authorize.Net's
secure site. Once the transaction has been completed, Authorize.Net informs
your CactuShop, which updates its records to show the status of the
transaction and sends order notification to the store owner and customer (if
required).
One big advantage of using an external card payment system like
Authorize.Net is that you do not need to implement SSL on your site since the
card details are entered on Authorize.Net’s system.
V25102002 Copyright 1998-2002 Cactusoft Ltd.
29
CactuShop ASP Shopping Cart – User & Developer Manual
The Authorize.Net scripts are
- AUTHORIZENET_mailorder.asp
- AUTHORIZENET_callback.asp
and should all be in the ASP folder of CactuShop
To switch CactuShop to use AUTHORIZENET, you must edit the config
settings under ‘Miscellaneous’.
paymentsystem (string)
This should be set to “AUTHORIZENET”.
The AUTHORIZENET payment scripts are configured from the
AUTHORIZENET part of the config settings. The details of each entry are as
follows:
AUTHNET_CallbackURL (string)
This is the full URL to AUTHORIZENET_callback.asp. Remember,
Authorize.Net will call this script from their server – it won’t work if you set
the name of a script that is not on a live webserver as Authorize.Net won’t
have access to it!
AUTHNET_ReturnURL (string)
This is where you want the user to return after the transaction
has completed (most likely your homepage). The purchaser will be
given a hyperlink to return to this location. Use a full URL beginning with http.
AUTHNET_EmailCustomer (string)
Whether you want CactuShop to email the customer when an order
goes through. Authorize.Net may also send its own email to the customer.
AUTHNET_EmailMerchant (string)
Whether you want CactuShop to email the store owner when an order
goes through. Authorize.Net will send its own email to the merchant too.
AUTHNET_LoginID (string)
The Login ID given to you by Authorize.Net
AUTHNET_TestMode (string)
If this is set to TRUE whilst you are testing then no billing of credit cards will
take place. You should also set testmode within the Merchant Management
system to be safe. When you are in testmode the page where you enter your
credit card details will clearly state this at the top.
AUTHNET_AuthorizeNetURL (string)
The default value is https://secure.authorize.net/gateway/transact.dll
.
It is very unlikely this will change. Don't touch it unless Authorize.Net tells you
to.
Some configuration to your account must be done at Authorize.Net's Web site
(Authorize.Net will have supplied you with access details). This is referred to
as Authorize.Net's Merchant Management System.
Within Authorize.Net's Merchant Management system you must set up
the following (in addition to standard setup info)... Login at
https://secure.authorize.net and when then click the settings option.
V25102002 Copyright 1998-2002 Cactusoft Ltd.
30
CactuShop ASP Shopping Cart – User & Developer Manual
- on the manage URLs page, add the URL of your callback page (same as
AUTHNET_callback.asp) and tick to make it the ADC Relay Response Default
and Valid ADC or Receipt Link.
- on General settings, tick Test Mode. Remember to untick this when you
want to go live.
Please review Authorize.Net's documentation. Authorize.Net gives you
the facility to customize the look and feel of their pages and a whole lot more.
5.3
Setting Up Protx VSP Form
For further Protx information see http://www.protx.com
PX_CallbackURL
This is the URL of the Protx call back page on CactuShop.
PX_CurrencyISO
The transaction will be made in this ISO currency code.
PX_EmailCustomer
This setting (‘y’ or ‘n’) determines whether Protx will send a payment
confirmation to the customer or not. CactuShop will send an order
confirmation so the Protx one may be deemed unnecessary.
PX_EmailMerchant
This setting (‘y’ or ‘n’) determines whether Protx will send a payment
confirmation to the store owner or not. CactuShop will send an order email so
the Protx one may be deemed unnecessary.
PX_OrderDescription
Description of the transaction.
PX_Password
Your Protx account password.
PX_SubmitURL
The URL of the payment page on the Protx site. This is unlikely to change.
PX_VendorEmail
The store owner email address that Protx will send any mails regarding the
transaction to.
PX_VendorID
Your Protx vendor ID.
Protx will give you account details to enable you to login and admin orders
from their end.
5.4
Setting Up PayPal
For further PayPal information, see http://www.paypal.com/
Make sure that you have Instant Payment Notification (IPN) turned on in your
PayPal account settings (My Account > Profile > Instant Payment Notification
Preferences > Instant Payment Notification (IPN)) before integrating your
CactuShop with PayPal.
PP_Cmd (string)
Paypal command instruction. The default value is “_xclick” (without the
quotes). This is very unlikely to change.
PP_Business (string)
V25102002 Copyright 1998-2002 Cactusoft Ltd.
31
CactuShop ASP Shopping Cart – User & Developer Manual
Your paypal account name (the email address you use to login to your paypal
account).
PP_NotifyURL (string) (optional)
This is the URL of the PayPal call back on your CactuShop. However if you are
only using your PayPal account for CactuShop transactions then you can enter
the notification URL on your PayPal configuration (My Account > Profile >
Instant Payment Notification Preferences > Instant Payment Notification (IPN)
URL).
PP_PayPalURL
The URL of the payment page on the PayPal site. The default is
https://www.paypal.com/cgi-bin/webscr, and is very unlikely to change.
5.5
Setting Up Verisign Payflow Link
For further Verisign Payflow Link information, see
http://www.verisign.com/products/payflow/link/
VS_Login (string)
This is your login name for Verisign – this information should be supplied to
you by Verisign when you set up your account.
VS_Partner (string)
This is your partner for Verisign. If you sign up through the Verisign site
directly this is generally ‘verisign’.
VS_Type (string)
This is Verisign’s ‘type’ attribute. It is very unlikely this will change. Do not
alter this unless Verisign tells you to.
VS_VerisignURL (string)
This is the URL of the secure payment form on Verisign’s web site. The
default value is https://payflowlink.verisign.com/payflowlink.cfm. It is very
unlikely this will change. Do not alter this unless Verisign tells you to.
5.6
Email Notification - Unencrypted
The default method for alerting you of orders is by email. Two mails are
formatted, one containing a confirmation of the order is sent to the customer.
The second, containing credit card details and order details, is sent to the site
owner.
Caution: This email is NOT secure and we would therefore advise that this
method is not used other than for testing/demonstration, etc.
5.7
Cactushop Encrypted Mail Add-on (“CEM”)
If you want to send secure email, we have a CactuShop add-on which
includes script-based single & triple DES encryption. This is not a part of the
standard CactuShop product - it is an extra. For pricing check our online
order form.
Please note: the encryption add-on only encrypts mails sent from the site –
it does not encrypt data passed between the browser and webserver and
therefore should only be used on sites using SSL (see 5.9 below).
There are 3 main steps to setting up encryption.
V25102002 Copyright 1998-2002 Cactusoft Ltd.
32
CactuShop ASP Shopping Cart – User & Developer Manual
5.7.1
Generating a key
DES, the encryption algorithm used in CEM normally uses a 64 bit key which is
reduced to 56 bits by excluding parity bits. 56 bits is effectively 56 binary 1s
or 0s. Each extra bit doubles the number of possible keys so a 56 bit key
would take twice as long to guess as a 55 bit key.
CEM also supports triple DES, an algorithm which repeats DES 3 times with
different keys giving a key size of 168 bits – therefore taking billions of times
longer to guess.
Cactushop represents DES keys in Hex code. Hex is base 16 to to count from
zero to 15 in hex is 0123456789ABCDEF. 16 is therefore represented by 10.
each character of Hex represents 4 bits or binary items. Therefore a 56 ( 64)
bit key can be represented by 16 hex characters and a triple DES key by 48.
Cactushop can automatically tell the difference between a 56 and 168 bit key.
Here are two example keys:
Single DES (56 bit)
0123456789ABCDEFxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx
Triple DES (168 bit)
0123456789ABCDEF0123456789ABCDEF0123456789ABCDEF
You can see that single DES keys fill up the used keyspace with “x”
characters.
DES encryption is very complex and therefore slow especially when
implemented in VBscript form for the ASP pages. Triple DES may take 10-15
seconds to encrypt even on a fast server. Therefore you may prefer to use
single DES – it is certainly strong enough to make cracking it for obtain credit
card numbers uneconomic (breaking 56 bit DES still takes months using large
amounts of expensive computing power).
5.7.2
Enabling CactuShop to send encrypted mail
First the config settings must be edited. Under Encryption set encrypt = y and
encryptionkeyfile to yourkey.cek (cek is the default extension used for
Cactushop key files).
For security reasons the key is not stored in the database but in the
config.asp. Edit the config.asp file in the includes folder –
encryptionkey="1212121212121212xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"
where the string is the data of your key.
5.7.3
Setting up the decryption software
Once steps 5.7.1 and 5.7.2 are complete, putting through a test order should
result in an email being sent to the shop owner’s email address. This will
contain an attachment called something like order342.ce2 – this is the
encrypted order.
To install the decryption software, copy all the files provided to a directory on
the machine you will use to receive the orders by email. In Windows Explorer
V25102002 Copyright 1998-2002 Cactusoft Ltd.
33
CactuShop ASP Shopping Cart – User & Developer Manual
go to Tools > Folder Options > File Types > New and add ce2 as the new
extension. Then associate this file type with the .exe.
Now ensure that you create a key of the same name you set in point 5.7.2, eg
yourkey.cek and fill the content of this key with the hex string you formed in
5.7.1. You can do this either by running the keymanager from the CEM
decryption software or creating the .cek file in notepad and saving in the
same folder as your decryption software.
Now you should be able to open the attachment from your email package and
see it load in decrypted form in the CEM decryption software.
5.8
Secure Back End Review – Requires SSL
One further secure method of viewing orders is to set CactuShop to store
order text in the database and send you an email notification of new orders.
The credit card details can be viewed by logging into your back end and
viewing orders through SSL online.
To implement this method:
•
•
•
Change the config setting under Miscellaneous SaveInDB to “y”
Ensure your secure certificate on the site is setup properly
Ensure you connect to the back end with https as opposed to http (for
example, https://www.mycactushopsite.com/cactushopback/)
Since you are now storing credit card details in the database we would
suggest that for security reasons you hold the database OFF of the web space
to prevent the chance of someone downloading it.
5.9
Setting Up SSL
In order to accept information such as card details securely through your site
you will need to implement Secure Sockets Layer (SSL). SSL uses public key
cryptography to encrypt a link between a browser and server, securing the
information transferred across that link. Cactusoft cannot offer support with
setting up SSL (you should contact your ISP); the information here is provided
purely as an overview of the process and technology.
Please note: SSL is not required on your site if you are using a payment
gateway such as WorldPay. In this case credit card details are entered at the
payment gateways site where SSL will already be installed and running.
5.9.1
SSL issues
Running pages through SSL creates some issues for CactuShop. SSL pages
can’t read cookies placed by non secure-pages and you can’t pass parameters
via the URL (“GET”). Fortunately, CactuShop passes parameters via POST for
the last few pages of the order process. You should run the cart in non-secure
web space, but pass to SSL for the payment side. To do this, recode the link
in the shipto.asp file to use an absolute URL for the form handler. This URL
should begin https://, rather than http://. If some items (eg images) on a
page are not in a secure area and are coded with a non-secure absolute URL
then you may get a warning when browsing the secure area (“this page
contains both secure and non-secure items”). To prevent this, ensure that
image links are not absolute so that they will be called with HTTPS when
viewed on secure pages.
V25102002 Copyright 1998-2002 Cactusoft Ltd.
34
CactuShop ASP Shopping Cart – User & Developer Manual
5.9.2
SSL access to the database
Some ISPs will set up SSL for your domain on a separate physical machine
that the one which holds your CactuShop installation. Please note that the SSL
pages must have access to the database in exactly the same way as the nonsecure pages. Please check with your ISP that your database will be
accessible from the secure pages (ie the secure pages are on the same
machine as the rest of the site, or the database can be accessed from the SSL
enabled pages in another way). If the secure area is on a different machine
and cannot gain access to the database, we have a system called CactusPay
to handle this – this is also supplied with the Cactusoft Encrypted Mail system.
It works in a similar way to payment gateways.
5.10
Other Payment Systems
We are working on adding built-in support for other major payment methods
too. These will be available free for CactuShop full customers as and when
they’re available.
V25102002 Copyright 1998-2002 Cactusoft Ltd.
35
CactuShop ASP Shopping Cart – User & Developer Manual
6
The Config System
This is the “junction box” of the whole system and contains most of the
switches to configure the commonly used elements of CactuShop. In v3 and
prior versions, the config.asp file was a list of constants and settings that
controlled many elements of the store. On v4, this has been largely replaced
by a databased application variable system using the tblCactuShopConfig
table to store the default settings. The database connection string still needs
to be set in the config.asp file, but once this is in place, other settings can be
changed online from the back end.
6.1
Basic Operation
The config settings are stored in server memory, using ‘application variables’.
These values are created by the config.asp file if it cannot find existing ones
in memory or if forced to update from the back end config setup page.
Application variables are shared across all pages and users of the application.
Only one instance of each is stored in memory. Although similar in nature to
session variables, application variables do not time out and do not hog huge
amounts of server memory when the site is busy since all users share the
same single set of variables.
6.2
The License Number
Each copy of CactuShop has a unique license number that must be present for
any site using the software on the web. Each license number may only be
used for one site. The part of the code that builds the license number into the
page HTML may not be removed. Please see the terms and conditions if in
doubt.
6.3
Database Connection
The settings relating to CactuShop’s connection with the database still need to
be set up in the config.asp file. The settings are as follows:
DBtype
This can be either “access” for MS Access or “sql” for MS SQL Server. This
setting controls the syntax used in SQL statements that incorporate DELETEs
or dates (because these use slightly different syntax on the two database
formats).
datasourcename
Two sample strings are supplied, for either MS Access or MS SQL Server.
These will obviously need to be edited to reflect the name of your database,
machine name and/or password. You can also setup your database as an
ODBC (Open Database Connectivity) datasource. To do this, first open the
ODBC administrator. In Win2000, this is under “programs” but in older
versions of Windows it is called 32bit-ODBC and is a control panel. You need
to add a system datasource, selecting the Access file or SQL Server database
you wish to use and giving it a name. Scripts such as CactuShop can then link
to this database by datasource name without knowing the path to the file. So
your connection string will change to:
datasourcename=”myodbcdatasourcename”
Note that we don’t specify any file with ODBC connections – just the name of
the datasource. In theory, you can change the database type and providing
V25102002 Copyright 1998-2002 Cactusoft Ltd.
36
CactuShop ASP Shopping Cart – User & Developer Manual
you give it the same ODBC datasource name as before, the scripts do not
need to be changed. In practice though (as previously discussed) minor
changes to the SQL statements are needed when changing from Access to
SQL Server. We’ve built in support for this, hence all you need to change is
the DBtype switch.
cursortype
This setting can prevent certain types of operations such as recordcounts from
returning correct values. Different versions of database drivers and operating
systems require a different setting here. As default the cursor is type 3, but
after upsizing to SQL, you may find the cart functions erratically and
procedures that require recordcounts return –1. In this case, try changing the
cursortype to 1. The effects of wrong cursor type can be so erratic that it may
not be immediately apparent what the problem is. If the cart acts weirdly, try
this before tearing your hair out.
6.3.1
Other database types
CactuShop is only tested with MS Access 2000, MS SQL Server 7.0 & 2000 and
MySQL v3.23.49. Other versions of Access and SQL Server should work fine
providing your server has the correct drivers installed. Older versions of
MySQL may not support some SQL syntax used in CactuShop. No changes of
scripts are required. If you need an Access file in 97 format this can be
downloaded from our web site ‘further downloads’ page.
If you wish to use CactuShop with Oracle or other databases, we would
suggest starting by switching the DBtype to SQL syntax. We cannot offer tech
support for other databases that CactuShop has not been specifically designed
to work with however.
6.4
The Config Table
6.4.1
Basic operation
As previously mentioned, this largely replaces settings that were held within
the config file prior to v4. The database contains the name of the application
variable, the value to be stored in it, and an identifier ‘s’ or ‘n’ to designate
whether the variable is a string or a number. So although every value is
stored in the database as a string, it is possible to control what type of
application variable is created from these settings.
6.4.2
Changing config settings
To edit the config values, go to the cactushopback/default.asp page and click
the ‘Edit Config Settings’ link in the centre of the page. This will bring up a list
of all settings in groups. To change a setting, click the modify button, update
the value, and submit it. Once you have made the settings you wish to
change, you must click the ‘update’ link at the top of the edit page.
Important: the database values held are simply the default values that
CactuShop will use to create the application variables. It is the application
variables held in memory that the site uses to generate the pages. If you
change values in the database using the CactuShop back end, these
application values are automatically regenerated when you click the submit
button after changing a value. Remember that if you change config settings
on the database and upload this, these new settings will not take effect until
the server reboots or you edit one of the values from the CactuShop back end
and submit the change.
V25102002 Copyright 1998-2002 Cactusoft Ltd.
37
CactuShop ASP Shopping Cart – User & Developer Manual
6.4.3
Config settings table
Below is a detailed list of the config settings that can be changed from the
‘edit config’ page of the back end.
Please note: there is no error checking of these config values to ensure that
they are present, or that the values that you set are within the ranges
accepted by CactuShop. For example, many settings require a ‘y’ or ‘n’, but
CactuShop does not check to ensure your entered value complies. Entering
values outside of the specified ranges may result in the site behaving
erratically or simply not working. Be very careful whenever you edit the config
settings and keep a note of any settings you change so you can restore the
previous values in the event of errors.
ALLOWABLE LENGTHS
In order to error check database input of strings to ensure they don’t exceed
the length allowed in the database, we can set values to use in errorchecking. These values should be the same as the corresponding field size in
the database. If you change the size of those fields within the database, you
should update the allowable lengths to ensure error-checking continues to
work. If overlong string input is made to a database, some older Access
drivers will just truncate the data string, but SQL Server and newer Access
drivers will display a database error and the query will fail. All allowable length
settings are named in the following format:
[name of database field] + _AL
So for example CD_CardholderCompany_AL is the allowable length of the
cardholder company field.
BACK END APPEARANCE
The back end of CactuShop does not use the same ‘skin’ system used for
formatting front end pages. The page display properties are set here in the
config table.
back_pagealign (string)
Page alignment of back end pages
back_pagealink (string)
Active link colour for back end pages
back_pagebg (string)
Background image for back end pages
back_pagecolor (string)
Page colour for back end pages
back_pagelink (string)
Link colour for back end pages
back_pagetext (string)
Text colour for back end pages
back_pagevlink (string)
Visited link colour for back end pages
BACK END SECURITY
backendlogin (string)
The login for the back end admin section
V25102002 Copyright 1998-2002 Cactusoft Ltd.
38
CactuShop ASP Shopping Cart – User & Developer Manual
backendpassword (string)
The password for the back end admin section
CACTUSPAY
CactusPay is a payment gateway specifically designed for sites where the
secure area their web host supplies is on a separate Windows server to their
main web space.
CP_CactusPayURL (string)
Full web address of the CactusPay secure area
CP_CallbackPassword (string)
Password used by the secure area when calling back the order confirmation
page on the main web site
EMAIL SETTINGS
CactuShop sends mail to both the shop owner and customers for a variety of
reasons. To send email from CactuShop, you must have at least one of the
supported email methods installed and set up on your web server.
emailmethod (string)
This specifies which of the several supported mail methods, or the two test
modes, is used. The four methods currently supported are: ‘CDO’ (Microsoft
standard), ‘Jmail’ (www.dimac.net), ‘ASPmail’ (www.serverobjects.com) and
‘Persits’ (www.persits.com). The two test modes are ‘write’, which disables
mail sending and writes the email to the screen instead, and ‘off’ which simply
disables mail sending altogether. When developing sites on a local machine or
network, the test modes allow you to simulate formulating and sending mail
without having to install mail components or wait for mail to be sent and
received in order to check it is formatted correctly.
mailserver (string)
This is the address of the outgoing SMTP mail server. It might be an IP
address or in the form of smtp.cactusoft.com. CDO does not require a value
for this setting, but the third party components do.
ownerfromemail (string)
Email address the mail sent from CactuShop will appear to come from
ownername (string)
Name of the shop
ownertoemail (string)
Email address that mail from the web site to the site owner (orders, enquiries,
etc.) will be sent to
subjectline (string)
Subject line of order emails to the site owner
subjectline2 (string)
Subject line of order confirmation emails to the customer
ENCRYPTION
CactuShop has an optional crypto package that allows sending of secure email
orders from the site.
encrypt (string)
Specifies whether encryption is on (“y”) or off (“‘n”).
encryptionkeyfile (string)
V25102002 Copyright 1998-2002 Cactusoft Ltd.
39
CactuShop ASP Shopping Cart – User & Developer Manual
This is the name of the key used to encrypt emails sent with the DES
encryption add-on. This name should be in the form yourkeyname.cek. This
keyname will appear unencrypted at the head of the encrypted file to enable
the decryption client to know which key to use to decrypt. If you use multiple
CactuShops, you can use a different key on each and the decrypt software will
know automatically which key to use to decrypt every order.
MISCELLANEOUS SETTINGS
addtobasketlink (string)
This can be set to either link (l), textbox (t) or dropdown (d). The link setting
displays a hyperlink by each version that when clicked diverts straight to the
basket.asp page, and adds a single item. The textbox and dropdown options
go to the basket via the speedorder_process.asp page and can add multiple
items at the same time.
allowedimages (string)
This is a comma-separated list of the image types (extensions) used for
images. Files types other than these will be flagged as errors on the back end.
A slight performance gain could be achieved by removing file types not used
for product or version images.
allowenquiries (string)
Specifies whether the store will feature the ‘make enquiry’ facility or not.
calcshipcostbyweight (string)
Determines whether shipping cost should be calculated according to the
weight of items in the basket or the total value of items.
cookiename (string)
This is the name that will be used for cookies within this install of the
shopping cart - makes it easy to prevent multiple CactuShops on the same
server from clashing.
defaultcountry (string)
The default country cookie is set when the user first hits CactuShop and this
sets the default value of the ‘ship to’ dropdown. On the second visit, the user
will get the country that they selected on the last visit as their default.
extendedcatpage (string)
This determines whether the prodtype.asp page should include versions or
not.
extendedhomepage (string)
This determines whether the home.asp page should include versions of the
featured products or not.
headtitle (string)
Page title on back end pages
luhncheckON (string)
The Luhn check is a mathematical test of whether a credit card number is of a
valid format or not. It does NOT validate or in any other way determine
whether an order is fraudulent or not. The purpose is purely to detect genuine
typing mistakes where one or more characters may be incorrect.
minorderval (numeric)
This is the minimum order value of orders you wish to accept, before tax and
shipping - can be any value from zero upwards.
ordertracking (string)
V25102002 Copyright 1998-2002 Cactusoft Ltd.
40
CactuShop ASP Shopping Cart – User & Developer Manual
Order tracking lets users login and gain information on the progress of their
order. If you don’t wish to enable this feature due to the added workload of
updating order details, it can be easily disabled here (the link on the template
will also need to be removed manually).
paymentauthorizeallpo (string)
This setting determines whether the shop will give all users the ability to pay
by with a purchase order number (essentially asking for the store owner to
invoice you, arrange payment by cheque, etc.). If not, only those customers
who have been set to ‘approved’ in the back end can make orders in this way.
paymentsystem (string)
CactuShop supports several different payment methods which can run sideby-side. This field stores a comma-separated list of the various options that
you wish to make available to your customers. Note that you will still need to
configure the invidividual methods that you have setup accounts for – all this
setting does is determine which methods you make available in the dropdown
on the shipto.asp page. Note that the string should be lower case and contain
no spaces.
prodtypemenuasdropdown (string)
This setting specifies whether to display the category navigation menu as a
hyperlinked list or a dropdown menu (with automatic submission on change).
prodtypepagesize (numeric)
Controls the number of items shown on each category page – any more items
than this in a category and page links (next, previous and numbers) will be
automatically generated.
saveInDb (string)
Determines whether the full order text (including credit card details) are
stored in the database or not. This should only be considered if the server is
well secured and your database is stored away from the http/ftp-accessible
space.
saveInEmail (string)
Determines whether order emails sent to the store owner include credit card
details or not.
searchmaxrecs (numeric)
Controls the maximum number of records found in a search
searchpagesize (numeric)
Controls the number of items shown on each search results page – if any
more items than this are found then page links (next, previous and numbers)
will be automatically generated.
shiptaxband (numeric)
Determines which band of tax will apply to shipping charges. Note that this
value MUST correspond to one of the four tax bands set up on the tax rates
page (i.e. 1, 2, 3 or 4). Zero is NOT a valid tax band – if you don’t wish to
charge tax on shipping, select a tax band that corresponds to a rate of zero.
showbasket (string)
This setting controls how the basket behaves when an item is added to it.
There are three options – ‘y’ means the basket will display when an item is
added to it, ‘n’ means that no basket will display (so the item will just appear
in the mini basket). The third choice is to set this value to a number – in this
case a message indicating that the item has been added to the basket will
V25102002 Copyright 1998-2002 Cactusoft Ltd.
41
CactuShop ASP Shopping Cart – User & Developer Manual
display for the number of seconds specified before redirecting back to the
product page. Note: CactuShop accomplishes the redirection using a metarefresh HTML tag. This is placed on the page by reference to the <head> tag
in your template. In order for this redirection to work, your template file
MUST include a <head> tag in lower case letters.
showtaxdisplay (string)
This allows tax to be removed from display so that only single prices are
shown and tax is not referred to. In order to use this, you should ensure all
items are set to a tax band of zero, since tax will still be calculated otherwise.
Please note that if you choose this method, CactuShop will remove tax
displays NOT calculate and show inclusive prices based on the tax you have
specified.
tracking (string)
This specifies whether statistical tracking is activated. Switching this off can
result in a small performance gain.
webshopname (string)
The name of the shop used within emails and on some pages
webshopURL (string)
The web address of the root of the CactuShop installation (not necessarily the
root of the web site if CactuShop is running in a folder on the site). A forward
slash should be included at the end. This URL value is used to form hyperlinks
to certain CactuShop pages within emails.
SHIPPING
zonearray(1) (string), zonearray(2) (string), zonearray(3) (string)
These specify the names of the three shipping zones. If you add more
shipping zones as detailed in 4.18.2, you will need to create new config
records for the names of these zones.
TEMPLATE
templatelocation (string)
This is the path of the skin template file used to format the front end pages
UNITS
currencyexplanation (string)
A brief explanation of what the currency name (perhaps an ISO code) means
currencyname (string)
Three letter ISO code or name of the currency for use in emails – many email
systems will garble currency characters such as £, so ASCII characters only a
recommended.
currencyunit (string)
Currency symbol for use in pages
weightunit (string)
Unit of weight used in pages
WORLDPAY
For information on setting up WorldPay, and the purpose of the various
WorldPay config values, please see section 5.1.
AUTHORIZENET
V25102002 Copyright 1998-2002 Cactusoft Ltd.
42
CactuShop ASP Shopping Cart – User & Developer Manual
For information on setting up AuthorizeNet, and the purpose of the various
AuthorizeNet config values, please see section 5.2.
PROTX
For information on setting up Protx, and the purpose of the various Protx
config values, please see section 5.3
PAYPAL
For information on setting up PayPal, and the purpose of the various PayPal
config values, please see section 5.4.
VERISIGN
For information on setting up Verisign, and the purpose of the various
Verisign config values, please see section 5.5.
V25102002 Copyright 1998-2002 Cactusoft Ltd.
43
CactuShop ASP Shopping Cart – User & Developer Manual
7
Language Strings System
7.1
Background
CactuShop v4.5 was a major departure from previous versions of CactuShop
in the way it handled non-product text on the pages. In v4.2 and before, this
general text was hard-coded into the ASP scripts. Wording such as the titles
on pages, names on buttons, and wording of auto-emails etc. were all hardcoded into the scripts.
Given this, producing a non-English version of CactuShop required some skill
in going through the scripts and translating the wording without inadvertently
damaging any of the functionality contained within the scripts. Furthermore, if
an updated script was released to fix a bug, or a new version of CactuShop
came out, the translation would be overwritten by importing the newer
scripts. This made it virtually impossible to keep a foreign language version up
to date with the current ‘master’ English version.
Even those in English-speaking countries would generally want to customize
the text on pages, and the same problems of overwriting these changes were
encountered when installing updates or new versions.
7.2
Advantages of the New Database System
Some other cart systems use simple text files to store the ‘language’ text.
These can then be replaced with foreign language versions as necessary. The
problem with text files is that they are difficult to work with, since searching
for the correct tag can be time consuming. They also mean the variables are
set on each page whether they are required or not. After some
experimentation and experience we opted for a databased system instead.
This allows the page to only pull out the values it needs and has some other
plus-points too.
Unlike text file language systems, working within the database gives more
functionality for sorting the strings and categorizing them into the area of the
software they apply to. MS Access in particular makes it very easy to sort by a
selected field. The database system also allows each record to have a
description indicating where and when that tag is used. This should make the
process of translation and finding particular tags much easier.
Finally, CactuShop is built with forward-compatibility in mind. Future versions
may well have extra language tags that are required for new features. Using a
database makes it easier to sort and import the new language tags, ensuring
that older translations of CactuShop can be brought up to date with the latest
version easily.
7.3
The Language String Editor
From v4.6 onwards, the language strings can be edited online from the back
end of CactuShop. It is simple to search for strings and replace them. This
way, you don’t need to take the database down each time you want to
change wording. Furthermore, the search capabilities in the online editor
make it easier to find and replace strings of text that by opening up the
database itself.
V25102002 Copyright 1998-2002 Cactusoft Ltd.
44
CactuShop ASP Shopping Cart – User & Developer Manual
7.4
The Language Strings Table
The text strings used throughout CactuShop are stored in the
tblCactuShopLanguageStrings table. Each record contains a number of
features:
7.4.1
LS_ID
The language string ID is a unique identifier used by the language string
functionality to pull the language tag from the database. It is a primary key
but as default is not set to auto-number. This makes it easier when importing
new language strings in the future.
7.4.2
LS_FrontBack
This is a single text digit to show whether this language tag record is used on
the front (f) or back (b) end of CactuShop. It can be useful in sorting the
records and allows for the back end tags to be translated separately from the
front end tags if required. This is useful for users who only wish to translate
the front end to their language and aren’t too bothered with doing the back
end since the translation is just for their customers’ benefit.
7.4.3
LS_Name
The name of the string is used within the ASP pages to pull the value from the
scripting dictionary. The names are broadly representative of what the tag
represents in English.
7.4.4
LS_Value
This is the actually display text that will appear on the page. It is this text that
should be translated and changed for foreign-language versions.
7.4.5
LS_Description
This is a description/explanation of this particular language tag. This text is
not displayed or used by CactuShop – it is purely guidance for translators and
developers working with CactuShop’s language strings.
7.5
7.5.1
The Language Strings Functionality
PageStrings
At the top of most pages, there is a constant called PageStrings set. This
string of numbers is used by the LoadStrings function in the config.asp file to
pull out the language tags required for this particular page. Each number is
the LS_ID value of the required string. There are also some strings that are
needed on every page (for the minibasket, etc.) specified within the language
strings code of config.asp.
7.5.2
LoadStrings
This function is called from the config.asp file and is located in the
functions.asp file in the includes folder. It formats a query to pull out the
required language tags on each page by LS_ID value. It creates a scriptingdictionary of all the values and their respective tag names (LS_Name). This
makes the pages easier to understand since language tags can be referenced
by name rather that a totally obscure ID number.
V25102002 Copyright 1998-2002 Cactusoft Ltd.
45
CactuShop ASP Shopping Cart – User & Developer Manual
7.5.3
WriteString and GetString functions
These functions pull the actual display text value from the scripting dictionary.
GetString pulls the value, WriteString pulls the value AND writes it to the
page. So areas where a string of text is built up but not written to the page
(email text for example) should use GetString, while you can shortcut having
to response.write the GetString value by using WriteString.
V25102002 Copyright 1998-2002 Cactusoft Ltd.
46
CactuShop ASP Shopping Cart – User & Developer Manual
8
Support
8.1
Scope of Tech Support
Cactusoft will offer tech support to customers through documentation
available from our web site, the knowledgebase and email.
For further details, see www.cactushop.com
We would ask all customers to follow through the tech support channels in
the following order:
a. Read this manual, especially the FAQ - 80% of the problems
notified to us are covered in detail already.
b. Search the knowledgebase – this online resource on our web site
contains questions that previous users have asked, with our answers
added. A few keywords should find any issues already listed if they
have been previously encountered.
c. Ask a question on the knowledgebase – we give priority to
questions added to the knowledge base. The answers will be entered
online and will be available to future users who may come across the
same issue. We do not publish the email addresses of those posting
or add them to a mail list – they are purely used for our admin staff
to contact the user for more details if required.
8.2
8.2.1
FAQ
What does the error ‘must use updateable query’ mean?
This is the most common problem reported by those trying to set up
CactuShop. Some pages work OK, even databased ones, but others seem to
generate this error. Please refer to section 2.3 for details on how to set up the
database with the correct permissions.
8.2.2
I get a 500 error. What does this mean?
Internet Explorer has an unhelpful setting to make error messages look more
‘friendly’. However, this is generally unhelpful as it seems to reduce the
amount of error information. To get clearer error messages, try this in IE:
Tools > Internet Options, then click ‘Advanced’ tab. Uncheck the box for
‘Show friendly HTTP error messages’ and hit ‘ok’. Once you have these clearer
error messages, try searching for the error (or part of it) in our
knowledgebase – most previously-encountered problems are there.
8.2.3
What is the database password?
The default database password is ‘cactushop’. This can be changed from
within Access.
8.2.4
What is the back end login and password?
The default back end login and password on the full version are both
‘cactushop’. For information on changing these values, see section 4.1.
8.2.5
Can I change the currency to dollars?
Yes, it is easy to change the currency displayed in CactuShop without
changing or messing with the international settings of your server. So even a
V25102002 Copyright 1998-2002 Cactusoft Ltd.
47
CactuShop ASP Shopping Cart – User & Developer Manual
company in the US can display prices in Euros if they choose. Please refer to
section 6.4 for details.
8.2.6
Can I have a full version for a trial period?
We have the lite version for this purpose. The basket is less robust and some
of the payment and extraneous functionality is missing, but it should be more
than enough to test the set up, customization and and operation of the
shopping cart. You can even design your skin and populate your database
using the lite version.
8.2.7
Will you do some modifications?
We will be happy to quote on any modifications you may need to CactuShop.
As a script-based system with a common database format, it lends itself very
well to modifications. We can either build entire systems based on it, or just
make small adjustments that you or your clients might require. However, we
don’t make modifications to the lite or full version on a speculative basis (“can
you make it do this and then send it to me and I’ll probably buy the full one”,
etc.).
8.2.8
Will the software run on Linux?
ASP can be run on Linux/Unix using third party software (see halcyonsoft.com
or chilisoft.com). However, CactuShop is designed, tested and supported only
on Microsoft platforms. We cannot guarantee that it will run on non-MS
platforms and cannot offer support for platform dependent issues on those
systems. We would therefore suggest setting up the lite version first to satisfy
yourself that the full version will run.
8.2.9
What is your upgrade policy?
We offer free upgrades to customers for a period of six months after the initial
purchase. This includes any equivalent new versions of the product (i.e. if you
purchased version 3 less than six months ago, you can get a free upgrade to
v4). If you obtain an upgrade in this way, we also permit you to upgrade
other CactuShop licenses that you purchased or own with the new code. If
you need to upgrade an older license, there is a £50 (British Pound) admin
fee, but you may upgrade other CactuShops you own with this. The charge is
purely for admin purposes, it’s not a new license.
8.2.10
Can I use a visual editor?
The ‘skins’ template feature is designed to make visually designing a site far
less problematic. The visual design and functional elements are separated
meaning your programmers can modify code while your designers work on
the appearance. The template is designed with no hidden code sections or
other features that might be distorted or misread by visual editors. However,
we would advise against editing the other pages in a visual editor, even newer
versions of FrontPage and Dreamweaver that claim not to modify code. A
good text editor such as the one with MS Visual InterDev is best. If you are
stuck with Notepad, try using the excellent free ‘Metapad’
(www.liquidninja.com/metapad/) instead – this is as small and quick as
Notepad but has essential code monkey features like line numbering and
multiple undo.
8.2.11
How does the licensing work?
The first copy of CactuShop you purchase is £200. Subsequent copies are
£100. Even if you bought a previous version, you are still entitled to the
V25102002 Copyright 1998-2002 Cactusoft Ltd.
48
CactuShop ASP Shopping Cart – User & Developer Manual
‘subsequent license’ pricing. For developers using large quantities of licenses
(more than 20 per year), please contact us for discounted rates. The license
number must be visible in the HTML code that the buildpage.asp include
generates.
8.2.12
How much is it in US Dollars?
CactuShop is £200, which at the time of writing is a little under US$300. Your
card will be billed £200 and the charge you will actually pay will be the
converted rate in your local currency plus any commissions your credit card
company might apply. If in any doubt about the exact amount in your local
currency that you will pay, please check with your credit card company first.
V25102002 Copyright 1998-2002 Cactusoft Ltd.
49