Archive for May, 2008

ZenCart: Develop an Advanced Plugin Without Overwriting Core Files

May 26th, 2008

At Activo, Inc. we have a few products that integrate between ZenCart and other systems. Recently, we went through the exercise of rewriting our Activo ZenCart POS (RunIt) Integration plugin so it will not require overwriting any core files. It took some time to read and research the ZenCart’s best practices and to follow the documentation, however once we learned what is available and how to use it, converting the code was a breeze. Our previous version of the plugin included already some usage of the flexibility of ZenCart but to complete the abstraction we needed to use the initSystem and the Observer Class.

Making sure that your plugin does not override any other core files or doesn’t require tweaking any core files is important for several reasons. First, overriding core files prevents smooth upgrades – it doesn’t matter how small of a change you introduced once upgraded you will always have to reintroduce the change. Second, a plugin that does not override core files have better chances (95%+) that it will interact smoothly with other non-obtrusive plugins. Third, respecting the platform’s API extends the life of your plugin over several versions of the platform that it plugins to. The following four different methods or subsystems are available for writing efficient and non obtrusive plugins within ZenCart:

Template Override Mechanism

This is the most common way of modifying your own shopping cart and making it stand out from other ZenCart systems. I believe the template override system was introduced right after ZenCart was span off of osCommerce. While, the current templating system is not my favorite (Joomla CMS has a much better template system), it does introduce all the flexibility that one needs in order to generate a custom template in ZenCart. At Activo, we have developed several shopping carts that do not resemble a typical ZenCart site. Here is how:

  • look under the /includes/templates folder – you will find the two templates that ship with every ZenCart: ‘default_template’ and ‘classic’. To add your own template, create a new folder try to use related name to your site or store and make sure to follow linux web folder naming conventions as this folder will be used for every CSS, Image, or Javascript files on your site.
  • Add the description file to your newly created template folder. This file will allow some information to be displayed in the admin area of ZenCart under Admin > Tools > Templates.
  • You probably want to add a jpeg or gif screenshot image of your template front end, however this is optional. If you do, don’t forget to place it in /includes/templates/<Your Template Folder>/images and put the name of the file inside the ‘template_info.php’ file in the ‘$template_screenshot’ variable.
  • At this point you have a template that will display everything exactly as the default_template because each file that cannot be found under your newly created template folder, ZenCart will look for the same file under the ‘default_template’ folder. So, to custromize just copy one file at a time from the default_template folder and begin customizing.

Note there is a lot more to this templating system than the files that you can override under the custom template folder. This will require its own article altogether.

‘extra’ Files Automatic Inclusion

If you spend enough time looking around the ZenCart folder, you will find a few folders that start with the words ‘extra_’. Any PHP files under these will run through execution before any page loads. The main purpose of these folders however, is to include definitions or init values necessary for some modules or components that you install or that you are writing. Since these folders run before anything ‘interesting’ happens with ZenCart, it won’t help to run scripts here. Similarly you will find ‘extra_*’ folders under the /admin/includes and some additional all around the site with more specific purposes, here is the full list with a small description for each one:

  • /admin/includes/boxes/extra_boxes – Extra submenu items for anything but the first column of the admin menu.
  • /admin/includes/extra_configures – Configurations files for admin panel plugins.
  • /admin/includes/extra_datafiles – Data files and data file definitions for the admin panel plugins.
  • /admin/includes/functions/extra_functions – Additional function files. These functions will be declared globally in the admin panel and can be used form your plugins.
  • /includes/extra_cart_actions – Custom shopping cart actions. Special logic to the shopping cart.
  • /includes/extra_configures – Configuration files which will be included in the front end.
  • /includes/extra_datafiles – Data files and data file definitions for the front end plugins.
  • /includes/functions/extra_functions – Additional function files. These functions will be declared globally in the front end and can be used form your plugins.


The initSystem of ZenCart is an extendable system that allows programmers to define what happens on initialization while remaining within the ZenCart framework. In simple words: it lets a programmer set your plugin environment in any way, shape, or form without rewriting the ‘application_top.php’ file. From the wiki page directly:

The term initSystem, apart from being a tag used to group certain PHP files together in the new documentation, is meant to embrace all of those files that are automatically included/initialised before any ‘command’ scripts can be run.

Zen Cartâ„¢ uses a (non Object Oriented) page controller pattern to decide the scripts to run, based on HTTP_GET parameters. The most important of these is the ‘main_page’ HTTP_GET parameter. Depending on that parameter, a command script is then run. Each commmand script resides in a directory in /includes/modules/pages.

The essence of how to use it is well described in the wiki page. What’s nice here is that ZenCart’s own internals make use of this system and you can see it under the ‘init_includes’ folder. It is fairly easy to add your own init script files and extend ZenCart to fit your needs. Make sure to read all of the documentation on the wiki page since there are some easy-to-overlook pitfalls like file name conventions and the order of which things happen in this system.

Observer Class

The Observer Class system of ZenCart is a sophisticated way to avoid core hacks in common places. It is a design pattern that is being used a lot in operating systems, and GUI design. It introduces a notion of events. A set of global events is declared throughout the ZenCart system and you can define your own logic or set of tasks that can be invoked by attaching your class to a specific event or a set of events. The list of events is pretty vast with the latest version of ZenCart (ver 1.3.8a) and can be seen at the wiki page for this system.


The above four methods of customizing and extending ZenCart is all that a good programmer needs in order to develop a robust, scalable, modular, and secure shopping cart website. These systems do not exist in osCommerce or any other open source shopping cart systems out there, at least not at the same level of maturity.



eCommerce, PHP/MySQL, Web Development, ZenCart , , , , , , , , , ,