Variables

Perhaps you recall that word I mentioned earlier: variable, it may seem like a complex concept but it really isn't. There are variables in basic algebra which we all learn in school. When programming, an expression such as x = 4 will assign the value 4 to the variable x. Variables in phpBB templates work exactly the same way, they represent a value: for example an integer (whole number) or a string (fragment of text).

When you code a template you use HTML combined with variables, or placeholders for variables. Variables can be recognized by the braces that surround them, an example from index_body.tpl:

{L_LOGIN_LOGOUT}

Which, for those who have chosen English as forum language, is replaced by "Log in" or "Log out" (depending on whether the user is logged out or logged in).

Blocks

Apart from variable placeholders there is also something called a block. A block is a part of your code, marked with certain block code, that is generated iteratively, in other words repeated for a set number of times. This may seem abstract at first but let me show you an example from index_body.tpl:

<table width="100%" cellpadding="2" cellspacing="1" border="0" class="forumline">
  <tr> 
	<th colspan="2" class="thCornerL" height="25" nowrap="nowrap"> {L_FORUM} </th>
	<th width="50" class="thTop" nowrap="nowrap"> {L_TOPICS} </th>
	<th width="50" class="thTop" nowrap="nowrap"> {L_POSTS} </th>
	<th class="thCornerR" nowrap="nowrap"> {L_LASTPOST} </th>
  </tr>
  <!-- BEGIN catrow -->
  <tr> 
	<td class="catLeft" colspan="2" height="28"><span class="cattitle"><a href="{catrow.U_VIEWCAT}" class="cattitle">{catrow.CAT_DESC}</a></span></td>
	<td class="rowpic" colspan="3" align="right"> </td>
  </tr>
  <!-- BEGIN forumrow -->
  <tr>
	<td class="row1" align="center" valign="middle" height="50"><img src="{catrow.forumrow.FORUM_FOLDER_IMG}" width="46" height="25" alt="{catrow.forumrow.L_FORUM_FOLDER_ALT}" title="{catrow.forumrow.L_FORUM_FOLDER_ALT}" /></td>
	<td class="row1" width="100%" height="50"><span class="forumlink"> <a href="{catrow.forumrow.U_VIEWFORUM}" class="forumlink">{catrow.forumrow.FORUM_NAME}</a><br />
	  </span> <span class="genmed">{catrow.forumrow.FORUM_DESC}<br />
	  </span><span class="gensmall">{catrow.forumrow.L_MODERATOR} {catrow.forumrow.MODERATORS}</span></td>
	<td class="row2" align="center" valign="middle" height="50"><span class="gensmall">{catrow.forumrow.TOPICS}</span></td>
	<td class="row2" align="center" valign="middle" height="50"><span class="gensmall">{catrow.forumrow.POSTS}</span></td>
	<td class="row2" align="center" valign="middle" height="50" nowrap="nowrap"> <span class="gensmall">{catrow.forumrow.LAST_POST}</span></td>
  </tr>
  <!-- END forumrow -->
  <!-- END catrow -->
</table>

The TR and TH tags make up the header for the table of categories and forums, i.e. the captions that say Forum, Topics�, Posts and Last Post�. Directly below is a block marker, it says that the code between it and its END counterpart makes up a block. As you see, this block contains the code for creating the categories on the forum index. This code will be repeated, with the variable placeholders replaced by the category address/url for its link ({catrow.U_VIEWCAT}) and its name ({catrow.CAT_DESC}).

Within the category block is the forum block, so for every category, this block will be repeated as well, generating the list of forums, building and populating the table with forum names, descriptions, number of topics, posts, information about the last post and a list of moderators to mention a few.

Switches

The third typ of template markup is the switch, it is a conditional control structure, as a programmer would explain it. A switch consists of a pair of markers, BEGIN and END with a condition. The condition might be that the user that requested the current page (that is the user clicked a link that led to it) is not logged in. You can see such an example here below taken from index_body.tpl where a switch is used to hide the log in box if the user is already logged in, or in other words, only show the log in box if the user is logged out:

<!-- BEGIN switch_user_logged_out -->
<form method="post" action="{S_LOGIN_ACTION}">
  <table width="100%" cellpadding="3" cellspacing="1" border="0" class="forumline">
	<tr> 
	  <td class="catHead" height="28"><a name="login"></a><span class="cattitle">{L_LOGIN_LOGOUT}</span></td>
	</tr>
	<tr> 
	  <td class="row1" align="center" valign="middle" height="28"><span class="gensmall">{L_USERNAME}: 
		<input class="post" type="text" name="username" size="10" />
		   {L_PASSWORD}: 
		<input class="post" type="password" name="password" size="10" maxlength="32" />
		<!-- BEGIN switch_allow_autologin -->
		     {L_AUTO_LOGIN} 
		<input class="text" type="checkbox" name="autologin" />
		<!-- END switch_allow_autologin -->
		    
		<input type="submit" class="mainoption" name="login" value="{L_LOGIN}" />
		</span> </td>
	</tr>
  </table>
</form>
<!-- END switch_user_logged_out -->

In summary

Customizing your forum template is essentially about editing the HTML and putting the block markers, switches and variable placeholders where you need them.

A few words of advice, due to the way the phpBB template engine (also called parser) is designed, there are a few restrictions:

• Block markers must be on separate lines, this is generally true however there are a some exceptions
• Block markers and switches must be closed (END) in the same order they were opened (BEGIN)
• Block markers, switches and variable place holders must be typed (or preferably copied) exactly as you see them, letter case and all

If any one of these criteria isn't met the parsing of the page will fail and you will get an error message. It will most likely refer to template.php and mention eval()'d. You can read more about it here:
http://www.phpbb.com/kb/article/parse-error-evald-code/

Every tpl file has access to different variable placeholders, you can find a list of variable placeholders organized by what tpl file they are available for here:
http://www.jakob-persson.com/node/541

I believe you have your work cut out for you know, going through every TPL file and design it to your liking. Remember to keep backup copies of your files in case something goes wrong so you can revert back to a previous version. Should you run into problems you're welcome to request help here at my forums.

In part four of this guide I will cover some common questions and problems when designing phpBB templates, talk some more about themes and what you can do with them and how you do to export your template so that you can distribute it for others to use and enjoy as well as write about a thing or two I've learnt when designing for phpBB. So keep reading and designing!