Zen Cart Documentation – Modules

Dev: Shipping Modules

Mon, 01 Jan 0001 00:00:00 +0000

Introduction

A shipping module applies a shipping cost to an order, based on some calculation method. Each shipping module requires a minimum of two files:

A class file: /includes/modules/shipping/modulename.php
A language file: /includes/languages/current_language/modules/shipping/lang.modulename.php (or simply modulename.php in 1.5.7 and below).

The language file contains all the translatable language text for the module while the class file contains the module’s processing portion. A shipping module can include one or more methods.

Shipping Class

The class defined in /includes/classes/shipping.php handles the loading of the shipping modules during Zen Cart storefront order-processing.

Anatomy of a Shipping Module

Class Names

A shipping method’s filename (e.g. myshipping.php) is also used as its class name:

class myshipping extends base
{
  ...
}

Note: Since an order’s shipping selection is stored as a string combining a shipping module’s name plus an underscore (_) plus the shipping-method selected, a shipping module’s name cannot include an underscore!

Class Variables

A shipping-module’s class definition includes, at a minimum, the following publicly-available variables:

Variable Name	Variable Type	Variable Usage
code	string	Contains the unique identifier for this shipping-module; normally set to the module’s class name.
enabled	bool	Determines whether (true) or not (false) the module is enabled for use during the current storefront checkout.
title	string	Contains the title displayed for the shipping-module in both the Admin Modules > Shipping and the storefront shipping quote. This variable is normally initialized during class construction to a (shopfront) language-file definition in the shipping module, e.g. MODULE_SHIPPING_(module name)_TEXT_TITLE
description	string	A description of the module displayed only in the Admin, Modules > Shipping. This variable is normally initialized during class construction to a (shopfront) language-file definition in the shipping module, e.g. MODULE_SHIPPING_(module name)_TEXT_DESCRIPTION
tax_class	integer	Identifies the `tax_class_id` associated with the tax to be applied to this shipping module’s costs. If the value is 0, the shipping cost is untaxed.
tax_basis	string	When the shipping cost is taxed, identifies the basis for the tax computation: either Billing, Shipping or Store.

Class Methods

Constructor

A shipping-module’s class constructor performs initialization of its class variables and determines whether the shipping module is enabled for the current order. Upon completion, the class variable enabled identifies whether (true) or not (false) the module is to be enabled for storefront processing.

class myshipping extends base
{
    public function __construct()
    {
    }

    ...
}

quote

This function determines the quote (i.e. the shipping cost) for either each of the module’s available methods or for the specified module sub-method, depending on the function’s $method input value. If no quote(s) is/are available, regardless the value provided for the $method input, the shipping module sets its quotes property to either (bool)false or an empty array ([]) and returns that value. Otherwise, the quote information is returned in the class propertyquotes: an associative array containing the following fields:

Element Name	Required	Type	Description
id	Yes	string	Set to the shipping method’s class variable `code`, i.e. its class name.
module	Yes	string	Set to the shipping module’s language file title, e.g. MODULE_SHIPPING_(module name)_TEXT_TITLE
methods	Yes	array	A simple, i.e. numerically-indexed, array of associative arrays. See below for each entry’s definition.
tax	No	float	If the shipping cost is to be taxed, the value returned is the rate to be applied. For instance, if the shipping is to be taxed at 8.37% this value will be 8.37; this value is normally that returned by call to the function `zen_get_tax_rate`.
icon	No	string	If an icon is associated with the shipping module, this value is set to contain an HTML `img` tag (usually generated by call to `zen_image`) that sources that icon.
error	No	string	If an error results from the quote’s generation, this field contains the error-message to be displayed.

Each element of the methods array contains the following fields (depending on the shipping module, there might be additional fields):

Element Name	Type	Description
id	string	Set to the shipping method’s class variable `code`, i.e. its class name.
title	string	A text string containing the method name, e.g. MODULE_SHIPPING_(module name)_TEXT_WAY This text string is appended to the shipping module title to identify multiple methods within the same shipping module that may produce several quotes.
cost	float	The cost associated with the current shipping method.

Basic quote function processing is illustrated below.

