Working with CS Cart: Template Suggestions

It has been a little while since I posted my first “Working with CS Cart” entry. The previous post showed you how to change the footer of an existing CS Cart skin, something useful but not really complex like for example selecting different page templates depending on the page or controller you are viewing.

One of my clients had some very varying templates for different sections of the cart. If you are familiar with Drupal you know that the Drupal system looks automatically for specific template names depending on the currently requested URL based on specific criteria. Essentially this is exactly what I needed CS Cart to do, however I had to include a little hack in order to implement such a mechanism.

Suggestion Criteria

Usually the frame of a website design stays the same which would logically reside in the index.tpl, however the display of the actual content might be different for several sections/pages in the cart. For this we will have to modify the main.tpl file. Here you will see the default way of displaying the “frame” for content in CS Cart but what if we had a design that has a different structure for the home page and inner pages? Further more, what if one category has a different structure than the rest? Well now we are getting closer to build up our criteria. To make things short let me sum up the criteria I have setup for my client’s project:

  • Each controller (index, pages, products, categories etc.) may have a different structure
  • One or more pages may have a different structure
  • One or more categories may have a different structure
  • One or more products may have a different structure

Having those criteria defined gives us a great deal of flexibility to basically be able to control the content’s “frame” in any situation.

Smarty Modifier: Looking for a template

Unfortunately CS Cart nor Smarty have any built-in functionality to check whether or not a template exists from within a template, so I had to go in and quickly implement such a functionality. In order to keep things simple and not change any core code I had to think of a way to implement template suggestions from within a .tpl file which would require extending Smarty. Ideally an implementation of the required functionality would look something like this

{if $page_template|valid_template}
  {include file="`$page_template`"}
  {include file="default.tpl"}

Looking through the Smarty documentation you will learn that this function is a Smarty modifier but in fact we are not modifying any values only running a quick check on the existence  of a template file. So we will simply create a new modifier for Smarty in order to do the check. Go to your CS Cart installation and create a file called modifier.valid_template.php in the /lib/templater/plugins open it up and copy and paste the following code into it

 * Checks the presense of a template.
 * Usage example:
 * {if $page.include_file|valid_template}{include file=$page.include_file}{/if}
 $GLOBALS['smarty'] = $smarty;
 function smarty_modifier_valid_template($template_name)
   $smarty = $GLOBALS['smarty'];

We are simply creating a wrapper for the Smarty template_exists function. Now whenever we use this modifier we can check if a template path is actually an existing template.

Putting it together

Now we have our function to check if a template exists and our criteria. It is time to put it all to work. First of all we will create the implementation of our first criteria “Each controller may have a different structure”. For this back up the main.tpl file before editing it. Once this is done simply rename the backup to “default.tpl” so that we have a fallback template in case no specific templates were found for any of the controllers. Now we will replace the content of main.tpl with this

{capture assign='page_template}main/page_{$controller}.tpl{/capture}
{if $page_template|valid_template}
  {include file="`$page_template`"}
  {include file="main/default.tpl"}

It is as simple as these 6 lines to have custom layout for each of the controllers. Note that this snippet will look for the templates in the directory “main” which will have to be created manually and all page_<controller_name>.tpl files will reside in there.

Now you can create for example a page_index.tpl in order to differentiate the structure of the main.tpl for the homepage from the rest of the site. For any other controller simply create a file called ‘page_<controller_name>.tpl’ in your skin. If you are not sure about what controller is used for the section you want to change, simply enable debugging from the administration, navigate to the page you want to have changed and look up the “$controller” value in the debug window.

This change will only comply to our first criteria; we need more. For this we will need to create some more files and folders. I will document here how to implement suggestions for pages only but the same method can be applied to categories and products too. For better maintainability we create a new folder called “pages” in the “main” folder where all the page specific templates and a default.tpl fallback will reside. Also create a file called “page_pages.tpl” in the “main” folder. Here we will add the following code

{capture assign='page_template}main/pages/page_pages_{$page.page_id}.tpl{/capture}
{if $page_template|valid_template}
  {include file="`$page_template`"}
  {include file="main/pages/default.tpl"}

Now we have setup a mechanism for CS Cart to look for main/pages/page_pages_<page_id>.tpl for page specific structures. Simply create folders and files for the products and categories controllers to do the same and you’re good to go.

Simple, ain’t it?


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 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, the frontend of the cart ( 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:


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
  • – 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:

  I added this by reading this <a href="" target="_blank">article</a>

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.

Working with CS Cart

In the past week I have been put to the task to implement a new skin for the CS Cart eCommerce Software. Usually the projects I work on are based on either Symfony framework, Drupal or WordPress; taking up this project on a new platform with a 2 week turn around was quite a challenge.

One might expect when purchasing a software which advertises itself as “a perfect platform for custom eCommerce requirements”, it would be thoroughly documented but I had to find out that this was not the case. Of course one can find answers around the Internet. However it is a tedious and time wasting task. I was left with having to dig through core code and debugging to somehow get a grasp on the internals. To CS Cart’s defense, the design template I received to integrate into CS Cart was extremely customized.

On this note I will start writing up a small series on development with CS Cart covering basic changes to existing skins, writing add-ons and creating your own skin.