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

Before attempting to follow the tips or instructions here, be sure you have a firm grasp of the basics.

Remember that 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>

One of the main features of the template set system, is the "portability" of a template set. What this means, is that a template set can easily be transfered to a different installation, on a totally different domain name, with minimal work. However, this requires the template set is created with portability in mind. Having a portable template set is a must for any designer wishing to distribute custom template sets created. It is also a good idea for site owners as well, as it makes it easy to work on a design on a "test installation" then easily transfer the design to the live site once it is ready. It may even be necessary for parts that are shared between the client side and the admin panel, such as buttons used in the cart.

Below are some helpful Dos and Don'ts to follow while you are in the process of customizing your template design, or even creating a new template set from scratch. If you are already finished creating a custom template set, but it is not "portable", see the instructions in the next section.

• Do always put any media files¹⁾ used for the design, into the external folder within your template set. <
• Do Not put media files in the main_page folder within the template set. This folder is reserved for .tpl template files only. <
• Do Not put media files outside of your template set. (See the first "DO" tip above) <
• Do, within template files, use the special Smarty tag that looks like {external file='folder/filename.png'} in place of a URL for a media file located in the external/ folder in your template set. The "Add a Tag" tool on the template editor can create the tag for you, you just select the external file you want to reference and it will insert the tag for you. The default templates have plenty of examples of how to use this as well.
  • Good:

    <a href="index.php"><img src="{external file='images/logo.jpg'}" alt="My Site!" /></a>

    <

  • Bad:

    <a href="index.php"><img src="geo_templates/my_templates/external/images/logo.jpg" alt="My Site!" /></a>

    <

  • Even Worse:²⁾

    <a href="index.php"><img src="images/logo.jpg" alt="My Site!" /></a>

    <

<

• Do, within CSS files, use the relative URL, relative to the CSS file, for any URL to other media files. For example, if referencing an image file located in geo_templates/my_templates/external/images/bg.jpg you might use the following in your CSS file located at geo_templates/my_templates/external/css/main.css:

  div.main {
  background-image : url('../images/bg.jpg');
  }

  Note: This is a made-up example only. <

• Do Not use the absolute URL for media files. See tips above for what you should use instead. <
• Do Not, in links, use absolute URL for any link to a page on your own site. In other words, don't use an absolute URL for a link when it is possible to use a relative URL instead.
• More tips to come! If you think of any useful tips not covered here, let us know! ³⁾ <

If you already have a customized template set, but it is not transferring to another site easily so you need help making your template set more portable, below are some general instructions to help you get there.

<tip c n>Note: These instructions are general guidelines only, additional steps may be required for unique scenarios that might be specific to how something is being accomplished in a custom template set.</tip>

1. In the admin panel on the site with the custom template set (which we will refer to as "Live Site" in the rest of these instructions), go to Design > Template Sets and use the Download button to download the template set. <
2. In the admin panel on a test installation (which we will refer to as "Test Site" in the rest of these instructions), go to Design > Template Sets and use the Upload Template Set tool to upload the template set you just downloaded from Live Site.<tip c n>Note: If you don't have a test installation, you will need to set one up before you can continue. With your license you can have one "live" installation, and one "test" installation that is only used for testing purposes like we are doing in this tutorial. Install the software in a different folder as your live installation, and use a different database. Ideally it is best to be located on a different server as well⁴⁾, but that is not required. If your test installation is on a different server, it must be using a URL that is "obvious" it is a test installation, and not used for live listings, for instance installed in sub-folder "testing" or similar, or using a sub domain like testing.example.com.

Once you have a second test installation set up, and you are to the stage of entering your license key, contact [email protected] to have the test installation location added to your existing license.</tip> <

1. On your Test Site, in the admin panel, make sure the template set uploaded is the only "active" template set (besides the default template set), then view the front side of the Test Site.
2. Browse to different pages on the front side, if possible. Depending on just how "non-portable" the template set is, you may not even be able to browse the site at all. Or everything may look perfect. If that is the case, you may not need to do anything further! If things don't look perfect however, keep reading. <
3. Figure out anything that is missing from your Test Site, things like images, CSS files, JS files, etc.<tip c n>Tip: If you need help finding all the "missing files" that your custom design is referencing, we recommend using Firefox with the Firebug Plugin installed. Enable the plugin, then view the "Net" tab within the Firebug console. It will list every file that was used to display the current page you are viewing, and tell you any files it could not find. What you are looking for is those files that are not found, with status of "404 Not Found".</tip> <
4. For all the missing files, get them⁵⁾ from your Live Site, and upload them to your Test Site but inside the external/ folder in your template set. For instance, if you originally had some images located in images/ folder on the Live Site, upload those images inside geo_templates/my_templates/external/images/⁶⁾ on the Test Site. You can upload them with FTP or using the admin panel at Design > Manager, we recommend the latter to make sure they are uploaded to the correct location. <
5. For each file you uploaded to the external/ sub-folder in your template set:
   1. On Test Site, in admin go to Design > Text Search. Do a search for the filename, then click on the search results tab for Template Contents. <
   2. Look for the first found match for any template file, that references the file "directly" instead of by using the external Smarty tag. In other words, you are looking for first one where the match is not preceded by something like {external file=. Click the button to edit that template. <
   3. On the edit page, click on the <..> Source Code Editor tab if it is not already on that tab.
   4. In the template source code that is displayed in the editor, find where the file you searched for is being used, you will be replacing it with an "external" smarty tag. To do this, highlight the entire URL for the file, and above the editor window, click on the blue tag icon to bring up the Insert a Tag tool. Within the tool, click the external tab. Then in the Select File drop-down, find the file you are replacing, and select it. Then click Insert External Tag button, and close the tool. Ensure that the URL got replaced by the external tag properly, then save the contents of the template file. <
   5. Repeat these steps until all "direct references" to the file are replaced by external smarty tags. <

<

1. Keep doing that, until you have removed all direct references to images or CSS files, and replaced them with "external" Smarty tag. <
2. In your CSS files, update any URL references (for instance, for image backgrounds) to point to the image relatively. In some cases you may not even need to make changes, if already referencing relatively and the location of images is the same relative to the CSS file (difference is that now it is in the external/ sub-folder in your template set). <
3. Check for any more parts of your design that are still not self-contained in your custom template set, and fix them to be located in the template set. <