Working with CS Cart: The basics

As I announced earlier I will be writing in the next few weeks about CS Cart customization. In this post I will talk about the basics of the CS Cart structure and how you can start to make changes to existing Skins (by changes I mean structural, not design changes). I will assume at this point that you already downloaded and installed CS-Cart on your development environment and are ready to go on with the customization. In case you have not, check out http://www.cs-cart.com for more information on the different licenses and how to install the software.

Basic Structure

Looking at the directory structure you will notice the skins directory in your installation. This is where CS Cart stores the currently installed skins for your cart software. During the installation you were asked to choose a skin, if you haven’t chosen the basic skin, please do so from the administration section. Within the “basic” directory in the “skins” directory you will find three more entries, “admin”, “customer” and “mail”. These three directories refer to the three main sections of CS Cart skinning, one for the administration section (by default accessed by http://www.example.com/admin.php), the frontend of the cart (http://www.example.com/) and any from the system sent emails. Each of those directories has a number of files and sub-directories for you to play with, however you will later learn that you will probably not need to work with any of them, but rather create your own files to override existing files.

Most, if not all the files residing in these directories are .tpl files which are Smarty templates. If you are not familiar with Smarty I strongly suggest that you go over to their website and check out their documentation.

Template Hooks

I had to learn the hard way that most changes in CS Cart can be done using template hooks. The CS Cart documentation mentions template hooks briefly but doesn’t give very good examples or explanations on how to use them. What are template hooks you ask? According to CS Cart’s documentation,

Template hooks are parts of a template enclosed in the tags “{hook name=”section:hook_name”}{/hook}” that can be supplemented or completely redefined by any addon.

So how do we utilize these hooks? Let’s do this by example; open up the index.tpl file in the customer directory. In the bottom you will find a hook defined just before the body close tag. We will use this hook to add some static HTML to all pages in the store front. The CS Cart documentation says that hooks can be used by addons; does this mean we need to create an addon? Simply said, yes, however the guys over at CS Cart were kind enough to add an addon called “My Changes” which is essentially an empty addon used for customization purposes, so we won’t have to create one. This addon is by default enabled. Have again a look at the hook definition in the index.tpl, note down the section in the name attribute (“index”) and the hook name (“footer”). This information is enough for us to get things started.

In the addons directory under customer create now the folders “my_changes/hooks”. The hooks folder is the point where CS Cart will be looking for any hooks grouped by section, naming you will have to also create the sub-folder “index”. Your structure should look like this:

skins/
  basic/
    customer/
      addons/
        my_changes/
          hooks/
            index/

Before we go on and utilize the hook we will have to decide how we want to add the static HTML content. There are three types of utilization: pre, post and override. The pre hook will prepend any content to the defined hook and the post hook will append to the defined hook. This is very practical if for example the hook is enclosing any content already contained in the original template. An example for this is the index:main_content hook in the main.tpl template, but more to this file later on. The override hook will completely replace the predefined contents of the hook area. We currently do not know if other addons are utilizing the footer hook and we want to be sure that the static HTML is in the middle, meaning not prepended nor appended to the content, hence we will use the hook override. We will have to tell CS Cart somehow that we want to override the hook’s content, this is easily done by creating a file with the name “footer.override.tpl”. In general the filenames are as follows:

  • hook_name.pre.tpl – Add changes before content
  • hook_name.post.tpl – Add changes after content
  • hook_name.override.tpl – Replace content with changes

Simply open the footer.override.tpl and add any static HTML to it, like for example:

<p>
  I added this by reading this <a href="https://mozzymoz.wordpress.com/2011/10/26/working-with-cs-cart-basisc/" target="_blank">article</a>
</p>

Now simply go to your storefront, refresh and see the changes taking effect in the bottom of the page. In case you cannot see the changes, go to your administration and add ?cc to your query string in order to clear the cache.

This is all it takes to make changes to an existing skin. I do admit that this example is not really something that is useful, however you could play around with this code and see that you could for example easily add a Share This widget to all of your pages.