Building input pages

MOF Web Based Shopping Cart System @ 2001
Notes on how to build input pages

Table of Contents | FAQ | Installation | Security Issues | Building Input Pages | Formatting
Configurations1 | Configurations2 | About Configurations | Troubleshooting | Customizing

These programs are protected by copyright and may not be resold or distributed. Please see the copyright notice for more information on your end user license for this program.

MOF uses Forms

MOF is not a database driven cart. It's one of the only shopping carts in its class, and has almost unlimited adaptability. It is capable of accepting input from almost any kind of Form input you can dream up. So, the more skill one has with Forms, the quicker they will be able to design and deploy their product pages.

We have included a wide collection of examples with MOF. Explore the examples to get a quick start on how to create input pages or use this reference to get all the details.

What's in this document

• Use the examples
  The quickest way to get started for those who already have skill with Forms
  
  
• How does MOF work ?
  A brief explanation of how cgi scripts do what they do
  Some basics about how html forms work with cgi scripts
  A very brief Form tutorial

• Building your Online store
  Rules for making your Product Input Pages
  • Rules for the name=value pairs in your input
  • Understanding MOF's input modes:
  • MODE 1: QUERY STRING (GET) INPUT
  • MODE 2: SINGLE PRODUCT INPUT
  • MODE 3: CHECKBOXES LISTS
  • MODE 4: MULTIPLE PRODUCTS, ONE SUBMIT
  • Other Considerations in making input
  • Pseudo HTML and other tricks
    
  • Price adjusting product options
  • Price Input for product and product options
  • Quick reference for mode types

USE THE EXAMPLES

If you used the Installation.html instructions to install MOF on your server, the example pages should be installed in the ../mofcart/ directory, ready to POST to the cart. The examples include cut and paste html for the Form(s) in that example, and some brief tips on using that type of input

HOW DOES MOF WORK ?

1. You build Form based input pages for products
2. The Form sends data to the processing scripts (add to cart)
3. The processing scripts send results back to the browser

How It Works

Forms are built in standard HTML. You can build forms into a Web page with a standard HTML editor, like MS Front Page, Dreamweaver, HomeSite.

Forms collect information using objects like: text box, checkbox, dropdown box, list box, radio buttons, textareas.  These various objects are capable of collecting input. Each object will have a NAME and VALUE pair associated with it. 

Example: a simple text box on your page, will have a "name=Something" and the "value" will be what the user enters into the box.

a checkbox: You give it a "name=checkbox_one", and a value of "True/False" is collected depending on if the user checked it or unchecked it.

When the "submit" button is clicked, all information collected by the Form is sent to a processing script --> mof.cgi residing on your server. The scripts take over from there.

There are some good tutorials on Forms at cgi-resources.com if you need to learn more. You can also find help on Forms, and Form objects (or elements) in the help section of your favorite HTML editor.  Here's out own very brief tutorial.

Form basics

A Form area in HTML has an opening and closing. Any Form input objects between the opening and closing will be collected and sent to the script when the submit button is clicked.

<FORM .. method=POST action=URL to script> Start Form area
Input elements here ..
</FORM> End Form area

HTML editors will set this up for you

In the beginning <FORM .. > tag you will be declaring two things:

1. The "method" to use when submitting all the collected input data.
2. Where to send the whole collection of input data, "action"

This example says to send all the input collected in my Form to a program called: mof.cgi
Note the full URL, where mof.cgi is located on the world wide web.

<FORM method=POST action="http://www.domain.com/cgi-bin/mof.cgi">

So, your Form page has collected some input, and you have told the Form to send everything to a processing program located at http://www.domain.com/cgi-bin/mof.cgi,   when the user presses the "Go" or "Submit" button on the Form.

