Gallery2:Themes:Reference:Smarty - Gallery Codex
Personal tools

Gallery2:Themes:Reference:Smarty

From Gallery Codex

Smarty

Smarty is a PHP templating system which is used by Gallery2 to assemble the pages that are presented to the user. Templates allow a great degree of customisation of Gallery2 by separating the design of its web pages from the code that is needed to make Gallery run. By using a special markup language alongside standard HTML, customised themes can be created which display the core Gallery items in different ways.

Documentation and Tutorials

Full documentation for the Smarty system is available on its web page at http://www.smarty.net. There is also a crash-course to Smarty on the site, and there are many Smarty tutorials available on the web by searching.

Using Smarty Templates

Smarty templates consist of a mix of HTML and Smarty markup language. This allows them to display dynamic content, for example if you wished to display a welcome message to a user on your Gallery page you could use the following code in your page template:

<p>Hello, <b>{$user.userName}</b></p>

To do the same as a plain HTML file would require a lot of effort in the PHP code that runs Gallery and would be a lot less customisable than using a separate template system. Working knowledge of the following Smarty concepts and tags would be useful for writing theme templates for Gallery2:

  • Writing Smarty templates using HTML and Smarty markup
  • Variable access using {$variableName} syntax
  • Conditional statements using {if}...{else}...{/if}
  • Array access using {foreach}...{/foreach}
  • Object access using {object->method}

Debugging Templates and Exploring Variables

If Gallery2 debugging is turned on, Smarty will produce debug output every time it renders a template. This output appears in a separate window and shows all of the variables used in the page, which can be invaluable in debugging a template when it doesn't work as expected. It is also a useful way to view all of the variables passed into the template by Gallery2, particularly if you need to access theme or user information.

To turn on Gallery2 debugging, you will need to edit the config.php file located in the root directory of your Gallery installation. There is an explanation of Gallery2's debugging modes followed by a statement:

$gallery->setDebug(false);

To turn debugging on, change this line so that it reads:

$gallery->setDebug('buffered');

Save config.php and copy it back to the Gallery root directory. When you now view any Gallery page, you will see the Gallery debug output at the bottom of the page, and the Smarty debug output should appear in a separate pop-up window. If it does not, make sure that popups are allowed for your Gallery site.

Making Data Available in a Template

Some items of information are made available to a template as standard by Gallery2. However, there are some items that have to be requested by your theme file before they will be accessible from the template. Typically this is done through the loadCommonTemplateData function call in the various showXXX functions in your theme.inc file. For a discussion of the options available, look at the source code for GalleryTheme.class which can be found in the Gallery's /modules/core/classes/' directory.