Customizing MOF

Merchant OrderForm Web Based Shopping Cart System @ 2001
Notes on customizing in various ways

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.

How Do I .. ?

• Customizing computations for:
  • Discounts
  • Handling
  • Insurance
  • Shipping
• Customize the screen templates
• Customizing navigation buttons
• Customizing placement of navigation buttons
• Hook up to a processing gateway via POST
• Create a minimum purchase required message
• Bypass the Billing information screen
• Add new fields to the Shipping information screen
• Add new fields to the Billing information screen
• Add new payment methods
• Set up a third party affiliate program link

Notes about customizing MOFcart program files

1. Always keep good backups, and once something is customized and operating as you want, then renew your backups from the server. If you have custom mods for the MOFcart files on your server, then Do Not use program files from the MOF distribution packages. This is common sense, but beginners don't think of that.

USING MOF'S CUSTOM COMPUTATION AREAS

All of MOF's computations for the Order summary screen are done in moflib.pl. We've embedded branching in each of the computation sections where a "custom" flag can be triggered from the mof.conf settings. When a custom flag is used for primary discount, handling, default shipping, shipping methods, or insurance, then computations are redirected to whatever custom code you have placed in that section

1. Custom primary discount computation : moflib.pl : LINE 1390
   # CUSTOMIZE PRIMARY DISCOUNT COMPUTATION #
2. Custom handling computation : moflib.pl : LINE 1575
   # CUSTOMIZE HANDLING COMPUTATION #
3. Custom insurance computation : moflib.pl : LINE 1630
   # CUSTOMIZE INSURANCE COMPUTATIONS #
4. Custom default shipping computations : moflib.pl : LINE 1830
   # CUSTOMIZE DEFAULT SHIPPING COMPUTATION #
5. Custom multiple shipping methods computations : moflib.pl : LINE 2000
   # CUSTOMIZE USER SELECTED SHIPPING COMPUTATION #

Each of the custom computation areas provides settings for:

Line item override

MOF is set to display a particular item in the Order summary line item summary only if that item's computation result is greater than zero. If primary discount computes to zero, the line item for "primary discount" will not display. Enable the line item override to display it anyway.

Amount item override

MOF is set to display the currency formatted result of any item's computation (0.00) in the amount column of the line item summary. Define any string in the amount item override to display instead.

Both the line item override and amount override allow one to quickly adjust the line item behavior to display something like : "International shipping to be added" : to be added

variables

Each custom computation area has notes on what variables are available to that section.

Searching @orders

MOF keeps all cart items in the @orders (global) array. Look at any one of the cart scratch files in the ../orderdata/ directory to see the format. You will see the format is identical to the <FORM></FORM> input format ..

Quantity----Item----Description----Price----ShipCode----TaxCode

So, let's say you set up certain flagged items throughout your web site : and that you designated a flagged item by assigning the product a TaxCode = 10 (in the input), and that you wanted to find the number of flagged items, and combined price of only the flagged items, to do something with it in the handling computations:

my ($FlaggedPrice, $FlaggedItems) = (0,0);
my ($q, $i, $d, $p, $s, $t);

foreach (@orders) {
($q, $i, $d, $p, $s, $t) = split(/$delimit/);
$FlaggedItems += $q if ($t == 10);
$FlaggedPrice += ($q * $p) if ($t == 10);
}

You could now use the following results in a custom computation:

$FlaggedItems = how many TaxCode (10) items were ordered
$FlaggedPrice = combined price of all TaxCode (10) items ordered

Customizing the MOFcart templates

See Docs > Formatting.html

Custom navigation buttons

All navigation button (image) names, widths, heights, etc. are defined in the configuration files.

• See Docs > Formatting.html : TOP NAVIGATION MENUS
• See Docs > Formatting.html : OTHER NAVIGATIONAL LINKS
• See Docs > Formatting.html : BOTTOM NAVIGATION MENUS

Load up a thumbnail preview of all the images in the /mofcart/ directory. Create your own buttons, or edit ours. If you change dimensions on the images, you'll need to change the width : height attributes defined in the configuration files.

