Templating Manual

POPFile 0.22 introduces a Templating system that has moved all the UI HTML out of the Perl code. This allows those who don't know Perl to make major changes to the UI. Templates are only part of the POPFile skinning system, skins must also have a CSS file. Together they make up the skins a user can select from the POPFile Configuration page.

The Default skin contains the base template files that all other skins use. Each page of the UI is broken down into pieces to allow easier modification and handle common page elements in one place rather than seperatly each time they appear on a page. All skins use the default template files unless they provide their own in their individual directory. So if you want to change only a part of the UI you only need to copy the one appropriate template file to your skin directory and modify it.

For an example of how Templates can be used see the skin OceanBlue in POPFile's skins directory.

Example Page Layout

To better understand how this works we will look at how the template files make up the final history page:

history-page.thtml
   common-top.thtml
   common-middle.thtml
history-page.thtml
   history-navigator-widget.thtml
history-page.thtml
   history-search-filter-widget.thtml
history-page.thtml
   history-navigator-widget.thtml
   common-bottom.thtml

The first file looked at by POPFile in building the page is the one for the specific page you are on, in this example history-page.thtml. That page defines what other templates to use.

All pages include the common-*.thtml files. The common-top template contains only the doctype, html, and head tags. The middle contains the shell<> or tables for the main body area of the UI.

The page specific stuff goes after the middle so we continue with history-page again. From there we include history-navigator-widget and a little while later history-search-filter-widget. Then towards the end we include history-navigator-widget again. And then common-bottom closes the shell table adds the footer and closes the body and html tags.

Template Tags

The templating system uses tags similar to HTML to insert other pieces of code or text through includes or variables into the finished page. It also uses these tags for loops and condition statements to repeat certain parts of the HTML code or to skip parts of the code when its not needed.

The tags are all of the form <TMPL_*> and other than the variable or file names they specify are in all capital letters so they are easily distinquished from the actual HTML.

Template Variables Conditions and Loops

These look a bit confusing and messy to begin with, but after working with them for a while you will get used to them. They allow us to build the non-static parts of the UI pages. To better understand them lets look at an example:

<table>
  <TMPL_LOOP NAME="Loop_1">
 
  <TMPL_IF NAME="row_odd">
  <tr bgcolor="red">
  <TMPL_ELSE>
  <tr bgcolor="blue">
  </TMPL_IF>
 
    <td>
      <TMPL_VAR NAME="title">
    </td>
    <td>
      <TMPL_VAR NAME="value">
    </td>
  </tr>
  <TMPL_LOOP>
</table>

This example will print a table with a variable number of rows. The number of rows is specified by the Perl code that loads this template. To achieve the variable number of rows, the TMPL_LOOP template tag is used. Each time through the loop, a new row is added in the output. In other words, the code inside the TMPL_LOOP tag is added as often as specified in the Perl code.

The TMPL_IF and TMPL_ELSE tags are used here to give odd and even rows different backgrond colors. The Perl code needs to specify whether the template variable “row_odd” is true or not, and the template will use the correct html code accordingly and give the row either a red or a blue background.

Finally, the values for the table cells are inserted using the TMPL_VAR tag. Again, these are determined by the Perl code.

The Template Module

POPFile does not handle these templates all on its own. When possible its often better to use an existing Perl module than build a custom one. In this case there were a few different choices for templating and HTML::Template was chosen. Much more documentation on the module is available at their site: http://html-template.sourceforge.net/html_template.html

 
devel/template.txt · Last modified: 2008/02/09 19:04 by manni

Should you find anything in the documentation that is incomplete, unclear, outdated or just plain wrong, please let us know and leave a note in the Documentation Forum.

Recent changes RSS feed Donate Driven by DokuWiki
The content of this wiki is protected by the GNU Fee Documentation License