smartytemplate.php: Your theme's powerhouse
To step into more advanced aspects of the Drupal Theme system with a Smarty theme requires the creation of an additional file within your theme's directory.
(e.g. themes/blumarine_smarty/smartytemplate.php)
This file allows for
- Overriding Themable Functions see howto for phptemplate here: http://drupal.org/node/11811.
- Introduction of complex logic into your templates.
- Easily registering custom and existing functions for use within your templates.
- Defining additional variables for use within your templates.
An example for overriding an existing themable function follows:
(heavily borrowed from the phptemplate howto)
First, you need to locate the appropriate theme function to override. You can find a list of these in the API documentation. We will use theme_item_list() as an example.
If you want to override a theme function not included in the basic list (block, box, comment, node, page), you need to tell Smarty Theme Engine about it.
To do this, you need to create a smartytemplate.php file in your theme's directory. This file should contain the required
<?php
?>The function definition for theme_item_list() looks like this:
<?php
function theme_item_list($items = array(), $title = NULL, $type = 'ul') {
?>Now you need to place a stub in your theme's smartytemplate.php, like this:
<?php
/**
* Catch the theme_item_list function, and redirect through the template api
*/
function smarty_item_list($items = array(), $title = NULL, $type = 'ul') {
// Pass to Smarty Theme Engine, translating the parameters to an associative array. The element names are the names that the variables
// will be assigned within your template.
return _smarty_callback('item_list', array('items' => $items, 'title' => $title, 'type' => $type));
}
?>We replaced the word theme in the function name with phptemplate and used a call to _smarty_callback() to pass the parameters ($items, $title and $type) to the Smarty Theme Engine.
Alternatively, you can use the theme's name as opposed to 'smarty' in the function name (e.g., if the theme were bluemarine_smarty: bluemarine_smarty_item_list or smarty_item_list could both be used).
Now, you can create a item_list.tpl file in your theme's directory, which will be used to theme item lists. This function should follow the same logic as the original theme_item_list().
Sometimes it is not appopriate to hand off rendering to a template file. If the overridden theme function makes more sense being written in straight php then you can skip the invokation of smarty with the _smarty_callback() call and return output directly.