Note: the package navigation buttons were created with GIF transparency to allow the CSS HOVER effect when A.Link. The effects are not onMouseOver effects, but CSS effects

Customizing placement of navigation buttons

MOFcart has two ways of placing navigation buttons on the various cart pages. The simplest and most reliable way is to use the settings in the configuration files

mof.conf
mofpay.conf

These settings appear near the bottom of each config file. You can disable any or all of the various navigation buttons, or specify different image locations, dimensions, etc. If you use the config file settings, MOFcart will handle all of the logic for your various 9 cart templates, and the navigation buttons will appear as part of the actual MOF dynamic output (not as part of your templates).

You can also include any or all of the navigation buttons as part of your cart templates by using some simple javascript to link an image/button/text to trigger the appropriate <FORM> function as referenced by the Form Name.

For example: Let's say we have a <FORM> with the object name "formPreviewSubmit"

<FORM ACTION="coded" METHOD="POST" name="formPreviewSubmit">
(one of many forms embedded in the program code)

By referencing a given <FORM> collection by its document.name we can trigger that function from anywhere we want, and are not restricted to submitting that form between the <FORM> opening and closing </FORM> tags.

Here's how an outside link can trigger a <FORM> from anywhere we want, from a button image placed anywhere on a template page:

<a href="javascript:document.formPreviewSubmit.submit();">Next</a>

Note: The corresponding bottom navigation button must be enabled. MOF sets up the main <FORM> input for various cart functions from the bottom navigation buttons, so unless the corresponding bottom navigation button is enabled, then there will be no Form for the javascript to call. If you want to make your main buttons on the top, then you can simply turn the bottom navigation scheme into small text links, thereby, enabling the forms, but without the bulky buttons at the bottom.

Important: We have listed all formFunctions that are available on each cart page. You can only call the formFunctions that are available for that particular cart page, as listed in the tables below. You cannot call a formFunction that does not exist for that cart page. For example: You cannot set up a javascript link to the Shipping Info page from the Billing Information page. The formFunction does not exist at the Billing Information cart area.

Also, you will want to be careful if you decide to set up javascript triggers for formFunctions on your templates (outside the logic of the MOFcart code). MOF knows how to handle various situations, and may not display a button, even though it is fully enabled, because the situation doesn't warrant the function. For example: If you delete the cart then you do not want the "next" button available. MOF's code know how to deal with this, but your templates don't. You cannot perform any of this logic from the templates, only the code can perform logic. MOFcart provides you with options to enable Top and Bottom navigation schemes. It's probably best to just let MOF handle it.

Also, you cannot embed the "Continue Shopping" function in your templates because MOF tracks the referring URL to dynamically produce this link. Also, the "Edit Cart" function cannot be embedded in your templates, because MOF parses the Continue Shopping url along with this link, and you cannot account for that in your templates. You should never place a "View Cart" function in any of your cart templates. The "View Cart" link is meant only for a real html page (or dynamic page asp, php) outside the cart templates. MOF will track the referring url from a "View Cart" link, if you make a "View Cart" link in the cart templates, then the referring url will be the cgi script itself, which you do not want.

Here are the various <FORM> names that you can trigger with javascript

1. Opening Cart Page: Template: <mofviewcart.html>

2. Shipping Information Page: Template: <mofshipping.html>

3. Order Summary Page: Template: <mofsummary.html>

4. Billing Information Page: Template: <mofbilling.html>

Form Name	Function
formCheckout	Posts to "Place Order" from the Billing Info screen

How to hook up to a processing gateway via POST

Most of the gateway services provide a <FORM> POST method of POSTing a transaction to the gateway servers. Many also provide a more sophisticated way for carts to interact with the server, called an API (Application Programming Interface). An API usually requires a separate module or program that must be installed on your server, which can get very technical and complicated. At this point MOFcart does not integrate with any APIs.

