| 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 $ 0.35 rate would be applied to the total quantity of products that had a ShipCode = 1. When the script finds a product ordered with the ShipCode = 1, then it goes to the array @items1 and extracts the settings for whichever Method is active. Important: you must at least enter a zero for each element, and you must separate each element with a comma. When you set @items2 with a completely different set of definitions, then you can create extremely individual rates. The "standard" rates for all products with a ShipCode = 2 could be very different than the rates for ShipCode = 1. |
| Examples of Item Code Shipping
settings >>> GO TO TABLE OF CONTENTS If you wanted to give all orders with the ShipCode = 1 a minimum of $ 12.50 for the Express Foreign method no matter how many number 1 items were ordered, and anything after $ 12.50 would adjust an additional $0.50 per each number 1 item ordered, then: $use_ship = 1 If you wanted to make sure that a minimum of $ 12.50 shipping charge was applied to any set of orders where someone chooses the Express Foreign method of shipping, then just add the global setting: $min_Fexpress = 12.5 The $use_items schema only uses a number counting and not an amount. An amount is not needed because this coding schema is a distinguishing characteristic in and of itself -- all ShipCodes of 1 are of a particular type item, with a particular shipping requirement for a given Method. The script totals the quantity of products with the ShipCode = 1, computing the rate for the active Method, looks for any minimum or maximum rules to apply, and keeps a summary of the computed shipping charges for that ShipCode's quantity of products. Then the script does the same for the next ShipCode in the system, ShipCode = 2, and so on. Also, a repeating or one-time setting is not needed because a minimum / maximum setting for each @items definitions is able to set a one-time charge for that ShipCode. These values will limit that ShipCodes summary total to a high / low value. For example: For the quantity of products with ShipCode =1 A one-time $
4.50 charge for "Foreign Express" Method of
shipping is set this way: As you can see, the one-time shipping charge of $ 4.50 is applied as the summary of ShipCode 1's total. Important: the $ 4.50 is applied to the summary computations for ShipCode =1 only. If someone orders only one item with a ShipCode = 1, then $ 4.50 will be the total shipping charge. However, if products with other ShipCodes are ordered on the same invoice, then, while all ShipCode = 1 products will total to $ 4.50 only, the actual final shipping amount on the invoice will be a compilation of ALL the summary totals for each ShipCode set of rules in your system where someone has ordered a quantity of products for any given ShipCode. Also, if you use the Minimum - Maximum settings in the global functions for Standard - Express - Standard Foreign - Express Foreign, then you can create an "overall" Minimum - Maximum shipping charge for the method used. This means that after all individual computations are compiled and summarized for each ShipCode, then a final total can be tested against a global "Minimum" or "Maximum" for the shipping total. To make use of this feature just give the global settings your limit values for any of the shipping methods you want to apply this to. For example: You can set an overall Minimum
shipping charge of $ 18.95
for any out of the country express orders, by
setting: If you don't want any overall Minimum - Maximum to apply for a particular method, just leave it set to zero. If these global settings are all set to zero while using the individual item ship code system, then there will be no "global" adjustments to the overall shipping charges. The only Minimum - Maximum adjustments that will be applied are those you set in the item arrays |
| Some things that go without
saying >>> GO TO TABLE OF CONTENTS Note: you cannot use a ShipCode in your HTML definitions that has not been defined in your system of shipping codes in the configuration file, and when defining your system you must use only sequential numbers starting from one. Example: if you need to have 4 different ShipCodes, then you can only use the numbers 1, 2, 3, and 4 when putting a ShipCode value in your HTML OrderForm input page. You can't use a system of 4 ShipCodes and put a 5 as a ShipCode value in your HTML OrderForm definitions, because the script won't look for a "5" when computing each item's ShipCode. The script will only look for the values 1, 2, 3, and 4 in a system of 4 ShipCodes. Likewise, you can't define a system of 4 ShipCodes in the configurations, and try to use values in your HTML definitions starting with 5, 6, 7, and 8. I guess I really didn't need to say all this paragraph above, but you never know what some energetic soul might hope to do. |
| 7. Enabling Custom Fields >>> GO TO TABLE OF CONTENTS What can these settings do?
$use_fields
Other Information About Hobbies and Interests
There are three arrays that define:
@custom_titles = ( 'Type of Hobby','Area of Interest' )
|
| 8. Other Switch Functions >>> GO TO TABLE OF CONTENTS What can these settings do?
$special_ship
$redirect_url = "../index.html";
$log_file
The three RDB files provide a way to import all invoice information into any PC Database program that will import from ASCII flatfile delimited text files, like Access 97. The three files also provide your invoices sorted to separate files so that when you import the information you can build a relational design. You can see how the three files are printed and related in Appendix 4 - Structure of the related RDB files.
|
| 9.
Return Link Settings >>> GO TO TABLE OF CONTENTS What can these settings do?
Configuration details $site_name = "Your Site Name Here"
Here's an example of using a
logo Important: If you use double quotes to enclose this HTML tag, then you'll have to use the perl escape character "\" preceding quotation marks or other sensitive characters like @$, etc. Study the example above to see that where a double quote appears in HTML tags, it is preceded by the left backslash. This tells the perl interpreter that the next character is a literal character, since double quotes is a special character in perl. You can simply enclose the whole thing in single quotation marks, which tells perl that it's all literal characters. Here's an example of using font
attributes to highlight a plain text site
name
|
| 10. Merchant Information >>> GO TO TABLE OF CONTENTS What can these settings do?
$on_attributes =
"<strong>";
Make sure and enclose your information in double or single quotes: $site_address = "111 Merchant
Ave."; |
| 11. File
Locations >>> GO TO TABLE OF CONTENTS What can these settings do?
This section of configurations identify the file names and locations of all the files used by the scripts. The first processing file is not listed here, because it is started by your HTML OrderForm input Page, when you do the FORM POST Action. All other files that the scripts will need to work with are identified by name and/or location here. Remember: These files can be used by the processing scripts only if permissions are set correctly. Even though the file is listed in your CGI-BIN, if it doesn't have complete write permissions, then the script won't be able to write it. The script has built in error messages to tell you if a needed file can't be opened by the script. |
| These are the files needed by the
scripts: >>> GO TO TABLE OF CONTENTS orderconfig.cgi
orderform14.cgi
orderfinal14.cgi
ordermain.rdb
|
| A quick note about absolute
addressing >>>> GO TO TABLE OF CONTENTS The simplest way to make everything work is to just dump all these files in your CGI-BIN, then you only have to use the filename.cgi, and you don't have to mess with using absolute addressing to identify location. This is what we did in the Quick Start section. The script looks for the files in the local directory first, unless directed to look elsewhere. If you need to mess with absolute addressing, then this would be the entire pathway as if you were identifying a place on your hard drive, except you are identifying an actual location on your server's hard drive. It is not the HTTP address used in Browsing the Web. The HTTP address is a virtual address, and is not an actual pathway on your server's hard drive. It is a virtual pathway, known by the server's HTTP software, but the scripts can't write or read files via the Web HTTP address or location. The scripts must have the actual hard drive location of files it will be writing to or reading from. An absolute pathway would look
something like this on my local computer: This example places the main log file in a completely different directory than the CGI-BIN, and gives the absolute (actual) "pathway/filename.dat" so the script knows exactly where on the hard drive to write something. The script can't write through a virtual pathway like a Web address. It can only write to a hard drive. An absolute pathway might look
something like this on a server's hard
drive. This example writes to the main log file located in a sub directory on my public-web directories, providing the file has the correct permissions. It allows you to write the file in a location other than the CGI-BIN where the scripts reside. Again, this cannot be an HTTP address like you use in your Web browser, since a Web page is only a virtual location designated by the servers HTTP software. |
| Setting file
locations >>> GO TO TABLE OF CONTENTS Now, just make sure that you identify the filename (and locations if need) for all the following processes. You can change the filenames if you want, but then make sure you identify the correct file name in the file location settings below:
|
| Setting the delimiter used with the RDB log
files >>> GO TO TABLE OF CONTENTS There is one lone setting in this section which is used to define a delimiter for the RDB file logging. If you use the RDB logging, then you'll need to define a delimiter. This is a good one to use. $delimit = "~";
Here's an example of how the delimiter works in the RDB files. 1004~1004-512-444-7777~8/12/98~11:30:02~Master Card~Customer The above example has logged one record and six fields. There is more information on the exact structure of the ASCII flat file delimited database files in Appendix 4 - Structure of the related RDB files. |
| 12. Merchant and Customer Mail Options >>> GO TO TABLE OF CONTENTS What can these settings do?
This is the one set up part that people have the most trouble with. That's because server mail program locations and set ups vary more than other things. The trick to getting the mail working on Merchant OrderForm is to get the correct mail program location identified, and of course to have the correct send to address. |
| Where do you send the mail to ? >>> GO TO TABLE OF CONTENTS Once your mail program location is identified, then you can send mail:
$mailprog = '/usr/sbin/sendmail';
$mailprog = '/var/qmail/bin/qmail-inject';
The program Sendmail for Windows has also been recommended for NT applications, and is more affordable. A possible configuration is to install it on the NT Web Server Drive under D:|mail and then add it to the NT Environment. Then identify the address for Merchant OrderForm as: $mailprog = "/mail/sendmail"; Where you send the mail to: $myemail = 'yourname@domain.com';
|
| Now, you're ready to mail some
mail >>> GO TO TABLE OF CONTENTS Most problems with the mail portion are as mentioned above, the sendmail or sendmail simulated program is not identified correctly. Once this part is working, just turn on the switches to send the mail. $merchantmail
Warning: See the notes in the section called An important note about security about where you are sending mail to when you send Merchant invoices via email. $customermail
One last mail setting: $site_location = "http://www.yourdomain.com/";
|
| An important note about
security. >>> GO TO TABLE OF CONTENTS Here are some important recommendations about security with your Merchant OrderForm set up. Use SSL on a virtual domain when available I recommend that you use a secure web server SSL (the https: protocol) for transport of the FORM data to your web site, and that you keep the log file of invoices secure while on your server .. Make sure the log file doesn't live in a Public Web access area. A virtual domain would be secure, but not a simple user Public Web area. The Log file would be unsecured with a simple user Public Web area, and you wouldn't want to store credit card numbers like this. Make sure it's on a secure virtual domain web site. SSL is a function of your server's software, so you'll need to contact your server admin on how to send your CGI scripts through their HTTPS protocol and their site certificate. Once you have the HTTPS address to use, then you will call up FIRST your HTML OrderForm input Page through this secure HTTPS protocol. The link to your OrderForm input Page
from wherever will be through the HTTPS protocol. Now, any information between the browser and the script processes is encrypted via the HTTPS protocol, until you exit the last CGI process, or make a browser call to a non HTTPS location. When you exit the last CGI processing file, then you will be leaving the secure area. If you don't have a virtual domain with strict permissions, and you put the DAT file and the RDB files that log the invoices on a Public-Web set up, then at least give the DAT file and RDB files some very confusing name like <BFGIZ23432datafile.dat> and prevent a Web browser from reading a listing of your cgi-bin directory. Place an <index.html> file that reads "NO Access to this area" or something like that in your CGI-BIN, then whenever a browser tries to get a listing of the CGI-BIN directory, it defaults to the index.html file which has a message "No Access to this area." A virtual domain is set up with stricter permissions, and usually forbids access from Public Web inquiries trying to access a file on the CGI-BIN via the Web. |
| Keep the mail off the internet or use
PGP >>> GO TO TABLE OF CONTENTS If you enable the email options to have the Merchant receive a copy of the invoice via email, then use some form of encryption, like PGP. If you are mailing to an account on the same server as your OrderForm then it will be processed locally and should not go out over the internet. If mail account and OrderForm processing files are on the same server, the mail would be processed internally by the server, and not open to the Internet mail exchange. Make sure it's on the same server, or use encryption. PGP encryption is a utility program that is installed to process your mail. I don't know much about setting these up. But PGP would be set up as a program that you sendmail to, instead of the regular sendmail program. If you want to email me some more information of using PGP with Merchant OrderForm, then I'll put you on the permanent list of registered users with a lifetime membership. It is considered professional to state on the opening order FORM whether your process is secure or not .. |
| A checklist for installing CGI on Unix type
servers. >>> GO TO TABLE OF CONTENTS Here are some brief things you can check to make sure you have installed the scripts correctly on your Unix based server.
>whereis
perl
This will tell you the location of the perl
interpreter.
If you have Telnet
Access or using NT, you can type from the prompt or unix
shell
>perl
-v
Which will give you the version of perl that you are
running.
"require
filename.cgi" to "require
filename.pl"
|
| A collected FAQ for Merchant Order Form
v1.5 >>> GO TO TABLE OF CONTENTS I have included some of the common questions and installation problems that people are having with Merchant OrderForm. Here is a list of the FAQ stuff: |
| Can I do this with the shipping
configurations ? >>> GO TO TABLE OF CONTENTS Try not to embrace the RONCO method for your shipping schema--if you buy this I'll throw in this, and this, and yes, even this. This is an uneven configuration and the existing rules have no way of knowing how everyone around the World might dream up that very special shipping deal guaranteed to promote entrepreneurial fame. It's probably best that you get the basic idea of how MOF uses shipping rules first, and then see if you can fit your needs into that schema, rather than the other way around. Think about the shipping computations in one of three ways:
Basically, you can't do anything that is arbitrary or uneven with the existing configuration rules. You can however, do anything imagined by either writing your own perl code in the custom shipping section, or having someone (like myself) write the code for your custom shipping needs, even to the point of using a complicated table of shipping charges. This is an example of an uneven shipping schema: Shipping is $ 3.50 for
1 to 3 items, and then $ 1.00 per each additional item, up to 15
total items, where the shipping is free, unless it's express,
then shipping continues at $ 1.00 per additional item up to a
total of 25 items, when if becomes
free.
This can be written in about 8 or 10 short perl code
lines, but can't be accomplished from the MOF
settings. I'm looking at the actual 1999 UPS
shipping tables, and hope to be working on a few "plug-ins" that
will give MOF the ability to consult free standing shipping
tables in different ways. One could use the actual UPS tables, or
build their own tables. I just need the time to get to
this. |
| Can MOF accept input from multiple
OrderForms ? >>> GO TO TABLE OF CONTENTS Yes, but it can't consolidate them into one invoice. The MOF scripts will try to process anything you throw at them from anywhere in the World from an HTML FORM submission. However, MOF set up any cookies or reference that a particular OrderForm was submitted from the same person who wants a consolidated invoice. You can have hundreds of OrderForms which submit to only one location of the scripts for processing, and MOF will throw invoices back to the correct person, as fast as your computer will run, but MOF processes only one OrderForm at a time. Note: If you use one location of MOF to process OrderForms from several different sites, or several different locations within the same site, then all LOGGING will be stored in the same log file, because MOF uses the same set of configurations.
|
| Can MOF submit totals to my Online
Authorization Service ? >>> GO TO TABLE OF CONTENTS I'm researching a few of these services, which seem to have interface techniques that are easy to install. However, the Merchant OrderForm v1.5 package you have doesn't have any built in settings or configurations to just turn this on or off. Please contact me RGA@IO.COM with the name of the authorization service that you want to use, and I'll look into it. In many cases, it's a simple matter of submitting the final invoice amounts and other limited information via hidden variables, or the Environment QUERY_STRING variables. MOF simply submits some of its output to the appropriate service, and the service takes over from there. Some perl knowledgeable folks have linked Merchant OrderForm's output to an authorization service. If you are doing this, then I would be interested in collaborating with you on this, and can offer you a FREE lifetime membership for the Merchant OrderForm scripts in exchange for documenting your work. Or if you are working on doing it yourself, then I would be interested in assisting so that we could get it working smoothly. |
| Is MOF compatible with MS FrontPage 9x
? >>> GO TO TABLE OF CONTENTS Who cares ? Well, Big Bill probably cares, and I don't mean Mr. Clinton. I know, Big Bill doesn't even know about Merchant OrderForm, but he knows about MS Front Page 9x, and might care if you use his company's software. Big Bill's help system for MS FrontPage 9x probably doesn't explain that CGI scripts can be installed from HUNDREDS of programs all the way from FTP programs to HTML editors. Now, just exactly how you might do that with MS FrontPage 9x, or even if it will do that, I must confess, I don't have a clue, mainly because MS FrontPage 9x is one of the FEW pieces of Microsoft software that hasn't found its way onto my computer, or into my pocketbook. I've never used it. The important questions are do you know how to -OR- can MS FrontPage 9x:
My guess is that MS FrontPage 9x will do all of those three things, you'll just have to learn how to work it. Your Web pages or any CGI scripts don't actually integrate with MS FrontPage or any other Web publishing software. Web publishing software is just an agent to make and transfer HTML files to your sever, or to FTP other files to your server like JPG, GIF, or even CGI files. Web Sites and CGI programs actually LIVE on your ISP server. Once you have constructed and transferred the files, then your Web Publishing software has nothing to do with how the HTML or CGI files work on the internet. These questions are more relevant than the MS FrontPage 9x compatibility one:
|
| Basic trouble shooting
tips: >>> GO TO TABLE OF CONTENTS When the three processing files and one configuration file are installed correctly, you will be able to initiate a direct call from your Web browser to the http address where each script is located. You can initiate each script stand alone, by calling it up with your browser as in the example at my site. A direct browser call to the first
processing file: Although, a direct call to the first file like this gives you the incomplete input message, you know the file is running, else you would not get this message. The message is a result of the script processing without any input. You can make a direct call to the other two processing files in the same way to isolate which script is not running. If you get an "Error 500 Internal Server Error" then the script is not installed correctly, or it could be contaminated. Contamination could occur if not transferred correctly, not stored in Unix format for Unix type servers, etc. If you have access to the perl interpretor then run a perl -c ( for code check ) on the files. > perl -c filename.cgi
If you are not accessing perl 5 on your server, you will get an error checking the code on these scripts. Perl 4 will give you an error with the <sprintf> function. > perl
-v
This will give you the version your are
running.
If you get "Error 500 Internal Server Errors" keep reviewing the "CGI Installation Notes" until you get it right. You missed some subtle installation necessity. Of course "File Not Found" errors mean you don't have all the files linked correctly. But, running each script stand alone, for testing, will eliminate "File Not Found" errors. If one of the scripts returns a "Document Contains No Data" error then the script is running, meaning it has all the correct permissions, pathways, and is being processed by the perl interpreter, yet the perl interpreter has found a syntax error in the script. This invariably happens as someone goes to modify the script in some way, and misses the very strict syntax rules for balancing containers, quotation marks, not using the escape character for perl's designated characters, etc. Again, if you run a perl code check it will tell you where the error in the syntax is. >perl -c
filename.cgi |
| Error Opening DAT files or RDB
files >>> GO TO TABLE OF CONTENTS This is an internal message embedded in the last processing script. The final script sends it if it can't find the DAT files or the RDB files.
|
| Appendix 1 >>> GO TO TABLE OF CONTENTS Name - Value pairs used in the OrderForm input Page This is a list of the names that are already being used in the script processing or in the HTML OrderForm input Page NAME - VALUE pairs. Do not uses these same names if you make new fields in your OrderForm input Page or it will cause some conflict in the scripts processing information.
|
| Appendix 2 >>> GO TO TABLE OF CONTENTS Acronyms for using with State tax matching These are the NAME - VALUE pairs that are listed in the drop down box for identifying the shipping destination state. If you are going to enable the Tax these states option, then you need to use the two letter acronyms below to identify which state(s) will be matched for tax to be included, and which states will be matched for before - after exceptions. You can build your own drop down box if you want, but the rule is:
|
| Appendix 3 >>> GO TO TABLE OF CONTENTS Names used for Country Drop Down Box These are the country values used in the drop down box for shipping country. If you enable the $use_country feature, to automatically change the shipping rate for foreign shipping destinations, then you need to use the exact country as defined in the drop down box for the $match_country setting to identify what the domestic country is.
|
| Appendix 4 >>> GO TO TABLE OF CONTENTS Structure of the related RDB files This is the order of the fields that get printed to the main RDB file ordermain.rdb. If there is no data entered for a particular field, then a null is stored to that place, with the delimiter intact. There are 37 Fields printed in the ordermain.rdb file in the following order. If you import this file to a PC Database, then you'll want to set up this sort of structure to import directly into. All formatting is stripped from the dollar numbers, so the computations are stored in this file as non-formatted 2 decimal numbers
|
| Standard
Disclaimer >>> GO TO TABLE OF CONTENTS Okay, as mentioned at the opening of this file, and at the top of each of the scripts - By opening and configuring these scripts for your server and application you thereby assume any and all responsibility for the use and outcomes of this program. There are absolutely no warrantees or guarantees that come with these scripts. When you download the scripts you assume all responsibility for anything resulting from their use. |