Development Wiki

Using the phpBB3.0 Template System

From phpBB Development Wiki

Revision as of 05:10, 17 April 2009 by Battye (Talk | contribs)

1.2. Using the phpBB3.0 Template System

This section focuses on the template system from a Modifications perspective. It contains both PHP code examples as well as corresponding template file markup examples.

phpBB3 uses a template system to separate the generation of (x)html from the program logic. The actual appearance is further delegated to stylesheets. MODs are required to follow that philosophy.

1.2.1. Template Files

The templates are stored in the styles\<style name>\template directory. The files should contain normal, clean markup plus template variables and control structures. Use the CSS classes for styling and avoid doing it inline. The extension of the template files is .html.

To load a template file, use the $template object's set_filenames method, which takes an array of handles pointing to template filenames. Use 'body' as handle, as it will be displayed automatically by page_footer; for custom handles you'll have to call $template->display manually.

	'body' => 'your_template_file.html')

1.2.2. Template Variables

The means of transporting data to the template is the use of template variables.. By convention, template variable names are always all-uppercase. Variables output to the user are enclosed in curly braces (e.g. {L_SOME_VARIABLE}) while variables in control structures are used directly.

The naming conventions for template variables are:

  • Template related variables are prefixed with "T_". These are usually pre-assigned by the phpBB3 core code
  • Variables to be used in control structures or for form actions etc. are prefixed with "S_".
  • Variables containing URls are prefixed with "U_".
  • Language variables for output are called "L_LANGUAGE_KEY". Where "LANGUAGE_KEY is an existing language entry's key. These are assigned automatically
  • Language variables for use in javascript are called "LA_LANGUAGE_KEY". Where "LANGUAGE_KEY is an existing language entry's key. These are assigned automatically
  • Values for display are not prefixed.

1.2.3. Assigning Template Variables

While language and template variables are automatically set, you will need to manually set other kinds of data you want to use in your template file. This is done by using the template object's assign_vars method.

Language variables are automatically assigned. You can use them by prefixing their name with 'L_'.
	'S_SOME_VARIABLE'		=> $some_variable,
	'NOW'				=> time(),

1.2.4. Control Structures

The template system supports a number of control statements, like loops and IF-THEN -ELSE. Those have been expanded vastly since phpBB2, so that they should be worth a look for everybody. Block Variables

While block variables were phpBB2's only way to have conditionals and loops in templates, they are now back as loops exclusively. Assigning Block Variables Using Block Variables Conditional Statements

IF -THEN-ELSE Logical Operators Including Other Templates

1.2.5. Pagination

1.2.6. Templates for MODs

MODs should come with prosilver and subsilver versions of the templates (final verdict pending). The prosilver versions are required to validate as XHTML 1.0 Strict , the subsilver versions as XHTML 1.0 Transitional. Try to follow the design of the original templates, for instance use tables in prosilver only for tabular data like the memberlist and not to design forms. Moreover, no MODs will be accepting using PHP in template files.

Using PHP in template files is not permitted for MODs; html should be rarely used in php files.