I've been watching the forums, and I'm seeing many folks make many modifications to their cart. This is great!

However, I'm also seeing users of Zen Cart talk about making changes to important files such as:

/includes/filenames.php
/includes/languages/english.php
/includes/languages/english/*.php

and many others.

Just a warning and note - you should not be modifying these files, if you want future upgrades to be simpler!

There is a file override system in place that works very well, and makes it so you do not have to modify the core files.

If you have modified these files, the next time you go to upgrade to the latest release of Zen Cart you will over-write these files and lose your changes.

Ok, so how do you avoid this problem, and what's the right way to use the override system?

Below, I've written up steps on how to use the system correctly - and NOT modify your core files!

All of my examples below assume
*You are using the english language. You get the idea for your own language.
*The example template name is /CUSTOM


**Note, be sure to also read the FAQ on How do I create a new Custom Template? **

================================

Modifying the default Language File - /includes/languages/english.php

Example: You need to modify the title, so that instead of reading Zen Cart!, it reads Your Store Name!

Make a directory with the same name as your template name in /includes/languages, so you now have /includes/languages/custom.

Copy english.php to this directory.

Then, you can make any needed modifications in your new:

/includes/languages/custom/english.php


================================

Modifying Language Files - /includes/languages/english/*.php (all files within this directory)

Example: You need to modify some text in account.php - Let's say you want to change every instance of the word 'Account' to 'Profile'

Make a directory with the same name as your template name. Assume your template name is custom. This directory path would be:

/includes/languages/english/custom

Copy the original file /includes/languages/english/account.php to this new folder, /includes/languages/english/CUSTOM

Then, modify the file in the custom folder. This will 'override' the existing file in /includes/languages/english, thereby leaving the core file intact and alone.

Another example: in /includes/languages/english/CUSTOM/meta_tags.php (a copy of /includes/languages/english/meta_tags.php):


becomes:




================================

Modifying Template Files - /includes/templates/template_default/templates/tpl_*_default.php

Example: You need to modify some HTML in tpl_account_default.php

In your templates directory ( /includes/templates/CUSTOM ) you should already have a folder templates ( /includes/templates/CUSTOM/templates ).

Copy tpl_account_default.php to this directory. You can then make your changes, and it will again 'override' the base file in /includes/templates/template_default/templates directory.

You should only copy files over to your /CUSTOM template directory that you make modifications to. If you do not make modifications, then by default, the shop will call the default file from the template_default directory.

================================

Modifying Sidebox Templates

These follow the same format as your regular templates (see above), with the exception of the sidebox path:

/includes/templates/CUSTOM/sideboxes

================================

Modifying Sideboxe Modules - /includes/modules/sideboxes/*.php

Example: You may want to modify sidebox information.php to include another link.

In your sidebox directory (/includes/modules/sideboxes), create another subdir with the same name as your template /CUSTOM, so you now have /includes/modules/sideboxes/custom

Copy /includes/modules/sideboxes/information.php to this new folder

You can then modify the copy to suit your needs, and the custom version will over-ride the default information.php in /includes/modules/sideboxes

You can verify this sidebox is being over-ridden by logging into Admin->Tools->Layout Boxes Controller. In the column, 'Box File Name', if the text appears in RED, it is being over-ridden.

================================

Calling custom file names - /includes/filenames.php

Example: You create a custom page, about_us and need to call the filename.

Rather than putting a new define in /includes/filenames.php, you should call the filename from the existing extra_datafiles directory:

/includes/extra_datafiles.

Create a new filename, about_us_filenames.php and place this file in /includes/extra_datafiles.

In this file, you would have the code:


This file will be called automatically, as would any other file in this directory, thereby telling the system what your custom filenames are.

Try and keep the same format for other new files you make...example, calling a file named or related to  blah would be named

blah_filenames.php

================================

Calling custom database tables - /includes/database_tables.php

Example: You create a new database field for your UPS tracking system, ups_track and need to define the table name for your code.

Rather than putting a new define in /includes/database_tables.php, you should call the table name from the extra_datafiles directory,

/includes/extra_datafiles.

Create a new filename, ups_track_database_tables.php and place this file in /includes/extra_datafiles.

In this file, you would have the code:


This file will be called automatically, as would any other file in this directory, thereby telling the system what your custom database table names are.

================================

Extra Language Files

Example: You need an extra file to call extra language definitions for a new box you created, Resource Center

In /includes/languages/english/extra_definitions, you would create a file named resource_center_box_defines.php. In this file, you would put all language definitions for your new custom sidebox.

This directory automatically gets loaded, ensuring your language definitions for custom boxes or pages are called.

================================

Adding Extra Javascript to a specific page

Example: You need to load some javascript for your bizrate account, so that it loads from the existing page checkout_success.php after the order has completed.

In the directory /includes/modules/pages/checkout_success, create a new file named jscript_bizrate.js

In this file, you would put your custom javascript code bizrate gave you, such as:


Same thing..if you were using google's conversion tracker. Create another file in the required folder (ie: checkout_success if to be processed only on that page), maybe named jscript_google.php

================================

CSS File Adds & Modifications

Example: You have created a new CSS class for something unique for your site.

Rather than add this to your existing CSS file in /includes/templates/custom/css/stylesheet.css, create a new file in this same dir named styleSOMETHINGHERE.css and add your CSS data in there.

Zen Cart will automagically load all the "style*.css" files from that folder, in alphabetical order, when drawing your store's pages with that template.

================================

Upgrades

Last, we need to talk about the subject of upgrades!

So, you're now using the Zen Cart overrides system properly! Congratulations, give yourself a pat on the back. Now, an upgrade comes - You dont have to worry about it over-writing your custom files, because all of yours are in custom directories!

So, you do your upgrade thing. What if new code was added to core files that you are overriding? Now, you can take your custom directories, and compare the code to the NEW core file.

Example, if you made customizations to your /includes/languages/custom/english.php file, and now with the upgrade, there are some new defines in /includes/languages/english.php you obviously need to get those new defines into your english.php

The easiest way of doing this is going to use a file comparing utilty!

I highly recommend using Beyond Compare - yes, it costs $30 but it is worth far more than that!
Ok, if you're cheap, you can always go with WinMerge, open source and free.

Once you've got your file comparing utiltiy, you can compare your /includes/languages/custom/english.php to the new core file, /includes/languages/english.php and EASILY incorporate the new changes into your override file.  Repeat for all your customized files in all your overrides folders.  Then upload the changes to your site, along with all the other updates for the new release.   There are other FAQ's on upgrading, which go into more details, but this is the overall concept.