CGI programs accept what was sent, will process the data, then send results back to the originating browser.  MOF is written in Perl, but one could use other languages to interact with a server's CGI (Common gateway interface). The CGI gateway simply provides an interface between some program that exists on the server, and the World Wide Web. The server's web server software is responsible for managing this interface. CGI allows a Web browser to contact a program, and the program to talk back to the browser via the World Wide Web.

If you're learning about Forms and want to see this in action, then make a simple Form with your HTML editor:

In Dreamweaver: Insert > Form
Method: POST
Action: http://www.merchantpal.com/run/formtest.pl

Insert > Form objects > button (submit)
Insert > Form objects > textfield

Save the form and test it

In FrontPage: Insert > Form > Form
Right Click inside the Form container
Select Properties
Click Options button:
Method: POST
Action: http://www.merchantpal.com/run/formtest.pl

Then, insert some Form objects, save the Form, and test it

Want to kick it up a notch ?

Okay, go grab some of the cut and paste HTML Form code in any of the MOF example pages. Make sure the code is on your clipboard, then go to the simple test form you just created. Find the FrontPage or DreamWeaver tab to view the HTML code. Once in HTML view, paste in your copied Form code where the old test <FORM ..> </FORM> area is. Or you can simply paste the new Form code somewhere below the other </FORM> ending tag. Pages can have multiple Forms. Make sure you don't overlap the Forms, keep them separate.

Now go back to the editor display, and adjust the action properties for the Form to:
Action: http://www.merchantpal.com/run/formtest.pl

BUILDING YOUR ONLINE STORE

MOF was built with ability to accept almost any kind of Form input.  MOF will probably be able to process almost any Form you are creative enough to make.  Use a simple Buy Me button next to a product, or you can put an unlimited number and type of product options along side a product.

MOF has some specific rules that you must follow in constructing your Forms. Each of the examples have notes on the rules for that method and mode. Use the following sections to reference all the detail on MOF's different input modes and rules.

RULES FOR THE NAME=VALUE PAIRS

Except for one of MOF's input modes, the product input that you build will always have "order" as the name for the product. The value of any object with name="order" will contain a string that defines information about the product.

The value string containing the product information will have either 5 or 6 pieces (fields) of information about that product, depending on the mode you are using.  Those pieces of information are separated by a delimiter. MOF is already set to recognize the delimiter pattern of 4 minus signs.  You can change the delimiter in the configuration files if you want, but we know this one is reliable.

name="order"

(6 fields) value=Qty---- Item----Description----Price----ShipCode----Tax
(5 fields) value=Item----Description----Price----ShipCode----Tax

• Price: is in decimal format, no currency symbols: 12.95
• ShipCode: can be weight, or another flag, use plain numbers:
  0.12 is 12/100 of a unit (lb or whatever)
• Tax: is a simple switch: either on (1) or off (0). 
  Identifies an item as taxable (1) or not (0)

Note: The QUANTITYBOXES mode of input is done a little different.  The name=order must be numbered to match any other input associated with that product.  We'll cover more about that later.  For now, just note that all products, except those submitted under the QUANTITYBOXES mode, will always be name="order"

For INPUT name: use only alphanumeric characters, and don't use any special or fancy characters.  Name is case sensitive

For INPUT value: you can use the underscore, single hyphen, periods, numbers, decimals, and space in your input value="MOF Product Information".  

• Don't use any of these characters: ` ! @ # $ % ^ & * ( ) { } / \ < >
• Don't use any Perl special characters, quotes, semicolon, etc.
• Don't use the | character
• Don't use the double colon ::  
• Don't use the HTML tags < and > for HTML input
  MOF has a special way of handling HTML input
  
• Use the square bracket characters [  or  ] instead of regular < html > tags
  for HTML [pseudo tags] in the input if you need to pass HTML to the cart

All these characters are reserve characters with MOF and/or Perl. You could get unpredictable results if you use any of the above characters in your INPUT

Don't to put in any < HTML > tags in your INPUT values.  HTML tags will not confuse MOF, but it will confuse some browsers like Netscape as MOF attempts to Pass and Parse these characters. MOF has a special way of handling HTML input if needed.

