(from Style and Themes - to be updated)

How to modify .tpl files

About Smarty
The .tpl (template) files are written using the Smarty template language, which has its own syntax, etc. Smarty is mainly used for defining environment variables and the logic that follows (like who to show what when how). See smarty.net.

Modifying the .tpl files isn't recommended if the site's appearance can be changed using CSS alone; sometimes it is necessary, though, but be sure to be familiar with Smarty syntax and how Tiki uses Smarty files before going this route.

The Template Tree

Tiki's templates are called in a specific order within the code, so it's good to know what is a parent of what, particularly for the main few used for the basic layout of the site.

Templates (most frequently modified)

• tiki.tpl: the main template defining the layout, which calls:
  • header.tpl: the HTML head section (avoid modifying, if possible)
  • tiki-site_header.tpl: site Look & Feel options and/or menu
  • tiki-top_bar.tpl: possibly menu and search form
  • tiki-bot_bar.tpl: bottom banner links/credits bar

(Whether tiki-site_header.tpl or tiki-top_bar.tpl or both needs to be modified depends on what theme files are used as a starting point for a custom theme. New themes tend to use tiki-site_header.tpl for more Look & Feel components, and reserve tiki-top_bar.tpl for the menu (usually a CSS, or suckerfish, menu) and sometimes the search form.)

The new power of L&F custom code

In Tiki 4 and Tiki 5, a number of custom code text areas have been added on the Look and Feel admin page that may make it unnecessary to modify the relevant .tpl file, depending on what the desired customization is. This course should be considered first as it's easier to update the site to new Tiki versions when there are fewer file customizations.

Smarty template start/end tags

To put Smarty template beginning and end tags in comments in the final page source, as of Tiki 4 there is an option in Admin Features(tiki-admin.php?page=features), under the Developer tab, called "Smarty Template usage indicator". As indicated on that page, "Use only for development, not in production because these warnings are added to emails as well, and visible to the users." You can then check the final page source to see what code is produced by what Smarty template file.

Theme-Specific Templates

To modify the layout of Tiki in your theme, edit theme-specific copies of default Tiki template files. While CSS editing is used to specify the details of page appearance, it may be necessary to edit template files to make major rearrangements of items on the page. But an increasing amount of flexibility is being added to Tiki via admin configuration, which tends to make template editing unnecessary.

Overriding templates

Since Tiki13 and afterwards, Tiki themes are self-contained. For older versions, see link below.

The theme directories are stored in the themes directory, with the same name as the theme. For example, themes/custom_theme_name.

A theme's files will override any default template file. You just need to put a modified template file in the directory themes/custom_theme_name/templates/.

For example, if we want to modify the forum listing in our screensite theme, we'd just place a copy of the file templates/tiki-forums.tpl in themes/screensite/templates/ and then edit the new theme-specific copy of the tiki-forums.tpl file.

Tiki will substitute whatever is in your custom theme directory for the .tpl files in the default directory.

This technique works on files in the subdirectories, too. That is, to change the application menu in your theme, just copy the file mod-application_menu.tpl from templates/modules/ to themes/custom_theme_name/templates/modules/.

This technique works for theme options as well. That is, if you want to modify the forum listing only for the option my_custom_option of theme custom_theme_name, just copy the file templates/tiki-forums.tpl in themes/custom_theme_name/options/templates/. Theme options custom templates take precedence over theme custom templates and over default templates.

It's recommended that as few template files be customized as possible, and the customizations kept as minimal as possible, in order to keep the maintenance and updating of the files easier. The more extensive the customization, the harder to keep in sync with the functionality of Tiki as it advances.