Templates

Every template is an instance of the Template class defined in include/utils.php. Rack templates are parsed and executed as PHP and therefore can execute arbitrary PHP code. However, it is advised to keep it simple in order to maintain separation between rendering and internal logic. This page covers the documentation of functionality that is specific to templates.

WARNING! No data is escaped by default. Always explicitly escape your template variables and be careful which data you access in templates.

Template variables (context)

Templates are intitialized with a context object, which is an associative array. The individual elements of this array are made available in the templates as regular variables (see extract). Consider the context

$context = [
  'title' => 'Home',
  'page_id' => 'index'
];

and the template

<html>
  <head>
    <title><?= $title ?></title>
  </head>
  <body>
     <h1><?= $title ?></h1>
     page_id: <?= $page_id ?>
  </body>
</html>

which renders as

Home

page_id: index

Template functions

All global functions are available in templates. The template class provides the following additional functions for escaping data to prevent XSS attacks.

html($data) Escapes data to be used as (part of) an HTML element's content.
attr($data) Escapes data to be used as (part of) an HTML element's attributes.
format_plain_text($text) Escapes and wraps paragraphs in <p> elements.

Remember! No data is escaped by default. Always explicitly escape your template variables and be careful which data you access in templates.

The following snippet shows how these functions should be used.

<section>
  <h1><?= $this->html($title) ?></h1>
  <?= $this->format_plain_text($some_text) ?>
  Author: <a href="<?= $this->attr($url_to_author_page) ?>"><?= $this->html($author_name) ?></a>
</section>

Template inheritance

Rack templates support basic template inheritance, provided by the following functions:

Template->extends($template) This function sets the parent template, where <php>$template</php> as a path relative to the current template.
Template->begin($block_name) This function begins a new block.
Template->end() This function ends a block.

Note that nested blocks are not supported and that blocks are only allowed in templates that extend a parent template.

The following snippets demonstrate the use of blocks and template inheritance.

page.phtml

<?php $this->extends('layout.phtml') ?>
 
<?php $this->begin('content') ?>
Hello world!
<?php $this->end() ?>

layout.phtml

<html>
  <head>
    <title><?= $title ?></title>
  </head>
  <body>
   <?= $content ?>
  </body>
</html>

More control structures

Rack templates are parsed and executed as PHP and therefore can execute arbitrary PHP code. However, it is advised to keep it simple in order to maintain separation between rendering and internal logic.

By convention, templates use the Alternative syntax for PHP control structures. Definitions of non-anonymous functions in templates are forbidden (by design) and anonymous functions should only be used in templates in exceptional situations.

Table of Contents