-
Notifications
You must be signed in to change notification settings - Fork 61
Custom Payment or Shipping module
Programmers have the ability to create custom payment and shipping modules in Web Store. We recommend starting with a copy of a shipping or payment module that most closely resembles what you'd like to do.
The properly way to modify the search functionality is to create a new class file for your payment or shipping method. In practice, this means creating a new file in your /custom_includes folder under the /payments or /shipping sub-folder. Web Store will read both /custom_includes/payments and /xlsws_includes/payments looking for modules, so it's not necessary (nor recommended) to put your own modules in xlsws_includes as this can cause upgrade problems.
The advantage to extending the function this way instead of simply modifying the original file is future Web Store updates will not overwrite your custom function since the /custom_includes folder will never be touched during an upgrade.
Begin by copying an existing module and placing it in the corresponding folder in custom_includes. For this exercise, we will copy the file /xlsws_includes/shipping/flat_rate.php and copying it to /xlsws_includes/shipping/flat_rate.php since we will use this as a basis for our custom module.
The first thing we will need to do is change the class name and the filename. Note that in all cases, the class name and filename match, so the flat_rate filename will also be in the file as:
<?php
...
class flat_rate extends xlsws_class_shipping {
...
?>
Rename flat_rate to a new name, such as custom_flat_rate and rename the file to custom_flat_rate.php.
There are places within the module that load settings by using the class name. Earlier Web Store code had these hardcoded, with lines such as:
$config = $this->getConfigValues('flat_rate');
These should have now been replaced with:
$config = $this->getConfigValues(get_class($this));
But if you still have older code, you will need to change this to avoid loading the wrong configuration settings.
Note that these functions must all be public
Every shipping module contains a total() function which is the primary function called by Web Store to determine a price. In some modules, total() calls other modules for further processing (such as to contact an external website) but total() is ultimately responsible for passing back the calculated price to Web Store. You can modify this function for your own calculation.
total() is passed values including the full $cart structure and address information which can be used as criteria for evaluating the price.
total() should return an array containing the calculated value, along with the LightSpeed Product Code that will be used when downloading the order (this is just a Config field value previously set up in Admin Panel). The return value should look like:
return array('price' => $price, 'product' => $config['product']);
returning "false" shows the "Can't calculate shipping price" error to the customer during checkout, indicating the module is an invalid option.
The check() module returns a true or false on whether the module should be displayed at all. The primary check performed is if configuration values exist at all, indicating that the store owner has properly configured the module through Admin Panel.
Additionally, check() can be used at runtime to control if the module even shows up at all as an option for the customer. (Note that at this time, the cart and shipping address info is not available to this function.)
The config_fields() function is called by Admin Panel when configuring the module. Each field set shows as an option when configuring. Options can be text entry blanks, on/off switches or dropdowns. At runtime, such as in the total() function, you can evaluate how the store owner has configured the module (such as an account number) to determine the result.
Called when module is first turned On with the On/Off slider in Admin Panel. Can be used for preliminary configuration
Called when a module is turned Off with the On/Off slider in Admin Panel. Can be used for cleanup tasks. NOTE in Version 2.1 and below, when you turn a module Off, all configuration information is removed from Web Store. This means if you have entered an account number in Admin Panel, this will be lost if the module is turned off.