| FAQ | Hosting Packages | Sign Up Now |
|
|
|
 |
 |
||||||
 |
Merchant OrderForm v1.5 Documentation |
| <----Return to Manual Click for printer friendly page What do you want to order today?
|
| Will I be able to
install this program? >>> GO TO TABLE OF CONTENTS Merchant OrderFormv1.5 are program scripts written in Perl 5 code for use on Unix type or NT systems using CGI (Common Gateway Interface). The program scripts are installed and run on the server where your Web Site is. You should be able to install the OrderForm page and the program's script files if:
|
| How do I make it do
this? >>> GO TO TABLE OF CONTENTS Merchant OrderFormv1.5 is loaded with settings and options, from simple to complex, that can be adjusted and/or configured to process your OrderForm input in many ways. You can read an overview of each configuration section's abilities and limitations under the heading further on in this document: Each of the configuration sections begins with an overview of what that group of settings can do. If you need to know if you can adjust things the way you need them, then find your way to the "What can these settings do" section for that group of configurations, and consult the summary there.You can also find answers for other questions under the heading: |
| What is Merchant OrderForm ? >>> GO TO TABLE OF CONTENTS Merchant Order Formv1.5 is a smart Online OrderForm and invoice system for small product collections. It interacts smartly with the user, and presents friendly feedback. It does not process credit card or online check transactions in real-time. It provides four ways to process orders from your Online Customers:
You can layout your HTML OrderForm page using checkboxes, dropdown boxes, listboxes, radio buttons, or hidden input, and Merchant OrderForm will sort out your Customer's orders and present smart looking invoices. Merchant Order Form v1.5 will handle as many New Products as your server has memory; however, this would not seem practical since the customer doesn't want to go through hundreds of checkboxes to order items. So, it's probably more applicable to smaller collections of products, whereas, a database / shopping cart system seems more user friendly for large product collections. A database / shopping cart system also allows the shopper to "add" products from any page on the Web Site, and collect in a "cart." Merchant OrderForm produces invoices from one OrderForm at a time. |
| Quick Start
Instructions >>> GO TO TABLE OF CONTENTS You need to do two things to get the scripts up and running in test mode:
|
| Setting correct file
permissions >>> GO TO TABLE OF CONTENTS Here are the files you need to FTP and
the corresponding permissions they need to work. Transfer all 9
files, and set the 4 "cgi" files with complete "execute"
permissions, then set the 2 "dat" files and 3 "rdb" files with
complete "execute" and "write" permissions. |
| Filename | Owner Permissions | Group Permissions | Other Permissions |
| orderconfig.cgi | Read, Write, Execute | Read, Execute | Read, Execute |
| orderfinal14.cgi | Read, Write, Execute | Read, Execute | Read, Execute |
| orderform14.cgi | Read, Write, Execute | Read, Execute | Read, Execute |
| ordercount14.cgi | Read, Write, Execute | Read, Execute | Read, Execute |
| orderlog.dat | Read, Write, Execute | Read, Write, Execute | Read, Write, Execute |
| ordernumber.dat | Read, Write, Execute | Read, Write, Execute | Read, Write, Execute |
| ordermain.rdb | Read, Write, Execute | Read, Write, Execute | Read, Write, Execute |
| ordercustom.rdb | Read, Write, Execute | Read, Write, Execute | Read, Write, Execute |
| orderorders.rdb | Read, Write, Execute | Read, Write, Execute | Read, Write, Execute |
|
| Running the scripts in test mode >>> GO TO TABLE OF CONTENTS Perform a test and see if you can run each of the scripts independently from your Web Browser. You don't need to submit anything from the HTML orderform to run them. Simply plug in the HTTP addresses where you placed the scripts on your server into your Web Browser's address or location bar. Here's an example from my site.
Of course, you'll get error messages when you run the first script <orderform14.cgi> saying you haven't completed the data entry fields, but the script is running, it's doing exactly what it's supposed to do without the information submitted by your OrderForm Page. You'll also get incomplete information when you run the other two scripts this way <ordercount14.cgi> and <orderfinal14.cgi> because they aren't processing any relevant information, but the scripts should still run. The <orderfinal14.cgi> file will not test this way if "cyber permission" is enabled. It is disabled in the download package. Unless you turned it on in the configuration file, then it should be disabled. Also, all other switches are initially turned off in the configuration file, disabling things like file locking, file logging, and mailing, which could prevent this final file from executing independently. When you have tested all three main script files and they are running on your server, then you are ready to begin your journey of configuring Merchant OrderForm for your site needs. You can place your HTML input OrderForm file <orderform14.html> anywhere you want, and point the FORM POST tag to the first processing file <orderform14.cgi> Here are some examples:
|
| Setting Up Your OrderForm Input
Page >>> GO TO TABLE OF CONTENTS There is a main example HTML OrderForm included in the package <orderform14.html>. It includes all the input fields that you might want to use for your OrderForm. There are also some samples of different ways you might want to make your OrderForm input page. They are meant to serve as examples, and you can create your own HTML OrderForm if you want. You can also modify the example OrderForms any way you want for your site needs. If you create your own OrderForm then just make sure you use the same name / value pairs that I have used. A detailed listing of these name / value pairs can be found in Appendix 1 at the end of this documentation. The scripts process information by these names only. Therefore, your OrderForm input Page will have to use these same "input names." |
| Here are some ways you may want to
customize your OrderForm input Page: >>> GO TO TABLE OF CONTENTS
|
| What are those other files in the package
? >>> GO TO TABLE OF CONTENTS My examples of the HTML OrderForm input Pages also include links to picture windows to put images of your products in. You can take this out, and everything will work fine. The <scripts.jpg> file is just a logo. When you configure the three processing files, you can use a similar image for your site logo, or you can omit the image and just use a name. |
| Adding products to the HTML OrderForm
input Page. >>> GO TO TABLE OF CONTENTS Merchant Order Form v1.5 scripts will process the product items in your HTML OrderForm input Page as long as you keep to the format I've set up. Here are the two rules:
<input
type="checkbox"
This tag will create a new checkbox that, when checked
by the user, will send the Item Name, Item Description, Price,
and ShipCode to the CGI processing files. The processing files
will identify only the "order" NAME for processing product
data, and the VALUE data will be extracted correctly only if the
delimiters are used correctly. You can use any input type you like as
long as the name / value pair follows the pattern outlined. You
can use radio buttons, drop down boxes, list boxes, check boxes.
Just make sure you always name a product "order" and give
the value the 4 elements defined. All of your product names will
be "order." This is how the scripts tell it's a product to be
sorted out separately from the other information. Usually, HTML
Form input names would not be duplicated; however, you must
duplicate them here.
name="order" value="Item Name----Description of the Item----11.65----1"> You can also format the appearance of your checkboxes, dropdown boxes, listboxes, radio buttons anyway you want. The way they appear on the page, the type of labeling you use has nothing to do with the underlying input name / value tags. You can use images, links, or anything else to list and describe your products as long as the underlying input name / value attributes are correct. If you get errors from the invoice processing you better check this portion very carefully and make sure that the NAME and VALUE delimiters are correct. The delimiter "----" 4 minus signs together with no spaces between text must be correct, and you must include all 4 pieces of information in correct sequence for the VALUE. The Price must be in 2 decimal format "100.00" and it must be a raw number with no dollar signs or other formatting like commas, etc. If the price is fifty cents then you would show that as "0.50", or $1,275.35 would be shown as "1275.35". The ShipCode must be free of any formatting also, and can contain only a numerical value. For now, you can just put ones for your ShipCode. Merchant OrderForm v1.5 has some serious flexibility when computing shipping charges, and in order to fully appreciate what you can do with your ShipCodes you may have to read about shipping computations in the next section called - Working with settings in the configuration file. |
| How to think about using the
ShipCodes:
>>> GO TO TABLE OF CONTENTS You don't need to understand the configuration file in detail at this point, but you will need some forethought to how you want to assign ShipCode values to each product. So, I will cover some information on how to think about using the ShipCodes. |
>>> GO TO TABLE OF CONTENTS There are two ways to think about using the global shipping schema: Calculate shipping charges as percentage of price The second way to use global settings is to set up your shipcodes as either a:
Either this item would be 35 cents to ship, or it would weigh 0.35 pounds.
|
>>> GO TO TABLE OF CONTENTS Don't even think about using these settings unless you are ready to think about multiple arrays in perl 5. This schema uses 12 individual settings for each shipcode assigned, and can get complicated. Better to start with the suggestions above, which should cover most shipping needs. If you want to use this level of computations then, you would use a system of numbering for your ShipCodes starting at 1, and proceeding in sequence to how ever many different individual computations you need. It might help to think of this schema in the same weights and amounts way, except that we won't be assigning weights and amounts in the HTML OrderForm input Page tags. Instead, we will be assigning a group number to each product, and in the configuration file we will assign the particular characteristics (amounts / weights) for that group. In this schema, you create a more complex system of shipping rules, where individual sets of shipping rules will be applied to each ShipCode. This system must use sequential integers starting from one. If you plan to use this method, don't assign decimal numbers to the ShipCodes, else the script won't recognize the ShipCode. When these settings are enabled in the configuration file, the script looks only for ShipCodes 1, 2, 3, 4, etc. Example: Let's say we have four different ShipCodes from 1 to 4 exactly. You can give any number of products a ShipCode of 1, thereby assigning it to the individual computation rules for group 1. Likewise for group 2, 3, and 4. Note: You don't have to use all the groups you set up, but that would be rather silly, not to mention pointless. If you set up a 4 number system, and only use ShipCodes for 1, 3, and 4, in your line of products, well then, obviously, you only need to use a 3 number system. The script will work fine looking for any products with a ShipCode of "2" and seeing none, will go on to checking the other ShipCodes. In computing, the scripts will look for all the 1's, then all the 2's, etc., keeping a cumulative total for each ShipCode. |
|
>>> GO TO TABLE OF CONTENTS This built in feature is enabled in the configuration file, and bypasses all other shipping computations. It's a way for someone to write their own code for processing shipping charges. If you're going to do this, then assign ShipCodes as you would in the "Individual Item Settings" above, in sequential integers starting at 1. Then when you write your code in the actual processing file, you write your own rules for computing each ShipCode group. There are more notes about this further on in the documentation at the section - Other Switch Functions. |
| Working with settings in the
configuration file >>> GO TO TABLE OF CONTENTS Each of the configuration sections begins with an overview of what that group of settings can do. If you need to know if you can adjust things the way you need them, then find your way to the "What can these settings do" section for that group of configurations, and consult the summary. Here are the major configuration sections that govern the behavior of the program:
|
| Some basics before we get
started. >>> GO TO TABLE OF CONTENTS Once your scripts are running in test mode, and you have set up your OrderForm input Page, then you are ready to configure the features and settings you want to use. Merchant OrderForm gets its instructions on what to do from the configuration file, so you'll be editing this file. Important: Use an ASCII editor only, do not use a rich text, or fancy word processor to edit the files unless it lets you work in ASCII mode only. It's also best to use an ASCII editor that will store the file in Unix format, if you are working from a Windows machine. Two of the processing files are too large for the regular Windows Notepad. Therefore, you may have to find a good ASCII text editor. Check out the NoNags Web Site. Okay, I wish I knew of some encouragement here. The configuration file is almost five pages long printed. If you're not used to CGI installations or perl looking code, then I know it looks like a mess. The good news -- you don't have to read about the features you don't want to use. But, if you want to turn on a feature, or adjust a setting, then the best way to do that is to use this portion of the documentation as a reference. If you're pretty savvy about perl looking stuff, then jump right into the file and start setting stuff by using the comments embedded in the configuration file. The file you'll be opening is called <orderconfig.cgi> and here's some points to know about cruising around this file:
# this is a comment
about something
You don't need to modify anything past the # character. You're looking at notes and instructions.
|
| 1. Tax
Variables and Configurations >>> GO TO TABLE OF CONTENTS What can these settings do?
$use_tax
$tax_before
|
| 2.
Discount Variables and Configurations >>> GO TO TABLE OF CONTENTS What can these settings do?
Here is an example of an uneven discount schema, which cannot be produced by MOF settings, but can be produced by custom code: Discount $ 2.00 first 3
products, and $ 1.00 every product thereafter until 10 products
are purchased, then discount every additional purchase $
1.50.
$use_discount
$min_discount
|
| Examples of the relationship between
rates and increments >>> GO TO TABLE OF CONTENTS Compute an exact five percent discount on every dollar
spent Compute a one-time discount of $ 10 on all orders over
$ 150
$use_discount = 1 turn on the discount computations $repeat_discount = 1 repeat the computation rule at each $ 100 dollars $num_discount = 0 do not use the number of products increment $amt_discount = 100 instead set the amount increment for every $ 100 $rate_discount = 5 set the rate to $ 5 for each $ 100 of total invoice amount
If we add a $min_discount and $max_discount to the last example then we can create a situation where at least a $ 5 discount is applied regardless of how much is spent, and the discount does not go over $ 20. Compute across the board a $ 5 discount
but not to exceed $ 20 with the last
example Compute a $ 10 volumediscount for each 10 products
purchased
|
| 3.
Handling Variables and Configurations >>> GO TO TABLE OF CONTENTS What can these settings do? The exact same things as the settings for discount explained in the preceding section.
The handling computations work exactly the same way as the discount, except they are, of course, added to the sub total after discount. The exact same schema is used. You can assess volume handling charges, a one time charge, or a percentage handling charge. Compute a five
cent handling charge for each dollar
spent |
| Shipping Configurations - Introduction >>> GO TO TABLE OF CONTENTS The shipping computation schemas follow rules that are very similar to the rules we have already been studying for Discount computations and Handling computations. Here's a quick list of what the shipping configurations do:
This is covered in the
section - Shipping
Configurations - Methods
Settings
This is covered in the
section - Shipping
Configurations - Global Settings
The Methods Settings and Computation Settings in
the Global and Individual schemas interact
together. Both Global and Individual schemas have settings for
each of the four methods that can be use.And the section - Shipping Configurations - Individual Item Code Settings |
| 4. Shipping Configurations - Methods
Settings >>> GO TO TABLE OF CONTENTS What can these settings do?
Four sets of rates can be used:Standard, Express, Foreign Standard, Foreign Express. So, you are able to use four different sets of rate variables which will be applied to the computation rules. The particular set of rate variables being applied to your computation rules, depends on how you configure the following options:
Enable this feature
by: Note: the "match_country" value must come from the drop down list on the OrderForm. You must use one of the exact Country names in the Select Country Names section found in this documentation - Appendix 3. Whenever a shipping destination uses a Country other than the Merchant Country defined in "match_country" then a foreign rate is applied. Two other sets of rate variables can be applied to the computation rules--Standard or Express shipping rates. You can allow the Customer to choose between these two methods by enabling the "use_rates" switch. This will place two radio buttons on the "Select Quantities - Verify Information" page allowing the Customer to select an Express rate if desired. When you enable this feature, the default rate is "standard" unless the Customer changes it to Express. You can also place your own text defining what is meant by "standard" and what is meant by "Express". The settings to use this feature
are: If you don't want the Customer to choose between "standard" or "express" rates, then you can disable the "use_rates" feature, but you must then set a default rate to be used in the computation rules. Disable Customer choices, and enable a
default "standard" rate like this: Disable Customer choices, and set a
default "express" rate like this: Note: you may not have both the "use_standard" and "use_express" switches enabled. If you do this then nothing will be triggered for defining what the default rate is. If you have the Customer choices enabled, then it doesn't matter what you have placed in the default settings, it will be overridden by the "use_rates" Customer choices. Note: when you get to the next section "Setting the computation rules," then you will see that there are settings for all four Methods --standard, express, foreign standard, express foreign. Make sure that you have placed values in all of the sets of rate variables that you will be using in your particular Method configuration. For example, if you don't use the Customer choices feature, and you don't use the Out of Country feature, and want to apply a $ 0.35 per pound standard rate set to all invoices, and you don't want a minimum or maximum limit, then you only need to have values for the "standard" set of rate variables: Only standard set of rate
variables: For another example, if you will be using all four possible options -- standard, express, foreign standard, express foreign, and you want a minimum shipping charge for any of these options, then you will need to give all sets values. If you leave these setting out, then the computations will attempt to act on a zero, which will zero out your shipping charges. The rule is -- make sure and place values for any of the four shipping rate methods that your particular configuration will be using. |
| 5. Shipping Configurations - Global
Settings >>> GO TO TABLE OF CONTENTS What can these settings do? For any one of the four methods the Global settings can:
This is an example of an uneven shipping schema: From 1 to 3 products
ordered charge $ 3.50 and then charge $ 1.00 for each item after
that, up to a total of 15 products, then the shipping charge is
free.
While the actual code to compute this example is fairly
simple, and can be custom written in perl code embedded in the
special shipping section, the global rules cannot produce an
uneven computation like this.
Configuration details The Global shipping computation rules work with the same strategy as the discount or handling computations. The computations can be adjusted to work with weight or dollar amount, and they can be set for a one-time charge, or a repeating computation. As already mentioned, the simplest way to think about ShipCodes using the "Global Settings" is to think of computing a rate per weight or cost per item. When using the ship code computation rules you are computing thusly:
There are four sets of rates --
standard, express, standard foreign, express
foreign You define the "computation rule" with the following three variables. Then, depending on the Method selected, the "computation rule" is applied to the appropriate set of rates. $repeat_shipping
|
| Examples of Global Shipping
Rates >>> GO TO TABLE OF CONTENTS Calculate a
"standard" shipping charge of $ 0.35 per pound with a minimum $
3.95 shipping charge: The num_shipping increment is 1 ( whatever ), so a 0.35 rate is applied to every 1 (whatever) units, and if minimum rate is set, then the minimum will be assessed, until the rate is over that value -- then anything over $ 3.95 is computed at 35 cents per 1 (whatever). The ShipCodes in your HTM OrderForm input Page are relative and can be anything; however, you need to have some plan for your ShipCodes so that computations are meaningful. Now, make sure and set all the other rate values if you are using all four methods. For example, if you have enabled $use_country and $use_rates then it is possible that any one of the four sets of rates may be selected. So, you need to make sure you have all four sets of rates defined. Note: the above example assumes that you used a "weight" schema for assigning ShipCodes in your HTML OrderForm input Page. Note: you only get to configure one computation rule. For example, you can't calculate an "express" shipping charge of $10.50 for anything from 1 to 10 pounds, and then assess a $1.25 per pound rate for anything over 10 pounds. This rule really uses two different increment settings. You can also just use a configuration based on the Total dollar Amount of products purchased, for example: Set up rates that would include
insurance based on dollar value. Note: you can't use one set of computation rules for "standard" and another set of rules for "express." You can only create one set of computation rules which will be applied to whichever set of rates is chosen by the method configurations. |
| 6. Shipping Configurations - Individual Item Code
Settings >>> GO TO TABLE OF CONTENTS What can these settings do?
|
| An overview of how it
works >>> GO TO TABLE OF CONTENTS
|
| How to set up the array
elements >>> GO TO TABLE OF CONTENTS With each array @items1 you are
basically creating individual definitions as you did in the
section above on "Global Settings." The "Global Settings" has 12
values defined: |
|
These set the values to be used in computations whenever the "standard" rate Method has been chosen |
|
These set the values to be used in computations whenever the "express" rate Method has been chosen |
|
These set the values to be used in computations whenever the "Foreign Standard" Method has been chosen |
|
These set the valued to be used in computations whenever the "Foreign Express" Method has been chosen |
|
The 12 elements in the item arrays
correspond to these same settings. Remember to be very careful in
making these arrays, and keep commas exactly between each of the
12 values as in the examples included in the packaged
configuration file. Here's what the elements correspond
to: |
|
|
|
|
|
||||||||
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
The above example has set No minimum or maximum rules, but has set the following rates to be computed for this ShipCode (let's say it's ShipCode 1): If the "standard" Method was selected a $ |