Keep everything on one line, correct your editor if it splits up long lines with line breaks in the html.  Some editors like to Tab enormous spaces in the source, and some like to split input value=lines with great white spaces and line breaks.  This sort of thing can mess up what you are trying to send MOF, because not all browsers are capable of handling INPUT that is split up. Some of the old Netscape for windows and especially newer IE Mac browsers have problems with INPUT that is split.

UNDERSTANDING MOF'S INPUT MODES

MOF is expecting instructions and specific input for different types of products.  You instruct MOF how to process the input you are sending it by using one of four input modes.  MOF processes product input differently for each of the input modes.

The first input mode is via the Query String (GET).  When MOF finds product information at the Query String level, then it goes to work to sort it out in the simplest way:  One product at a time under the name="order" where the value contains all 6 fields of the product information.  The only other allowed piece of information that can be submitted via the QueryString is the ViewCart function.  You can call the ViewCart function by a standard hyperlink where the directive "?viewcart" is submitted as the only piece of information on the QueryString. If you attempt to submit anything else via the QueryString then MOF will discard it or give you an error.

If MOF doesn't find anything on the QueryString, then it looks for POST input.  Use hidden input to tell MOF which mode you are using:

<INPUT type="hidden" name="postmode" value="SINGLEPOST">
<INPUT type="hidden" name="postmode" value="CHECKBOXES">
<INPUT type="hidden" name="postmode" value="QUANTITYBOXES">

Each of the three postmode(s) trigger MOF to process your product input differently, and so the rules for that mode must be followed when you are making your product input.  You can see the notes further down with specific rules for each mode.

Note: Ignore the concept of "quantity boxes" when thinking about this postmode. The postmode "MULTIPOST" would have been a better suited name. Don't let the names lock you into Form design. Quantityboxes mode can use checkboxes, or radio buttons.

If you fail to define what postmode you are using, MOF will tell you it's unable to determine the post mode.  MOF will also try to check your product input, and in many situations tell you that you don't have all the necessary product information if all (5) or all (6) fields of information are not accurate for a particular POST mode.

Each of the four input modes have a Rules Checklist in the next section.
Here's a brief table to summarize how the four Modes differ:

* All product options field name(s) must be defined in the mof.conf configuration file, or the data will not show up in the cart.  For help on this see: Docs > Configurations1.html

Note: Only SINGLEPOST or QUANTITYBOXES mode allow for extra product option input

** Security Warning: Parsing product information via the QueryString allows the product's data to be altered by changing values in the browser's address bar and URL string. You should not use these methods of linking products to the cart if you are at all concerned about price tampering.

MODE 1: QUERY STRING (GET) INPUT

Security Warning: This method parses product information via the QueryString and the product's data can easily be altered by changing values in the browser's address bar and URL string. You should not use these methods of linking products to the cart if you are at all concerned about price tampering.

example

• Example_Single1.html

You can submit using the Form GET tag or an <A HREF> link.

Rules for input:

• uses the name=order: mof.cgi?name=order
• use 6 fields in value=Qty---- Item----Description----Price----ShipCode----Tax
• include Plus+Separators+In+This+Input+For+Spaces
• extra product options not allowed

Notes:

The only submission via the Query String that is accepted other than an "order" is for the "?viewcart" and "?test" functions.

Example link to trigger the viewcart function:
<a href="../cgi-bin/mof.cgi?viewcart">View My Cart </a>

The ViewCart function must be ?viewcart exactly, and cannot have any value after it.

MODE 2: SINGLE PRODUCT INPUT

<INPUT type="hidden" name="postmode" value="SINGLEPOST">

This is the postmode most commonly used. It handles all kinds of input, as you can see in the examples below, however, you can submit only one main product to the cart at a time

Use this mode to:

