How a template set is chosen

The template system uses a Cascading Template Set¹⁾ model. When the system is looking for a template to load, it looks through all of the active template sets, in the order the template sets appear in the admin. You can change that order by clicking on the up and down buttons in the Template Seek Order column. This allows you to use a collection of "partial" template sets.

For a scenario where this might be useful: Say you have a partial template set that might contain "seasonal" alterations to images and the main CSS file. No changes to your main templates are needed, it's mainly to change the look of it. During the season, you would activate the template set, and move it to be at the top of the template seek order. Now when the system is looking up the location for any of the images or the CSS file, it would find the files in the seasonal template set, and use those instead of your main ones. For the files it does not find in the seasonal template set (like all the main templates) it would find them further down in another template set that is lower in the "template seek order". Once that season is over, to go back to using the normal images and CSS file, just de-activate the seasonal template set. It can be a little confusing at first, but once you get a hang of how it works it gives you a lot of control and power to do a lot of things you would not be able to do as easily with a traditional template system.

For a more technical illustration of how a particular template from a particular template set is loaded, read on.

For the purposes of this explanation, we'll assume the following file structure exists inside geo_templates/ :

Contents of geo_templates/:

• blufyre_startrek/ [(made-up) Template set distributed by a 3rd party]
  • main_page/
    • [Full "main body" template set, with it's own template to page attachments and everything]
  • text.csv [Text import file with recommended text changes]
• customized_search/ [We made a separate template set for 1 template file, to make troubleshooting that one file much easier]
  • system/
    • search_class/
      • details_form.tpl [Customized search form template]
• default/
  • addon/ (contains various addon templates)
  • external/
    • [Contains un-altered media files (images,css,js) that are used in templates]
  • main_page/
    • [Contains ALL overall templates and sub-templates, un-altered]
  • module/
    • [Contains ALL module templates, un-altered]
  • system/
    • [Contains ALL system templates, un-altered]
• my_templates/ [Template set containing misc. templates that are modified]]
  • module/
    • module_zip_filter_1.tpl [Modified zip filter module template]
• t_sets.php [File generated by template system, that stores which template sets to use and in what order to search through them]

Now, lets assume in the admin, the list of Active template sets is in the exact order listed below:

• blufyre_startrek
• my_templates
• customized_search
• default ²⁾

When the software is getting a template to use, this is the steps it follows when using the above setup:

• The system needs to load the template system/cart/display_cart/index.tpl to display the {body_html} for the main cart page.
  1. Looks for file:
     geo_templates/blufyre_startrek/system/cart/display_cart/index.tpl
     File does not exist, so it continues searching.
  2. Looks for file:
     geo_templates/my_templates/system/cart/display_cart/index.tpl
     File does not exist, so it continues searching.
  3. Looks for file:
     geo_templates/customized_search/system/cart/display_cart/index.tpl
     File does not exist, so it continues searching.
  4. Looks for file:
     geo_templates/default/system/cart/display_cart/index.tpl
     File Found!
  5. If Cache is turned on, the system saves the location that it found the file, so that next time it knows to go straight to the geo_templates/default/ directory to find it without having to look through all the other template sets first.
• This time, we're on the search page, and system is looking for the template system/search_class/details_form.tpl
  1. Searches through the template sets like last time. This time it stops on the file found in customized_search/ template set. Even though the file existed in default, since customized search was higher on the list, the template from that template set was chosen.