How to install one of my 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.

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.php

you would ftp to your site, change directory to public_html, then to zencart, then to includes, then modules, then order_total, and transfer the file ot_quantity_discount.php to that directory.

If your cart is under (say) /httpdocs/public_html/, the instructions would be the same; cd to this location, then down into includes/modules/order_total and copy the file in.

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 Totals), 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 accomodate 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. 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

Discount Preview contains a file called

./includes/modules/custom/inc_qd.php

If 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

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

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 phpMyAdmin so you can see if any errors occur during execution. Ask your host if you're not sure how to run this tool.

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!

Example 1: Quantity Discounts

In this example, we will assume your cart is installed under public_html on your webserver

• 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."

• 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

If the information you learned reading this site is helping your store make more money, please consider making a donation. Thank you!

Want more Zen Cart?     Tips and Tricks     Contributions     Extensions     Custom Software     Newsletter