Joomla! VirtueMart 1.1 Theme and Template Design

Open your browser and log in to your Joomla! site. Alas, you should see the VirtueMart control panel instead of the Joomla! control panel.

This simple exercise demonstrated that sometimes a useful change does not need complex coding. What we need is a little knowledge of how things work. I bet you probably understand what we have done above without explanation. After login, Joomla! will automatically go to the default component, hardcoded in the file helper.php. For standard Joomla!, this will be the com_cpanel component. In Exercise 1.1, we have changed this default backend component from com_cpanel to com_virtuemart. Instead of VirtueMart, we can certainly change the default to other components such as community builder or MOSET.

In the MVC presentation framework, the job of building a web page is divided into three main tiers. The backend tier is the data that is stored in the database (strictly speaking, there is no prescribed data storage format though a database is a natural way to manage the data). We need to grab data needed to build the web page. This tier of the job is done by the Model, which describes how data is stored and how data can be retrieved from the data server.

The frontend tier determines what and how data is presented on the browser. This is the job of the View. For a given dataset from a Model, there can be many different ways to present the data. Let's say, we have a set of statistical data, for example. We can present this data as a bar graph or a pie chart. Each of these presentations is called a View of the same Model.

Now statistical data is just a set of numbers. How can we convert them into a bar graph or a pie chart? That is exactly how the Controller comes into place. A Controller is a routine specifying how to convert the Model into various Views. One major advantage of this separation of data (Model) and presentation (View) makes changes to the application much easier. We can change the presentation independent of the underlying data and vice versa.

So, in the Joomla! 1.5 world, we will have a set of Models which interface with the database, a set of Views to tell the browser how to present the data, and a set of Controllers that control how to convert the Model into the View. According to the best practice, all Joomla! 1.5 components should follow this same structure. Thus, each Joomla! 1.5 component should have two subdirectories called models and views. Also, the root directory will contain a controller.php which extends the Joomla! controller's capability. This structure is revealed as we look at the contents of a Joomla! component which we had done previously. However, because of historical reasons and others, not all components follow this best practice. VirtueMart is one of those exceptions.

In the VirtueMart world, data manipulation is the responsibility of class files located in the classes subdirectory, which we looked at briefly while navigating through the Joomla! file structure. The class file starts with a prefix ps_ (probably derived from the historical name phpShop) followed by the data name. Let's go back to the VirtueMart file structure we've been looking at in the first section of this chapter. Navigate to the classes subdirectory under the VirtueMart administrator directory. You can see a lot of files starting with the ps_ prefix. Most of these files define a class in the data tier of VirtueMart. So you will expect the ps_product.php file to handle the product data, ps_shopper.php to handle the shopper data, and so on.

On the other end of the framework is the presentation tier, which is responsible to send back the HTML to the browser for display. VirtueMart 1.1 adopted a very flexible template structure where the major HTML code is separated from the data and processing logic. These template files are placed in the frontend VirtueMart directory and have been grouped into sets under the structure called theme. A VirtueMart theme is basically a collection of template files which control the frontend look of a VirtueMart shop. Thus, you can compare template files to a similar structure like a Joomla! view. Different template files will present VirtueMart data in different ways. For example, you can change the product listing page of the shop from a vertical list of items to a tabular view of items by simply changing one of the templates. For an example of how this can be done, you can refer to Chapter 3, Exercises 3.7 and 3.8.

So far, we haven't touched on the processing logic where data is converted into the presentation. In VirtueMart, we do not have controllers. Instead, the processing is done in the page files located within the html subdirectory under the VirtueMart administrator directory. All the page files are named in the pattern of {module}.{page}.php where module is a section of functions in VirtueMart, as we explained in the introduction.

Before we carry this similarity too far, it should be noted that VirtueMart is not actually implementing the MVC framework. So it deviates from this separation of data and presentation principle from time-to-time, as we shall see. Many times, the output of HTML code mingles with the data processing logic in the class file, making customization very difficult.

Let's look again at the real VirtueMart administrator directory for more insight. By navigating to the html subdirectory under the VirtueMart administrator directory, we can see a lot of files named in the pattern {module}.{page}.php. We see, for example, files such as shop.cart.php, shop.browser.php, checkout.index.php, admin.show_cfg.php, and so on. .php of course is the file extension which tells us (and also the operating system) that this is a PHP script file. {module} is the name of a VirtueMart module. {page} is the page name within the VirtueMart module. From the name shop.cart.php, we know this page belongs to the shop module and has a page name cart. Actually, this is the PHP script responsible for the processing of the shopcart page. Similarly, shop.browse,php will control the processing of the browse page, also part of the shop module. On the other hand, checkout.index,php will control the major logic of checking out. checkout is another module in VirtueMart and the name index suggests this is the starting page for the checkout process.

