Zen Cart custom software development, Zen Cart modules, Zen Cart Expert eCommerce with Zen Cart!

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

Examples : I have provided several examples of osCommerce Installations.

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 osCommerce 2.2 Quantity Discounts contribution as of version 1.0.1:
catalog/includes
catalog/includes/languages
catalog/includes/languages/english
catalog/includes/languages/english/modules
catalog/includes/languages/english/modules/order_total
catalog/includes/languages/english/modules/order_total/ot_quantity_discount.php
catalog/includes/modules
catalog/includes/modules/order_total
catalog/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
catalog/includes/languages/english/modules/order_total/ot_quantity_discount.php
catalog/includes/modules/order_total/ot_quantity_discount.php
catalog/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/catalog, then to install the file catalog/includes/modules/order_total/ot_quantity_discount.php you would ftp to your site, change directory to public_html, then to catalog, 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/catalog, the instructions would be the same; cd to this location, then down into includes/modules/order_total and copy the file in.

It is possible to not use the "catalog" directory. Your entire cart could be under (say) /httpdocs/public_html/. You would know this because there would be directories like "admin" and files like "login.php" under here. In this case, to transfer the file catalog/includes/modules/order_total/ot_quantity_discount.php you would ftp to your site, change directory to public_html, then to then to includes, then modules, then order_total, and transfer the file ot_quantity_discount.php to that directory.

So to install this contribution, there are really just three actions required:
  • Copy these two files into your cart
  • Go to Admin > Modules > Order Total, select Quantity Discounts, and press the Install button. (Note that under osC 2.3.3, you must first press the "Install Module" button at the upper right hand side of the screen to see the list of uninstalled modules.)
  • Adjust the sort orders of the modules under Admin > Modules > Order Total. One method I recommend is to multiply the default values by 10, and adjust from there. For example:
    Sub-Total 10
    Shipping  20
    Discounts 21-29
    Tax       30
    Total     40
    
    Be sure the values are unique (i.e. do not use any particular number twice).


Database Changes

Some mods require database changes.

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.

In osCommerce 3.0, tables can have prefixes. If you are using phpMyAdmin and have used a prefix in your database, you will need to modify the .sql file to reflect this. For instance, if the file creates a table called "orders_mytable"
CREATE TABLE orders_mytable(
...


you will need to change this to reflect your prefix, i.e.
CREATE TABLE osc_orders_mytable(
...
assuming your prefix is "osc".

If you have used a prefix, it is stored in includes/configure.php; look for the variable DB_TABLE_PREFIX. This is only available in osCommerce 3.0.

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=MyISAM
to
ENGINE=MyISAM


Core Files

I chose the example of Quantity Discounts for osCommerce 2.2 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?

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, if you are modifying the file admin/invoice.php then 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".)

Template Files (osCommerce 3.0 only)

In osCommerce 2.2, modifying the "skin" or "theme" of the cart required you to directly change pages under the catalog directory. For instance, changing the appearance of the shopping cart page was done by modifying catalog/shopping_cart.php.

osCommerce 3.0 changes this by introducing "templates." 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.

Language Files (osCommerce 3.0 only)

Language file handling in osCommerce 3.0 is different than in osCommerce 2.2. Using the example of Quantity Discounts again, in osCommerce 2.2, if you modify the file ./catalog/includes/languages/english/modules/order_total/ot_quantity_discount.php you will see the changes you have made reflected immediately. In osCommerce 3.0, if you change the corresponding language file
includes/languages/en_US/modules/order_total/better_together.xml
you must re-import the new strings into your database. Go to Admin > Configuration > Languages, check the box next to your language and press the Import button. Select the "Replace All" radio button and press the Import button. You will now see the changes you have made.

Example 1: Quantity Discounts (osCommerce 2.x)

In this example, we will assume your cart is installed under public_html/catalog on your webserver
  • Copy catalog/includes/languages/english/modules/order_total/ot_quantity_discount.php to
    /public_html/catalog/includes/languages/english/modules/order_total/ot_quantity_discount.php
  • Copy catalog/includes/modules/order_total/ot_quantity_discount.php to
    /public_html/catalog/includes/modules/order_total/ot_quantity_discount.php

Example 2: Better Together (osCommerce 2.x)

In this example, we will assume your cart is installed under httpdocs/testsite on your webserver, and that you are not using the directory "catalog" - you have skipped this level.
  • Copy catalog/includes/languages/english/modules/order_total/ot_better_together.php to
    /httpdocs/testsite/includes/languages/english/modules/order_total/ot_better_together.php
  • Copy catalog/includes/modules/order_total/ot_better_together.php to
    /httpdocs/testsite/includes/modules/order_total/ot_better_together.php
  • Copy catalog/better_together_marketing.php to
    /httpdocs/testsite/better_together_marketing.php

Example 2: Better Together (osCommerce 3.0)

In this example, we will assume your cart is installed under httpdocs/testsite on your webserver.
  • Copy includes/modules/better_together_marketing.php to
    /httpdocs/testsite/includes/modules/better_together_marketing.php
  • Copy includes/languages/en_US/modules/order_total/better_together.xml to
    /httpdocs/testsite/includes/languages/en_US/modules/order_total/better_together.xml
  • Copy admin/includes/modules/order_total/better_together.php to
    /httpdocs/testsite/admin/includes/modules/order_total/better_together.php
  • Copy ./includes/modules/order_total/better_together.php to
    /httpdocs/testsite/includes/modules/order_total/better_together.php
Still having problems? I will install most of my mods for a fee (generally $60). Click the PayPal button below.

Notes on Installing in Frozen/Edge

There are a few additional steps required when installing my software with these releases:
  • These releases have removed the filename defines from includes/filenames.php. So you will have to modify the code wherever you see the string FILENAME_ and replace the whole string with the name of the file. For example:
    FILENAME_SHOPPING_CART => 'shopping_cart.php'
    FILENAME_PRODUCT_INFO => 'product_info.php
    etc.
  • These releases have removed some defines from includes/configure.php. I would recommend simply re-adding them to this file.
      define('DIR_WS_INCLUDES', 'includes/');
      define('DIR_WS_FUNCTIONS', DIR_WS_INCLUDES . 'functions/');
      define('DIR_WS_CLASSES', DIR_WS_INCLUDES . 'classes/');
      define('DIR_WS_MODULES', DIR_WS_INCLUDES . 'modules/');
      define('DIR_WS_LANGUAGES', DIR_WS_INCLUDES . 'languages/');
    
  • In some cases, the variable $language must be declared as global, where this was not required before.


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?

  • Product ID: In the catalog, click on the product to open the product info page. In the address bar of your browser, you see something like
    ... product_info.php?products_id=24&osCsid=...
    
    The products_id = 24 tells you the product's id is 24.
  • Category ID: In Admin > Catalog, single click on the category you're interested in. In the address bar of your browser, you will see something like
    categories.php?cPath=3&cID=11
    
    If you were to double click on it, you'd see something like
    categories.php?cPath=3_11
    
    The category you want to use is "11".

    In the same way, in the catalog you can hover over this category in the categories sidebox and see
    catalog/index.php?cPath=3_11
    
    This re-confirms that the category is "11."
  • Manufacturer ID: Go to the Manufacturer's sidebox on your catalog home page and select a manufacturer. The resultant URL will look something like this:
    catalog/index.php?manufacturers_id=8&osCsid=rhifpa0duotjnoadm4e5is70k0
    
    The "manufacturers_id=8" component of this URL indicates that the id for this manufacturer is 8.