Known splits templating into templates and template types.
Templates are the styling information for each individual page element.
These have names of the form foo, or foo/bar, and may be split up with an indefinite number of forward-slashes. They are structured like relative folder paths; whatever works in a UNIX-style relative folder path, works in a Known template name.
By convention, Known uses lower-case template names.
Examples:
The template type is the kind or category of template we’re dealing with.
By default, Known assumes we’re talking HTML5 (referred to internally as the default template type).
However, if you want to build an RSS feed, for example, your template type might be rss.
Each template type contains its own set of templates. However, templates always fall back to the “default” template type, so that if you try to draw, for example, page/navigation in the rss template type, and it doesn’t exist, page/navigation in the default template type will be called instead (if it exists).
All template files are PHP scripts with the extension .tpl.php. These script filenames correspond to the template name, such that:
You can have multiple top-level templates folders; Known will search them in the order they were added using Bon::additionalPath($path), falling back to the main Known folder at the end.
Variables are accessible in a template file through the $vars array. The BonTemp template object is accessible in template files through a variable called $t.
Examples:
Templates are called by accessing the current site template:
$t = \Idno\Core\site()->template();
You can add variables to pass to the templates by simply adding them as properties to the template object:
$t->title = 'Example title';
$t->foo = $bar;
If you want to set a template type other than default, you call it using setTemplateType($templateType):
$t->setTemplateType('comicsans'); // See?
Finally, to draw a particular template, you call $t->draw($templateName), which returns the rendered template as a string:
$renderedContent = $t->draw('foo/bar');
Or to echo it directly:
echo $t->draw('foo/bar');
The template object also contains a special function to draw the page. This echoes the shell template, and assumes you have (at a bare minimum) set the title and body variables:
$t->drawPage();
For example, to display a stream of items stored in an array called $items, using a template called example/items you might call the templating engine as follows:
$t = \Idno\Core\site()->template();
$t->title = 'Stream';
$t->items = $items;
$t->body = $t->draw('example/items');
$t->drawPage();
The example/items template file itself needs to be stored in templates/default/example/items.tpl.php, and might look something like this:
<?php
if (!empty($vars['items'])) {
foreach($vars['items'] as $item) {
echo $this->__(['item' => $item])->draw('example/item');
}
}
The template file could also contain raw HTML.