With all the background information, we will be able to appreciate the importance of themes and templates in the VirtueMart engine. When you type a VirtueMart URL on the browser (that is, URL that consists of index.php?option=com_virtuemart), the browser will send the request to the Joomla! site. After some initialization and routing code, the Joomla! engine will feed the request to VirtueMart for rendering the main part of the page.

The first thing VirtueMart will do is the section of initialization, including loading some basic classes, setting up the session, checking the permissions of the user, and so on. It will then check whether the request includes a pending function that needs to be done. If there is any, it will invoke the function before processing the page.

After the function is complete, VirtueMart will pass the processing to the HTML page (for example, shop.cart) requested. The page will load the relevant data using the appropriate class file, combining it with the session and/or configuration data already loaded. All necessary data will then be fed into the relevant template file to generate the HTML code that needs to be passed back to Joomla!. After a further filtering process by Joomla!, the HTML code will be sent as a response back to the browser for display.

Sometimes you just want to change the text that is displayed on a certain page. This is especially the case when you are using VirtueMart in a different language environment. VirtueMart does come with several language files, but the translation may not suit you. And even when your site is totally English, you may still want to replace a text or two to fit your client's or your own shop's specific needs. There are two ways you can do this.

On one hand, you can modify the language file that comes with VirtueMart. This will involve finding the appropriate language file that contains that specific language element you want to change. VirtueMart language files are placed in the languages subdirectory of the VirtueMart administrator directory. The language files are further subdivided into modules, with each language having its own .php file. You should first look into the common subdirectory where language elements used in more than one module are placed. Open the language file in an editor and search for the text you want to change. If you cannot find it in the common subdirectory, you need to look in the individual module directory. For example, if you need to change text on the browse page, then you will look into the shop subdirectory to see if you can locate that language element, since the browse page is controlled by the shop.browse.php file and so it belongs to the shop module. We will demonstrate how this can be done in Exercise 1.2. Customizing language elements is discussed in detail in Chapter 5, Changing the Look of VirtueMart.

In this exercise, we are going to customize two language elements found on the Product Listing page, as shown in the following screenshot:

As an example, we are going to change the text for Browse and Sort by. As we shall see, the Product Listing page is actually processed by the module page shop.browse. So we will expect these language elements to be found in either the shop language file or the common language file. These are the two files we are going to search for these two elements.

Layout changes are those that involve moving elements around on the page or changing the style of an element. For example, you may want to make the product name look bigger. Or you want to display the price before the product SKU and so on. These are all layout changes that can be easily done once you locate the template file that needs to be modified.

For styling changes, you can either add the CSS style in the template file or modify the theme CSS file. Sometimes you can even change the style by modifying the Joomla! template CSS. Obviously, there are pros and cons for each of these approaches. While considering what to change, you should also think of future compatibility. It may be better to restrict the number of modified files to a minimal, but that also depends on other requirements as well.

Layout changes can also be dynamic. You may want to use one layout under a certain condition and another layout if a different condition applies. You may, for example, want to use one CSS style for products in a certain category and a different CSS style for products in another category. This again will involve PHP coding. We will also be doing some exercises of this kind in later chapters (See, for example, Exercise 3.6).

Frontend behavior changes are changes that involve JavaScript running on user's computer. You may come across a JavaScript that can create a reflection effect for the product image. Adding this kind of behavior is actually pretty straightforward. Usually this is accomplished by putting the JavaScript in the template file and modifying one or two HTML elements. The JavaScript can also be added to the theme.js file or included by other means (See Chapter 5, Changing the Look of VirtueMart, and Chapter 9, Theme Customizations, for details of using JavaScript when making behavior changes).

Another example of behavior changes is changing the Ajax add-to-cart pop-up. Some people find the time that the pop-up appears too short or too long. This can be adjusted in the theme.js file or in the template file (See how this can be done in Exercise 8.2.).

Each of the templates will have a set of available fields that you can use. Sometimes you may want to display the same information in a different format. Examples of this kind of change are the product_availability and product_thumb_image fields. Many magic touches can be done in the template itself without involving changes to the VirtueMart class or page file.

