Version 4.5.0. Copyright © 2015-2019, Vinos de Frutas Tropicales.
Current Support Thread on the Zen Cart forums: https://www.zen-cart.com/showthread.php?200407
Released under the General Public License (see the file named LICENSE
in the plugin's distribution for full details). This script is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.
Usage Notes:
order-total
modules are incompatibile with EO, especially if they require storefront conditions to perform their processing.Edit Orders (EO) is a Zen Cart admin module that allows administrative users to edit a customer's order to:
This section identifies the processes you'll use to initially install Edit Orders, upgrade or uninstall EO entirely.
Notes:
zen_add_tax
(present in /YOUR_ADMIN/includes/functions/general.php) not pre-round its return value. Refer to this tab for more information./admin/currency_cron.php
script; see this Zen Cart issue for details.If your store uses a version of Zen Cart prior to 1.5.6, there are core-file overwrites required by this plugin; you should always backup your cart's database and files prior to making any changes. Unzip the plugin's package file and then:
zc155
of EO's distribution, providing the in-core zc156 notifications required:YOUR_ADMIN
sub-directory to match your store's admin-directory name).First, delete the files that were copied to your Zen Cart's file-system, then copy the contents of the plugin's /docs/edit_orders/uninstall/uninstall_eo.sql
to your clipboard and paste into your admin's Tools->Install SQL Patches to complete the uninstall process.
The installation for Edit Orders changed drastically for v4.2.0 and later. Following is a "secret decoder ring" to let you where files from those earlier releases have been moved (or removed) in the v4.2.0 or later distributions of EO:
EO v4.1.7 or earlier | EO v4.2.0 or later |
---|---|
/1_modified_core_files/includes/classes/order.php | /includes/classes/order.php |
/1_modified_core_files/includes/classes/order_total.php | — |
/1_modified_core_files/includes/classes/shipping.php | — |
/1_modified_core_files/your_admin_folder/orders.php | /YOUR_ADMIN/orders.php |
/1_modified_core_files/your_admin_folder/images/icon_edit.gif | — |
/1_modified_core_files/your_admin_folder/includes/languages/english/orders.php | — |
/2_new_files/your_admin_folder/edit_orders.php | /YOUR_ADMIN/edit_orders.php |
/2_new_files/your_admin_folder/images/icon_billing.png | /YOUR_ADMIN/images/icon_billing.png |
/2_new_files/your_admin_folder/images/icon_comment_add.png | /YOUR_ADMIN/images/icon_comment_add.png |
/2_new_files/your_admin_folder/images/icons/icon_customers.png | /YOUR_ADMIN/images/icon_customers.png |
/2_new_files/your_admin_folder/images/icon_details.gif | /YOUR_ADMIN/images/icon_details.gif |
/2_new_files/your_admin_folder/images/icon_invoice.gif | — |
/2_new_files/your_admin_folder/images/icon_shipping.png | /YOUR_ADMIN/images/icon_shipping.png |
/2_new_files/your_admin_folder/images/icon_track_add.png | /YOUR_ADMIN/images/icon_track_add.png |
/2_new_files/your_admin_folder/includes/edit_orders.css | /YOUR_ADMIN/includes/edit_orders.css |
/2_new_files/your_admin_folder/includes/auto_loaders/config.eo.php | /YOUR_ADMIN/includes/auto_loaders/config.eo.php |
/2_new_files/your_admin_folder/includes/auto_loaders/config.zc154_compatibility.php | — |
/2_new_files/your_admin_folder/includes/classes/attributes.php | /YOUR_ADMIN/includes/classes/attributes.php |
/2_new_files/your_admin_folder/includes/classes/editOrders.php | /YOUR_ADMIN/includes/classes/editOrders.php |
/2_new_files/your_admin_folder/includes/classes/EditOrdersQueryCache.php | /YOUR_ADMIN/includes/classes/EditOrdersQueryCache.php |
/2_new_files/your_admin_folder/includes/classes/eo_plugin.php | — |
/2_new_files/your_admin_folder/includes/classes/mock_cart.php | /YOUR_ADMIN/includes/classes/mock_cart.php |
/2_new_files/your_admin_folder/includes/classes/plugin.php | — |
/2_new_files/your_admin_folder/includes/extra_configures/edit_orders.php | /YOUR_ADMIN/includes/extra_configures/edit_orders.php (Placeholder, can be removed) |
/2_new_files/your_admin_folder/includes/extra_datafiles/edit_orders_defines.php (Placeholder, can be removed) | /YOUR_ADMIN/includes/extra_datafiles/edit_orders_defines.php |
/2_new_files/your_admin_folder/includes/extra_datafiles/eo_sanitization.php | /YOUR_ADMIN/includes/extra_datafiles/eo_sanitization.php |
/2_new_files/your_admin_folder/includes/functions/extra_functions/common_orders_functions.php (Placeholder, can be removed) | /YOUR_ADMIN/includes/functions/extra_functions/common_orders_functions.php (Placeholder, can be removed) |
/2_new_files/your_admin_folder/includes/functions/extra_functions/edit_orders_functions.php | /YOUR_ADMIN/includes/functions/extra_functions/edit_orders_functions.php |
/2_new_files/your_admin_folder/includes/init_includes/init_eo_config.php | /YOUR_ADMIN/includes/init_includes/init_eo_config.php |
/2_new_files/your_admin_folder/includes/init_includes/init_zc154_compatibility.php | — |
/2_new_files/your_admin_folder/includes/languages/english/edit_orders.php | /YOUR_ADMIN/includes/languages/english/edit_orders.php |
/2_new_files/your_admin_folder/includes/languages/english/extra_definitions/edit_orders.php | /YOUR_ADMIN/includes/languages/english/extra_definitions/edit_orders.php |
/2_new_files/your_admin_folder/includes/languages/english/images/buttons/button_add_product.gif | /YOUR_ADMIN/includes/languages/english/images/buttons/button_add_product.gif |
/2_new_files/your_admin_folder/includes/languages/english/modules/plugin/eo.php | — |
/2_new_files/your_admin_folder/includes/languages/english/modules/plugin/plugin.php | — |
/3_install/your_admin_folder/includes/auto_loaders/config.eo_onetime.php | — |
/3_install/your_admin_folder/includes/init_includes/init_eo_install.php | — |
/4_optional_items/1_onetime_discount/1_new_files/includes/languages/english/modules/order_total/ot_onetime_discount.php | /includes/languages/english/modules/order_total/ot_onetime_discount.php |
/4_optional_items/1_onetime_discount/1_new_files/includes/modules/order_total/ot_onetime_discount.php | /includes/modules/order_total/ot_onetime_discount.php |
/4_optional_items/1_onetime_discount/1_new_files/includes/languages/english/modules/order_total/ot_misc_cost.php | /includes/languages/english/modules/order_total/ot_misc_cost.php |
/4_optional_items/1_onetime_discount/1_new_files/includes/modules/order_total/ot_misc_cost.php | /includes/modules/order_total/ot_misc_cost.php |
Part of the simplification of the EO installation process is to lessen the core-file changes required. Zen Cart 1.5.5a has been updated to include additional notifiers within the admin's Customers->Orders processing and Zen Cart 1.5.6 (and later) expands on that update. EO now makes use of those notifications to add its buttons and icons to that tool.
The possibility does exist, however, that these required notifiers didn't get included when a store's Zen Cart installation was upgraded from a prior version. The following table lists the notifiers that allow EO to perform its processing.
Module Name | Notifier "Key" | Comments |
---|---|---|
/YOUR_ADMIN/orders.php | NOTIFY_ADMIN_ORDERS_MENU_BUTTONS | Built-in, issued during the orders-listing display, after creating the upper button-group for the selected order in the sidebar. |
/YOUR_ADMIN/orders.php | NOTIFY_ADMIN_ORDERS_MENU_BUTTONS_END | Built-in, issued during the orders-listing display, after creating the lower button-group for the selected order in the sidebar. |
/YOUR_ADMIN/orders.php | NOTIFY_ADMIN_ORDERS_SHOW_ORDER_DIFFERENCE | Added, issued during the orders-listing display, enabling additional icons to be associated with each order's line-item when creating the bottom button-group. This notifier is based on the like-named one in the Zen Cart 1.5.6+ repository. |
/YOUR_ADMIN/orders.php | NOTIFY_ADMIN_ORDERS_EDIT_BUTTONS | Added, issued during an order's detailed view when creating the bottom button-group. This notifier is based on the like-named one in the Zen Cart 1.5.6+ repository. |
/includes/modules/order_total/ot_shipping.php | NOTIFY_OT_SHIPPING_TAX_CALCS | Issued during an order's "order-totals" processing, allowing the order's shipping tax-rate and tax-description to be overridden. See this Zen Cart commit for zc156 for details. If your store runs on a zc155 variant, you can safely copy the entire zc156 module for use while you plan your store's zc156 upgrade! |
The base Zen Cart admin version of the zen_add_tax
function, present in /YOUR_ADMIN/includes/functions/general.php
, currently pre-rounds its returned result … unlike the storefront version. Starting with EO v4.4.0, this condition must be corrected before you can use Edit Orders; you'll see the following message displayed in your admin's header if the condition exists.
To correct the issue, you'll need to edit that function, changing:
/** * Add tax to a products price */ function zen_add_tax($price, $tax) { global $currencies; if (DISPLAY_PRICE_WITH_TAX_ADMIN == 'true') { return zen_round($price, $currencies->currencies[DEFAULT_CURRENCY]['decimal_places']) + zen_calculate_tax($price, $tax); } else { return zen_round($price, $currencies->currencies[DEFAULT_CURRENCY]['decimal_places']); } }
… to …
/** * Add tax to a products price */ function zen_add_tax($price, $tax) { global $currencies; if (DISPLAY_PRICE_WITH_TAX_ADMIN == 'true') { //-bof-edit_orders-lat9: Don't pre-round values, aligning with storefront // return zen_round($price, $currencies->currencies[DEFAULT_CURRENCY]['decimal_places']) + zen_calculate_tax($price, $tax); return $price + zen_calculate_tax($price, $tax); } else { // return zen_round($price, $currencies->currencies[DEFAULT_CURRENCY]['decimal_places']); return $price; } //-eof-edit_orders-lat9 }
Edit Orders is easy to use; the interface looks similar to the Customers->Orders processing that is built into Zen Cart. Once the plugin is installed, navigate to Customers->Orders and click the "edit" button to view the editable details of the order.
Starting with v4.3.0 of EO, a checkbox input ("Reset totals prior to update?") appears next to the upper update button. Its default value is controlled by Configuration->Edit Orders->Reset Totals on Update — Default. If an order includes order-total modules (like Group Pricing) that affect both the order's total and tax values, you might need to tick that box to have EO correctly calculate any updated order.
Note: We do not recommend clicking "edit" on completed orders. When you edit an order, all order-totals are recalculated including tax, sub-total and total. Editing a completed order may result in undesired changes!
Once you've opened an order for editing, you can edit the customer, billing and/or shipping addresses as needed:
To add a product to the order, start by clicking the "Add Products" button near the center of the page and
Once you've made your selections, click the "Add now" button.
You can update (edit) each product's quantity, name, model, price, one-time charges, tax-rate and product options. When you're finished, click the "update" button to save your changes.
Price calculations for order-totals are processed by the order-total modules directly and not Edit Orders. This helps prevent math errors and ensure consistency. Not all 3rd party order-total modules were written with the capability to be loaded and run against an order from the Zen Cart admin interface.
Many of the common order-total modules are automatically calculated for the order based upon store settings and information present in the order. Automatically calculated order-totals such as ot_tax, ot_loworderfee, ot_subtotal and ot_total cannot be edited or removed from an order.
To add an order-total to the active order's calculations:
shipping
, you need to also choose a specific shipping-module name.To remove an order-total from the active order's calculations:
To update an order-total for the active order's calculations:
Note: Prices are displayed with or without tax based upon the storefront settings not the admin settings, in an attempt to emulate the environment in which the order-totals are calculated. Most of the order-total modules are designed to run from the storefront only. Refer to the Zen Cart configuration setting DISPLAY_PRICE_WITH_TAX
.
To change an order's status and/or add a comment to the order, follow the procedure you use within the built-in Customers->Orders processing and click the "update" button to apply the changes to the order.
The following is a list of some commonly installed 3rd party Zen Cart modules (plugins) known to be compatible with Edit Orders. The list is mainly confined to 3rd party plugins which also affect customer orders or placing customer orders. Please refer to the appropriate module for further notes and instructions (if any).
Order-total modules are used to change the total cost of an order. Edit Orders uses the same order-total modules as the storefront checkout process. Most of the order-total modules which ship with Zen Cart have been validated and work as expected (ot_coupon, ot_gv, ot_loworderfee, ot_shipping, ot_subtotal, ot_tax and ot_total). Both ot_subtotal
and ot_total
must be enabled for Edit Orders to function correctly.
If your store includes products with attributes and your want EO to display your products' attributes in the same order as the storefront operation, you'll need to make a change to /includes/modules/attributes.php
. See this Zen Cart posting for additional information.
if (PRODUCTS_OPTIONS_SORT_ORDER=='0') { $options_order_by= ' order by LPAD(popt.products_options_sort_order,11,"0")'; } else { $options_order_by= ' order by popt.products_options_name'; }
if (PRODUCTS_OPTIONS_SORT_ORDER=='0') {
$options_order_by= ' order by LPAD(popt.products_options_sort_order,11,"0"), popt.products_options_name';
} else {
$options_order_by= ' order by popt.products_options_name';
}
Edit Orders has been validated with Local Sales Tax v2.3.5 or newer installed; previous versions are not supported. To integrate the two plugins, you'll need to copy the file /includes/functions/extra_functions/functions_local_sales_taxes.php
to /YOUR_ADMIN/includes/functions/extra_functions/functions_local_sales_taxes.php
for that order-total module to "find" the functions it needs!
Note: The tax rate shown next to individual products reflects only the Zen Cart configured tax rate. It does not include any tax rates defined by Local Sales Tax. The sales tax rate cannot be adjusted by Edit Orders for the Local Sales Taxes module.
Because Edit Orders loads the same order-total modules as the storefront checkout process, all enabled modules must be able to be loaded and processed from the store's Zen Cart admin-console. Because Zen Cart traditionally does not use those modules during admin-level processing, many 3rd-party order-total modules were designed without the authors taking this into consideration.
The most common symptom caused by a problematic order-total module (when editing an order) is the presentation of a "blank" page when adding a product to (or updating) the order. In most cases taking a look at the generated debug log provides valuable insight as to how to correct the underlying issue. Another option is to disable all add-on order-total modules and then enable them one-by-one to determine which order-total module is causing the blank page.
Here are some common causes of issues with 3rd-party order-total modules and possible corrective actions:
/YOUR_ADMIN/includes/functions/extra_functions
directory.$_SESSION['cart']
instead of those present in the $order
object to determine the associated value to display.$order
object.You can view the details of these changes on the plugin's GitHub repository.
zen_draw_input_field
.sort_order
, if the field exists in the database.ot_shipping
- BUGFIX: Document change required if a store uses a cron-job for the currency-cron.
- The following files were changed:
- /YOUR_ADMIN/edit_orders.php
- /YOUR_ADMIN/includes/classes/editOrders.php
- /YOUR_ADMIN/includes/classes/mock_cart.php
- /YOUR_ADMIN/includes/classes/observers/EditOrdersAdminObserver.php
- /YOUR_ADMIN/includes/functions/extra_functions/edit_orders_functions.php
- /YOUR_ADMIN/includes/init_includes/init_eo_config.php
ot_onetime_discount
causes PHP warning on initial display in admin's Modules->Order Total.shipping_tax_rate
to the orders
table.NOTIFY_ADMIN_ORDERS_LISTING_ROW
to NOTIFY_ADMIN_ORDERS_SHOW_ORDER_DIFFERENCE
.edit_orders
use; corrects unwanted interaction with Admin New Order.get_products
function.\YOUR_ADMIN\orders.php
.ot_loworderfee
module.