|
|
v1.23 Documentation
|
"The Document Is The Application,"
"Open Web Document Connectivity (OWDC),"
"The Htmlscript Developers Registry,"
"hts-connect," "Jyve,"
"Koolcat," "htmlscript"
and the htmlscript "blades" logo are
trademarks of Htmlscript Corporation. "NSAPI" is a
trademark of Netscape Communications Corporation.
All other trademarks are the property of their respective
owners. ©1995, 1996, 1997 Htmlscript Corporation.
All rights reserved.
|
I. OVERVIEW
II. INSTALLATION
III. PRELIMINARY PLANNING
IV. BUILDING YOUR CATALOG
V. CATALOG CONFIGURATION
VI. THE UPSELL SYSTEM
VII. EDITING CATALOG CONTENT
VIII. ORDER PROCESSING SYSTEM
IX. DATA STRUCTURES
I. OVERVIEW
An online catalog may be many different things depending on its actual
implementation. Essentially, a catalog is a collection if information
formatted to be navigated by those interested in it's
contents (i.e. potential customers). Catalogs are typically organized
into categories which contain selections of related items
(i.e. products) for the shopper to peruse. Items selected for
purchase are displayed to the shopper before the they commit to
"purchasing" them by entering information to an order form.
Upon submittal of the completed order form, the shopping
experience terminates, and the process of fulfilling the
customer's order begins.
The KoolCat System follows the above specified guideline, and adds
powerful features for the shopper and for the catalog
developer/administrator. The result is a robust and powerful
shopping/selling machine.
Catalog Functionality: The Consumer Perspective
Depending on how many catalogs have been created using the
KoolCat system, the shopper is shown either a catalog,
or a selection of catalogs to browse. Once a catalog is selected,
the system creates a uniquely named shopping basket file
which contains information on the shopper's trip through the
catalog, and and offers the shopper a choice of either browsing,
searching through, or closing the catalog. "Closing" the catalog takes
the shopper back to the main screen to select a different catalog.
- The KoolCat Shopping Basket System
For the purposes of this discussion, the first catalog
selected will be known as "Catalog A". The shopper
may choose, at any time during the shopping trip through
Catalog A, to bookmark their position in
Catalog A, go back to the main catalog page and shop
in Catalogs B, C, D, etc. before returning to their
bookmarked position in
Catalog A to follow through with a purchase by
filling out an order form. When
returning to Catalog A, the shopping basket file
created at the point of catalog selection will be
used to finish the shopper's trip through the catalog and
generate an order - as long as the shopper hasn't closed
the catalog. If Catalog A was closed before going
to another catalog, the next time Catalog A is
opened, a new shopping basket will be created with a
different file name.
Abandoned baskets expire after a specified period of time
which is configurable in the KoolCat Administration
System. If the shopper returns
to a bookmarked screen in a catalog and the basket file
has expired,
an error message will appear when the system tries to read
from- or write to- the basket file.
- The KoolCat Shopping Experience
The beginning screen of a selected catalog presents
the option to "Browse" through a selection of
categories in the catalog, to "Search" the entire
contents of the catalog, or to "Close" and move to
a different catalog (in the case that multiple catalogs
exist on the system).
- Browsing The Catalog
The "Browse Catalog" option gives the shopper a
similar selection, only the display table is
borderless and contains hyper-linked category names,
or hyperlinked graphics representing the different
categories in the catalog. Under the category
selection table, the shopper has the option to
view "Entire Catalog," or to return to the
"Main Menu" of the catalog.
- Searching The Catalog
The "Search" option gives the shopper a text
entry field for a search query, and a submit button.
Product names and or descriptions that match the
search query are then
displayed as hyper-linked text with thumbnail
graphics in a bordered, three-column table.
Thumbnail graphics are an optional component
of product records.
The selected category screen contains the current
category title or representative graphic at the
top of the screen. Product names in a selected
category display the same as they do in any screen
responding to a search query, but show the names
of all products classified under that category
selected. Below the product selection table, all
other category titles or representative graphics
appear as hyper-links. Standard "Back" and
"Return To Main" buttons appear at the bottom
of the screen.
- Product Display And Selection
A product selected from a category display
generates the display for that individual
product. A description of the product appears
under the product name. Below the description,
the price of the product appears centered in blue
text. Further down the screen, the product
display graphic appears with the product code,
weight of the product, and the current number of
such products currently in the basket. Options
to add to or remove from the basket a specific
quantity of the item are made available
to the shopper as are navigation options to go to
other categories, "Back," and "Main."
- Committing To Purchase And Ordering
As soon as products are added to the shopping
basket, new options to "View Contents of
Basket," and "Order Now!" become available
throughout the catalog's navigation. The shopper
may then either view and edit any of the
information in the shopping basket and continue
shopping, view and edit the contents of the basket
and fill out the order form, or simply fill out
the order form and commit to purchase. After the
order form is completed and submitted by the
customer, the optional upsell system selects a special
offer from a list of valid upsell items to give the
customer before writing the order to the order file.
The customer may either choose to accept the special
offer and add the upsell item to the order, or to
decline and submit the order as is.
- Order Confirmation and Processing
When the order is written to the order file, an order
notification email message is automatically sent to
the order notification list, and the final "Thank
You" screen is generated for the customer.
Prerequisites
The entire KoolCat System is written in in the htmlscript
4GL v2.99. KoolCat will run on any web server where
htmlscript v2.99 has been installed.
If you are a user on a system that has not yet installed
the htmlscript engine, you have one of three options:
- Refer Your ISP or Hosting provider to us
Get your system administrator to install htmlscript
so that you may begin using the KoolCat system.
- License KoolCat from an
"Official KoolCat Vender"
- Find an htmlscript-enabled ISP or Hosting Service in
hts-connect
Contact one of the many ISP's and Hosting Services
that offer htmlscript access for free with their service.
-
Become An htmlscript Licensee
Purchase an htmlscript license, and install the htmlscript
engine on your own web server or CGI-BIN. Many ISP's
offer a personal CGI-BIN with virtual domain accounts
hosted on their servers. If your ISP offers such a service,
install your own copy of the htmlscript engine and configure
it to run exclusively in your own CGI-BIN directory.
Administration System
Creating online catalogs with the KoolCat System is as
easy as filling out a form. No HTML or programming
experience of any kind is necessary to build and maintain
catalogs using KoolCat. However, advanced knowledge of htmlscript,
and web development in general, will make the configuration and
functionality of your
finished catalog system more robust. The administration system takes
information entered to its forms and writes that data to
catalog-specific files from which the run-time module can
later read to generate catalogs.
Maintaining catalogs, and processing their orders is very easy.
Generate shipping and accounting reports from order batches
that you control. Edit any order or delete it if
necessary. When order batches have been fully processed,
an archiving system lets you save those order records for
future use. The system may be configured to email you, as
well as your order processing departments, when a new
order is written to the catalog's main orders file.
With a single installation of KoolCat, you may create
any number of catalogs which contain any number of
product categories which may contain any number of products.
Each product in the catalog may contain an unlimited number
of attribute selections associated with it for specifying
sizes, colors, flavors, makes, models, comments, etc.
Upsell System
Optionally, you may use the upsell system to assign a special
discount price to a list of selected products and assign a specific
list of other "prerequisite" products to each item in the upsell
list to ensure that upsell products are logically offered.
Run-Time System
Depending on the number of catalogs you've created using the
Administration system, the run-time system will display either
a single catalog, or a selection of catalogs for the
shopper to visit. As the consumer begins navigating a catalog
created with the KoolCat System, a shopping basket file is
automatically generated with a unique name and updated according
to the decisions made by the user during their shopping trip.
Different catalogs created by the same system will generate
different shopping basket files.
The user may fill their basket with products from any category
in the catalog - adding or deleting any quantity of items at
any time. When the shopper has finished shopping and filled out
the order form, the upsell system chooses an appropriate item to
display with a special price that is good only at that very moment.
The upsell system will not try to sell an item at the special
upsell price if that item has already been added to the shopping
basket. Shopping basket files left untouched within a specified
period of time are subject to possible deletion.
II. INSTALLATION
KoolCat installs the same way as any
htmlscript application. Copy files
containing htmlscript source into your
htmlscript applications directory.
Copy data files into a directory where
your htmlscript applications can read
and write data.
You can have KoolCat automatically installed into your user
account by visiting one of the
Official Venders
in our "KCVender" vending machine network.
Source code for the KoolCat v1.23 System is made up of three modules:
- The "Administration System" (kcadmin.hts) is
used to create and manage catalogs.
- The "Run-Time
System" (koolcat.hts) implements catalogs which
you've created based on the information found in
their associated data files.
- The optional
Data Converter (kcupdate.hts) changes the structure of all
your existing v1.0 data to work with the new v1.23 system.
Step-by-Step Installation Instructions:
If you've had one of our
Official Venders auto install KoolCat for you, the
following source code and data files should already be
in place for you to properly run the system.
- Install Source -
Place all source code modules
("koolcat.hts," "kcupdate.hts," and "kcadmin.hts")
into your configured htmlscript applications directory.
Edit "koolcat.hts" and "kcadmin.hts" to read and write
data files in the correct data directory relative to
your configured htmlscript data directory. A configuration
variable called 'mydatadir' contains a value which is the
name of the directory under your htmlscript data directory
where your KoolCat data files are (will be). The default
value of
"" for 'mydatadir' tells the application to read and write
data in your top htmlscript data directory. If your
data directory for KoolCat is a subdirectory of your
htmlscript data directory, you must enter the name of
that directory prepended to a forward slash (/) as the
value of 'mydatadir'.
EXAMPLE:
|
<LET mydatadir = "subdirectory/">
|
Following
are the line numbers in each where your must edit the
value of 'mydatadir':
- "kcadmin.hts" -- Line 36
- "koolcat.hts" -- Line 38
Note: If you are simply upgrading
your catalog system to v1.23, the only step necessary
after installing source files and pointing them to
the proper data directory, is to
convert your data.
-
Place data files ("kcaccess.dat," "koolcat.conf,"
"clrslist.dat," and "taxtemp.dat") in your
KoolCat data directory. This directory is specified
from within the source for each module as the value of
a configuration variable called 'mydatadir' (the default
value for 'mydatadir' in each module is "" - which
points to your top htmlscript data directory).
-
Create a directory called 'archive' under
your KoolCat data directory for order batches which
have been fully processed. The order processing
module will only move order batches to this
'archive' directory on your command.
If KoolCat has been auto-installed for you, the
"archive/" subdirectory should already be in place.
III. PRELIMINARY PLANNING
KoolCat's functionality is designed to simplify the task of
editing any of your catalogs' content, but it is a good idea
to start with a plan for your catalog before you jump in and
start building anything. When you are ready to begin building
the catalog, we suggest that you have the following items prepared
to help you stay organized:
- List of Categories
Group all of your products into a list of categories
- Product Database
Include the following information for each product:
- Product Code
- Product Title
- URL for thumbnail graphic
- Prices
- Regular Price
The price used for the standard
product display screen.
- Upsell Price
The price of the product when it is
displayed as an upsell item after the
order form has been filled and
submitted.
- Taxability
- URL for display graphic
- Description
Description of the product as it
will appear in the catalog
- Weight
Establish a standard measure of weight to use
for all of your products. If a product weighs
less than the standard unit of measure that you
have chosen, establish a numeric value for the
unit of measure (i.e. 0.5 lbs.) When the product
is later added to a customer's shopping basket,
the product's weight will be used to calculate
shipping charges.
- Product Category
- URL to Product Category Graphic
- Product Attributes
Products in your catalog may have and unlimited
number of attributes. List all attributes associated
with each product, and possible selections for
each attribute. Make sure to specify which attribute
prompts may contain multiple selections and which may
contain one single selection.
- Customizing Messages
Create all of the messages that KoolCat will
generate in your catalogs:
- HTML Displays
Construct HTML documents containing all
of the information (text and graphics)
that will be displayed in the browser when
integrated with the rest of the catalog's
interface. Make sure that all <IMG SRC
references are hard, full path URL's to
the graphic, and that all <A HREF links
contain full path URL's to the actual
location of the link's destination.
- Catalog System Intro
The introduction to the catalog
system as a whole, and to its
selection of catalogs.
- Catalog Main Screen
The "Welcome" message on the first
screen of the catalog selected.
- "Thank You"
The "Thank You" message at the very
end of the shopping experience when the
shopper becomes a customer and fills
out the order form.
- Email Message to Order
Processing Department
The order notification message sent
to order processing departments and
to anyone else to be included in the
order notification list.
IV. BUILDING YOUR CATALOG
Accessing KoolCat in Your Browser
As soon as you've installed the KoolCat distribution into the
right directories on your server, you can go about building your
catalog by pointing your browser to run "kcadmin.hts".
KoolCat is an application written in htmlscript, and because the
htmlscript language is designed to be parsed and executed by
the Htmlscript Engine (which is a CGI program), you must specify
a URL to the application that will envoke the engine from your
server's cgi-bin to run it.
Following is the anatomy of such a URL:
EXAMPLE:
The above example applies when building catalogs using "kcadmin.hts",
and when running the catalogs you create using "koolcat.hts".
"file.hts" above may be preceded with a directory
name and slash if the directory where you've installed KoolCat is a
level below your configured htmlscript applications directory
("subdirectory/file.hts").
EXAMPLE:
|
http://www.server.com/cgi-bin/htmlscript?subdirectory/file.hts
|
Another possibility is that the name of the Htmlscript Engine
on your server is something other than "htmlscript." Consult with
your site administrator.
EXAMPLE:
|
http://www.server.com/cgi-bin/someprogram?subdirectory/file.hts
|
Getting Started
Run "kcadmin.hts" in your browser.
From the Administration System's main screen, hit
"Create New Catalog". The system will return with prompts
for catalog title and administrator password. After you've
re-entered the new administrator password, KoolCat will tell
you that a new catalog has been created and assigned a
Catalog ID#. When a new catalog begins life, all data files
associated with that catalog are initialized with the
Catalog ID# prepended to the string names of each respectively.
As a convenience, you may want to keep a log of
the catalog titles and catalog IDs created with the
system to monitor the maintenance of each different
catalog in your system.
Adding Categories
After you've gone through catalog creation, you may begin
the process of filling your catalog with it's content.
Hit "Contents of Catalog" from the main administration menu, then
hit "Add Category".
KoolCat is natively configured to look at catalog content
as a list of products where each product is associated with
one product category. The first logical step in
building your catalog is creating the names of these
product categories.
The text entry fields on the "Add Category" screen are designed
to accept both a URL to a graphic that will represent the category
and a string of text as the name for the category. If there is no
graphic to represent the category, the text entered to the "Category
Title" entry field will display in <H1> size where category
names appear. URL's entered to the field will cause the
graphic referenced by the URL to display in the catalog
wherever that category name appears. When the category name
appears as a screen header, the graphic will appear as a
display only. The graphic will otherwise display as a link
with a default border wherever categories display as menu
options for the end user or for the catalog administrator.
Add as many categories as you want. Categories display
in a three column borderless table.
Adding Products
Hit "Add Product" from the "Catalog Contents" menu and begin filling
the product information form. The process of filling your
catalog with products will be much easier if you've assembled
a product list confining all of the information needed for the
form. Following is a breakdown of all the fields in the "Add
Product" form:
- Product Code Text Field
The best product codes to use are those which
indicate the kind of product and it's associated
category. You may already have established an SKU#
system for your inventory. Product codes may only
contain alphabetic and numeric characters without spaces.
Note: Product codes must begin with
a letter, a number, or an underscore ("_"), may
contain no spaces, and may only be a string made of
alphabetic or numeric characters.
- Product Title Text Field
The name of the product as it will show in the
standard product display screen of the catalog.
- Thumbnail Graphic URL Text Field
Smaller "thumbnail" sized product graphic appearing
in a given category's product selection screen. The
graphic will display left-aligned and adjacent to the
product name in table cells of a bordered three column
selection table. Both the thumbnail graphic and the
product name will be linked to the standard product
display for the given product. If the product is one
that needs no thumbnail graphic, simply enter "none,"
and the product name will be all that's displayed in
the product category display.
- Product Price Text Field
Regular Price that will appear in the standard
product displays of the catalog. Upsell pricing
will be established later in the construction of
your catalog. Enter only numeric information here.
The KoolCat system
will format that numeric value to display with
U.S. money format and will also use it for various
calculations.
- Taxability
Whether or not the product is taxable.
- Product Image URL Text Field
Regular sized product display graphic appearing
in the standard product display screen.
- Product Description Text Field
The description of the product appearing in the
standard product display screen.
- Weight Text Field
The total weight of the product. Enter only a decimal
numeric value here. Shipping charges will be calculated
using the value entered, so string data will result
in unspecified outcome for shipping charges.
The default unit of measure for all products in the
catalog is pounds. This unit of measure will appear
next to the text entry field as it is read from the
standard shipping data file which was generated when
the catalog was created. Later, you will be able to
change the catalog's standard unit of measure if necessary.
- Product Category
Select the product's category from the list of radio
selections.
- Creating Attribute Prompts and Selections (Y/N)
KoolCat's product attribute management system lets
you offer
many different versions of the same product with
options like make, model, color, size, flavor, etc.
Select "Yes," then hit "Add Product" to submit
the product information entered so far. The system will
return with another form containing the following fields:
- Prompt Text
Enter text for the prompt which will instruct
the shopper how to specify the given attribute
(i.e. "Select Size").
- Selection Formats
Choose the type of form input device to be used
in the catalog to display attribute options for the
shopper. A response from the shopper is required
for all attribute selection prompts except those
formatted with checkboxes. Following are the
formatting options available and some examples
of each:
- Radio Buttons
(Single possible value)
Formats options under the prompt into
radio buttons from which only one may be
selected by the shopper.
- Checkboxes
(Multiple possible value)
Formats options under the prompt into
checkboxes. The shopper may select
one, several, or all of the options
displayed in this format. The limit for
attribute selection options formatted into
checkboxes using KoolCat is 15. This is
the only selection formatting device
containing a limit for options created.
- Scrolling Selection Box
(Single possible value)
Similar to the radio button format where
only one option in the selection may be
chosen, the selection
box format displays options in a scrolling
box for the shopper to peruse. This method
is of use when space is a consideration.
If there are many options to display for a
given attribute, they may all be fit into
this size-fixed selection device.
- Text Box (Single possible value)
If the prompt for the shopper will simply
be asking for a string of text as a specific
description of the product attribute, this
formatting selection will generate a text
entry field for the shopper to enter a
custom order, request, specific description
of the item, or any other kind of note.
After choosing a selection display method for
an attribute prompt, hit "Create". The next form to
appear prompts you to enter the text of the first
option in the list. Enter text for the first
option and hit "Add Option". Another "Add Option"
form then appears for you to add text for the
next option.
When creating a prompt with a text box, the
contents entered by the shopper in the text box
will be the only possible value for that attribute.
After submitting the text for the prompt, the
following screen will be a form to enter the next
attribute selection prompt for the product.
Each time the "Add Option" form comes up after
submitting information on another option, you may
choose to hit "No More Options" to cap off the
number of options for a given attribute prompt.
After hitting "No More Options," the responding
screen is a new form giving you the choice of
either adding another attribute prompt with a
new selection format or altogether terminating
the data entry for the product in question by
hitting "No More Data".
V. CATALOG CONFIGURATION
The catalog configuration part of the Administration System
lets you alter the way your catalog will behave in many
different ways. Here you can create a list of payment options,
and shipping methods, as well as establish the standard unit
of measure for calculating different shipping charges. You
can also create a custom tax table which your catalog will use
to calculate sales tax figures for the way that your company
does business. You may also want to apply some advanced techniques
to the way that your catalog will display and function.
Texts and Email
Hit "Texts / Email" in the configuration menu.
The form that appears is
a set of text entry fields which automatically generate
both HTML displays and email messages when shoppers
navigate a catalog and when orders
are submitted. The entry fields that generate HTML
displays may accept HTML, htmlscript, text, or a
combination of all three. The entry field which
generates the order notification email message must
contain text alone or text with htmlscript code.
Following is a brief explanation of how to use each of the
entry fields in the Message Customization form:
- Catalog Title
(Text Only)
Each catalog created with the system will
be accessible as a selection of many catalogs from
one place - both to you as the administrator, and to
your customers as they shop your catalogs. Text
entered to this field will be understood by KoolCat
to be the title of the catalog, and will be made available
as an option inside of a selection box containing
titles of all catalogs created in a given catalog
system. As customers enter the KoolCat catalog system,
they select from a list of catalog titles one catalog
at a time. Each different catalog generates a
different shopping basket and order record for the
same customer.
NOTE:
Text is the only acceptable data type for entry to this field.
Arbitrary results will occur when the entry for catalog
title contains HTML as an attempt to manipulate the display
of the catalog title in the catalog's start-up screen and
the catalog selection device. Selection boxes cannot contain
HTML. Since the same string of text will be used by KoolCat
to both display the title in the browser, and make it
available as a selection option.
- Introduction on Catalog Selection Page
(Text, HTML, or htmlscript)
When your catalog system is first loaded to a browser, part
of the content incorporated into its start-up is a welcome
message that appears to mark the beginning of the catalog
system, and to deliver information about you, your company,
and or the contents of the different catalogs in the system.
Content entered to this field will generate such a display
only if you create more than one catalog for your customers.
As you use the Administration System to manage your catalogs,
and possibly alter the configuration of one or another, this
field always appears in the "Customize Messages" form
regardless which catalog's messages you happen to be editing.
Make sure that any <IMG SRC... references to graphics
are full URL's to the graphic, and not simple paths
relative to a current working directory on your web
server. The KoolCat system will be run by htmlscript
in a specified directory, so relative
references to graphic files will not work.
EXAMPLE:
|
<IMG SRC = "http://www.server.com/images/graphic.jpg"...>
|
- correct
|
|
|
|
<IMG SRC = "./images/graphic.jpg"...>
|
- incorrect
|
- Introduction on Main Catalog Page
(Text, HTML, or htmlscript)
This field will generate the "Welcome" message that
appears below the title of a catalog when selected
from the main catalog system. As with the "Catalog
System Introduction" field, you may put any HTML or
htmlscript code here as well as plain text to generate
the greeting for your selected catalog. Remember to
reference graphics with full URLs and not relative paths.
- "Thank You" At Final Page
(Text, HTML, or htmlscript)
After shoppers have entered information to an
order form and committed to purchasing, their shopping
experience ends with a "Thank You" message. This
message may be as simple or as complex as you want.
To simply tell the customer "Thank You" and display
some contact information on your company with a graphic,
compose a basic HTML display and place it's content
into this field. You may also enter a simple text string,
like "Thank You for your order...".
To get more serious about what to tell the customer
after they've committed to spending their money, you
may want to construct a "thank you" message that
potentially gives them information on their order
(i.e. tax and shipping information, fulfillment
scheduling, etc.). This may be accomplished with
some very basic htmlscript coding that uses
variables created in the order form.
Included with the instructions that are built
into the "Catalog Texts and Emails" form, is a
list of variables available when constructing
the catalog's messages. These variables have no
values until the order form has been filled out and
submitted by the customer and a new record has been
written to the "*orders.dat" file. Because of this,
the variables in the list are only available for the
"Thankyou" browser message and for the email messages
sent by the catalog system since they all are generated
after the order form is filled out by the customer.
Available Variables
|
name
|
Shipping Name
|
|
shipaddress
|
Shipping Address
|
|
city
|
Shipping City
|
|
state
|
Shipping State
|
|
zip
|
Shipping Zip Code
|
|
country
|
Shipping Country
|
|
phone
|
Shipping Phone Number
|
|
fax
|
Shipping Fax Number
|
|
email
|
Shipping Email Address
|
|
company
|
Shipping Company
|
|
ship
|
Shipping Charge for Order
|
|
tax
|
Sales Tax on Order
|
|
total
|
Order Grand Total
|
|
ordernum
|
Order Number
|
|
|
bname
|
Billing Name
|
|
baddress
|
Billing Address
|
|
bcity
|
Billing City
|
|
bstate
|
Billing State
|
|
bzip
|
Billing Zip Code
|
|
bcountry
|
Billing Country
|
|
bphone
|
Billing Phone Number
|
|
bfax
|
Billing Fax Number
|
|
bemail
|
Billing Email Address
|
|
bcompany
|
Billing Company
|
|
cardtype
|
Type of Credit Card
|
|
cardname
|
Name on Credit Card
|
|
method
|
Shipping Method
|
|
startdatetime
|
Time order was placed
|
|
The htmlscript code necessary for evaluating variables
from the order form is as easy as <EVALUATE
variablename>. The following example is how the first
line of a "Thank You" message might look for the customer
to personalize the message:
"Thank You <EVALUATE name>,...."
will replace itself with the contents
of 'name' in the context of the particular order.
- Email to Order Processing Department
- Email address that sends a
message to order processing department (Must
be a valid email address)
- Subject of message sent to order processing
(Text Only)
- Body of message sent to order processing
(Text and htmlscript code)
Colors
Hit "Colors" in the configuration menu. The "Color Schemes" screen
lets you choose from a selection of existing color schemes and gives
you the power to create you own. Using a table of established
"names" for hex triplet colors, you can create and update new
and existing color schemes by choosing the names of colors
for different things in your catalog - like background, text, links,
selected links, viewed links, cells in basket contents tables,
cells in product list tables, and the cells in the table that makes
up the invoice.
After selecting an existing color scheme from the drop-down
menu, you may choose to either "apply" that color scheme to the
catalog, or to "update" the configuration of that color scheme.
Below, you can add other custom color schemes with their own
names, or delete existing color schemes from the selection.
Upsell System
KoolCat's upsell system is an optional configuration option
which allows the you to create a list of specially priced
products from which an "upsell item" is chosen to offer the
customer after they've submitted the order form. Please
see section VI. THE UPSELL SYSTEM
for detailed information.
Shipping Charges
Hit "Shipping Charges" from the configuration menu. The
responding screen contains a single field form for updating
the standard unit of weight measure for calculating shipping
charges added to an order. Below this form, a table displays
the following information on existing shipping methods:
- The name of the shipping method
- The rate charged per standard unit of weight measure
- The minimum charge for using the shipping option
regardless of weight
Hit the "Update Shipping Table" button after changing any of
the information in the text entry fields for each shipping method
listed or selecting one to be removed.
Hit "Add Shipping Method" to add new shipping options to the
table with the all above information.
Sales Tax
KoolCat is packaged with a pre-installed tax table containing
the standard sales tax rates
for the 48 contiguous American states, Alaska, Hawaii, The
District of Columbia, The US Virgin Islands, and Puerto Rico.
Each tax region (state) is left deactivated as a default.
Create your own custom sales tax configuration by either
activating, deactivating, or removing regions listed,
changing the pre-installed tax rate for a region (Default zero%),
or adding new ones with special tax rates.
To edit contents of the table, make your changes to the tax
table and hit "Update Tax Table." To add a new tax region,
hit "Add To Table" located below. Enter the name
of the tax region and the percentage figure (numeric
value only) for tax in that region.
Tax regions in the table left inactive will not display
in the order form selection box for the field named
"Region". If you plan to use data from the order form
to generate mailing or shipping labels, it is a
good idea to activate all of the states in the
pre-installed table, but to edit the tax rate to zero for all
of the states where you don't charge sales tax.
Payment Methods
Hit "Payment Methods" in the configuration menu. KoolCat
is packaged with a default selection of pre-installed
acceptable payment methods - all of which are credit cards
(Visa, American Express, and Mastercard).
To remove payment methods, simply check one or several of
the check boxes located beside each payment option in the
table and hit "Update Table". To add a payment method,
hit "Add Method" and enter the name of the payment method in
the single-field form provided. Payment methods will appear
in a pull-down menu as part of the order form.
Plug-Ins
This powerful feature of KoolCat is an option
for more advanced users of the system, and is
non-essential to bringing a catalog on line.
At nine different points in the catalog system, you may
incorporate content from any document or application
accessible via the WWW into your catalog without the
need of hosting that content on your server. The way
that KoolCat does this is by emulating a browser and
"calling" the remote host to make a standard HTTP
request. Documents and applications called by your
KoolCat catalog may also be hosted on the same
server as your catalog system.
Hit "Plug-Ins" in the configuration menu, and view the
form that appears. Eighteen text entry fields prompt for URL's
to different applications or documents, and sets of
radio buttons next to each entry field prompt for the method to
use in calling these applications or documents. For nine different
screens in the catalog
system, you may assign two different plug-ins to bring content into
the given screen - one as a "header" above the standard
content generated by KoolCat and another as a "footer" below.
When calling documents that are simple
HTML pages, use a method of "GET". When calling applications
written in htmlscript, use a method of "POST". Any kind
of code that can generate anything in a browser may be the
content of the remote document called into your catalog.
The most basic implementation of plug-ins is
to call static HTML pages that display
graphical menu bars and or any information about
your company - like trademark information. You may want
to use different plug-in pages for headers and footers of
different screens in each catalog.
The option of updating plug-ins assignment in the "Catalog
Selection Screen" appears while configuring plug-ins for each
catalog in your KoolCat system. While the plug-ins chosen for
screens 2 through 9 will display only in a given catalog, the
plug-ins chosen for screen 1, "Catalog Selection," will affect
your KoolCat system as a whole. If only one catalog has been
implemented in the system, plug-ins assigned to the Catalog
Selection Page will not appear as there will be only one
catalog in the system to shop.
Following are the screens in your catalog(s) for which you may
configure plug-ins for "header" and "footer" information.
- Catalog Selection Page
- Main Screen of Selected Catalog
- Category Selection Screen
- Category Contents Display Screen (Also, "View Entire Catalog" Screen)
- Search Results Screen
- Product Display Page
- Product Attribute Selection Screen
- Product Upsell "Special Offer" Screen
- Thank You Screen
Advanced Options
This option allows you to set a life span limit for abandoned
shopping baskets, and to specify a URL to the secure version of
KoolCat running on a secure server.
Abandoned Baskets
Each time someone begins shopping through your catalog, a
new shopping basket file is created containing information
on all of the purchasing decisions the customer makes
while in the catalog. If at any time during the shopping
experience, the customer needs to go elsewhere, they
can bookmark where they are in the catalog, actually turn
off their computer all together, and later return to the
catalog with their shopping basket intact. If the customer
forgets about the bookmark and the shopping basket, the
basket file will be there waiting for them until it
expires according to the life span limit specified in the
"Abandoned Baskets" configuration.
Baskets that have been used to actually generate a finished order
stay in the data directory until their associated order batches
are archived and deleted. Processing orders and order batches
is discussed in
Section IX. ORDER PROCESSING SYSTEM.
The "Advanced Options" screen shows the current shopping basket
life span configuration and provides an interface for
editing that configuration. Specify the number of minutes,
hours, or days that you wish to be the standard life
span limit for baskets that are left active without
generating a finished order. Complete the new
configuration by hitting "Update Catalog." Any baskets that have
been left abandoned for longer than your configured life span
will be deleted with their corresponding ".mem" files the next
time a new batch of orders is created. Again, the
baskets that have generated orders will remain until
they are deleted when their corresponding order
batch is archived.
Secure Transactions
If you will be running your catalogs and administration system
on a secure server, enter the URL to "koolcat.hts" as it will be
on your secure server.
Note that both the secure and non-secure servers must
utilize the same data space for KoolCat to function properly.
EXAMPLE:
|
https://secure.server.com/cgi-bin/htmlscript?koolcat.hts
|
For optimum performance, only the order
processing parts of the catalog and the administration system will
run in the secure environment. This field left blank will allow
the KoolCat system to run in standard "http://" mode.
VI. THE UPSELL SYSTEM
As shoppers explore your catalog, they will be making
purchase decisions that will lead up to an opportunity to
review the items they've added to their shopping basket.
When the shopper becomes a customer and fills out the order
form, committing
to purchase an item or a group of items, the Upsell System
gives the customer one last opportunity to purchase on impulse
while "their wallet is open at the counter".
Setting The Percentage Point
Select "Upsell System" from the Configuration menu, and
establish a percentage point at which the system will compare
the upsell price of an candidate upsell item to the subtotal
of the customer's order. If the percentage point is 75%, for
example, the upsell system will look through the list of upsell
items for items with a upsell prices which are less than or
equal to 75% of the basket subtotal.
The Upsell System performs a series of operations to determine
which products can and cannot be displayed to the customer as
upsell items. Following are the steps that are taken by
the system to weed out unqualified upsell items, and then
select an appropriate upsell item for a given purchase.
- The system looks through the entire list of upsell
items and considers only those with prices at or below
the percentage point set for upsell item candidacy.
- Any upsell item which has already been selected
at regular price may not be selected as an appropriate
upsell item. The upsell
system looks through the currently qualified list
of upsell items and disqualifies any upsell item
who's regular-priced counterpart is already in
the shopping basket.
- Product prerequisites are checked to verify that necessary items
have been purchased to offer the upsell item. For example, if
light bulbs are on special, you may not want to offer them unless the
customer is purchasing a lamp.
- From the the final cut, the upsell system then
randomly selects the single item that will be displayed
to the customer as a final opportunity to purchase at
the compelling upsell price.
- The selected upsell item is then displayed to the
customer with a "Special Offer" message explaining
that "If you act now, you can get the following
product at special discounted price of only $N, a
savings of $n off the regular price...", calculating
the savings when compared against the regular price
of the item as advertised in the standard catalog
display for that product.
Below the "Special Offer" message, all associated
product attribute prompts for that product are then
displayed at once with the product description and
product display graphic. The only possible quantity
of the upsell item to purchase is one.
The customer may choose to hit a single checkbox to
accept the offer, or they may choose to leave the box
unchecked - rejecting the offer, and then simply hit the
"Fill My Order" button.
From the Upsell menu, hit "Add Products", then select a product
from your "List Of Products and Codes" table to be added to the
upsell list of products. If you know the product code of a
given item, you can skip the selection table, and simply enter
the product code and upsell price to the "Add Upsell Product"
form, and submit this new upsell data by hitting "Add It".
The system then confirms that the product has been added to the
list of upsell items, and prompts for the next upsell item to
be added.
Updating Upsell Product Information
When all items have been added to the upsell list with
special prices, you can then go about grouping the items
in the upsell list with products in the regular priced
inventory. Hit "Update Products" in the Upsell System
menu and select an upsell item to update. The update
form will allow you to update the upsell price for the
product as well as edit the prerequisite table for
the product.
Left to default configurations, the upsell system will
consider an upsell product an appropriate candidate for
the sale even if the upsell product is not specifically
related to any of the products in the customer's basket.
This may be good if all products in a catalog are
inter-related, and if the upsell product chosen for one sale
could be the upsell product chosen for any sale in the catalog.
If, however, different categories in your catalog contain
items that are completely unrelated to products in other
categories of the same catalog, the upsell item chosen for
a given sale must be specifically valuable to that customer
in order for it to be an appropriate upsell item presented
for that sale.
A solution to this problem is the Prerequisite Table. To
selectively assign products as "prerequisites" for items in
the list upsell of products, hit "Update Products" from the
Upsell System menu. Pick a product in the "List Of Upsell
Products" to update, check the checkbox labeled "Update
Prerequisites Table", and hit "EDIT".
The Prerequisites Table displays below a header telling you
which upsell item you are currently updating. The table
contains information on all of the products in your
regular-priced inventory with a checkbox beside each product
labeled "Prerequisite". Below the table you may choose one
or many of the following:
- Select All
Regenerates the table with all of the checkboxes
checked as prerequisites for the upsell item.
- Deselect All
Regenerates the table with all of the checkboxes
"un-checked" as prerequisites for the upsell item.
- Update
If all of the products that you want to be
prerequisites for the upsell item in question
are checked, the "Update" button will cause the
system to update the data file to reflect the
new status of the upsell item.
- Done Updating
This button takes you out of the "Update Products"
system, and presents you with navigation options.
VII. EDITING CATALOG CONTENT
Literally anything entered to any catalog may be edited or deleted
at any time. Hit "Contents," and view the options available in
the responding screen. Products may be "moved" from one category
to another or deleted, and any information associated with any
product may be edited including product code, name, description,
etc. Categories may be created, edited, and deleted.
List of Codes and Titles
Throughout the "Contents" portion of the Administration System,
the option to view "List of Codes and Titles" is always available
where necessary. This button will list all of the products in
your catalog with their product codes, names, and the associated
category of each.
Editing Product Information
Hit "Update Product." If you know the product code of the
product that you wish to update, enter that code to the field
labeled "Product Code (Current)," and go directly to the field
needing the updated information. Once you've entered the new
information to all of the fields needing an update, hit "Update"
at the bottom of the form, and the record for that product in the
catalog file will be updated.
If you do not know the product code of the item needing an
update, hit the "List of Codes and Titles" button
and select a product from the table displaying products in
the catalog. The same "Update Product" form will then
return to the screen with all current product
information filled into the fields of the form. Change
the necessary product information, then decide if any of
the product attribute information will need editing as
well. If so, choose the check box for adding or updating
the attribute information at the end of the form and
hit "Update". A new table will display for updating
that product's attribute information.
The update table for product attributes displays each
attribute prompt that has been created for the product
and each attribute selection listed below each prompt.
This information is displayed in a column labeled
"Current" at the left of the table.
In the next column of the table, labeled "New", the same
information is displayed inside of different form input
devices for you to edit. The selection method for displaying
the attribute selections appears in a drop down menu to
change if needed, and the text for each prompt and attribute
is displayed in a text box for you to edit.
To the right of the "New" column, a "Remove" column
contains a checkbox for each prompt and option. Any
option may be removed alone or as one of several to
be removed at once. All items who's remove boxes are
checked when you hit the "Update Info" button at the
bottom of the table will be deleted. After hitting
"Update Info" for anything, the table will regenerate
to display the newly updated information. If a prompt
is checked to be removed when you hit "Update Info,"
all of the options grouped with that prompt will be
deleted with the prompt.
Edit Category Information
To change the name of a category, go to the "Contents of Catalog"
screen, and hit the "Edit" button under the "Category" section of
the table. Similar to the "Update Product" screen, a "List of
Categories" button at the top of the page shows a selection of
the category names currently in the catalog. If you already know
the current name of the category you wish to change, enter that name
into the field labeled "Category Title (Current)," then enter the
new name for the category in the "Category Title (New)" field. You
may also enter a new URL to a graphic that will represent the category
in the field provided. To submit your changes, hit "Update Category."
Changes made to a given category will also update the records of all
products which were associated with the previous category name.
VIII. ORDER PROCESSING SYSTEM
Orders that come into the catalog are written to a main
orders file called "*orders.dat" (where "*" is the catalog ID#).
This is where orders stay until they are grouped into a
new batch of orders. This enables you to deal with orders
in an organized manner while collecting new orders. When
orders in the "*orders.dat" file are grouped into a new
batch file, the "*orders.dat" file is zeroed out to prepare
it for new orders that come in next, and the new batch is
automatically assigned a batch ID# that corresponds with
a batch label specified by the order processor.
Hit "Order Processing" in the Administration System Main menu.
The appearance of the responding screen will be depend on whether
there are any new orders to process. If there are no new orders
in the main orders file, the system automatically takes you to the
"Select Batch" screen to choose a batch to process. If there are
new orders in the main orders file, the system generates a screen
displaying the number of new orders that are in "*orders.dat" and
gives you a text entry field to label the new batch. To create a
new batch, enter a label for the batch and hit "Create Batch." To
leave the orders file the way it is and accumulate more orders before
grouping them into a batch, hit "Select Batch." Following is a
guide to what happens depending on the circumstances present when
starting up the order processing system:
-
Create New Batch
If you've selected to create a new batch, the system
takes you to a screen that displays the new batch
label and batch ID# above the two processing options
for the orders in the batch:
- Editing Orders
The "Edit" button generates a table containing the
order number, the customer's name, the date of the
order, and a radio button to select the order for
editing. The "Edit Order" screen lets you edit any
information entered to the order including quantities
of items ordered as well as purchase, shipping,
billing, and contact information entered
by the customer.
- Order Reports
The "Report" button makes a multi-purpose
"Accounting Report" on each order in the
batch. The system goes to all of the data files
containing data on the orders in the batch,
reads in all of that data, and displays it
formatted in the browser.
Reports on all of the orders in the
batch are generated at once in the same browser
display, but are sequential and show
all information gleaned from each individual
order - one order at a time.
- Select Batch
The "Select Batch" screen displays information on
all active batches organized into a five column
table containing the batch label, batch number,
time created, total orders, and a "Select" button
for each batch represented in the table.
The system then displays a screen with the same
information issued in the "Select Batch" table,
but only for the batch selected. Below the table,
three processing options are made available: "Edit,"
"Accounting Report," or "Archive and Delete." The "Edit" and
"Accounting Report" options from this screen function identically
as discussed above in the processing of a new batch created.
IX. DATA STRUCTURES
With the exception of the main catalog configuration files
"koolcat.conf," "kcaccess.dat," "taxtemp.dat," and "clrslist.dat,"
all data files generated for each catalog are
of the format "*filename.dat" - where "*" is the would-be catalog ID
# prepended to the name of each data file. Each data file is
a bar ("|") delimited flat file where each record is a new line.
However, "kcaccess.dat" only contains a sidle line which contains
a single field.
The Data Converter
For those who have built their catalog system with the KoolCat
v1.0 System, the v1.23 distribution contains a data conversion
module called "kcupdate.hts" for changing the structures of all
your data files to function properly with the new versions
of administration and run-time systems. Following are the
recommended steps to take in converting your v1.0 data to
work with KoolCat v1.23:
- Back Up Your Data
Save all your existing data as it's
been working with KoolCat v1.0. and store it
in a safe place other than the directory where
it currently is. Leave all of your data in place.
- Run "kcupdate.hts"
This application presents you with a single text entry
field form that asks for the location of your data.
Enter the location of your existing data in relationship
to your configured htmlscript data directory. The default
directory where "kcupdate.hts" looks for your data is a
subdirectory called "koolcat/" under your configured
htmlscript data directory. Enter the name of this directory
if it is something other than "koolcat/" and hit "Update Data."
If all of your KoolCat data resides in your top htmlscript
data directory, enter a dot (".") in the field labeled
"KoolCat Data Directory" and hit "Update Data."
You should only need to use "kcupdate.hts" one time. After
running "kcupdate.hts," all of the data that you've been
using with your KoolCat v1.0 system should be ready to run
with the new KoolCat v1.23 system.
The following list of data files come bundled with the standard
distribution of the KoolCat System:
- "koolcat.conf"
This file acts as the global configuration file for your
KoolCat system, and contains all information specific to
each catalog created with the system.
Each catalog is represented by at least one record in
"koolcat.conf," but may be represented by many. Each
product category created in the catalog will produce a
new record in "koolcat.conf" that will contain that
product category in the "category" field of the record.
Information in all other fields will be identical to
the rest of the records associated with that catalog.
Data Structure:
|
catid
|
ID# for a catalog created with the system. This number
is established as the value of the htmlscript system
variable "time_t" when the catalog is created.
|
|
pwd
|
Password for administering the catalog
|
|
category
|
Name of a category under which items in the catalog may be
classified.
|
|
catgif
|
Image URL for a graphic representing
a category name in the catalog
|
|
title
|
The official title of the catalog
|
|
welcome
|
Welcome message displayed at the first page of the catalog
|
|
thankyou
|
Thank you message displayed after an order is placed
|
|
selection
|
The message displayed at the catalog selection page
(if there are multiple catalogs on the same system)
|
|
sendord
|
"From" address for email sent to order processor.
|
|
subjord
|
"Subject" of email sent to order processor
|
|
bodyord
|
Body of email sent to order processor
|
|
header1
|
Plug-In called at top of catalog selection page
|
|
hmethod1
|
method for calling header 1 ("GET" or "POST")
|
|
footer1
|
Plug-In called at bottom of catalog selection page
|
|
fmethod1
|
method for calling footer 1 ("GET" or "POST")
|
|
header2
|
Plug-In called at top of catalog main page
|
|
hmethod2
|
method for calling header 2 ("GET" or "POST"
|
|
footer2
|
Plug-In called at bottom of catalog main page
|
|
fmethod2
|
method for calling footer 2 ("GET" or "POST")
|
|
header3
|
Plug-In called at top of category selection page
|
|
hmethod3
|
method for calling header 3 ("GET" or "POST")
|
|
footer3
|
Plug-In called at bottom of category selection page
|
|
fmethod3
|
method for calling footer 3 ("GET" or "POST")
|
|
header4
|
Plug-In called at top of catalog/category contents page
|
|
hmethod4
|
method for calling header 4 ("GET" or "POST")
|
|
footer4
|
Plug-In called at bottom of catalog/category contents page
|
|
fmethod4
|
method for calling footer 4 ("GET" or "POST")
|
|
header5
|
Plug-In called at top of search results
|
|
hmethod5
|
method for calling header 5 ("GET" or "POST")
|
|
footer5
|
Plug-In called at bottom of search results page
|
|
fmethod5
|
method for calling footer 5 ("GET" or "POST")
|
|
header6
|
Plug-In called at top of product display page
|
|
hmethod6
|
method for calling header 6 ("GET" or "POST")
|
|
footer6
|
Plug-In called at bottom of product display page
|
|
fmethod6
|
method for calling footer 6 ("GET" or "POST")
|
|
header7
|
Plug-In called at top of product attribute selection page
|
|
hmethod7
|
method for calling header 7 ("GET" or "POST")
|
|
footer7
|
Plug-In called at bottom of product attribute selection page
|
|
fmethod7
|
method for calling footer 7 ("GET" or "POST")
|
|
header8
|
Plug-In called at top of Product Upsell page
|
|
hmethod8
|
method for calling header 8 ("GET" or "POST")
|
|
footer8
|
Plug-In called at bottom of Product Upsell page
|
|
fmethod8
|
method for calling footer 8 ("GET" or "POST")
|
|
header9
|
Plug-In called at top of Thank You page
|
|
hmethod9
|
method for calling header 9 ("GET" or "POST")
|
|
footer9
|
Plug-In called at bottom of Thank You page
|
|
fmethod9
|
method for calling footer 9 ("GET" or "POST")
|
|
ordrcpnt
|
Email address (or comma delimited list of address) of
person(s) to inform when an order is placed
|
|
secure
|
indicates whether server supports "https" (secure) protocol
|
|
exptime
|
Expiration time for shopping baskets
|
|
mailserver
|
Name of mailserver to use for sending email
|
|
colorscheme
|
Name of color scheme used in the catalog
|
|
usdata
|
Percentage of order total under which
prices for possible upsell items fall
|
|
wtunits
|
Standard unit of weight measure used for items in the catalog
|
- "kcaccess.dat"
At start-up, "kcadmin.hts" prompts the catalog administrator
to establish a password for using the system. Upon submittal of
the form, "kcaccess.dat" is written to with the
newly established password.
Data Structure:
|
accessword
|
Password to access the Administration System
("kcadmin.hts") as a whole
|
- "clrslist.dat"
This is a file of single field records which contain the names of
140 hex triplet colors which are recognized by name alone.
"kcadmin.hts" reads from this file to generate a colored list of
these color names from which you may select a name to use in
creating color schemes.
Data Structure:
|
colorname
|
The name of a color that generates a hex triplet value for use as a
color attribute value in customizing text and background colors.
|
- "*colors.dat"
This file contains information on each color shcheme available for use
in creating color schemes in your KoolCat system. Each color scheme
created is represented by one record in the data file.
Data Structure:
|
scheme
|
name of the scheme
|
|
newlink
|
color for unbrowsed links
|
|
atlink
|
color for selected links
|
|
viewedlink
|
color for browsed links
|
|
background
|
background color
|
|
inventory
|
color for table of products placed in basket
|
|
products
|
color for table of products in the catalog
|
|
invoice
|
color for invoice on thank you page
|
|
txcolor
|
color for all text
|
- "*catalog.dat"
(i.e. "123456789catalog.dat")
Each product in the catalog is represented by at least
one record in "*catalog.dat." When a product contains no
attributes, only one record represents that product in
the file. When a product contains at least one attribute
associated with it, two or more records will represent that
product in "*catalog.dat" - depending on how many
attribute prompts the product contains, and how many
selection options each attribute prompt contains.
In the case where the product contains one or more
attribute selections, and the first attribute selection
is made up of five options, seven or more records will
represent that product in "*catalog.dat". All of the
records representing that product will be identical
with the exception of the values contained in the flag
and extras fields:
- Record I.
Contains the value "type" in the flag field,
and the text for the type of selection device
used for displaying options in the extras field:
"radio," "checkbox," "select," or "text" in the
extras field.
- Record II.
Contains the value "prompt" in the flag field,
and the text for the attribute selection prompt
in the extras field.
- Record III.
Contains the value "option" in the flag field,
and the text for the first attribute selection
option in the extras field.
- Record IV.
Contains the value "option" in the flag field,
and the text for the second attribute selection
option in the extras field.
- Record V.
Contains the value "option" in the flag field,
and the text for the third attribute selection
option in the extras field.
- Record VI.
Contains the value "option" in the flag field,
and the text for the fourth attribute selection
option in the extras field.
- Record VII.
Contains the value "option" in the flag field,
and the text for the fifth attribute selection
option in the extras field.
If the next product attribute were a single text area
under a prompt, three more records would represent that
product attribute:
- Record IX.
Contains the value "type" in the flag field,
and the value "text" in the extras field.
- Record X.
Contains the value "prompt" in the flag field,
and the text for that attribute prompt in the
extras field.
- Record XI.
If there are no more attributes associated
with the product, this record acts as a
delimiter, and contains the value "none" in
both the flag and extras fields indicating
that the next record in the data file is
the first record representing a different product.
In the case were there are more attributes
associated with the product, this record looks
just like record I., only it contains information
about the next attribute with the value
"type" in the flag field, and the text for the
type of selection device used for displaying
options in the extras field: "radio," "checkbox,"
"select," or "text" in the extras field.
Data Structure:
|
prodcode
|
Product code assigned to the product.
|
|
title
|
Name given to the product
|
|
thumb
|
URL to thumbnail graphic for the product
|
|
price
|
Regular price of product
|
|
gifurl
|
URL to product display graphic
|
|
description
|
Product description
|
|
category
|
Category under which the product is classified
|
|
weight
|
Product weight
|
|
taxable
|
Indicates whether product is taxable
|
|
flag
|
Flag indicating whether record contains
additional product info:
"type," "prompt," "option," or "none"
|
|
extras
|
Attribute Information: prompt text, option text,
"radio," "checkbox," "select," "text," or "none"
|
- "*orders.dat" (i.e. "123456789orders.dat")
This is the main orders file into which new orders are
placed until the order processor groups them into a new
batch of orders. When ever the new orders in "*orders.dat"
are grouped into a batch, this file is zeroed out to ready
it for receiving more new orders.
A single order may be represented by at least one record
in "*orders.dat," depending on whether an upsell product
was added to the basket total at the time when the order
was processed. If no upsell product was sold, only one
record represents the order taken.
A single record will also represent the order when the
upsell product sold has no attributes. When the
upsell product does contain at least one attribute selection,
the order is represented by at least four records:
- Record I.
Contains the value of variable 'usprod' in the flag field,
and the product code for the upsell product in the
usdata field.
- Record II.
Contains the value of "prompt" in the flag field,
and the prompt text for the upsell product
attribute selection.
- Record III.
Contains the value of "option" in the flag field,
and the text for the upsell product attribute
option selected in the usdata field.
- Record IV.
Contains the value of "none" in both the flag
and usdata fields to mark the current record as
the final record representing the order.
In the special case where the only attribute
associated with the upsell product is formatted
with as a selection of checkboxes, and the customer
has chosen to purchase the upsell product displayed
but has left the checkbox formatted attribute
information unmarked with any selections, the order
may be represented by only three records:
- Record I.
Contains the value of "usprod" in the flag field,
and the product code for the upsell product in the
usdata field.
- Record II.
Contains the value of "prompt" in the flag field,
and the prompt text for the upsell product
attribute checkbox selection.
- Record III.
Contains the value of "none" for both the
flag and usdata fields in the record as none
of the options in the attribute selection
have been checked by the customer.
Data Structure:
|
ordernum
|
Order Number
|
|
name
|
Contact person at shipping address
|
|
shipaddress
|
Street address for shipping location
|
|
city
|
City for shipping address
|
|
state
|
State for shipping address
|
|
zip
|
Zip Code for shipping address
|
|
country
|
Country for shipping address
|
|
phone
|
Phone number at shipping location
|
|
fax
|
Fax number at shipping location
|
|
email
|
Email address of contact person at shipping location
|
|
company
|
Company Name at shipping location
|
|
bname
|
Contact person at billing location
|
|
baddress
|
Street address of billing location
|
|
bcity
|
City for billing address
|
|
bstate
|
State for billing address
|
|
bzip
|
Zip Code for billing address
|
|
bcountry
|
Country for billing address
|
|
bphone
|
Phone number at billing location
|
|
bfax
|
Fax number at billing location
|
|
bemail
|
Email address of contact person at billing location
|
|
bcompany
|
Company name at billing location
|
|
cardtype
|
Credit card type to which the order is charged
|
|
cardno
|
Credit card number charged
|
|
expdate
|
Expiration date on credit card charged
|
|
cardname
|
Name of card holder on credit card charged
|
|
cartfile
|
Name of shopping basket file that generated the order
|
|
ship
|
Total shipping charges for the order
|
|
tax
|
Total sales tax for the order
|
|
total
|
Grand total of the order charged to credit card
|
|
method
|
Shipping method chosen for the order
|
|
startdatetime
|
Date and time of the order (numeric 'time_t' value)
|
|
flag
|
Flag indicating whether an upsell product was displayed
to the customer after the order form was submitted:
"usprodcode," "prompt," "option," or "none"
|
|
usdata
|
Contains information on the upsell product if applicable.
Contains the value of "none" if no upsell product was sold
or if the current record is the last sequential record
representing a given order in the data file.
|
- "*basklist.dat" (i.e. "123456789basklist.dat")
This file contains the file names of all of the open shopping
baskets that have not yet generated orders, and the time
that the basket files were created.
Data Structure:
|
fname
|
The file name of the open shopping basket
|
|
startdatetime
|
The date and time the basket file was created (string value)
|
- "*usdata.dat" (i.e. "123456789usdata.dat")
This file contains a list of products available for
upsale, their upsell (discount) prices, and a list of
related prerequisite products that must be in the customer's
shopping basket when the order form is submitted before the
given upsell product may be presented to the customer.
Each product in the list of upsell products is represented
by at least one record in "*usdata.dat" - one record per
related prerequisite product associated with the upsell
product.
Data Structure:
|
usprod
|
Product code of upsell product
|
|
usprice
|
Upsell price for that product
|
|
relprod
|
Product code of related prerequisite product
|
- "*credit.dat" (i.e. "123456789credit.dat")
This file contains the list of credit cards accepted as
payment for ordering products in the catalog
Data Structure:
|
creditcard
|
Name of the credit card accepted for payment
|
- "*taxes.dat" (i.e. "123456789taxes.dat")
As a default, this file contains the names of the
48 contiguous American states, Alaska, Hawaii, The US
Virgin Islands, and Puerto Rico. In the same record,
two other fields contain the numeric value of the tax
rate required in that area, and a toggle "on/off" value
for whether that state will appear in the selection of
states available for shipping and billing addresses in
the order form.
Data Structure:
|
taxstate
|
Name of the region (state)
|
|
tax
|
Rate of sales tax for the region (state)
|
|
usage
|
Toggle switch value to determine whether the
option will appear in the state selection portion
of the order form. Contains the value of "on" or "off."
|
- "*shipping.dat"(i.e. "12456789shipping.dat")
This file contains the list of shipping methods available
to the customer. In the each record with the name of the
shipping method, two other fields contain the minimum charge
and rate per unit of weight measure for using each
shipping method.
Data Structure:
|
method
|
Name of the shipping method
|
|
base
|
Minimum charge for using the shipping method.
|
|
rate
|
Decimal numeric value of the rate per unit
of measure charged for using the shipping method
|
- *journal.dat
This file contains a list of order batch ID #s associated
with the batches of orders created from "*orders.dat," the
label assigned to the batch by the order processor,
and the date and time the order batch was created.
Data Structure:
|
bnumber
|
Unique batch ID # automatically assigned
the order batch when it was created
|
|
bname
|
The label assigned to the order batch
by the order processor
|
|
startdatetime
|
Date and time the order batch was created (string value)
|
- Sample Basket Files (i.e. "kc9557858640976.dat")
When a customer begins shopping through a catalog, this
file is created and named with a prefix "kc" combined
with the concatenated values of environment variables
"process_id" and "time_t," and a file extension of ".dat".
The fields in each record contain the product code of each
item, a unique identifier for that item in the basket,
quantity of the item selected, a flag field indicating whether
the item contains any associated attribute information,
and an extras field containing the attribute selected
for the item.
The shopping basket file, "kc*.dat" is very similar in
structure to that of "*orders.dat" and "*catalog.dat"
in that each item added to the basket must be represented
by at least one record in the data file, but may be
represented by many - depending on how many attribute
selections are associated with each product added to
the basket, and on the number of options available for
each attribute selection.
In the case where the product added to the basket contains
one attribute selection associated with it, three records
represent the product in the basket file:
- Record I.
Contains the value of "prompt" in the
flag field, the text for the attribute selection
prompt in the extras field.
- Record II.
Contains the value "option" in the flag field,
and the text of the attribute option selected
for the product in the extras field.
- Record III.
Contains the value "none" for both the flag
and extras fields indicating that the current
record is the last record in the file representing
the product added to the shopping basket.
When the product contains multiple associated attribute
selections, 'Record III.' with "none" values for both
flag and extras fields acts as a delimiting record
indicating that the following record contains information
about another product added to the basket.
Data Structure:
|
prodident
|
Unique product identifier for the item in the basket
with it's particular attribute selection information
|
|
prodcode
|
Standard product code of the item in the basket
|
|
qty
|
Quantity of the item in the basket
|
|
flag
|
Contains data indicating the presence of any
product attribute information for the item in the
basket. May contain the value of "prompt," "option,"
or "none."
|
|
extras
|
Contains attribute option selected for the item in the
basket if any. Otherwise contains the value "none."
|
- Sample Memory Files (i.e. "kc9557858640976.mem")
The "memory variables" file is used to maintain
variables and their values when it is not possible
to pass them through a form or the command line.
The most generally useful implementation of the
memory variables file is in it's use of the
"secretcode" memory variable. This variable is a
randomly generated number which can be used as a
security verification mechanism from within your
Plug-Ins.
Possible Implementation:
Say, for example, that you are marketing electronic
media which can be obtained via FTP. Upon receipt of
an order after the "Thank You" message is displayed to
the customer, Plug-In 3 could be used to send login
and password information to the customer for
downloading merchandise.
However, you would not want to simply send them the
information without any verification that they just
placed an order (the customer may be a hacker who has
figured out how to call your Plug-In, in which case,
you would not want to let them know the FTP information).
The solution to this problem is to verify that the
calling module (e.g.: "koolcat.hts") is actually what
called the plug-in. This is accomplished via the
"secretcode" memory variable, which is passed through
to the plug-in, and can be referred to as "secretcode"
from within the plug-in.
Also passed through to the plug-in is the name of
the basket file (from which it is possible to derive
the name of the memory variables file), and the path
name of the order file (starting from configured htsdata
directory) from which the name of the configured
koolcat data directory can be derived. As stated
earlier, the memory variables file has an
identical name as that of the basket file, but
one with a file extension of ".mem".
To verify security, simply check that the secret
code passed to the script is the same as the secretcode
contained in the basket file. Following is some
htmlscript code that will perform such a security check:
Further explanation of htmlscript code may be found
in the
Htmlscript Reference Manual.
<## store the "secretcode" variable passed to the plug-in so that it
is not lost or reassigned, and so that it can be referenced later ##>
<LET savesecretcode = secretcode>
<## next, derive the name of the koolcat data directory (derived from
"orderfile" variable - which is also passed through to the plug-in) ##>
<LET len = orderfile EIN orderfile>
<LET savelen = len>
<LET mydatadir = orderfile>
<WHILE (len NE 0) AND (orderfile SUBSTR "&[len], 1" NE "/")>
<LET len = len - 1>
</WHILE>
<IF len NE 0>
<LET mydatadir = orderfile SUBSTR "1, &[len]">
</IF>
<## get the name of the memory file (derived from "basket_id"
variable - also passed through to plug-in from "koolcat.hts") ##>
<LET membasket_id = basket_id FMT "0[Aa#]"$".mem">
<## load in memory variables then perform security check ##>
<IMPORT FILE = mydatadir$membasket_id>
<IMPORT ORDER = varname, value>
<IMPORT DELIMITER = "|">
<IMPORT DATA>
<LET &[varname] = value>
</IMPORT>
<## perform security check ##>
<IF savesecretcode NE secretcode>
<## "secretcode" read from mem file ##>
ERROR: <EVAL arg1>: Can't authenticate security code
<EXIT>
</IF>
In the case that the security check fails,
the following error message is displayed:
ERROR: [name of plug-in]: Can't authenticate security code
Data Structure:
|
varname
|
assigned name of variable
|
|
value
|
value to be assigned to "varname"
|
Top
|