The good news is that all gateways today have started to provide the easier POST method to connect to their server. In fact, some of them have the POST gateways and not an API. The more popular gateways provide both methods.

The POST gateway utilizes standard HTML <FORM> POST input to submit data to the transaction servers, and MOFcart provides a simple way to get the <FORM> connected to the cart.

MOFcart and Gateways Operational Sequence

First, I need to explain the operational sequence using a POST gateway, then I'll explain how to hook up your MOFcart to a POST gateway.

Using a POST gateway is very similar to the PayPal payment method built into MOFcart. All of the features of the cart are operating on your site, and a customer will progress through the sequence of Viewing the Cart, Shipping Information, Order Summary, Billing Information page, and then finally they will arrive at the Order Confirmation page after clicking the "place order" button.

When MOFcart presents the "Order Confirmation" page it does several things under the hood that you don't see. When the "place order" button is clicked, MOFcart will approve the information required on the Billing Information page, and if complete, MOFcart will:

1. Create/send the customer an order confirmation via email
2. Create/send the merchant an email notice that an order was placed
3. Create a web copy of the invoice if that feature is enabled
4. Update any databases that are operating (including ARES)
   (Note: all databases are additional plug ins for MOFcart)
5. Then, at last it will present the "Order Confirmation" page to the customer's browser

At that point, you can allow MOFcart to create a final "send" button, much like it creates the PayPal button to pass off to the PayPal servers. The customer must click the final "send" button to pass off to your particular gateway's transaction servers.

All of the gateway services can be set up to send an additional mail message to the customer, confirming that the transaction was completed, and credit card billed. So, the customer will receive two mail messages, and the merchant will receive two order notices.

One from MOFcart and then another from the gateway when the transaction is completed

The MOFcart mail message subject lists the Invoice Number in the subject, and then we send the Invoice Number to the gateway to set up in their mail. So, the merchant can match up who processed through the MOFcart and then went all the way through to finalize payment by matching up Invoice Numbers.

This is the only solution if you do not use an API. It works this way because MOFcart is not actually communicating with the gateway's transaction servers as it would with an API, but it is really just Posting the final data to the transaction servers, simply passing off the final data.

You'll want to keep MOFcart's mail messages turned on because the data that can be POSTed to the gateway's transaction servers is limited, and won't contain the order details that MOFcart can supply. If you want to turn off MOFcart's Customer Mail function, and have your customer only receive a message from the gateway, then that may work for you, but you will not want to disable the Merchant Mail notice, because it contains all the order detail.

If you do not want to haggle with duplicate mail messages, then an option might be to turn off the MOFcart mail, and use the web copy of invoices to find the order details. When the gateway server mails a merchant notice, you can find the Web Copy in the ../invoices/ folder corresponding to the invoice.

Decide on what kind of link you want between MOFcart and your gateway

Gateways can be very different in how much they allow you to do. Some are very limited in how much data you can pass, like PayPal, while others allow you to submit enough data to completely bypass any forms or stops on their servers, like the AuthorizeNet ADC Relay Response gateway. Consider what you need before deciding on a gateway service.

Here are some examples to explain that better:

If you do not have a merchant account, and don't want to collect credit card numbers live from your web site, and don't want to mess with setting up the MOFcart under SSL, then something like PayPal is an excellent selection. You never mess with credit cards, just have MOFcart pass off to the PayPal servers, and they will take it from there, using their forms, their SSL, etc.

If, on the other hand, you want to do the whole potato on your site, you have a merchant account, and you have SSL available to take live credit card numbers from the MOFcart Billing Information page, and you never want your customer to land on any forms that the gateway service has, then you will need something robust like AuthorizeNet's ADC Relay Response method. That gateway will allow you to post lots of data to the gateway transaction server, including the URL of a "callback" script on your web site. AuthorizeNet servers will handle the POST, and without using any of their forms, send back a response to a script on your web site and server, which will decide on what final message to display to the customer. So, if you want that kind of scenario, make sure you have found a gateway capable of the callback function, where you can bypass all their forms completely.

