TechOrder
Version 1.0
(C)2003 TNL Total Solutions All Rights Reserved.
http://www.TNLSoft.com
The most recent version of this document can be found at:
http://www.tnlsoft.com/tcn/docs/to/
Table Of Contents:
System Requirements
Software License
Uploading The Program Files
Uploading The TemplatesCustomizing The Templates
Template Descriptions
Advanced Template Functions
System
Requirements
Red-Hat Linux or Compatible System
Perl 5.00x or greater installed with all standard modules.
Sendmail Installed
1. NOTICE: We are willing to license the software product titled
TechOrder, referred to as ‘software product’ to you, referred to
as 'Customer' only on the condition that you accept all of the terms contained
in this license agreement. Please read this license agreement carefully before
using the software product. By using the software product Customer agrees to
be bound by the terms of this agreement. If the Customer does not agree to these
terms, we are unwilling to license the software product to Customer, and Customer
should not use it. In such case, promptly return the software product and all
other material included.
2. OWNERSHIP AND LICENSE.
This is a license agreement and NOT an agreement for sale. It permits Customer
to use one copy of the Software product on a single machine (Desktop or Server).
The software product, including any text, data, code, images, animations, and
other materials incorporated in the software product, is owned by us or our
licensors, and is protected by U.S. and international copyright laws. Your rights
to use the software product are specified in this Agreement, and we retain all
rights not expressly granted to Customer in this Agreement.
3 INTELLECTUAL PROPERTY RIGHTS. Customer acknowledges that TNL Total Solutions,
its vendors, and/or its licensors retain all Intellectual Property Rights in
and to the patents, copyrights, trademarks, service marks, trade secrets, ideas,
concepts, techniques, inventions, processes, or works of authorship comprising
or embodied in the products or services provided by TNL Total Solutions hereunder,
including without limitation the TNL Total Solutions-designated hardware and
software supporting such services and the TNL Total Solutions web site interface
designated for Customer’s use (collectively, the "Service Components").
The Service Components do not include Customer’s browser software or Customer’s
hardware platform. Customer acknowledges that no title to the Service Components
is transferred to it under this Agreement, and that it does not obtain any rights,
express or implied, in the Service Components.
Customer may not reverse
engineer, disassemble or decompile the software product or make any other attempt
to obtain the source code to the software product. To the extent Customer creates
any Derivative Work of any of the software product, such derivative work shall
be owned by TNL Total Solutions and all right, title and interest in and to
such Derivative Work shall vest in TNL Total Solutions. To the extent Customer
acquires any right to the software product or Derivate Works of the software
product, Customer hereby assigns to TNL Total Solutions all right, title and
interest in and to such software product and Derivative Works of software product.
Customer agrees to execute any assignment agreements or instruments as TNL Total
Solutions may request to vest in TNL Total Solutions all such ownership rights.
4. GRANT OF LICENSE: Customer
may use one copy of the software product on a single machine. Customer may use
the software product on a different machine only if Customer first delete the
files installed on the first machine. Printing or downloading into an electronic
file more than one copy of any of the contents of this software product is prohibited.
Other than the foregoing, Customer may not copy any portion of the software
product to any other media. Customer may not copy any of the documentation or
other printed materials accompanying the software product. Customer may not
alter the source code in any sense what so ever. Default in payment or lease
of license will result in the license being revoked.
5. No Assignment and Other
Restrictions. Customer may not rent, lend, or lease this software product The
License granted to Customer or your company, and under no circumstances may
be assigned or transferred by Customer without our prior written consent. Any
attempted assignment or transfer shall be null and void and shall result in
the immediate and automatic termination of the license granted under this license
agreement.
6 LIMITED WARRANTY. We make
the following limited warranties, for a period of thirty (30) days from the
date of purchase from us or our authorized dealer:
(a) Media. The disks (if applicable) containing the software product will be free from defects in materials and workmanship under normal use. If the disk fails to conform to this warranty, Customer may, as your sole and exclusive remedy, obtain a replacement free of charge if you return the defective disk to us with a dated proof of purchase.
(b) Software Product. The software product in this package will materially conform to the documentation that accompanies it. If the software product fails to operate in accordance with this warranty, you may, as your sole and exclusive remedy, return the software product and the documentation to TNL Total Solutions along with a dated proof of purchase specifying the problem and we will provide you with a new disk containing the software product or a full refund at our election
(c) WARRANTY DISCLAIMER:
We do not warrant that the software product will meet your requirements or that
its operation will be uninterrupted or error-free. We exclude and expressly
disclaim all express and implied warranties not stated herein, including the
implied warranties of merchantability and fitness for a particular purpose.
Some states do not
allow the exclusion of implied warranties, so the above exclusion may not apply
to you. This limited warranty gives you specific legal rights and you may also
have other legal rights, which vary from state to state.
7. LIMITATION OF LIABILITY:
Our liability to the Customer for any losses shall be limited to direct damages,
and shall not exceed the amount Customer originally paid for the software product.
In no event will we be liable to Customer for any indirect, special, incidental,
or consequential damages (including loss of profits) even if we have been advised
of the possibility of such damages.
Some jurisdictions
do not allow these limitations or exclusions, so they may not apply to you.
8. United States Government Restricted Rights. The software product and documentation
are provided with restricted rights. Use, duplication, or disclosure by the
U.S. Government or any agency or instrumentally thereof is subject to restriction
as set forth in subdivision (c)(1)(ii) of the Rights in Technical Data and Computer
Multimedia Product clause at 48 C.F.R. 252.227-7013.
9. TERMINATION. This
license and your right to use this Multimedia Product automatically terminate
if Customer fails to comply with any provisions of this Agreement, destroy the
copy of the software product in your possession, or voluntarily return the software
product to us. Upon termination Customer will destroy all copies of the software
product and documentation.
10 MISCELLANEOUS PROVISIONS.
This Agreement will be governed by and construed in accordance with the substantive
laws of Oregon. This is the entire Agreement between us relating to the software
product, and supersedes any prior purchase order, communications, advertising,
or representations concerning the contents of this package. No change or modification
of this Agreement will be valid unless it is in writing, and is signed by us.
If you have any questions
about this Agreement, write to us at TNL Total Solutions, P.O. Box 22441, Eugene,
OR 97402
Uploading The Program Files
This document assumes
that you can install pre-written perl scripts. Unpack
the archive to your local machine with the directories in tact.
Two folders should have been created one called 'cgi' and one called 'stores'.
Upload the contents of the CGI folder into your cgi-bin directory. Upload these files in ASCII mode and set the permissions accordingly. Usually you permissions are set at 0755 for cgi scripts. You may want to check with your hosting company to be certain.
Uploading
The Templates
Once you have installed and configured the script you are now ready to upload
the template files. The template files must have permissions set so that the
cgi scripts and read and write to them and the folders they reside in.
Create a folder on your website that where the orders will be stored. You may call this anything you like but it should match Full Server Path To Store Orders that you will later specify in the configuration.
For the sake of documentation we will call this folder ORDERS. Inside the orders folder you are going to create a folder that matches the name of your store. Since this is your first store pick a name, this name is somewhat like a username and you'll want to keep it short and remember it. Avoid using special characters, spaces, and mixed case (Upper And Lower Case Combinations) in the name. So, if you decide to call your your store ACME the directory structure would look like:
../orders/acme
Orders will be stored in this folder. Inside the ACME folder you will want to create a folder called templates and upload the contents of the TEMPLATES folder in this archive.
Upload these templates in ASCII Mode.
You are now ready to setup the order form.
Configure Your First
Store.
If you completed step two correctly you are now ready to configure your first
store. Point your browser to the TOSETUP.CGI file.
You will be asked for the name of the store this should match the name of the folder you created when you uploaded the templates. In our documentation above we called our store ACME.
You are presented with the main program configuration options:
Path To SendMail Program:
This is the UNIX sendmail program. If you are not sure of what this is contact
your system administrator.
URL to TORDER.CGI:
What is the URL to the TORDER.CGI script. This should also be changed in your
order form file.
Full Server Path To Store Orders:
This is the folder where you want the order files to be saved. This should be
a FULL server path. Be sure to include the trailing slash ( / )
Secure Root URL To Orders:
This is a URL. This url should be the correlating URL to the FULL SERVER PATH
TO STORE ORDERS. This url will be used to retrieve your orders through the web.
Merchant Email::
This is the email address that notifications will be sent to. This also will
appear in the FROM field for the customer confirmations.
AuthorizeNET SIM Configuration.
Test Mode?
If selected all transactions will not actually be submitted for payment. This
is useful for testing your new order system.
AuthorizeNet ID :
Enter Your AuthorizeNET login ID.
Transaction Key :
This key can be obtained in your AuthorizeNET merchant area and is required
for this script to function correctly. This key must be entered exactly as AuthorizeNET
provides it to you.
Tax Rate Setup
Tax State:
This should be your home state or the state where you do business in. Orders
from the selected state will be charged the tax rate specified below. .
Tax Rate :
This is the tax rate that should be charged to order from the state specified
above. The tax rate should be entered as a decimal value (i.e. 6.5% = 0.065).
If you do not want to charge tax enter a 0.
Shipping Setup.
You can configure your 4 predefined shipping options below. Dollar values should
not include a dollar sign ($). Percent values should be formatted in decimal
format (i.e. 10% = 0.10)
Setting Up The
Order Form
Your order form page can reside on any server on the internet. Basic knowledge
of HTML and FORMS is required to customize the generic order form to meet your
requirements. The form should POST into TODER.CGI.
The sample order form provides an excellent example of how to
setup various purchase types. You may acquire as much or as little data from
the customer as you see fit. It will all be saved with the order if configured
correctly. The following fields are the bare minimum of form fields required
to post into TechOrder.
Required Fields:
| Field Name | Description |
store |
This should match the store name. In our example in the configuration portion of this document we called the store ACME. |
from |
This is a field you
don't have to hide. The contents of the FROM field should always be the customer's email address. In most cases they will fill this in themselves. |
pid_# |
These
4 fields represent the product components, SKU/ID, Quantity to order,
Product Description (as shown on the invoice), and the price. |
qty_# |
|
desc_# |
|
price_# |
|
bill_first_name |
The credit card holders first name. |
bill_last_name |
The credit card holders last name. |
bill_address |
The credit card holders address. |
bill_city |
The credit card holders city. |
bill_state |
The credit card holders state. |
bill_zip |
The credit card holders zip code. |
bill_country |
The credit card holders country. |
shipping |
This should contain your shipping options (if any). Option values must represent the option number in your configuration. Allowed values are 0, 1, 2, 3, 4.. |
card_type |
The credit card holders card type. |
card_number |
This field is specifically
reserved for the credit card number. This field will always be syntactically checked to be sure a true credit card number has been entered. If you are testing the script you can use ‘0’ to get around this validation. If you are not asking for a credit card simply make this field hidden with a value of 0. |
card_month |
The credit card expiration month in MM format. |
card_year |
The credit card expiration year in YY or YYYY format.. |
required |
If you have added additional fields to your order form and wish to make them required you can add a hidden form field named 'required' the value of this field should contain a list of field names that should be required. Fields should be separated with a comma. |
All other fields will be passed and saved in the order file so long as the order
template file asks for the field. It is recommended that
you use plain english field names, particularly if you are forcing some fields
as required. If the user does not complete a field that is
marked as required then they will be given the true field name that wasn’t
filled in. So if you are asking for a telephone number and
you name that field ‘tn’ the script will say ‘Field tn is
required’. Visitors may not know that ‘tn’ is supposed to
be telephone number.
Templates
All templates work in the same way. They are a flat ASCII
text files that uses regular HTML comment tags to capture field data.
For example, in the template you specify where you would like the form data
to show up by using a html comment tag with the
fieldname as the comment. If your field name is 'Address', a line in your template
file might look like:
Visitors Address.......: <!--Address-->
<!--Address--> is then replaced in with what the visitor entered in that
form field.
Some of the template files have special tags to display relevant items such
as time or date. It is important not to name any of your
form fields these special tag names.
The template files and any special tags are listed below:
review.html |
This is
the HTML file that the customer is shown after they fill out the order form.
This template usually lists the items they are ordering and displays totals,
tax and shipping rates before the order is actually submitted. Please note that any images you choose to include on this page need to be relative to the CGI path you installed the torder.cgi script into. Special Tags:
|
||||||||||||||||
confirmation.html |
This page is displayed
when a customer completes the checkout process. Typically this page will
display their confirmation/order number. Please note that any images you choose to include on this page need to be relative to the CGI path you installed the torder.cgi script into. |
||||||||||||||||
declined.html |
This page is displayed
when a customers credit card was declined by AuthorizeNet Please note that any images you choose to include on this page need to be relative to the CGI path you installed the torder.cgi script into. |
||||||||||||||||
custemail.txt |
This is the email sent
to the customer once their order is submitted. You may include any value
on your order form including the following special fields. Special Tags:
|
||||||||||||||||
export_template.txt |
The export template
is used if you want to later import your orders into a third party program
or spreadsheet. By using a template for this the formatting of the import
file is completely in your hands. This template works as the rest of the
templates in the system. An example template is included. All fields on your order form are available to you as well as the following special fields. Special Tags:
|
||||||||||||||||
merchemail.txt |
This is the email that the merchant receives to inform them a new order has been placed. | ||||||||||||||||
order_template.txt |
This template is the
actual order file template. It should include what is actually saved with
your order. Anything that you put on your orderform should be included in
this file. Special Tags:
|
Advanced
Template Functions
TechOrder comes with TechScript a very easy to use html preprocessor. TechScript
provides webmasters with the flexibility to utilize perl/php-like scripts on
the order system templates. The TechScript scripting language allows you to
do simple arithmetic, conditional statements, file/url includes, cookie functions
and display system variables such as the date, time, referring page..
When used with the TechOrder you can manipulate what the user sees on the templates based on what they have entered. For example, on the order confirmation page you could display different text or graphics based on what shipping option the visitor selected.
TechScript is a constantly evolving language and is constantly being updated, please check to be sure you are running the most current release. A capsule language reference can be found at here.
Exporting Orders
Every time an order is placed a line is added to the file called exportdata.csv.
This is a plain ascii/text delimited flat database file.
All popular database systems allow for a ascii/text delimited import. By customizing
the export_template.txt file the field order can
be customized to meet practically any situation.
.Access Control
You MUST implement access control on your orders directory.
With apache web servers this can be accomplished by using .htaccess. TNL Total
Solutions offers a free web based tool to manage your .htaccess files available
for download at http://www.tnlsoft.com/tnlsoft/item.php?item=3
(c)2003 TNL Total Solutions • All Rights Reserved
TNL Total Solutions
P.O. Box 22441
Eugene, OR 97402
877-567-7441