• Submit one product at a time to the cart
• Allow extra product options
• Allow quantity to be input by customer
• Defaults to 1 quantity if quantity field omitted
• Ability to select main product from a DropBox

examples

• Example_Single2.html
• Example_Single3.html
• Example_Options1.html
• Example_Options2.html
• Example_Complex1.html
• Example_Complex2.html
• Example_PriceInput1.html
• Example_PriceInput2.html
• Example_TextArea.html

Rules for input:

• For the product
• specify postmode=SINGLEPOST as hidden input
• uses name=order for main product
• use 5 fields in value=Item----Description----Price----ShipCode----Tax
• do not need plus+separators in your input
• quantity is separate input, using name=quantity
• may submit quantity as hidden or text input
• may omit quantity input, MOF will default it to 1

• product options
• define optional field name(s) in mof.conf configurations1.html
• define optional field name(s) as required if needed configurations1.html
• define optional field name(s) as price adjusting if needed configurations1.html
• define optional field name(s) as price input if needed configurations1.html
• the selected (default) option value="" (null) if it is a required field

Notes:

You can have multiple Forms on one page

MODE 3: CHECKBOXES LISTS

<INPUT type="hidden" name="postmode" value="CHECKBOXES">

Use this mode to:

• create a checklist OrderForm layout
• submit multiple products to the cart at one time
• where you do not require product options

examples

• Example_OrderForm1.html
• Example_OrderForm2.html
• Example_OrderForm3.html

Rules for input

• check an item if you want it
• product options not allowed
• specify postmode=CHECKBOXES as hidden input
• each checkbox will be name=order
• each checkbox value will have value=6 Fields
• use 6 fields in value=Qty---- Item----Description----Price----ShipCode----Tax
• quantity is the first field in the input
• unlimited number of checkboxes under the name=order on same Form
• checking the box includes the item when "add to cart" clicked
• you can use a ListBox, DropBox, or Radio Buttons with this mode 
  See Example_OrderForm3.html

Notes:

If using this design for our store, be careful not to overcrowd the pages. It's probably more customer friendly to break things down into several pages, grouped by category, than to make a long page list

MODE 4: MULTIPLE PRODUCTS, ONE SUBMIT

<INPUT type="hidden" name="postmode" value="QUANTITYBOXES">

Use this for

The only reason you would consider using this mode is if you need the ability to submit multiple products at one click, and the power to have product options, all on the same Form. This mode has the combined ability of CHECKBOXES and SINGLEPOST modes, which allows you to create sort of an order form with varied product options

I probably never should have written in this mode, because SINGLEPOST mode can do everything this can do, except submit multiple products, but someone would have asked for it. It can be a little complex to use

examples

• Example_Options3.html
• Example_PriceInput3.html
• Example_Matrix.html

Rules for input

