QuickEStore 6.1 User's Guide
Table of Contents
QuickEStore 6.1 User's Guide
INTRODUCTION
Thank you for purchasing QuickEStore v.6 by John Kim Hoarty.
This versatile and easy to use Cold Fusion(TM) code will have you doing business on the
Internet within minutes. Simply create a "store" directory under your web server's root
directory and move the unzipped QuickEStore files into it, keeping the directory structure
of your QuickEStore files intact.
Set up the enclosed Microsoft Access database as a datasource in Cold Fusion Administrator
(or get your ISP to do so). Then copy your logo or graphic file to the "images" directory under
your "store" directory. Finally, password-protect the "orders" and "admin" directories. Then,
point your browser to the index.cfm file in the “admin” directory of your QuickEStore and click
on “Setup” in the left-hand menu frame. Answer a few simple questions using the interactive
web-based form. Refer to this document for help answering the questions.
Note: You are responsible for securing the "orders" directory which will contain credit card
information! An online store is only as secure as you make it. QuickEStore was designed to
run on a secure server which is capable of invoking SSL upon checkout.
QuickEStore is fully compatible with the CFX_CyberCash tag for full integration with the
CyberCash(TM) internet transaction processing service. This tag is available at the
Allaire Website (www.allaire.com).
PART I: INSTALLATION
STORE SETUP ROUTINE
Open the "setup.cfm" file on your web server. It's in the "admin" directory of your QuickEStore.
For example, if you created a directory called "store" under your root web directory (usually
"C:\InetPub\wwwroot"), then you would point your browser to
http://www.yourdomain.com/store/admin/setup.cfm.
Step 1: Enter datasource name.
Action: Type a name for your datasource. The datasource must already be set up in Cold Fusion
Administrator before proceeding.
Step 2: Enter store name.
Action: Type a name for your store. Spaces and special characters are okay and there is no limit
to the number of characters you can use. Well, maybe 255 characters.
Step 3: Use Customer Self-Service?.
Action: Select Yes or No. Customer self-service is a feature that sends a modified
e-mail confirmation to your customer. This e-mail confirmation will contain a link to a page
called "orderstatus.cfm" within the "custserv" directory on your website. Clicking this link will
launch a browser and display the customer's order along with a "status" that you can set from
your admin console. The default status is "Processing Order". Note that using this feature
requires that you perform "Advanced Order Processing" in order to change the order's status
from the default. Advanced order processing will be discussed in more detail later.
Step 4: Charge shipping according to Price Threshold, Weight, or Option/Rate table.
Action: QuickEStore supports three methods for calculating shipping costs. Whichever method
you choose, you will later be prompted to enter the various 'thresholds' at which shipping
charges will increase, or custom options and their corresponding rates. If you won't be
charging shipping, just choose either "Price" or "Weight" and click "Next". This is also where
you indicate how you want orders saved--they can be written to an html file for viewing in a
browser, or they can be e-mailed to you. Note: If you are using customer self service, you
must choose "View orders as web pages". Regardless of the order delivery method chosen, your
QuickEStore will retain full order history on each customer in the database for viewing and
reporting at any time.
Step 5: Enter the state(s) for which sales tax will be charged and the applicable tax
rate.
Action: Here you have the opportunity to enter a state for which purchases will
incur a sales tax. You may enter as many states as you want. Upon entering the last state
and tax rate, you may either click "Add Another State" or "Continue". Enter tax rate
percentages as whole numbers (i.e., 5.5, 6, etc.). Note that you may do this at any time
by clicking on “Tax Table” under the left-hand “View/Edit” menu in your QuickEStore
Admin Console.
Step 6: Enter e-mail address for order notification.
Action: This is the e-mail address where notifications of orders placed will be sent
and where orders are sent if that option is chosen.
Step 7: Enter path to order directory.
Action: This should be a directory with “System” read and write permissions. Orders will be
written to this directory. Enter logical path (i.e., C:\InetPub\wwwroot\orders). Please note that
this should be a password protected directory and not available to the browsing public!! Security
is your responsibility. Credit card information will be kept here. To protect this directory,
remove the “Everyone” group from the “security/permissions” tab of this folder (NT).
Step 8: Enter URL to order directory as shown.
Action: Enter the fully qualified domain address of the order directory. This is so the
application can create links to this directory. Should start with "https:" assuming you have
access to a secure server.
Step 9: Enter path to store.
Action: Enter the directory path to the store. I.e., "C:\InetPub\wwwroot\store".
Step 10: Enter URL to store.
Action: Enter the URL of the store. i.e.,
"http://www.mystore.com/store". Do not include a "/" at the end.
Step 11: Enter secure URL for checkout.cfm, i.e.,
https://www.mystore.com/store
Action: This will cause the application to invoke SSL for the checkout action. If you do not
have access to SSL, do not include the "S" in "https". This will cause a “could not connect to
server” error when you click on checkout.
Step 12: Store Logo graphic file.
It can be a gif or jpg file and will be placed at the top of your product, product detail,
and checkout pages. Optional. Graphic needs to be in a directory called "images" under
your store directory.
Step 13: Enter a password for store admin.
Action: Enter a password to protect your store admin and view orders pages. This is very important.
I still recommend that you invoke OS level security (NT or Unix permissions) on your admin and
orders directories for added security. You will be prompted for this password when you go to the
Admin Console from now on. When you enter the correct password, it is written to a session
variable. Subsequently, before any templates in your admin directory are served, QuickEStore will check for the presence of that variable and compare it to the password variable that you declare in this step,
denying access if they don't match.
Then, click on "Set Up Shipping Charges". If you do not wish to charge any
shipping, just click "Set Up Shipping Charges" and then click "Finish" without entering any
shipping information. If you do set up shipping, the first rate corresponds to the amount of
shipping charged to an order that is equal to or less than the first threshold, etc. Your
first entry should be a zero in each field. Your last entry should simply be an arbitrarily
large number, like 10000, and your maximum shipping charge.
Congratulations! You should now see a message that reads, "Congratulations! You have
successfully setup your QuickEStore! Simply go to Store Manager to add products and categories.
If you will be using product attributes, such as color and size, you will need to set those up
now. Simply click the bottom link on this results page.
Note: This setup procedure writes an "application.cfm" file to the store directory. It will
overwrite any application.cfm file already there! Also, you may get an error upon subsequent
setups if there is already an application.cfm file in that directory. Simply delete that file
to begin setting up your store with different parameters (like new paths). By the same token,
you can always edit the application.cfm template in a text editor (not a word processor) to
change parameter values, etc.
After configuring your attribute tables, click the link to "Add Categories" from your admin
menu to begin to add categories and products.
Add categories first, then sub-categories (optional). Then add products to categories.
Optionally upload pictures--it is recommended that you keep image files relatively small for
aesthetic reasons and so pages load quickly. Optionally insert descriptions. In the "live"
store, your Item Names will link to these descriptions and pictures. All that remains is for
you to provide a link from your homepage to the file, "prodpage.cfm", and you are in
e-business! You might want to save a copy of “prodpage.cfm” as “default.cfm” or whatever
your default document name (in IIS Administrator) is.
Order notifications will be sent to the e-mail address you provided. These are sent in HTML
format and include a link to "Store Manager". Optionally, orders can be sent here as well, but
this is only recommended if your e-mail account and web site are on the same server for reasons
of security.
PART II: THE QuickEStore ADMIN CONSOLE
Beginning with QuickEStore version 6, you are provided with one destination from which you
can manage your entire online enterprise, the QuickEStore Admin Console. Point your browser to the index.cfm template in the QuickEStore “admin” directory to access the console. The default password to access the Admin Console is “password”. We will now review each menu item in the console in order
from the top-down.
HOME
This link takes you to the homepage of your QuickEStore (prodpage.cfm).
SETUP
This link will invoke the setup script that is used to store variables critical to the functioning of
your QuickEStore. If setup has already been run, you can most likely make any changes you need
to make by clicking one of the other links in the Admin Console. If you must re-run setup, you should
first delete the “application.cfm” template in your QuickEStore root directory since any incorrect path
information contained in that file will affect the way the setup script runs on subsequent attempts.
THE “VIEW” MENU
ORDERS
View your orders either by clicking on the link provided in your order notification e-mail or by
clicking on the “Orders” link under the “View” menu in your QuickEStore admin console. Orders are only written to a file if “web order” was chosen during setup. If “email orders” was chosen instead, you will only receive orders in e-mail format. No record is written to file. In either case, however, complete order history is retained in the database for future reference using the Customer Relationship Management features of QuickEStore.
Orders are listed in order by order number/date (descending), so most recent orders are at the top. Click on an order to view its detail.
If you enabled customer self-service during setup, you will notice that the order has two links at the bottom, “Advanced Order Processing” and “Delete Order”. Advanced Order Processing will be discussed in detail later.
Delete Order only deletes the order file on which the link appears. Again, complete order history is retained in the database for future reference.
CUSTOMERS
Clicking on the “Customers” link will load a page with some easy to use customer query tools that
will help you locate your customers by last name, last order date, or order amount. The results page will list those customers fitting your query parameters, along with their e-mail address and last order date. Clicking on the e-mail address will launch the e-mail client that is associated with <a href=”mailto:”> tags, while
clicking on the customer name will launch a new “Advanced Order Processing” browser instance.
You may also query for customers by going directly to a specific order number. Enter the order number in
the “Go Directly to Order Number” input field on the customer query page and click “Submit”.
REPORTS
Clicking “Reports” will launch two query tools in the Admin Console main window. The topmost tool, “Quick Reports” will return a month-to-date and a year-to-date sales report that includes the following:
Total Sales
Total Orders Placed
Number of Customers
Average Order Amount
Total Sales Tax Charged
The second report tool requires a valid “from” and “to” date pair and returns the same information cited above for the specified date range. It also returns a year-to-date report by default.
THE “ADD/EDIT” MENU
PRODUCTS
You must define a category before attempting to add products to the database. Then, clicking
“Products” under the “Add/Edit” menu in the Admin Console will initially load a
single button that beckons, “Add Product”. Clicking this button will load your add product
form, with which you may enter the following product information:
Category, Sub-Category, Product SKU (Stock-Keeping Unit, or Product Number), Product Name,
Description, Price, Selling Units, Weight (in ounces), Product Image, Attributes, and Product
Layout Template. Note that only Category, Product Name and Price are required, although the
weight field must contain a zero if weight is not being recorded.
Price
Price is in US dollars and will accommodate two decimal places.
Selling Units
Selling Units is just a label that
some prefer to see next to the quantity field on the product detail page of the store. This label will
also appear on the order itself. This drop-down menu can be customized using standard HTML
syntax for a drop-down (SELECT) menu.
Weight
Weight is entered in ounces, but QuickEStore translates this into a total order weight in pounds
if weight-threshold shipping is employed. Leave zero if weight-threshold shipping is not being used.
Product Image
Product image allows you to upload a graphic file of your product to your website. Not all
browsers support the “enctype=multipart/form-data” form attribute. If you don't see the “Browse...”
button next to the product image input box, get a real browser! Otherwise, you'll have to up-
load your image files manually and add the image's corresponding “ItemID” (the ItemID of
the product the image represents) and filename information to the “ProdPics” table. Image files
should be either gifs or jpegs.
Attributes
You'll see “Choose up to 2 Attributes (optional):” if you have added global attribute types and
values to the database. To select one attribute type, simply left-click on it. To select two attribute
types, hold down the CTRL key while clicking on each selection, or “click and drag” across
both desired selections.
Select product layout template
Choose a product layout template that describes the way you prefer this product's image and
description to be juxtaposed. Don't worry if you area not using images for one or more products.
It is perfectly alright to leave one template selected even if images aren't being used.
Now, click on “Submit New Product”. If one or more attribute types was selected, you will now be prompted to indicate which attribute values are appropriate for this product. For example, if you chose
the attribute “Color”, you would now be prompted to select from the available color list those
colors for which this product is offered. Again, this will be accomplished using a “multiple” select
drop-down menu. Hold down your CTRL key or click and drag over your desired selections.
ATTRIBUTES:
Product attributes are supported beginning with QuickEStore version 3.1. In version 6, you are
given the opportunity to set unlimited global product attributes. You get to decide what to
call them, so they can be anything you want, i.e., "size", "color", "flavor", etc.
You may also choose to use just one product attribute.
Attributes are set up by clicking on the “Attributes” link under the “Add/Edit” menu in the QuickEStore
Admin Console. First, enter the name of your Attribute type, such as “Size” and then you will be prompted
to enter the various values that you want available during the “add product” function (i.e., S,M,L,XL).
Attribute values are stored in the database as a comma-delimited list, so do not use commas when
entering attribute values one at a time.
Notice that with each attribute value that you add, the value appears in a table under the heading “Value” across from its corresponding global attribute type. Furthermore, that global type is a hotlink which, when clicked, will make the values list editable. Be sure to enter your edits carefully, remembering that the
values are stored as a comma-delimited list in the “Attributes” table. Also realize that editing attributes and
their values will only affect products that are added after the fact. Existing products already have their attributes defined in the “Products” table.
After setting up the attribute tables, they will be available on the "Add Products" page as
selectable drop-down menus. First you select one or two of your attribute types, then you will
be prompted to indicate the values that should apply to that product for each selected
attribute type. These drop-down menus are "multiples", meaning you can hold down your CTRL key
and select as many as are appropriate for a particular product when adding new products. If you
don't highlight any attribute types on the "Add Products" page, this item won't have attributes,
in which case the product detail page will not display the attribute menu(s).
CATEGORIES
Clicking here will load a page in the main window of the Admin Console that offers “Add
Category” and “Add Sub-Category” buttons. Once a category has been entered, this template
will also produce a “Delete Category” button. Ditto for Sub-Categories. These buttons
will not delete a category or sub-category that contains even one product however. This is
for your protection and you'll thank me one day for thinking of this.
TAX TABLE
The Tax Table link is where you go to add sales tax rates for states in which you may be required
to charge a sales tax. As a rule, if you are doing business in North Carolina, for example, you'll need
to assess a charge of 6% of the order since that is the sales tax rate here. QuickEStore adds the
amount that you indicate to any order that is shipped to a state that you have entered into the sales
tax table. To add a state, simply choose it from the drop-down menu provided and enter the
appropriate tax rate using a whole number (e.g., 6.0, 5.75). Then click the button that says, “Add
Another State”.
Notice that with each state added, the state will be listed in a table below, along with its sales
tax rate. Clicking on the rate itself will make that entry editable for easy tax rate modifications.
There is also a “Delete” link to the right of each entry that will make it instantly go away.
SHIPPING
The behavior of this link depends on the shipping rate “method” that you chose during setup.
If you chose price or weight threshold shipping, you will see a form in the Admin Console
main window that prompts you to enter the initial price or weight threshold and its corresponding
shipping fee. This means that any order from $0.01 to the first threshold will be charged this
amount. So, for example, if you enter 20 and 3.75, then all orders up to twenty dollars will be
charged $3.75. The next threshold entered (with its corresponding shipping fee) represents the
amount added for shipping to orders from $20.01 to the limit entered, and so forth. To complete
this exercise, enter an arbitrarily large number such as 1000,000 and then indicate the highest
shipping fee that you anticipate charging and then click on “Finish”.
As with the Tax Table above, shipping limits and fees are reported in a table below the input
form with easy-edit links for your convenience. This makes editing these important tables a
very simple process.
If you have chosen the weight-threshold shipping method, the process is exactly as described
above except that you will enter weight limits in pounds rather than price limits.
If you chose the option/rate table shipping method, you will see a similar-but-different screen
at this point. Instead of entering price or weight limits, you will enter descriptions such as
“UPS Second Day Air” or “FedEx Overnight”, along with the amount that you will charge
for these services.
PART III: ADDITIONAL FEATURES
CUSTOMER SELF-SERVICE
QuickEStore now offers an exciting optional feature called "Customer Self-Service". When enabled
during setup (or by editing “application.cfm” after successfully completing setup), your customers
will receive an e-mail order confirmation/receipt that includes a link to the self-service page of your
site. By simply clicking this link, the customer can check the status of their order at any time. The status defaults to "Processing Order", although this default is easily modified. To change it, open “writeorder.cfm” in a text editor (Not a word processor) and search for the following query, about two thirds of the way down the page:
<cfloop query="showorder">
<cfquery datasource="#datasource#">
INSERT INTO OrderHist
VALUES(#nextnum#,#nextid#,#ItemID#,'#SKU#',#Quantity#,#ItemTotal#,
#TotItemWeight#,'#Att1#','#Att2#','Processing Order')
</cfquery>
</cfloop>
Change `Processing Order' to whatever you want, but be sure to enclose it in single quotes.
If you change it to something that is not on the default list, you can edit that list by opening “ord_detail.cfm” in your admin directory and looking for the following:
<!--- HERE YOU CAN EDIT THE ADVANCED ORDER PROCESSING STATUS LIST --->
Beneath this comment is the <SELECT> tag, or drop-down list, containing the default values for order status.
ADVANCED ORDER PROCESSING
If you are using Customer Self-Service, you still get an e-mail order notification for each order
placed in your store, but now it includes a link to "Advanced Order Processing". Here, you can view the customer's personal and credit information at the top, and a blank page at the bottom. You will notice that the order is flagged with the default order processing status and that the order number itself is a hotlink. Clicking this will display the order detail in the bottom frame. The bottom frame is where you can set the order status to any of the following:
"Processing Order", "Assembled", "Backordered", "Ret'd for Refund", "Ret'd for Exchange", or "Order
Shipped". If "Order Shipped" is chosen, the ship date defaults to the current date unless a date is manually entered in the "Ship Date" field of the form.
There is also a “Notes” field where you can enter a personalized message to your customer and it will be reproduced on the status page when the customer views it.
CUSTOMER RELATIONSHIP MANAGEMENT
QuickEStore 6 also includes a new feature called "Customer Relationship Management" or
"QuickE-CRM". You can query your database of customers using an intuitive form.
Look up customers by date of last order, order amount or order number. From the result set,
you can drill down to view order detail. Invoke this feature by clicking on the “Customers” link
under the “View” menu in your QuickEStore Admin Console.
USING THUMBNAILS
To have thumbnails displayed on your product page, you will need to use the "prodthumbs.cfm"
template in place of "prodpage.cfm". Rename "prodpage.cfm" to "prodpage.old" and rename
"prodthumbs.cfm" to "prodpage.cfm". Name all of your thumbnail images the exact same as your
full-size images but add "th_" to the front. Thus, "product1.jpg" becomes "th_product1.jpg".
That's all there is to it! Your prodpage will now display the product's thumbnail image and
name. All products must have a thumbnail to use this feature.
PRODUCT LAYOUT TEMPLATES
When adding or editing products, you will see four radio buttons indicated your desired product
page display for that product. You can choose from "image left, description right", "image
right, description left", "image top, description bottom", or "image bottom, description top".
You may want to try different displays for different products just to jazz up your site, or to
accommodate odd sized product pictures.
SHIPPING ADDRESS
QuickEStore now has a "shipping address" option. On the checkout page, a checkbox can be
deselected to indicate that the desired shipping address differs from the purchaser's address.
When unchecked, the subsequent page will prompt for shipping information.
RETAIN RETURN CUSTOMER CREDIT CARD INFO
QuickEStore now supports the retention of customer credit card information. On the checkout
(cart) page, a checkbox indicating that credit card information will be retained is by default
selected. Upon subsequent visits to the site, the customer's last-used credit card information
will prepopulate the credit card information part of the customer information form. The
information retained includes: customer credit card name, credit card type, card number and
expiration date. In order to use this feature, the customer's browser must support cookies.
INTEGRATING WITH CYBERCASH
If you want to integrate CyberCash online payment processing, go to http://www.allaire.com and
download the free custom tag, CFX_CyberCash and install it on your web server or check with
your ISP to see if it is installed. Then, rename your "writeorder.cfm" file to "writeorder.old"
and rename "writeorder_cyberchas.cfm" to "writeorder.cfm". Scan your new "writeorder.cfm"
template and locate the attributes in the custom tag where missing values are indicated.
Insert the values for your CyberCash account ID, etc., where indicated.
There is an issue with the way CyberCash handles failed orders when you use CyberCash in the “Auth Only” mode. This mode is typically chosen when the online retailer deals in tangible goods, as opposed
to digital goods or services. Auth Only means that CyberCash authorizes the transaction in real time,
but the merchant “batches” and submits the cleared transactions to the bank manually. This typically
takes place once a day in the evening.
The issue arises when an order fails the CyberCash authorization in AuthOnly mode. In this case, CyberCash will refuse that order number on subsequent attempts regardless of its legitimacy,
simply due to the fact that the order number was once refused. The issue then, requires QuickEStore
to increment its order number by one for every submission to CyberCash, regardless of the result of
that submission. To that end, the writeorder_cybercash.cfm template has been revised starting with
version six.
QuickEStore has always queried the OrderHist table for its maximum order ID and then added one in
order to determine the next order number. Therefore, to increment every order attempt requires each attempt to result in an order history record. The end result is that the merchant has an order history table with entries representing failed orders with amounts of $0.00. These entries do log the attempt, however, including name , address and credit card information, which can be useful if the attempt to order was sincere. Furthermore, your customer relationship page allows you to query the order history tables for
all orders over $0.00, and your reporting page will only calculate reports on orders over $0.00.
PART IV: ADDING SHOPPING CAPABILITY TO AN EXISTING SITE
Adding “shopping cart” functionality to an existing website is fairly straight-forward. The product
display page must be a cold fusion template in order to generate certain variables such as OrderID.
This can be as simple as renaming the existing page from, say, “products.html” to “products.cfm”.
Once this has been accomplished, simply add the following code for each product that you want
to make “purchasable”.
<cfoutput>
<form action="insertorder.cfm?#URLToken#" method="post">
<input type="hidden" name="ItemID" value=”Place ItemID Here”>
<input type="hidden" name="Price" value=”Place Price Here”>
<input type="hidden" name="OrderID" value=”#OrderID#”>
</cfoutput>
<!--- Product description goes here --->
<input type=”text” name=”qty” size=”4”>
<input type=”Submit” name=”Submit” value=”Add to Cart”>
That's all there is to it. If your product has attributes such as “Color” and “Size”, they too can be added.
They should simply be included as form input fields named “att1” and “att2”.
PART V: UPGRADING FROM VERSION 5.2 AND UP
QuickEStore version 6 adds a single table, ShipOptions, to the QuickEStore.mdb database. This table is only used if you choose the “option/rate” method for calculating shipping costs during setup. It would
be a simple matter to copy (or export) this table to your existing version 5.2 or later production database.
The new Admin Console should then work with your existing store by simply installing the “admin” directory and all of its contents to your webserver under your store's root directory. Just be sure to
backup your existing configuration.
Note that several files have been moved from your root store directory to the “admin” directory for added security. The admin directory is password protected by the admin password that you designate during setup. This way, by password protecting the “admin” directory with a session variable password, you
can manage every store function from one location. After ensuring that all of the Admin Console
functions are working properly, it is recommended that you delete the duplicate files from your root store directory. These would include attributes.cfm, deleteorder.cfm, edit_cats.cfm, edit_prods.cfm, save_cats.cfm, and save_prods.cfm.
Files added with this release include:
deletecust.cfm
deleteperm.cfm
Files changed with this release include:
attributes.cfm
editshipping.cfm
quickecrm.cfm
Files discarded with this release:
None
Previous upgrade information:
QuickEStore 5.2 included the tables, “Orders”, “OrderHist”, and “OrdHistDetail” for the first time.
QuickEStore 5.0 saw the addition of the “Customers” table to the QuickEStore.mdb database.
It is generally recommended that you not try to input data into your QuickEStore.mdb file manually.
The reason for this is that there are relationships between the fields in the various tables which
are not intuitively obvious. When using the Admin Console to input and edit data, QuickEStore maintains these relationships which may be compromised if you attempt to enter data by hand.
Support is available by e-mail at support@quickestore.com. Also visit our website at http://www.quickestore.com/faq.html to browse our Frequently Asked Questions (FAQ).
1
1