class myshipping extends base
{
    ...
    public function quote($method = '')
    {
        global $order;

        ...

        $this->quotes = [
            'id' => $this->code,
            'module' => $this->title,
            'methods' => [
                [
                   'id' => $method_name,
                   'title' => $method_description,
                   'cost' => $method_cost
                ],
                ...
            ],
        ];
        if ($this->tax_class > 0) {
            $this->quotes['tax'] = zen_get_tax_rate($this->tax_class, $order->delivery['country']['id'], $order->delivery['zone_id']);
        }
        if (!empty($this->icon)) {
            $this->quotes['icon'] = zen_image($this->icon, $this->title);
        }
        return $this->quotes;
    }

    ...
}

General Quote (all methods)

When the quote function is called with an input $method value of ’’ (an empty string) and one or more quotes is available, the function returns an array containing quotes for all methods it provides. One methods array entry is provided for each method applicable to the current order.

This form of the function call is used by the Shipping Estimator and in the shipping-method selection provided by the checkout_shipping page’s handling.

Specific Method

When the quote function is called with a non-empty value in the $method input and the quote is available, the function returns an array containing the quote for that specific method.

check

This function, called from admin-level Modules > Shipping processing, returns a boolean value indicating whether (true) or not (false) the shipping-module is currently installed.

class myshipping extends base
{
    ...

    public function check()
    {
        global $db;
        if (!isset ($this->_check)) {
            $check_query = $db->Execute("SELECT configuration_value FROM " . TABLE_CONFIGURATION . " WHERE configuration_key = 'MODULE_SHIPPING_MYSHIPPING_STATUS' LIMIT 1");
            $this->_check = !$check_query->EOF;
        }
        return $this->_check;
    }

    ...
}

install

This function, called from admin-level Modules > Shipping processing when the shipping module is initially installed, sets the module’s configuration into the Zen Cart database. The example shows how to insert the common, required, configuration elements into the database for the myshipping shipping module. If your shipping method requires additional settings, add them here.

class myshipping extends base
{
    ...

    public function install() 
    {
        global $db;

        $db->Execute("INSERT INTO " . TABLE_CONFIGURATION . " (configuration_title, configuration_key, configuration_value, configuration_description, configuration_group_id, sort_order, set_function, date_added) VALUES ('Enable Flat Shipping', 'MODULE_SHIPPING_MYSHIPPING_STATUS', 'True', 'Do you want to offer "my shipping" shipping?', 6, 0, 'zen_cfg_select_option([\'True\', \'False\'], ', now())");
        $db->Execute("INSERT INTO " . TABLE_CONFIGURATION . " (configuration_title, configuration_key, configuration_value, configuration_description, configuration_group_id, sort_order, date_added) VALUES ('Shipping Cost', 'MODULE_SHIPPING_MYSHIPPING_COST', '5.00', 'The shipping cost for all orders using this shipping method.', 6, 0, now())");
        $db->Execute("INSERT INTO " . TABLE_CONFIGURATION . " (configuration_title, configuration_key, configuration_value, configuration_description, configuration_group_id, sort_order, use_function, set_function, date_added) VALUES ('Tax Class', 'MODULE_SHIPPING_MYSHIPPING_TAX_CLASS', '0', 'Use the following tax class on the shipping fee.', 6, 0, 'zen_get_tax_class_title', 'zen_cfg_pull_down_tax_classes(', now())");
        $db->Execute("INSERT INTO " . TABLE_CONFIGURATION . " (configuration_title, configuration_key, configuration_value, configuration_description, configuration_group_id, sort_order, set_function, date_added) VALUES ('Tax Basis', 'MODULE_SHIPPING_MYSHIPPING_TAX_BASIS', 'Shipping', 'On what basis is Shipping Tax calculated. Options are<br>Shipping - Based on customers Shipping Address<br>Billing Based on customers Billing address<br>Store - Based on Store address if Billing/Shipping Zone equals Store zone', 6, 0, 'zen_cfg_select_option([\'Shipping\', \'Billing\', \'Store\'], ', now())");
        $db->Execute("INSERT INTO " . TABLE_CONFIGURATION . " (configuration_title, configuration_key, configuration_value, configuration_description, configuration_group_id, sort_order, use_function, set_function, date_added) VALUES ('Shipping Zone', 'MODULE_SHIPPING_MYSHIPPING_ZONE', '0', 'If a zone is selected, only enable this shipping method for that zone.', 6, 0, 'zen_get_zone_class_title', 'zen_cfg_pull_down_zone_classes(', now())");
        $db->Execute("INSERT INTO " . TABLE_CONFIGURATION . " (configuration_title, configuration_key, configuration_value, configuration_description, configuration_group_id, sort_order, date_added) VALUES ('Sort Order', 'MODULE_SHIPPING_MYSHIPPING_SORT_ORDER', '0', 'Sort order of display.', 6, 0, now())");

        ...

    }