Case in point: Verisign's PayFlow Link has some impressive account management utilities, but when Posting the transaction they have a callback script (return url function), but will not allow you to bypass all their services forms. Your customer will always stop on Verisign's "Receipt Page" before continuing on back to your web site. So, if you need the kind of seamless scenario in the AuthorizeNet example above, you'll get stuck using Verisign's PayFlow Link.

Both PayFlow Link and AuthorizeNet will allow you to utilize their SSL, their forms to collect credit card information. So, if you don't have SSL available for MOFcart, and do not want to collect the credit card number on your site, then you can configure the <FORM> POST set up for those services, to utilize their forms to collect the additional information. Most gateway services provide some way of customizing the forms to have your logo, colors, etc, but it usually winds up being a primitive alternative to the way MOFcart can look using a complete HTML template.

So, if you don't mind using the gateway's forms, or don't have SSL, then you don't need to collect credit card information on the MOFcart Billing Information page. But, if you can't live with the sometimes primitive forms on gateway servers, or you don't want Verisign advertising to all your customers on the "mandatory receipt page," then you'll need the MOFcart Back End running under SSL so you can collect all the necessary credit card information on the Billing Information page, and you'll need a gateway service that will allow you to bypass their forms entirely, utilizing a callback function to send your site the results of the transaction-approved or denied.

How to hook up your gateway's <FORM> POST to MOFcart

Once you decide on how you want MOFcart and the gateway to link, then get the manual from your gateway service. All gateway services will provide a manual on hooking up your site, often referred to as a "developer's manual," or the "integration manual," etc. If you have developer access to the MOFcart web site, then check to see if we have done your particular gateway pkg.

The manual will tell you exactly how to set up the POST to the transaction servers. You will need the HTML <FORM></FORM> POST code and variables from your gateway, and then you will need to integrate their POST code into one of MOFcart's two areas for Custom Gateway code.

You must manually integrate the FORM POST code into the <mofpay.cgi> program. There are two places this can be done. You must use the MOFcart custom gateway area that matches the type of integration you are seeking.

Decide on which MOFcart Custom Gateway code area you need:

1. Method One: You do not need to collect credit card/check info on the MOFcart Billing Info. page. You will be using the gateway's forms to collect or verify this info. This method still allows you to collect cc/check info on the MOFcart Billing Info page, however, you cannot use any of MOFcart's built in validation for cc/check fields, info. This method sets up a separate Payment Method line item which you will define in the MOFcart configs. You can pass as much data to the gateway as it will allow you. PayPal is a Method One example.
   
   
2. Method Two: This method places the gateway code where all credit card/check info is collected via the MOFcart Billing Info page as specified in the configs. So, you can use MOFcart's built in validation and requirements to collect all cc/check info. This is the code area you must use for a seamless operation using a "callback" script. You will rely on MOFcart running under SSL at the Billing Info page to collect all necessary cc/check info, and validate it before setting up the POST to the gateway. AuthorizeNet ADC Relay Response is a Method Two example.

Method One Instructions:

1. Enable the Method One gateway settings in <mofpay.conf>

$use_gateway_forms= 1;
$gateway_item_name = 'Line Item Name Here';

2. Prepare the HTML <FORM></FORM> POST code as per the gateway instructions and insert the code in the <mofpay.cgi> file around Line 1275 between the comments:

# CUSTOM <FORM> GATEWAY BEGIN CODE ---------------->
Insert your prepared gateway code here between the "BEGIN" and "END" markers
Make sure your insert is formatted to the perl print syntax
Make sure you use the perl escape character \ preceding any " as needed
Make sure that you Start <FORM> and End </FORM> your form correctly
# CUSTOM </FORM> GATEWAY END CODE <-----------------

Method Two Instructions:

1. Enable the Method Two gateway in <mofpay.conf>

$use_gateway_mof = 1;

2. Prepare your HTML <FORM></FORM> POST code as per your gateway instructions and insert your code in the <mofpay.cgi> file around Line 1300 between the comments:

