How to install one of my Zen Cart mods
This page is a rookie's guide to installing one of my mods. Many (although not all) other people package their mods the way I do, so this may also be useful if you're installing someone else's mods.Note: These instructions only deal with the mechanics of copying files to your cart. There may be many more instructions you need to follow for any particular mod. Please see the mod's help pages for details.
Background
If you installed your Zen Cart using Fantastico or perhaps had a friend or subcontractor install it for you, installing a mod might seem daunting. Don't worry - there's nothing to it as long as you follow some basic principles.Reading the instructions
This page shows you how to copy files into your cart. This is just one part of installation; there may be many associated tasks that need to be done. All my contributions come with a README file; please take the time to review it to get the whole picture of how installation is to be done.Reading the instructions before starting installation is a great way to reduce grief. In addition to the README file, many of my contributions have their own web page where I answer frequently asked questions.
Getting Started
Before you start, you'll need to verify that you have some things.- My mods are provided in zip format, so you'll need a tool to unzip the file.
- You'll need a tool to transfer the files from your local PC to your webserver.
- You'll need a simple text editor to do customizations to files
Zip File Structure
Here's the complete structure of the Quantity Discounts contribution as of version 1.09:./includes ./includes/languages ./includes/languages/english ./includes/languages/english/modules ./includes/languages/english/modules/order_total ./includes/languages/english/modules/order_total/ot_quantity_discount.php ./includes/modules ./includes/modules/order_total ./includes/modules/order_total/ot_quantity_discount.php ./README.txt
There are only two code files here and one README; the other things you see are parent directories for those files. An abbreviated listing of this is
./includes/languages/english/modules/order_total/ot_quantity_discount.php ./includes/modules/order_total/ot_quantity_discount.php ./README.txt
The hierarchy of these files is intended to exactly duplicate the structure of your cart. So if your cart is installed on your webserver under (say) /public_html/zencart, then to install the file
./includes/modules/order_total/ot_quantity_discount.phpyou would ftp to your site, cd to
public_html/zencartand then transfer the "includes" folder from the mod over.
This would put the file
./includes/modules/order_total/ot_quantity_discount.phpinto
/public_html/zencart/includes/modules/order_total/ot_quantity_discount.php
If your cart is under (say) /httpdocs/public_html/, the instructions would be the same; ftp to your site; cd to
/httpdocs/public_html/
then transfer the includes
folder over.
So in fact, to install this contribution, all you have to do is copy these two files into your cart, turn on the Quantity Discounts order total module (under Admin > Modules > Order Total), and you're done.
Templates and Core Files
I chose the example of Quantity Discounts because it's the simplest form of a mod - it contains only new, original files. What about something more complex which modifies existing files in the cart?Zen Cart has two facilities for dealing with situations like this, and you need to understand them prior to installing mods to save yourself grief the next time you upgrade your cart.
Since changing the "skin" or "theme" of the cart is the most common customization, the user interface is built to accommodate relatively easy customization. Zen Cart calls this mechanism "template overrides" and provides guidelines on how to create a custom template. In my mods, I assume the template name is "custom." So if you see a file with the name "custom" as part of its name, you know it's a template component. If you've used a name other than "custom" then you will have to move the file accordingly. Note: If you are using Zen Cart 1.5.5 or higher, your template name will be "responsive_classic" if you have not changed it.
Some examples: the Better Together Promotional Page contains a file called
./includes/templates/custom/templates/tpl_bettertogether_promo_default.phpIf your template name is "scott", you would install this file in
./includes/templates/scott/templates/tpl_bettertogether_promo_default.php
Discount Preview contains a file called
./includes/modules/custom/inc_qd.phpIf your template name is "apple", you would install this file in
./includes/modules/apple/inc_qd.php
Not all files can be handled by the template system. For instance, files in
includes/modules/pages
cannot be overridden.
My recommendation for files like this is that during the
installation process, you make a backup of the original file, and
name it <original-filename>.orig. For instance,
my
Gift Wrap at Checkout
contribution modifies the file
./admin/invoice.php
Prior to installation, rename this file
./admin/invoice.php.orig
This serves two purposes:
- In the event of a problem, you can easily restore the original file
- When it comes time to upgrade your cart, you can easily identify the core files you've changed by searching for files named *.orig
invoice_orig.php
or orig_invoice.php
)
Merging Template Files
Around Zen Cart 1.5.5, I started applying my template changes to the responsive_classic template rather than the template_default template. So if you want to apply one of my changes to your own template, do the appropriate compare, and then add the resultant difference to your template. Here's an example, which assumes you are installing Discount Preview:a) Notice that the file
includes/templates/custom/templates/tpl_shopping_cart_default.php
is changed by the mod (since the file includes/templates/custom/templates/tpl_shopping_cart_default.php
. is included).
b) Compare the copy of this file from the mod to the base file, which is (as of 2019) the original file
includes/templates/responsive_classic/templates/tpl_shopping_cart_default.php
from a fresh download of Zen Cart 1.5.6.
c) You'll see about a hundred lines of code added around line 149 of the original 1.5.6 file. You'll need to review the structure of the original file to determine where this line is in your copy of the template file. You'll see the point of insertion is right below this block:
<div id="cartSubTotal"><?php echo SUB_TITLE_SUB_TOTAL; ?> <?php echo $cartShowTotal; ?></div> <br class="clearBoth" />So just find that block in *your* template file (
includes/templates/YOUR_TEMPLATE/templates/tpl_shopping_cart_default.php
), and
insert the new 100 lines of code there.
Database Changes
Some mods require database changes. For instance, Gift Wrap at Checkout includes a file called orders_wrap.sql, which modifies your database.These files are best run through the Zen Cart admin panel, which will take care of the prefix (if you have one). To do this, go to Admin > Tools > Install SQL patches.
Alternately, you can run them using phpMyAdmin, but you will need to edit the .sql script to account for the prefix. errors occur during execution. Ask your host if you're not sure how to run this tool.
For instance, if the file creates a table called "orders_giftwrap"
CREATE TABLE orders_giftwrap( ...
you will need to change this to reflect your prefix, i.e.
CREATE TABLE zen_orders_giftwrap( ...assuming your prefix is "zen_".
If you have used a prefix, it is stored in
includes/configure.php
;
look for the variable DB_PREFIX.
If you do an install and get an error like
1146 Table 'yourdb.zen_better_together_admin' doesn't exist in: [SELECT * FROM zen_better_together_admin ORDER BY id DESC ] If you were entering information, press the BACK button in your browser and re-check the information you had entered to be sure you left no blank fields.This means you used phpMyAdmin but forgot to edit the .sql file to include your prefix.
The most important principle to remember when changing your database is that you must do a backup prior to making the change. You can do a backup using phpMyAdmin.
Not all database modifications will be done through a .sql file; for instance, any file which requires you to click an "Install" link from Admin > Modules is modifying your database. Be sure to make a backup!
Some mods use the "TYPE=MyISAM" syntax when doing a CREATE TABLE, which is not accepted by some newer versions of MySQL. If you get a message like this when running an SQL script:
ERROR 1064 (42000): You have an error in your SQL syntax; check the manual that corresponds to your MySQL server version for the right syntax to use near 'TYPE=MyISAM' at line 1
To fix this, simply edit the .sql file and change all instances of
TYPE=MyISAMto
ENGINE=MyISAM
Uploading
The best way to upload is to upload the ENTIRE includes directory from the unzipped file onto your includes directory, and the ENTIRE admin directory (if one exists) from the unzipped file onto your admin directory (after the appropriate renames):- If your admin folder is named ABCDEF, rename the admin folder in the unzipped mod to ABCDEF, and upload the entire folder.
- If the unzipped file contains template specific files, rename
the containing directories to the name of your template. For
instance, if your template is named "blue" and the mod has a directory
named
includes/modules/YOUR_TEMPLATE/
rename this toincludes/modules/blue
Similarly, if the mod contains a directory calledincludes/templates/custom
rename this toincludes/templates/blue
Example 1: Quantity Discounts
In this example, we will assume your cart is installed under public_html on your webserver- Upload the includes directory to your includes directory.
If you're doing it file by file (not recommended)
- Copy
./includes/languages/english/modules/order_total/ot_quantity_discount.php
to
/public_html/includes/languages/english/modules/order_total/ot_quantity_discount.php
- Copy
./includes/modules/order_total/ot_quantity_discount.php
to
/public_html/includes/modules/order_total/ot_quantity_discount.php
Example 2: Better Together
In this example, we will assume your cart is installed under httpdocs/testsite on your webserver, and that your template is named "brownie."- In the unzipped file, rename
./includes/templates/custom
toincludes/templates/brownie
- Upload the includes directory in the unzipped file to your httpdocs/testsite/includes directory.
If you're doing it file by file (not recommended)
- Copy
./includes/languages/english/modules/order_total/ot_better_together.php
to
/httpdocs/testsite/includes/languages/english/modules/order_total/ot_better_together.php
- Copy
./includes/modules/order_total/ot_better_together.php
to
/httpdocs/testsite/includes/modules/order_total/ot_better_together.php
- Copy
./includes/templates/custom/templates/tpl_better_together_marketing.php
to
/httpdocs/testsite/includes/templates/brownie/templates/tpl_better_together_marketing.php
- Copy
./includes/templates/custom/templates/tpl_better_together_marketing_images.php
to
/httpdocs/testsite/includes/templates/brownie/templates/tpl_better_together_marketing_images.php
- Copy
./includes/templates/custom/templates/tpl_better_together_xsells.php
to
/httpdocs/testsite/includes/templates/brownie/templates/tpl_better_together_xsells.php
- Copy
./includes/templates/custom/css/stylesheet_bettertogether_product.css
to
/httpdocs/testsite/includes/templates/brownie/css/stylesheet_bettertogether_product.css
Figuring out ID values
Most of my mods use IDs: category ids, product ids, manufacturer ids, etc. How do you know what values to use.It's really pretty easy. The first thing you need to do is turn off any SEO URL mod you have so you can see regular Zen Cart URLs, which contain a lot of information.
-
Product ID: This is the easiest one. When you go to the product info
page for a product in your cart, the URL will look like this:
http://mysite.com/index.php?main_page=product_info&cPath=54_61&products_id=173
The number after "products_id=" is the product id (173 in this case). - Category ID: This term has different meanings depending on the context; look at my Category Issues page.
- Manufacturer ID: See Manufacturers in Zen Cart.
Common Problems
- Blank Page:
If you get a blank page after an install, you can debug it by following the
blank page help.
- Not all blank page problems show up as a complete blank page! If you look at the bottom of your screen and see that the footer is missing, you have the blank page problem.
-
If you have the blank page problem, but don't see error files in your
cache directory, your permissions may not permit the webserver to write into the directory.
You can test this by editingincludes/functions/functions_email.php
and removing the first line (which is "<?php"). Refresh the browser page in which your are viewing your cart or admin, and check the cache directory. You should see an error file; if you don't, your permissions are too strict. Note that you may need to use your cPanel File Manager to fix them; not all systems allow ftp to set permissions. Remember to restoreincludes/functions/functions_email.php
!
- PHP issues which don't generate blank pages: Even if you don't see a blank page or a partially blank page, you could still have PHP interpretation issues. Look in the cache directory for error files. See the blank page help referenced above for details.
- File Transfer issues: Check the files you have transferred and ensure they are the same size as the ones on your host computer. Do not use SmartFTP, CuteFTP or browser based FTP. Do not use DreamWeaver's FTP. Use a proper FTP client such as FileZilla or Coffee Cup FTP.
- Renaming files incorrectly:
This can sometimes lead to a blank page situation. There's an
easy trick to it: when creating a backup file, just remember not to
use the extension ".php" for php files. For example, if you are
backing up
includes/functions/functions_prices.php
try backing it up to one of these names:includes/functions/functions_prices.php.YYMMDD includes/functions/functions_prices.php.orig includes/functions/functions_prices.php.v2
DO NOT call it something likeincludes/functions/old_functions_prices.php // NO!!! DO NOT DO THIS!
- Failed merges: Backup your files, then take my zip file, rename the template directories as explained above, and transfer the files as is with no more changes to your site. See if you still have the same problem. (In all likelihood you won't.) If you don't, you have merged your changes and my changes incorrectly. Introduce your changes back one at a time, and see where it breaks.
-
Many of my mods that require a setup() function (Better Together,
Combination Discounts, Big Chooser, Big Spender, Table Discounts, etc.)
Some people try deleting the setup function and wind up deleting the
final brace in the file, which causes a blank page on checkout. The
bottom of the file
includes/modules/order_total/the-mod-name.php
should look like this:function setup() { .. some statements here .... } } ?>
The final curly brace must not be deleted.
Please note that my prices for installation are for my mods only. I do not install third party mods unless you are a client who is on support.