    ...

}

keys

This function, called during admin-level Modules > Shipping processing, returns the database configuration “keys” associated with this shipping module. The configuration values are listed for the shipping module in the order specified by the returned array.

class myshipping extends base
{
    ...

    public function keys() 
    {
        return [
            'MODULE_SHIPPING_MYSHIPPING_STATUS', 
            'MODULE_SHIPPING_MYSHIPPING_COST', 
            'MODULE_SHIPPING_MYSHIPPING_TAX_CLASS', 
            'MODULE_SHIPPING_MYSHIPPING_TAX_BASIS', 
            'MODULE_SHIPPING_MYSHIPPING_ZONE', 
            'MODULE_SHIPPING_MYSHIPPING_SORT_ORDER'
        ];
    }

    ...

}

remove

This function, called during admin-level Modules > Shipping processing to remove this shipping module, removes all database configuration keys associated with the shipping method.

class myshipping extends base
{
    ...

    public function remove() 
    {
        global $db;
      	$db->Execute("DELETE FROM " . TABLE_CONFIGURATION . " WHERE configuration_key LIKE 'MODULE\_SHIPPING\_MYSHIPPING\_%'");
    }

    ...

}

Standard Configuration Settings

These common settings should be provided by all shipping modules:

Configuration Name	Configuration Value
`MODULE_SHIPPING_MYSHIPPING_STATUS`	Set to either ’true’ or ‘false’, identifies whether or not the module is currently enabled
`MODULE_SHIPPING_MYSHIPPING_ZONE`	If a zone is selected via the dropdown, the shipping module is enabled only for that zone.
`MODULE_SHIPPING_MYSHIPPING_TAX_CLASS`	If the shipping is to be taxed, identifies the Tax Class associated with that tax
`MODULE_SHIPPING_MYSHIPPING_TAX_BASIS`	Choose the address-basis (usually one of `Shipping`, `Billing` or `Store`) from which the tax is calculated.
`MODULE_SHIPPING_MYSHIPPING_SORT_ORDER`	Identifies the sort-order to be used when displaying the currently-enabled shipping modules.

Tips & Tricks

Procedurally, all configuration options for a shipping module names myshipping should be named MODULE_SHIPPING_MYSHIPPING_*, as should all language constants for the module, to ensure uniqueness of those constants.

Converting a shipping module to extend ZenShipping

Since 2.1.0 shipping modules have been changed to extend the ZenShipping base class. To convert an older module to this new style, make the following changes:

Change the class declaration to say extends ZenShipping.
You won’t need to declare the standard variables anymore; includes/classes/ZenShipping.php declares the following:

    protected $_check;
    public string $code;
    public string $description;
    public bool $enabled;
    public array $debug = [];
    public string $icon;
    public array $quotes;
    public $sort_order;
    public string $tax_basis;
    public $tax_class;
    public string $title;

Be sure the following functions have signatures that are compatible with the base class:

function quote($method = '') : array {
function install() : void {
function remove() : void {
function keys() : array {

Be sure any early return from quote() returns an empty array.

Troubleshooting

Since the admin-level processing by Modules > Shipping loads all .php modules present in the /includes/modules/shipping folder, make sure that any backup files in that directory have the .php extension changed, e.g. .php~ or .php.old, or errors will result during the admin loading.

Dev: Testing PayPal Modules

Mon, 01 Jan 0001 00:00:00 +0000

Testing PayPal Transactions

To test that PayPal is properly configured, you should test two methods:

Test by paying for something using a PayPal account (not the same account as your store).
Test by paying for something with a credit card WITHOUT creating or using a PayPal account for payment.

All of these tests are to be performed in “production” or “live” mode. Do NOT use a Sandbox for testing. (If you don’t know what this means, just proceed with testing.)

Testing using a PayPal account

You need a second PayPal account to do this. PayPal allows you to have two accounts per person: one personal and one business. For this test, you will pay for your purchase using funds on account in your personal PayPal account. You will be paying money to your store account (and refunding it).
Create or select a product which has a low price, such as $0.01 or maybe $1.00.
Purchase that product.
During checkout, choose the lowest-price shipping option.
During checkout, choose PayPal.
After the Checkout Confirmation screen, you’ll be taken to the PayPal website to make payment.
Enter your PERSONAL PayPal account username and password.
Confirm the transaction.
You will be returned to your store after completion.
Verify that you received two or three emails: one from PayPal, one from the store to you as a customer, and one from the store to your Admin address. If you did not receive the emails from the store within five minutes, then go to the Troubleshooting section of this document, above.
Log in to your BUSINESS PayPal account and refund your test transaction.

Testing without a PayPal account

To test payment by credit card without using a PayPal account, use these steps:

(Before proceeding, find your credit cards, and select one that’s not already associated with any PayPal account !!)

Create or select a product in your store which has a low price, such as $0.01 or maybe $1.00.
Purchase that product.
During checkout, choose the lowest-price shipping option.
During checkout, choose PayPal.
After the Checkout Confirmation screen, you’ll be taken to the PayPal website to make payment.
Underneath the login box for PayPal username/password, there is a link to Purchase without a PayPal account. Click that link.
Fill in and/or confirm your personal information.
Fill in your payment details including credit card number. (You should NOT use a credit card number that’s already associated with any PayPal account !!)
Confirm the transaction.
You will be returned to your store after completion.
Verify that you received two or three emails: one from PayPal, one from the store to you as a customer, and one from the store to your Admin address. If you did not receive the emails from the store within five minutes, then go to the Troubleshooting section of this document, above.
Log in to your BUSINESS PayPal account and refund your test transaction.

Dev: Order Total Modules

Mon, 01 Jan 0001 00:00:00 +0000

Introduction

Zen Cart order-total modules are used to calculate (and display) sub-totals, taxes, totals and other intermediary values for an order. Order-total modules can also calculate discounts or other subtractions from the amount a customer owes for an order. Each module includes, at a minimum, two files:

A class file: /includes/modules/order_total/my_order_total.php
A language file: /includes/languages/current_language/modules/order_total/lang.my_order_total.php (or simply my_order_total.php in 1.5.7 and below)

The language file contains all the translatable language text for the module while the class file contains the module’s processing portion.

Order Total Class

The class defined in /includes/classes/order_total.php handles the loading of the order-total modules during Zen Cart storefront order-processing.

Anatomy of an Order-Total Module

Each module can provide either basic or credit-class computations. Credit-class modules, like the Coupon (ot_coupon) or Gift Certificate (ot_gv) built into the Zen Cart base, can also operate on customer input during the checkout process.

Class Names

An order-total module’s filename (e.g. my_order_total.php) is also used as its class name:

class my_order_total extends base
{
  ...
}

Note: Unlike shipping modules, underscore characters (_) are allowed in order-total module names!

Class Variables

An order-total module’s class definition includes the following publicly-available variables, depending on the “mode” in which the order-total processes:

Variable Name	Variable Type	Basic	Credit Class	Description
code	string	✓	✓	Contains the unique “code” identifying this order-total; normally set to the module’s class name.
title	string	✓	✓	Identifies the title displayed for the module during the admin’s Modules > Order Total processing. This variable is normally initialized during class construction to a language-file definition.
description	string	✓	✓	Identifies the description displayed for the module during the admin’s Modules > Order Total processing. This variable is normally initialized during class construction to a language-file definition.
sort_order	integer	✓	✓	Identifies the relative order in which this module is processed; the value configured must be unique within a store’s Modules > Order Total settings. This value is used by the main `order_total` class (`/includes/classes/order_total.php`), which loads all active modules in ascending `sort_order` sequence.
output	array	✓	✓	Contains the order-total’s “output”, a PHP associative array containing the information to be displayed in an “orders-totals” section, e.g. on the `checkout_confirmation page`. See below for details.
credit_class	boolean	—	✓	Identifies, if present and set to boolean true, that the module is a credit-class object. When a module indicates that it performs `credit_class` processing, that order-total module provides additional class methods.

The order-total’s output array contains the following fields:

Array “Key”	Type	Array “Value”
title	string	The descriptive text to accompany the module’s addition to (or subtraction from) the order.
value	float	The numeric value that the module applies to the order. Positive values add; negative values subtract.
text	string	The character-display value associated with the module’s numeric `value`. This value is normally created via call to the Zen Cart `$currencies` class and represents the currency-formatted `value`.

Class Methods

The methods provided by an order-total module depend on whether the module provides credit-class processing.

Basic Order-Total Class Methods

These methods are provided by all order_total modules.

__construct

A module’s class-constructor method performs initialization of its class variables and determines whether the module is enabled for the current order. Upon completion, the class variable enabled identifies whether (true) or not (false) the module is to be enabled for storefront processing.

class my_order_total extends base
{
    public function __construct ()
    {
    }

    ...
}

process

This method, normally called during the confirmation and processing phases of the checkout process, performs the module’s special calculations. If the module’s conditions are satisfied, the module adds (or subtracts) its cost from the order’s current total and, optionally, makes any tax-related adjustments to the order’s tax.

Basic process function processing is illustrated below.

class my_order_total extends base
{
    ...
    public function process ()
    {
        global $order, $currencies;

        ...

        if ($this_totals_conditions_are_satisified) {
            $order->info['total'] += $my_cost;
            $this->output[] = array (
                'title' => $this->title,
                'value' => $my_cost,
                'text' => $currencies->format ($my_cost, true,  $order->info['currency'], $order->info['currency_value']),
            );
        }
    }

    ...
}

check

This method, called from admin-level Modules > Order Total processing, returns a boolean value indicating whether (true) or not (false) the module is currently installed.

class my_order_total extends base
{
    ...

    public function check ()
    {
        global $db;
        if (!isset ($this->_check)) {
            $check_query = $db->Execute ("SELECT configuration_value FROM " . TABLE_CONFIGURATION . " WHERE configuration_key = 'MODULE_ORDER_TOTAL_MY_ORDER_TOTAL_STATUS' LIMIT 1");
            $this->_check = !$check_query->EOF;
        }
        return $this->_check;
    }

    ...
}

install

This method, called from admin-level Modules > Order Total processing when the module is initially installed, sets the module’s configuration into the Zen Cart database. The example shows how to insert the common, required, configuration elements into the database for the my_order_total order-total module. If your order-total module requires additional settings, add them here.

class my_order_total extends base
{
    ...

    public function install () 
    {
        global $db;

        $db->Execute ("INSERT INTO " . TABLE_CONFIGURATION . " (configuration_title, configuration_key, configuration_value, configuration_description, configuration_group_id, sort_order, set_function, date_added) VALUES ('Enable My Order Total', 'MODULE_ORDER_TOTAL_MY_ORDER_TOTAL_STATUS', 'True', 'Do you want to enable "my order total" processing?', '6', '0', 'zen_cfg_select_option(array(\'True\', \'False\'), ', now())");
        $db->Execute ("INSERT INTO " . TABLE_CONFIGURATION . " (configuration_title, configuration_key, configuration_value, configuration_description, configuration_group_id, sort_order, date_added) VALUES ('Sort Order', 'MODULE_ORDER_TOTAL_MY_ORDER_TOTAL_SORT_ORDER', '400', 'Sort order of display.', '6', '0', now())");

        ...

    }

    ...

}

keys

This method, called during admin-level Modules > Order Total processing, returns the database configuration “keys” associated with this order-total module. The configuration values are displayed for the module in the order specified by the returned array.

class my_order_total extends base
{
    ...

    public function keys () 
    {
        return array (
            'MODULE_ORDER_TOTAL_MY_ORDER_TOTAL_STATUS', 
            'MODULE_ORDER_TOTAL_MY_ORDER_TOTAL_SORT_ORDER'
        );
    }

    ...

}

remove

This method, called during admin-level Modules > Order Total processing to remove this module, removes all database changes (normally just configuration keys) associated with the order-total module.

class my_order_total extends base
{
    ...

    public function remove () 
    {
        global $db;
      	$db->Execute ("DELETE FROM " . TABLE_CONFIGURATION . " WHERE configuration_key LIKE 'MODULE\_ORDER_TOTAL\_MY_ORDER_TOTAL\_%'");
    }

    ...

}

Credit-Class Order-Total Methods

These methods are provided by an order-total module that identifies itself as a Credit Class module by setting its $this->credit_class variable to true. The Coupon (ot_coupon) and Gift Voucher (ot_gv) modules that are built into Zen Cart are examples of this type of order-total module.

Note: While many of the credit-class order-total modules include a method named pre_confirmation_check, that method is never called during the checkout process and can be safely removed (if not used internally).

credit_selection

This method, normally called during the payment stage of the checkout process, returns an associative array containing information describing any form-related elements associated with the module’s processing. If the module has no value to return for the current order, an empty array should be returned.

The module is given the opportunity to process these fields via future call to its collect_posts method.

The selection array returned uses the following structure:

Field Name	Type	Description
id	string	Normally set to the current module’s “code”, e.g. `ot_my_order_total`.
module	string	Normally set to the current order-total’s descriptive name. This value is displayed to the customer.
redeem_instructions	string	Normally set to a language-constant, describes to the customer what the module does and how its processed.
checkbox	string	Normally set to a text string containing HTML tags required for some special processing by the module.
fields	array	A basic array containing one array-element for each customer-configurable input field used in this module’s processing.

Each fields array element is also an associative array, using the following structure:

Field Name	Type	Description
title	string	The text to display for any HTML `label` associated with the current field.
field	string	The HTML input tag used to gather this field’s input.
tag	string	Identifies, if non-blank, the value to be used for the `for` attribute of the generated `label` tag.

class my_order_total extends base
{
    ...

    public function credit_selection () 
    {
        $input_field_id = 'disc-' . $this->code;
        $selection = array (
            'id' => $this->code,
            'module' => $this->title,
            'redeem_instructions' => MODULE_ORDER_TOTAL_MY_ORDER_TOTAL_REDEEM_INSTRUCTIONS,
            'fields' => array (
                'title' => MODULE_ORDER_TOTAL_MY_ORDER_TOTAL_ENTER_CODE,
                'field' => zen_draw_input_field ('my_redeem_code', '', 'id="' . $input_field_id . '"'),
                'tag' => $input_field_id
            ),
        );
        return $selection;
    }

    ...

}

collect_posts

This method is called during the payment and confirmation stages of the checkout process, allowing a module to gather, inspect and process the $_POST variables that it identified by its credit_selection method’s return. The method returns no value.

If the order-total module’s processing discovers an issue with the posted information, it is the module’s responsibility to display a message to the customer to describe the problem and redirect back to the checkout_payment page to allow the form-input to be re-displayed and updated by the customer.

class my_order_total extends base
{
    ...

    public function collect_posts () 
    {
       ...
    }

    ...

}

update_credit_account

This method is called during the processing stage of the checkout process by the order class’ create_add_products function for each product iteration, enabling an order-total module to have “visibility” into the specific products that are in the order.

The method’s purpose is to allow a module to decide whether the current product in the order should add something to a credit account. For example, for the Gift Voucher processing, a check is made to see if the product is a Gift Voucher and then adds the GV amount to the customer’s GV account. Another use would be to check to see if the product would give reward-points and add those points to the customer’s points/reward account

The method’s input is the integer index into the current order’s products array and the method returns no direct output.

class my_order_total extends base
{
    ...

    public function update_credit_account ($i) 
    {
        global $order;
        if ($order->products[$i]['name'] == 'Some Special Text') {
           ...
        }
    }

    ...

}

apply_credit

This method is called during the processing stage of the checkout process by the order class’ create_add_products method just prior to that method’s completion. The method takes no direct input and returns no direct value.

The method’s purpose is to enable a module to test whether the customer has chosen to apply a credit amount to their order, reducing the order’s final total. If so, the order-total module’s processing performs some action, e.g. for a Gift Voucher, the customer’s GV account is reduced by the amount applied to the order.

class my_order_total extends base
{
    ...

    public function apply_credit () 
    {
       ...
    }

    ...

}

clear_posts

This method is called during the processing stage of the checkout process and gives a module the opportunity to remove any session-related information for the just-completed order. The method neither takes nor returns any direct values.

class my_order_total extends base
{
    ...

    public function clear_posts () 
    {
       unset ($_SESSION['my_redeem_code']);
    }

    ...

}

Standard Configuration Settings

These common settings should be provided by all order-total modules:

Configuration Name	Configuration Value
`MODULE_ORDER_TOTAL_MY_ORDER_TOTAL_STATUS`	Set to either ’true’ or ‘false’, identifies whether or not the module is currently enabled.
`MODULE_ORDER_TOTAL_MY_ORDER_TOTAL_SORT_ORDER`	Identifies the sort-order to be used when displaying this module.

Tips & Tricks

Procedurally, all configuration options for an order-total module named my_order_total should be named MODULE_ORDER_TOTAL_MY_ORDER_TOTAL_*, as should all language constants for the module, to ensure uniqueness of those constants.

Troubleshooting

Since the admin-level processing by Modules > Order Total loads all .php modules present in the /includes/modules/order_total folder, make sure that any backup files in that directory have the .php extension are renamed (use .php.bak or .php~), or errors will result during the admin loading.

Dev: Cloning a Shipping Module

Mon, 01 Jan 0001 00:00:00 +0000

Note: These instructions are for Zen Cart 1.5.8 and higher. For Zen Cart 1.5.7 and lower, please see Cloning a Shipping Module in 1.5.7 and below.

You can create new Shipping Module by making a clone of the closest matching Shipping Module to what you are trying to do.

As an example, we will consider the flat shipping module.

Shipping Modules have 2 parts:

The code file is located in:
/includes/modules/shipping/flat.php

The language file is located in:
/includes/languages/english/modules/shipping/lang.flat.php

To clone this module, for example, to flatfree.php you would:

copy flat.php to flatfree.php
copy lang.flat.php to lang.flatfree.php

Note: Be sure the filename you choose does not have an underscore (_) in it.

Next, you need to change all occurrences of the strings flat and FLAT as follows:

OLD	NEW
`flat`	`flatfree`
`FLAT`	`FLATFREE`

These identifiers are case sensitive.

These words are written separately or within the constants such as:

class flat {
... 
$this->code = 'flat';
... 
$this->title = MODULE_SHIPPING_FLAT_TEXT_TITLE;

becomes

class flatfree {
...
$this->code = 'flatfree';
...
$this->title = MODULE_SHIPPING_FLATFREE_TEXT_TITLE;

Be sure to make this change in the remove() function as well.

Once you have cloned the module then you can alter how it calculates shipping to the method that you need. This calculation is done in the quote() method.

Flat does not have complicated logic to compute a quote; it uses a single figure.

To see examples of quote calculations that are more complex, you might look at the items.php Shipping Module.

Cloning or creating a Shipping Module to function the way you need it is not too difficult if you just work through the steps on paper then recreate the same steps within the quote() function.

These forum threads might also give you ideas:

Dev: Cloning a Shipping Module (1.5.7 and below)

Mon, 01 Jan 0001 00:00:00 +0000

Note: These instructions are for Zen Cart 1.5.7 and below. For Zen Cart 1.5.8 and higher, please see Cloning a Shipping Module.

You can create new Shipping Module by making a clone of the closest matching Shipping Module to what you are trying to do.

As an example, we will consider the flat shipping module.

Shipping Modules have 2 parts:

The code file is located in:
/includes/modules/shipping/flat.php

The language file is located in:
/includes/languages/english/modules/shipping/flat.php

To clone this module, for example, to flatfree.php you would copy the two flat.php files to flatfree.php

Note: Be sure the filename you choose does not have an underscore (_) in it.

Next, you need to change all occurrences of the strings flat and FLAT as follows:

OLD	NEW
`flat`	`flatfree`
`FLAT`	`FLATFREE`

These identifiers are case sensitive.

These words are written separately or within the constants such as:

class flat {
... 
$this->code = 'flat';
... 
$this->title = MODULE_SHIPPING_FLAT_TEXT_TITLE;

becomes

class flatfree {
...
$this->code = 'flatfree';
...
$this->title = MODULE_SHIPPING_FLATFREE_TEXT_TITLE;

Once you have cloned the module then you can alter how it calculates shipping to the method that you need. This calculation is done in the quote() method.

Flat does not have complicated logic to compute a quote; it uses a single figure.

To see examples of quote calculations that are more complex, you might look at the items.php Shipping Module.

Cloning or creating a Shipping Module to function the way you need it is not too difficult if you just work through the steps on paper then recreate the same steps within the quote() function.

These forum threads might also give you ideas:

Dev: Adding Configuration Values to a Module

Mon, 01 Jan 0001 00:00:00 +0000

Over time, you may find that the initial set of configuration values for a module is not adequate. For example, you want to add a new feature, which requires its own configuration, or a vendor (a shipper or a bank) may require additional data to authenticate the account.

Warning on Missing Configuration Values

The old way of handling this situation was to ask the user to REMOVE the module, and then run the INSTALL again.

In the USPS plugin, for example,

            if (MODULE_SHIPPING_USPS_VERSION != self::USPS_CURRENT_VERSION || count($this->keys()) != $chk_sql->RecordCount()) {
                $this->title .= '<span class="alert">' . ' - Missing Keys or Out of date you should reinstall!' . '</span>';
                $this->enabled = false;
            }

Remove and re-install was annoying for users, and error prone in cases where modules had large and complicated configuration.

Dynamically Handling Missing Configuration Values

To detect and recover from this condition, the newer way is to simply add the configuration settings in the check() method. (Note that some older modules use the keys() method for this purpose; either method is acceptable.)

Care must be taken to ensure that the module is already installed (check the _STATUS setting) so that the config won’t be added twice when an the install method is run.

From paypalwpp.php line 704 in Zen Cart 1.5.7d,

    if (defined('MODULE_PAYMENT_PAYPALWPP_STATUS')) {
      global $db;
      if (!defined('MODULE_PAYMENT_PAYPALWPP_ECS_BUTTON')) {
        $db->Execute("INSERT INTO " . TABLE_CONFIGURATION . " (configuration_title, configuration_key, configuration_value, configuration_description, configuration_group_id, sort_order, set_function, date_added) VALUES ('Express Checkout Shortcut Button', 'MODULE_PAYMENT_PAYPALWPP_ECS_BUTTON', 'On', 'The Express Checkout Shortcut button shows up on your shopping cart page to invite your customers to pay using PayPal without having to give all their address details on your site first before selecting shipping options.<br />It has been shown to increase sales and conversions when enabled.<br />Default: On ', '6', '25', 'zen_cfg_select_option(array(\'On\', \'Off\'), ', now())");
      }
...

Dev: Cloning a Payment Module

Mon, 01 Jan 0001 00:00:00 +0000

Note: These instructions are for Zen Cart 1.5.8 and above. For Zen Cart 1.5.7 and below, please see Cloning a Payment Module in 1.5.7 and below.

You can create new Payment Module by making a clone of the closest matching Payment Module to what you are trying to do.

As an example, we will consider the moneyorder payment module.

Payment Modules have 2 parts:

The code file is located in:
/includes/modules/payment/moneyorder.php

The language file is located in:
/includes/languages/english/modules/payment/lang.moneyorder.php

To clone this module, for example, to venmo.php you would:

copy moneyorder.php to venmo.php
copy lang.moneyorder.php to lang.venmo.php

Note: Be sure the filename you choose does not have an underscore (_) in it.

Next, you need to change all occurrences of the strings moneyorder and MONEYORDER as follows:

OLD	NEW
`moneyorder`	`venmo`
`MONEYORDER`	`VENMO`

These identifiers are case sensitive.

These words are written separately or within the constants such as:

class moneyorder {
... 
$this->code = 'moneyorder';
... 
$this->title = MODULE_PAYMENT_MONEYORDER_TEXT_TITLE;

becomes

class venmo {
...
$this->code = 'venmo';
...
$this->title = MODULE_PAYMENT_VENMO_TEXT_TITLE;

Be sure to make this change in the remove() function as well.

These plugins might also help:

Optional Payment Method

Dev: Cloning a Payment Module (1.5.7 and below)

Mon, 01 Jan 0001 00:00:00 +0000

Note: These instructions are for Zen Cart 1.5.7 and below. For Zen Cart 1.5.8 and higher, please see Cloning a Payment Module.

You can create new Payment Module by making a clone of the closest matching Payment Module to what you are trying to do.

As an example, we will consider the moneyorder payment module.

Payment Modules have 2 parts:

The code file is located in:
/includes/modules/payment/moneyorder.php

The language file is located in:
/includes/languages/english/modules/payment/moneyorder.php

To clone this module, for example, to venmo.php you would copy the two moneyorder.php files to venmo.php

Note: Be sure the filename you choose does not have an underscore (_) in it.

Next, you need to change all occurrences of the strings moneyorder and MONEYORDER as follows:

OLD	NEW
`moneyorder`	`venmo`
`MONEYORDER`	`VENMO`

These identifiers are case sensitive.

These words are written separately or within the constants such as:

class moneyorder {
... 
$this->code = 'moneyorder';
... 
$this->title = MODULE_PAYMENT_MONEYORDER_TEXT_TITLE;

becomes

class venmo {
...
$this->code = 'venmo';
...
$this->title = MODULE_PAYMENT_VENMO_TEXT_TITLE;

These plugins might also help:

Optional Payment Method