XTemplate for programmers

Those familiar with building or modifying Cotonti templates will have seen and used template tags. Tags are short bits of code which, when parsed by XTemplate, are replaced by a block of HTML code. This ensures your template file exists only of HTML code. Any PHP generated code is handled by the plugin and parsed using a tag.

When developing a plugin, it’s important to know how to define tags and conditional blocks with the XTemplate system. Before, most plugins used the legacy way of getting HTML to be parsed and displayed. Although using XTemplate and your own template file is a much nicer way to build your plugin, you can still use the classic way for standalone plugins. You do this by using the variables $plugin_title, $plugin_subtitle and $plugin_body. These are assigned automatically to the tags {PLUGIN_TITLE}, {PLUGIN_SUBTITLE} and {PLUGIN_BODY}. In this case, you don’t need to create your own template file (and you can omit the tpl directory). Cotonti will use the skin’s plugin.tpl instead.

So you want to use your own template file. You start by defining the template file as a new XTemplate object. That’s right, the XTemplate system is an object oriented piece of code. Once you’ve created a new XTemplate object, you can use a collection of methods (functions) supplied by the XTemplate class. We will be using just two of them: assign() and parse(). First we create a new XTemplate object:

$t = new XTemplate(‘path/to/file.tpl’);

We are using $t as the XTemplate object variable name, but you can use any variable name you like. The ‘path/to/file.tpl’ is the path to the template file, from the Cotonti root folder. While this would work perfectly fine, it’s not a very flexible way to define the template file. Therefore we will use the cot_tplfile() function instead, like this:

$t = new XTemplate(cot_tplfile('pluginname', 'plug'));

The first parameter is the filename without extension. The second parameter must be set to'plug', since we’re dealing with a plugin. Other possible values are 'module' and 'core'. The cot_tplfile() function will look up the correct path to the template file. The filename must always start with the pluginname. If you want to use multiple template files, you should use filenames like this: pluginname.secondary.tpl. Remember to omit the extension when using cot_tplfile().

The next step is to assign some tags to your template file. We do this by using the assign() method on our XTemplate object:

$t->assign();

The assign() method can take single tags or an array of tags:

$t->assign('SINGLE_TAG', '<p>Piece of HTML</p>');
$t->assign(array(
	'TAG_ONE' => '<p>Piece of HTML</p>', 
	'TAG_TWO' => $somevariable
));

As you can see, it’s very simple to assign a bunch of tags with PHP generated content. While it’s a good way to implement the MVC design pattern, it’s still not very flexible. What if you want to display multiple rows of content from your database? XTemplate uses HTML comments and the parse() method to allow this. Lets say you just executed an sql query to get all pages. Likely you’ll be using a while loop to go through the rows. Consider this code:

while($row = $sql->fetch())
{
	$t->assign(array(
		'PAGE_ROW_ID' => $row['page_id'],
		'PAGE_ROW_TITLE' => $row['page_title']
	));
}

This would redefine the tags every time we go through the while loop, and result in the tag to be set to the last row’s value. To prevent this, we need to force parsing the tags directly after defining them. This is achieved with the parse() method.

$t->parse();

The parse() method takes one parameter: the block code. The block code is a unique code that is placed inside the template file as an HTML comment. It always has a BEGIN and END, like this:

<!-- BEGIN: BLOCK_CODE -->
...
<!-- END: BLOCK_CODE -->

You may have noticed that every Cotonti template file starts and ends with such a tag, effectively defining the entire document as a block. Usually this is the MAIN block, but you can use another if you really want to.

In the plugin PHP code, we will now add the parse() method to the while loop:

while($row = $sql->fetch())
{
	$t->assign(array(
		'PAGE_ROW_ID' => $row['page_id'],
		'PAGE_ROW_TITLE' => $row['page_title']
	));
	$t->parse('MAIN.PAGE_ROW');
}

The block we've just defined is named ‘PAGE_ROW’, but because it is to be used within the MAIN block, we prepend the block name with the parent block name and a dot to separate them. Our template file could now look like this:

<!-- BEGIN: MAIN -->
	<h1>{SINGLE_TAG}</h1>

	<!-- BEGIN: PAGE_ROW -->
	<p>{PAGE_ROW_TITLE}</p>
	<!-- END: PAGE_ROW -->
<!-- END: MAIN -->

If you don’t want or can’t use the MAIN block, you can replace it with another code. However, this will require you to do one more parse at the end of the plugin code. The MAIN block is automatically parsed by Cotonti, but any other blocks will need to be parsed manually by your plugin. Simply call the parse method again, and finally output the block (for standalone):

$t->parse('ALTERNATIVE');
$t->out('ALTERNATIVE'); // Only for standalone

It’s best to do this right before the PHP ending tag.