How to install a plugin

Adding a plugin to your store

If you installed your Zen Cart using Fantastico or perhaps had a friend or subcontractor install it for you, installing a plugin 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. Most plugins 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. This cannot be overstated. Even a straightforward plugin like Simple Google Analytics has steps in the README which must be done manually for the plugin to work; simply uploading the files under includes is not sufficient.

Why do plugin authors do this? Most often, it is done because the files that need to be updated manually are generally very customized on a per cart and per template basis (in the example of Google Analytics above, it’s includes/templates/YOURTEMPLATE/common/tpl_main_page.php that needs to be modified, and including this file as a whole would make no sense because it is always customized.

Getting Started

Before you start, you’ll need to verify that you have some things.

  • Plugins 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 plugin, as an example.

./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.php you would use your FTP tool to go to your site, change directory to public_html/zencart, and then transfer the “includes” folder from the plugin over.

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 plugin, 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 Totals), and you’re done.

Templates and Core Files

I chose the example of Quantity Discounts because it’s the simplest form of a plugin - 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 plugins 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. A common convention is to 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.php

If your template name is “scott”, you would install this file in

./includes/templates/scott/templates/tpl_bettertogether_promo_default.php

What’s On Sale contains a file called

./includes/modules/custom/sales_index.php

If your template name is “apple”, you would install this file in

./includes/modules/apple/sales_index.php

Not all files can be handled by the template system. For instance, files in includes/modules/pages cannot be overridden. A recommendation for files like this is that during the installation process, you make a backup of the original file, and name it .orig. For instance, the Gift Wrap at Checkout plugin 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.

Note that “.orig” should be a suffix onto the original filename. (Don’t name the file invoice_orig.php or orig_invoice.php)

Merging Template Files

If a plugin includes a template file change, you can simply compare the file provided to the unaltered file from a fresh Zen Cart download (using either template_default or responsive_classic as the base template, as appropriate) to see how to apply those changes to your template files.

Database Changes

Some plugins 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.

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 plugins 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=MyISAM

to

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 plugin 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 plugin has a directory named

    includes/modules/YOURTEMPLATE/

    rename this to

    includes/modules/blue

    Similarly, if the plugin contains a directory called

    includes/templates/custom

    rename this to

    includes/templates/blue

Too Much?

If this sounds like too much for you, the best route is to go onto the Zen Cart Commercial Help Wanted forum and hire a pro.




Still have questions? Use the Search box in the upper right, or try the full list of FAQs. If you can't find it there, head over to the Zen Cart support forum and ask there in the appropriate subforum. In your post, please include your Zen Cart and PHP versions, and a link to your site.

Is there an error or omission on this page? Please post to General Questions on the support forum. Or, if you'd like to open a pull request, just review the guidelines and get started. You can even PR right here.
Last modified March 18, 2024 by Scott Wilson (3db4324).