• For each product:
• each product is assigned a unique name=orderN
  (where "N" is the product's unique number in the Form)
• use 5 fields in value=Item----Description----Price----ShipCode----Tax
• do not need plus+separators in your input
• quantity is separate input, submitted as a text box name=quantityN
  (where "N" is the product's unique number in the Form)
• customer selects item(s) by entering a quantity

• For each product's option(s):
• define optional field name(s) in mof.conf configurations1.html **
• define optional field name(s) as required if needed configurations1.html
• define optional field name(s) as price adjusting if needed configurations1.html
• define optional field name(s) as price input if needed configurations1.html
• each orderN can have optional input using field(s) name=optionN
  (where "N" is the product's unique number in the Form)
  
• MOF groups all data belonging to a particular "N" as one product
• the selected (default) option value="" (null) if it is a required field

** Note:

Use only the "Root_Name" in the mof.conf settings. But use the "Root_NameN" in the actual Form. MOF looks for the Root_Name string first and then groups all the "N" items and options together.

Make sure your number system correctly groups a given item's quantity and options:
example:
Item 3 input: quantity3, order3, hatsize3, hatcolor3, etc
Item 4 input: quantity4, order4, pictureframe4, framecolor4, printsize4

How it works

MOF will find your information if set up correctly. When any quantityN is detected > 0, meaning the customer wants the product, MOF will then look for the matching orderN, and any matching Root_NameN product options that belong to the "N" group

You do not have to keep sequential numbering. This is especially nice, because if you edit the line of products on a particular page, and delete product 15, then you don't need to renumber everything sequentially.  You can skip numbers. 

 

OTHER CONSIDERATIONS WITH INPUT

You cannot mix the CheckBox postmode and the QuantityBox postmode within one form submission. It seemed redundant to allow for checkboxes And Quantity Box input to be mixed, since a quantity of 1 instructs MOF that the item is wanted for the cart, and a checkbox performs the same function. So, with QUANTITYBOXES you wouldn't need a checkbox to select the item, the quantity box serves the purpose.

If your site is running in frames, you should consider running the cart outside the frames. Frames create some special installation challenges for cgi scripts. MOF will run inside a target frame, but you will need to make the "continue shopping" option a fixed link to get back inside the frames. Frames also are problematic using SSL.

You can Target="Another_Window" in your input, but you should use the exact scheme throughout your Web Site, since some of the Cart Functions will be corrupted if you submit a Target="Another_Window" for some items, and use the default Window for others. The Rule is that ALL submission possibilities must go to the exact same Window, whatever that window is for your Web Site.

PSEUDO HTML AND OTHER TRICKS

Use: you can pass [ square brackets ] in any of the item, description, and product option input and MOF will handle it as HTML tags.

How it works

MOF simply converts any bracketed [ syntax ] to < syntax > for printing back to the browser. So, [HTML] can be set up in the product's input to force special formatting, anchor links to products, pass IMG src=URLs, etc.

example

<input type="hidden" name="order"
value="Work Hat---- [img src=http://url/to/hat.gif]Work Hat----24.99----2----1">

If you're familiar with HTML, you can see what will happen to the description input when MOF swaps out the [ ] for < >. The description will be printed in the cart with HTML, an image.

Rules and notes

You can submit HTML [pseudo tags] in both the Item and Description areas, and because all product options wind up printing in the item's Description area, you can also use any HTML [pseudo tags] in any product option input.

We've provided a switch in the configuration files to disable printing the Item input in sub total lines. If two of an item were ordered, MOF creates a sub total line, yet you may not want a large image displaying in the subtotal line, just the main item table. Enabling the $item_in_subline setting fixes this problem

If you are doing some creative embedding of HTML [pseudo tags] in your input and you don't want MOF messing with your formatting, then disable the setting: $makelist. This will run the entire description string together in one long string, and only your formatting will show up. The Example_TextArea.html input looks much cleaner with $makelist formatting turned off.

All HTML [pseudo tags] are stripped out before the MySQL and/or ASCII dB storage plug ins store their info for Item and Description.

The mail messages also strip out all HTML [pseudo tags] except for anything that appears to be a <li>, <br>, or <p>

Do not use the real < HTML > tag markers in any of your input. MOF does not have a problem with it, but your browser does. Also, do not put double quotes in any of your input. Again, MOF does not have a problems with this, but your browser does.

If you are installing MOF's back end under SSL, then all the image reference tags should call the SSL location of that image.  This will slow down the image appearing in the cart, because you are actually calling the image from one of your secure directories, but you must do it this way so that the final invoice (operating under SSL) will have the object referenced from the secure location.  IF you identify an image in your product input from standard HTTP locations, then when your customer gets to the final invoice, and MOF is ready to display the image, then your customer's browser will tell them that some items on the secure location are not secure.  Not a good message to show your customers.

Netscape v6.x will not display an HTTPS image from a regular HTTP page. Opera and MSIE do not have problems doing this

Make sure all your HTML [ pseudo tags ] are balanced. If you are missing opening or closing tags, then you could get unpredictable results in the browser

PRICE ADJUSTING PRODUCT OPTIONS

Use: you want the product's price to adjust for different options

You can specify that certain product option(s) input for a particular product are treated as special price adjusting Fields.  For any of your forms throughout your Store Front and site that you want to do this for, you must:

1. Define all price adjusting Fields in mof.conf
   define optional field name(s) in configurations1.html as price adjusting
   
   
2. Format all price adjusting input in a special way

You can only use price adjusting with the SINGLEPOST or QUANTITYBOXES modes. See these examples for price adjusting using SINGLEPOST mode:

• Example_Complex1.html
• Example_Complex2.html

You can use price adjusting radio buttons, drop lists, list boxes all in combination with regular product options for the same product as we show in our SINGLEPOST example page.  You can even set up a very complicated group of products.  The product options can be a mix of regular input and price adjusting input.

format

name="WhatEver" value="Option Description----2.99"

• name "Whatever" must be declared in mof.conf in @field_adjustments
• value has two elements separated by the default delimiter
• value="Option Description----Price"
  • where price is in two decimal 0000000.00 raw number
  •   0.00 = no change in product's price
  •   1.99 = a $ 1.99 increase in product's price
  • -1.99 = a $ 1.99 decrease in product's price

How it works

Any field name that MOF sees declared in the  @field_adjustments array will be treated as having two elements to it.  MOF will process the second element of price accordingly, making adjustments to the base price for the product. When all price adjusting options for a given product are processed, then MOF will reset the product's cart price to the newly adjusted price.  MOF will also display any price adjustments next to the option data in the invoice description section for that product.

Notes:

For the product description section of the cart to look well, you should probably include the Base Price of the initial product in the product description data.  That way a Base Price and any Adjusted pricing will show in the description details.  You don't need to include any price description for the Option input, because MOF will append the price to the Option description.

You can use the same Field Names for a regular field and a price adjusting field if you want to.  MOF will simply ignore any price adjustments in the value for a regular option that was submitted, because the regular options input does not have two elements for MOF to work with.  While this will work, it's probably a better idea to keep regular and price adjusting Field Names separate.  Once you declare a Field name as price adjusting, then it can be used that way throughout your site, even with different data as values.  MOF only needs to know that it is a special price adjusting field.

If you format any product option input as price adjusting, yet fail to declare it as a price adjusting field in the in the price adjust @field_adjustments then you will get unpredictable results in the orders table

PRICE INPUT FOR PRODUCT AND PRODUCT OPTIONS

Use: you need customers to enter their own price input for the main product, or as product options

as main price

You can specify a certain field to be seen by MOF as containing actual price input for the product's main price. See configurations1.html for the setting: $price_input

as product option(s)

You can also specify certain product option(s) input for a particular product to be seen by MOF as containing actual price input additions for a product

1. Define all price input Fields in mof.conf
   define optional field name(s) in configurations1.html as price input
   
   
2. Set up the input as a text box

You can only use price input with the SINGLEPOST or QUANTITYBOXES modes. See these examples for price input fields using SINGLEPOST mode:

examples:

• Example_PriceInput1.html - price input as main price
• Example_PriceInput2.html - SINGLEPOST as product options
• Example_PriceInput3.html - QUANTITYBOXES, mixed input

format

<input type="text" name="Whatever" size=15 value="">

• name "Whatever" must be declared in mof.conf in @price_input_adjustments
• You can only use a text box for this input
• okay to mix it with other types of input
• a field name cannot be used for both price adjusting and price input

QUICK REFERENCE FOR MODE TYPES

summary of rules

 
5 Fields Look like this
value="Item----Description----Price----ShipCode----TaxCode"

6 Fields Look like this
value="Quantity----Item----Description----Price----ShipCode----TaxCode"

These programs are copyright @ MerchantOrderForm.com, MerchantPal.com 2001