If you want to customize your site by editing *.tpl files, there are some things to consider. If files are edited directly, changes may be lost in future upgrades (extracting a new version can overwrite the modified files). Here are some options:
- Use a local tpl: create a directory called local in the same location as the tpl to edit. Copy the original tpl into the local directory and edit the copy. Note(1): This technique also works for files referenced by direct URL, such as js and css files. Note(2): When editing the .tpl be mindful of the syntax. For example do not add double quotes - "example" - within the code if they're also used to to start and end the line.
cd modules/slideshow/templates
mkdir local
cp Slideshow.tpl local
results in: modules/slideshow/templates/local/Slideshow.tpl
cd themes/matrix/templates
mkdir local
cp theme.tpl local
results in: themes/matrix/templates/local/theme.tpl
- Use a theme override: starting in Gallery 2.3, themes are able to override module tpl files. Example:
Let's say you want to change the bar.tpl file in the foo module.
modules/foo/templates/bar.tpl
First look in modules/foo/module.inc and find the line that sets the template version:
$this->_templateVersion = # or $this->setTemplateVersion(#)
Copy bar.tpl to themes/mytheme/templates/foo_#/bar.tpl and edit the copy. Only pages using mytheme will use this file. If you upgrade to a new version of foo module that has changed the structure of its templates such that your version may be incompatible, then it will include a new template version number. Gallery will then use the tpl from the module instead of the theme override. You can make a foo_# directory for the new template version and recreate the local changes. The advantage here is upon upgrade the module reverts to the default look, but it should work. An incompatible local tpl could cause errors on your site.
An example using block templates: To override a block template
modules/foo/templates/blocks/SomeBlock.tpl
You need to copy the file to themes/mytheme/templates/foo_3/blocks/SomeBlock.tpl (assuming the template version of module foo is 3)
- Note for subversion users: When using svn it is actually better to edit tpl files directly. Then you can use svn diff to see the changes, svn revert to get back the original file, and svn update will attempt to automatically merge local changes with new versions, or will report conflicts when unable to do so.
What if I don't see my changes
- Visit Site Admin / Maintenance and run the task to delete the template cache. This can also be done in the Cache Maintenance section of lib/support/index.php. When in doubt, it is always good to try clearing the cache. Note that due to how file timestamps are checked, it is always necessary to clear the cache when removing a local tpl or theme override and return to the original tpl.
- Starting in Gallery 2.3 compiled templates are cached such that file edits or the addition or local tpls or theme overrides are not seen. Visit Site Admin / Performance to turn off this caching while working on customizing your site or building a theme. Turn it back on when finished working on the tpl files to get the performance benefit.
- Template caching cannot be disabled via the administrative interface in version 2.2. Developers who are creating a new theme may find that manually deleting the cache is too cumbersome. A minor change the the Smarty class can force the templates to stop being cached. On line 150 of lib/smarty/Smarty.class.php:
var $force_compile = false;
Change this line to:
var $force_compile = true;
CSS images don't show
When you move the css to a local folder you have to do one of 2 things as well:
1. copy images it references to a local directory as well eg:
gallery2/themes/matrix/local/images/nav_last.gif
2. Edit the css to pint the images to the proper location.
Related information