# CUSTOM FULL GATEWAY BEGIN CODE ---------------->
Insert your prepared gateway code here between the "BEGIN" and "END" markers
Make sure your insert is formatted to the perl print syntax
Make sure you use the perl escape character \ preceding any " as needed
Make sure that you Start <FORM> and End </FORM> your form correctly
# CUSTOM FULL GATEWAY END CODE <-----------------

3. If the gateway has ability to submit results to a callback script, then you'll need to write the callback script. We have an example of that in the Authorize Net integration package.

More on building your gateway FORM syntax

This will be the hard part. Construct the exact post as required for the gateway. Then, create the code for perl by surrounding the entire gateway code with the ..

print " code here ";

.. syntax. Perl folks will know how to do this. If you are a beginner, then consult the example snippet we've placed in the <mofpay.cgi> file around line 1275 and 1300.

# CUSTOM <FORM> GATEWAY BEGIN CODE ---------------->
# Insert your custom gateway <FORM></FORM> code here
# See docs file: Final Invoice Variables.html for list of vars available
# You must start a <FORM> and close </FORM> the form in your custom code
print "<FORM ACTION=\"---URL-TO-POST-TO----\" METHOD=\"POST\"> \n";
print "<INPUT TYPE=\"hidden\" NAME=\"---RETURN-URL---\" VALUE=\"$gateway_return_url\"> \n";
print "<INPUT TYPE=\"hidden\" NAME=\"---INVOICE-NUM---\" VALUE=\"$InvoiceNumber\"> \n";
print "<INPUT TYPE=\"hidden\" NAME=\"---FINAL-AMOUNT---\" VALUE=\"$Send_API_Amount\"> \n";
print "<input type=submit value=\"Payment $currency $Send_API_Amount\"> \n";
print "</FORM> \n\n";
# CUSTOM </FORM> GATEWAY END CODE <-----------------

Important: you must use the input "name" as specified by your gateway docs, and then you must fill the "value" with the corresponding MOFcart variable that contains that data. You can find a complete list of all MOFcart variables available to the script at that point in the:

> Docs folder
> Final Invoice Variables.html

In addition to the variables listed in the Docs, you can use these variables for available data:

Note: It is possible that the MOFcart variable data may not fit the format exactly as the gateway specs require it to be submitted, in which case you will need to write a snippet for conversion before using in the gateway POST syntax.

How to customize a minimum purchase required message

In moflib.pl around Line 1340 we have placed a simple example of how to trigger the Validation screen for MOFcart when a certain condition is not met. The condition is evaluated at the end of all computations, so all results for Discounts, SHI, Tax, etc. can be used in writing the condition. You could even write the condition based on type of items in the cart if you loop through the cart, and used a flag for identifying certain items. So, almost anything is possible. Write the condition, and then trigger the ValidationMessage sub routine as we have in the example.

You may want to think about modifying the mofvalidate.html template to express the message better. The Validation template is really meant for displaying a message when a customer has missing information when attempting to place an item into the cart. The validation template appears in two contexts when you use it for your minimum purchase message.

 

Bypass the Billing information screen

This is a little trick that requires some minor code adjustment.  If you are only using one payment method, say for example, you only want to allow Mail or Fax payment, or the PayPal Web Accept method, and you don't want to collect any other information like Billing Address, Receipt Address, Comments, then you can trick Mof into bypassing the Billing Information screen.

By default, when you click the "checkout" button from the Order summary screen, the Billing information page will always trigger, because at the very minimum, MOF is looking for the payment method for user input.  So, even if you only have one payment method enabled, Mof will stop on this screen to set up the hidden input for that one payment method.

If you submit that payment method as hidden input from the Order summary POST, and don't have any other fields set to display or validate on the Billing information page, then MOF will bypass that screen.

Example:

Let's say you were using PayPal only, and not collecting any Billing information, but wanted to proceed directly to the Order confirmation, to display the PayPal button ..

In mof.cgi around LINE 1488