From time to time, you may want to add a data field to your shop. If you sell books, for example, you may want to add fields such as publisher and author. Adding data fields like this is not as simple as it may seem. First, you need to modify the database table, usually through a phpMyAdmin session. Then you will need to modify the class file to accommodate the new fields. You also need to modify the product form used in the backend so that the fields can be displayed and edited there. You will need to add this to the VirtueMart page file to pass it to the template. Finally, you will need to modify the template to actually display the field.

On the other hand, it will be much easier to add a new user field since VirtueMart allows adding/customizing user fields used in the frontend or backend. You should use the Admin/Manage User Fields menu option to update the user fields. (For a detailed discussion about customizing user fields, please see Login/Registration and Shipping Information in Chapter 6, From Shop Basket to Final Checkout.) If you need some detailed control on the user field behavior, this can be accomplished by modifying the class file or page file. In case the user field will need to be included in the order e-mail, the corresponding e-mail template will need to be modified as well.

Adding data fields to other data tables such as product category or order is also possible. The complexity of such kind of customizations will depend on the exact requirements.

Due to the complexity and technical skills needed in adding data, discussion of this type of customization will need to be done in a different book.

The processing logic in a comprehensive shopcart like VirtueMart is definitely very complex. While VirtueMart is already very versatile and can cater for many actual applications, there are still areas that may not fit your specific needs. In that case, you may want to modify the processing logic to make VirtueMart work for you.

For situations like this, the best strategy would be to restrict your modifications to one single module. For example, if you just need changes in payments, you can probably develop your own payment methods. Anyhow, you should note that most processing logic resides in the page file and cannot be changed in a template. And the undertaking may involve complicated programming. So, the most part of this type of customization will be outside the scope of this small book. However, you may still find a few exercises that will involve modification of the page file, especially in Chapter 10, Additional Customization Possibilities. But those modifications definitely will be brief.

Sometimes you may want to develop your own theme, providing very different functionalities and style. Or you could even plan to sell your final design. To make it less intrusive to your user, creating a new theme is probably a good idea. This type of customization is the subject of Chapter 8, VirtueMart Theme Anatomy, and Chapter 9, Theme Customizations.

VirtueMart is an online web store application. It does not provide accounting and customer management functions. Many users wish to make VirtueMart work together with their existing data system seamlessly. In that case, an integration system will need to be built. VirtueMart was intended to have an import/export system for that purpose. But unfortunately, the module is not well-developed and will need lots of effort to make it work.

There are many other types of VirtueMart customizations. We can create new VirtueMart page files to display what we want. For example, we could have created a new page for displaying manufacturers called shop.manufacturer. We can also create a new VirtueMart module called wholesaler to display pages only for a special group of shoppers. We can create new pages like wholesaler.browse, wholesaler.product_detail, and so on under this module. We can create new templates for the new page files and modules according to our needs and imagination.

How to create and integrate these pages with the bigger VirtueMart system, however, will be totally on our own.

Certainly, many real-world projects will be a combination of several of the customization types outlined previously. If you plan to customize VirtueMart involving a few of these areas, you need to have a thorough plan before you start. Otherwise, you may soon find the project becomes too big and is unmanageable.

First of all, you need to think about the scope of your project. Is it just a simple change of language elements or layout? Is all of the data already available? Do you need to modify the database or the class file? Do you need to change the processing logic? What modules will be involved? Will the change be done on a VirtueMart core or on a Joomla! module or even on Joomla! itself?

Sometimes a seemingly simple task may involve many modules of VirtueMart and can become very complex. The tax system, for example, involves several important areas of VirtueMart from the product list up to checkout. Any changes to the tax will thus not be a straightforward thing.

When you are aware of the modules that may need change, you should drill down to the files that needs changes. Are modifications restricted solely to template files? Which template file contains the code that needs changes? There are close to 80 template files in the default theme. Locating the file to change may not be easy. If case of doubt, you can refer to the Appendix, VirtueMart Template Reference which contains a reference to all the template files. You can also use the technique described in testing and debugging to locate the page file that you will need to look at.

Now you have an idea of the scope and the files that may need changes. But how are you going to make the modifications? Many modifications will be straightforward, especially if you are already comfortable working with HTML code. However, for more complex coding, it is better to leave it to the professional. If you have a team, probably someone in the team can be able to help. Otherwise, you will need to consider outsourcing. Professional help for small jobs are actually very affordable. You can consider using freelancers in the many online freelancer agents. Just be careful not to base your choice only on the lowest bid. Just like building a home, you won't want to compromise your safety by paying less.

No matter how you are doing the job, whether in-house or outsourcing, it is always a good idea to back up your site before starting any modifications. For very small projects, such as changing the layout of a page where a database is not involved, you can just create a backup of the files that will need to be modified. You can even delay the backing up process to a time after the development has started. For projects of considerable size, however, you will need to have a full backup of the site.

