How to install one of my osCommerce modsThis 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.
BackgroundIf 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 instructionsThis 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 StartedBefore 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 StructureHere'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.phpyou 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.phpto 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_totaland 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.phpyou 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.phpto 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 Totals, 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 Totals.
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 40Be sure the values are unique (i.e. do not use any particular number twice).
Database ChangesSome 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
Core FilesI 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.phpthen prior to installation, rename this file
admin/invoice.php.origThis 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
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.phpyou 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.xmlyou 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
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.
Example 2: Better Together (osCommerce 3.0)In this example, we will assume your cart is installed under httpdocs/testsite on your webserver.
Notes on Installing in Frozen/EdgeThere 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 whereever 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
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
$languagemust be declared as
global, where this was not required before.
Figuring out ID valuesMost 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=11If you were to double click on it, you'd see something like
categories.php?cPath=3_11The 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_11This 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=rhifpa0duotjnoadm4e5is70k0The "manufacturers_id=8" component of this URL indicates that the id for this manufacturer is 8.