# parse collected data ---------------->
# This is where you would put your hidden field to bypass
# The Billing Info page: example
print "<input type=\"hidden\" name=\"input_payment_options\" value=\"MAIL\"> \n";

Uncomment the print line to set up the hidden field "input_payment_options"
Then define the value=\"PAYPAL\" as the payment method acronym

You can use any of MOF's payment method acronyms:

<select Class="BillingBoxFormat" name="input_payment_options">
<option selected value="">Please Select Here
<option value=""> ------------------------------
<option value="VISA">Visa Credit Card
<option value="MAST">Mastercard Credit Card
<option value="AMER">American Express Credit Card
<option value="DISC">Discover Credit Card
<option value="DINE">Diners Club Credit Card
<option value="JCB">JCB Card
<option value="CART">Carte Blache
<option value="AUST">Australian BankCard
<option value="CHECK">Online Checking Draft
<option value="MAIL">Mailing or Faxing Payment
<option value="COD">COD Delivery
<option value="PAYPAL">Using PayPal Service
<option value="ONACCT">On Account
<option value="CALLME">Call Me For Card Info
<option value="GATEWAY">Pay By Custom Gateway
</select>

Also, you will need to turn off all settings in mofpay.conf that will trigger the Billing information screen to display.  In other words, you can't expect to bypass the Billing information screen if your config file is telling MOF to stop and collect Billing info fields, the comments box, the cyber permission, etc.  MOF will do as you say, even though it already knows the "hidden" payment method as set above in our little trick, it will still stop and attempt to collect any other info you are telling it to collect. 

All of the following settings must be set to off in mofpay.conf

• %billing_info_fields = ();
• %receipt_info_fields = ();
• %credit_card_fields = ();
• @credit_card_list = ();
• %checking_account_fields = ();
• $mail_or_fax_field = 0;
• $enable_onaccount = 0;
• $call_for_cc_info = 0;
• $enable_cod = 0;
• $enable_deposit = 0;
• $use_gateway_forms = 0;
• $enable_paypal = 0;
• $enable_comments_box = 0;
• $enable_cyber_permission = 0;

 

ADDING FIELDS TO SHIPPING INFO SCREEN

See mof.cgi LINE 515 :

# HOW TO ADD NEW FIELDS TO THE SHIPPING INFO PAGE #

ADDING FIELDS TO BILLING INFO SCREEN

See mofpay.cgi LINE 170 :

# HOW TO ADD NEW FIELDS TO THE BILLING INFO PAGE #

ADDING NEW PAYMENT METHODS

See mofpaylib.pl LINE 485 :

# BUILD PAYMENT OPTIONS

EMBEDDING AN AFFILIATE LINK

If you're wanting to place one of those simple HREF affiliate links to trigger each time an order is finalized, one place to do it is here

Very last lines in the mofpay.cgi script, where it is printing out the Order confirmation:

# YOU CAN PUT A SIMPLE <IMG SRC..> AFFILIATE [GET] LINK HERE -- Example
# The variable [$Send_API_Amount] is the Final amount after all computations
# (deposit if used)

print "<IMG SRC=\"http://www.URL.com/sale.cgi?cashflow=$Send_API_Amount\" border=0> ";

Also, keep in mind that MOF has a companion affiliate earnings system, that works right off your server, belongs to you, controlled and administered by you.

Use: ARES v2.4 (Affiliate Referral Earnings System) is a powerful companion affiliate program that runs exclusively with MOF. It is a fully automated, web based, two tier system that provides purchase tracking for affiliate earnings, representative earnings, customer discounts, real time sign-up, web based Admin, web based account management for affiliates, and more. It is an exclusive MOFcart companion program, available in the MOFcart developer's area for anyone licensed at the developer's level.

The best way to see it in operation is to sign up as an affiliate with MerchantPal.com services, where all MOFcart products are distributed. That will give you a tour of the system, and if you decide to actually use your affiliate links, you can earn real money.

You won't be able to access the Admin control panel, but you can view a complete set of the ARES v2.4 documentation here, which may give you an idea of how the Admin works

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