As not all servers are created the same, it is not unusual to develop, test, and debug your customizations on your actual server. In that way, you can be sure the server configuration will be the same when you go live. If your site is already live, there is a lot more consideration. During development and testing, the site may be affected. So you need to assess the impact on the site. By carefully planning for the modifications, it is possible to restrict your changes to files that are not in use, at least in the initial stage. You can also do the development and testing at a time when there is less traffic.

Doing development and tests on a live site is not always advisable. In such cases or if you want to reduce the effect on your live site to a minimum, you should consider making a clone of the site. Cloning a site is not difficult. It just takes time. Many hosting packages will allow you to create subdomains from your main domain. Say your live site has a domain www.yourdomain.com. You can create a subdomain like test.yourdomain.com. You can then copy all the files from the live site to this subdomain site and do development and tests there.

If you cannot create your own subdomain, you can also create a subdirectory under the main domain. If the subdirectory is called test, then you can access the development site using the URL http://www.yourdomain.com/test. While the subdirectory site may look less professional than a subdomain site, the working is basically very similar. In both cases, you need to remember to change the site URL in the VirtueMart configuration.

Another important point you need to consider is future compatibility. If Joomla! or VirtueMart issues an upgrade, how will that affect your customizations? Joomla! upgrade usually does not affect your changes, unless it is a major version change (such as from version 1.5 to 1.6). If it does, most probably it will affect the whole VirtueMart community and you should be able to find some help from the VirtueMart forum. More often than not, VirtueMart development team will issue a new version to support any new Joomla! version that will impact VirtueMart. But of course, there will be a time lag between the issues of the two upgrades.

The concern regarding version upgrade is very different, if there is a new version for VirtueMart. If it is a major version change (say from 1.1 to 1.5) where no patch is available, your customizations will probably be severely affected. A complete revision will then be mandatory. If this is just a minor version change, VirtueMart will usually provide a patch for each of its previous versions. You can then compare the list of files in the patch and the list of files you have modified. You are safe if none of the files overlap. Otherwise, you will need to merge the lines of code by hand.

To reduce the impact of version upgrade, you should try to limit the number of file changes as much as possible. The smaller the number, the less probable you will be impacted by a version upgrade. Usually, VirtueMart does not upgrade template files. So if your changes are all in templates, your customization will less likely be affected by a version upgrade. You can also further decrease the impact by creating a new theme for your customizations.

We don't have much to say about implementation at this point. The principles of implementation is too big a subject to deal with in detail here. As we work on the exercises, we will mention some general principles here and there though. However, our emphasis will remain on the specific design detail instead of the general principles. The only thing we need to mention is making a comment. You should mark the area of modifications in the file clearly, making comments as appropriate. This will be useful later when you want to do further modifications or a version upgrade is needed. For large projects, you should make a log of all changes or even keep a bugtrack. Of course, each of these extra steps will cost additional time and money.

After the coding is complete, you can start testing and debugging. Testing and debugging is also a big subject in itself and cannot be covered in detail here. We will note by passing a few suggestions specifically for VirtueMart debugging.

First of all, you should have PHP error reporting turned on during development, if that is possible. For an operating site, many web hosts prefer to turn off error reporting. This is in fact a best practice for live sites to avoid exposing site detail when an error occurs. However, testing without error reporting will be difficult and more time consuming. So if possible, turn error reporting to maximum. There is a Joomla! configuration that is supposed to control this. However, if your PHP configuration does not allow such kind of configuration change, the Joomla! configuration may not work. You may need to have your web host help to turn it on or, if your hosting allows, modify the php.ini file to allow this.

You can turn on VirtueMart debugging in the backend configuration to show some basic debug data. The debug checkbox is on the Global tab, in the Core Settings section. A similar setting is also available in Joomla! Global Configuration. The debug data can sometimes help you determine what's wrong with the code, but not always. Even with all this information, often the error cannot be identified until you print out some critical variables. So be prepared to make lots of use of the print statement to help debugging. We will give some further guidance on this as we work on the exercises.

One useful feature of the VirtueMart debug information is the filename that is involved in the data logic of a browser page. When debug is turned on, VirtueMart will print out the filename of the PHP script that controls the processing logic. This will help to locate the file that you will need to modify in case that information is not easy to guess.

Going live does not need any explanation. You just upload your code to the live site and things should work. Otherwise, you may need to remove the code from the live site and go back to the development site for testing.