This tutorial will walk you through all the steps necessary to customize system or module template file(s), without touching the base files in the default template set.

<tip c w>Warning: This is an advanced tutorial, involving making changes to template files.

Before attempting to make changes as described here, be sure you have a firm grasp of the basics.

Module and System templates, by their very nature, are very dynamic and closely related with their PHP file counterparts. Because of this there are certain risks involved with customizing such template files, as listed below.

Risks of Customizing System, Module, or Addon Templates:

• May require compatibility changes when updating the software. Such changes are the responsibility of the site owner and are not covered by the software update service provided by Geodesic Solutions. See Geo Updates & Customized Templates for more info, and be sure to read those sections BEFORE a problem occurs, as they have some pre-update steps that will help the transition. <
• Problems caused by customizations are not covered by Geo support, if support finds that something works with the "default" templates but not with customized templates, they will not be able to help further. Geo Support can try to help you with the how and where for editing templates, but they cannot make changes for you or try to troubleshoot problems related to customized templates. <

</tip>

Skills

• Basic understanding of how HTML, Smarty Templates, and/or PHP works will help. <
• Not afraid to learn new things. <

Handy tools when editing template files:

• Smarty Documentation <

Note that by module template, we mean any template used by a built in Geo module, one that is working "behind the scenes", one that is in the module/ sub-folder in a template set. A system template is one that is used by some overall system-level process, or used to display the dynamic part of the {body_html}, one that is in the system/ sub-folder in a template set.

Use the following instructions to modify 1 (or more) module or system templates. For the purposes of this tutorial, we will demonstrate how to modify system/cart/display_cart/index.tpl which is the template responsible for displaying the main cart view¹⁾ in Geo 5.0.

This tutorial assumes you already have your own template set created, and named my_templates²⁾. If you do not have a template set yet, be sure to create one using the tools available to do so in the admin panel, never edit files in the default template set.

1. In your Geo admin, and in this user manual, check to see if what you are attempting to accomplish can already be done by changing settings in the admin. You might find that you can already do what you are needing by making a setting change, which is always the better option over editing a system or module template file, as it makes updates much more easy. <
2. In the admin panel, go to the page Design > Template Sets. <
3. In the top right corner of the page, make sure you are in Advanced Mode. If you are not, click the button to Switch to Advanced Mode. <
4. On the page, make sure the settings are set as follows:
   • Next to my_templates - checkbox for admin editing is checked. <
   • Next to default - checkbox for admin editing is checked.³⁾ <
   • In Advanced Settings, check the box next to the setting Allow Edit of system, module, and addon Templates. <

<

1. Save the changes. <
2. In the admin, go to the page Design > Manager. <
3. In the manager, browse to the sub-folder within the default template set, that contains the file you wish to customize. For example: default/system/cart/display_cart/. You should be in the default template set, viewing the folder that contains the template file you wish to modify. <
4. Check the box next to the file(s) you wish to modify so that it is selected. For example: index.tpl. <
5. On the bottom of the manager window, click the link to copy the file. After you click it, the file(s) that were selected should appear in the File Clipboard below the manager, make sure that it lists the correct template file(s). <
6. On the left side of the manager, click on the Jump To link to go to the Base Folder. <
7. In the manager, click on the my_templates folder so that you are viewing the files within that template set. <
8. On the bottom of the manager, click the link to paste the file(s). Note that when copying/pasting any system, module, or addon files, all you need to do it browse into the template set you wish to copy them to, as it will automatically duplicate the "parent folder structure" for you. This is different than how main_page or external file copy/paste works, which will paste to the current folder you are viewing. <
9. Repeat the copy for any other templates you may want to customize, for instance if you also planned to modify the item.tpl file. Note that you should not copy a file unless you plan to customize it. You do not need to worry if the file you are customizing includes another template file, if you do not copy that template file, when it is included the system will automatically look for the file in the default template set if it is not found in my_templates.

<tip c w>Warning: Only copy files you are going to customize. With every file you copy over, when you next update the Geo software, there is a chance that template file may have changed to work differently, so the fewer files that are copied over, the less chance something might break and need adjustment after an update.

Also, be sure to keep the part at the top of the file that looks like {* $Rev: 12345$ *} - when you update you will be able to compare this "revision number" to the one in the default template set, to see if changes have been made in the new Geo version.</tip> <

1. Make changes to the file(s) in geo_templates/my_templates/, with the setting checked to allow editing system, module, and addon templates from the admin panel, you will be able to edit the templates in the admin panel or you can edit them directly using FTP, it is you choice. Just be sure, Do not change files in geo_templates/default/, as they will be over-written during an update. Also the templates in the default template set are fair game to be over-written by Geo support for troubleshooting purposes. <

When you update the Geo software, there is a chance a template you have customized may have changed, to add some new feature, to fix something, or perhaps just to change how it works to make it easier to understand. The result of such changes could be totally unnoticeable (such as some new feature may not be displayed), or it could cause the template to no longer work as intended.

<tip c n>Note: The update tips here only apply for system/, addon/, or module/ template customizations.</tip>

Since module and system templates are closely tied to their PHP file counterparts, it is likely that at some point, if you have customized a module or system template, you will need to make changes to it when you update the Geo software. Below are a few tips to help you with this task.

• At the top of each smarty template file should be something that looks like this:⁴⁾

{* $Rev: 12345$ *} When you customize a template, be sure you leave that top part intact in your custom template, and the same as the template from the default template set. <

• Make a copy of the default template set without any modifications, and keep it handy on your local computer. This will come in handy to compare a new template to the original one in your current version to see what has changed. <

In our user manual, in the New Release Info Section, for every release starting with version 5.0.0 we will list all of the template files that have changes in them for that release. View the forum post for every release between your current version and the version you are updating to, and make a note of every template file changed that you have made customizations to.

If you are updating from a version prior to 4.1.3, or if the number of updates between your current version and the latest makes it difficult to find all the template files that have changed, you can instead use this method to determine what templates might need changing: When you update, for every custom template you have, compare the Rev number at the top, to the one at the top of the corresponding template in the default template set. If the numbers are the same, you can breath a sigh of relief, as nothing has changed in that template in the new Geo version. If they are different numbers however, you know that something has changed in that template file, so there is a chance you may need to make changes to your customized template to account for it. If that is the case, see After update: Fixing Changed Templates

These are a few tips on what to do for when template files have been changed on the new release, the ones you found by following instructions in the Check for Template Changes section above.

For the "Easy" Changes:

Your main resource for seeing what needs to be changed, is the System & Module Template Changes (Moved) page in this wiki. In most cases you will be able to reference that page to see exactly what you need to change to bring your custom templates up to date.

If that is not the case however, keep reading as you may need to do some more complex things to bring your templates to be compatible with a newer version.

Manual Template Checking/Adjusting:

Compare the template from the new default template set in the new Geo version, to the copy of the default template set you made from the original Geo version. (you did make a copy before updating, right?) If it is a long file, you might need to use software that is designed to compare differences between files, commonly called a "diff" program. There are a lot of good diff programs out there, some can even show you a line by line comparison, and even highlight what has changed on each line for you. If you do not already have something that does file comparisons, you should be able to find such software online, just look for "diff software" in your favorite search engine or software download site.

Once you figure out what has changed between the old and new version of the template:

Editing Smarty templates is a lot better solution than having to edit PHP files, as there is less of a chance that there will be a change to a template file. But the chance is still there. When you update the Geo software, be prepared to run into a situation as outlined in the "non-trivial changes" above.

• Design > Template Sets - Help for the template sets page in the admin <